Model Metadata

To speed up development Phalcon\Mvc\Model helps you to query fields and constraints from tables related to models. To achieve this, is available to manage and cache table metadata.

Sometimes it is necessary to get those attributes when working with models. You can get a metadata instance as follows:

Once the application is in a production stage, it is not necessary to query the metadata of the table from the database system each time you use the table. This could be done caching the metadata using any of the following adapters:

As other ORM’s dependencies, the metadata manager is requested from the services container:

use Phalcon\Mvc\Model\MetaData\Apc as ApcMetaData;
$di['modelsMetadata'] = function () {
    // Create a metadata manager with APC
    $metadata = new ApcMetaData(
        [
            'lifetime' => 86400,
            'prefix'   => 'my-prefix',
        ]
    );
    return $metadata;
};

You can change the default metadata introspection in the following way:

This strategy doesn’t require any customization and is implicitly used by all the metadata adapters.

Annotations

This strategy makes use of annotations <annotations> to describe the columns in a model:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    /**
     * @Primary
     * @Identity
     * @Column(type='integer', nullable=false)
     */
    public $id;
    /**
     * @Column(type='string', length=70, nullable=false)
     */
    public $name;
    /**
     * @Column(type='string', length=32, nullable=false)
     */
    public $type;
     * @Column(type='integer', nullable=false)
     */
    public $year;
}

Annotations must be placed in properties that are mapped to columns in the mapped source. Properties without the annotation are handled as simple class attributes.

The annotation @Column supports the following parameters:

The annotations strategy could be set up this way:

Using the introspection strategies presented above, Phalcon can obtain the metadata for each model automatically without the developer needing to set them manually.

The developer also has the option of define the metadata manually. This strategy overrides any strategy set in the metadata manager. New columns added/modified/removed to/from the mapped table must be added/modified/removed also for everything to work properly.

<?php
use Phalcon\Mvc\Model;
use Phalcon\Db\Column;
use Phalcon\Mvc\Model\MetaData;
class Robots extends Model
{
    public function metaData()
    {
        return array(
            // Every column in the mapped table
            MetaData::MODELS_ATTRIBUTES => [
                'id',
                'name',
                'type',
                'year',
            ],
            // Every column part of the primary key
            MetaData::MODELS_PRIMARY_KEY => [
                'id',
            ],
            // Every column that isn't part of the primary key
            MetaData::MODELS_NON_PRIMARY_KEY => [
                'name',
                'type',
                'year',
            ],
            // Every column that doesn't allows null values
            MetaData::MODELS_NOT_NULL => [
                'id',
                'name',
                'type',
            ],
            // Every column and their data types
            MetaData::MODELS_DATA_TYPES => [
                'name' => Column::TYPE_VARCHAR,
                'year' => Column::TYPE_INTEGER,
            ],
            // The columns that have numeric data types
            MetaData::MODELS_DATA_TYPES_NUMERIC => [
                'id'   => true,
                'year' => true,
            ],
            // The identity column, use boolean false if the model doesn't have
            // an identity column
            MetaData::MODELS_IDENTITY_COLUMN => 'id',
            // How every column must be bound/casted
            MetaData::MODELS_DATA_TYPES_BIND => [
                'id'   => Column::BIND_PARAM_INT,
                'name' => Column::BIND_PARAM_STR,
                'type' => Column::BIND_PARAM_STR,
                'year' => Column::BIND_PARAM_INT,
            ],
            // Fields that must be ignored from INSERT SQL statements
            MetaData::MODELS_AUTOMATIC_DEFAULT_INSERT => [
                'year' => true,
            ],
            // Fields that must be ignored from UPDATE SQL statements
            MetaData::MODELS_AUTOMATIC_DEFAULT_UPDATE => [
                'year' => true,
            ],
            // Default values for columns
            MetaData::MODELS_DEFAULT_VALUES => [
                'year' => '2015',
            ],
            // Fields that allow empty strings
            MetaData::MODELS_EMPTY_STRING_VALUES => [
                'name' => true,
            ],
        );
    }