Models Metadata

To speed up development Phalcon\Mvc\Model helps you to query fields and constraints from tables related to models. To achieve this, Phalcon\Mvc\Model\MetaData 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:

  1. <?php
  2. $robot = new Robots();
  3. // Get Phalcon\Mvc\Model\Metadata instance
  4. $metadata = $robot->getModelsMetaData();
  5. // Get robots fields names
  6. $attributes = $metadata->getAttributes($robot);
  7. print_r($attributes);
  8. // Get robots fields data types
  9. $dataTypes = $metadata->getDataTypes($robot);
  10. print_r($dataTypes);

Caching Metadata

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:

AdapterDescriptionAPI
ApcThis adapter uses the Alternative PHP Cache (APC) to store the table metadata. You can specify the lifetime of the metadata with options. (Recommended for Production).Phalcon\Mvc\Model\MetaData\Apc
FilesThis adapter uses plain files to store metadata. This adapter reduces database queries but has an increased I/O with the file system.Phalcon\Mvc\Model\MetaData\Files
LibmemcachedThis adapter uses the Memcached Server to store the table metadata. The server parameters as well as the cache lifetime are specified in the options. (Recommended for Production)Phalcon\Mvc\Model\MetaData\Libmemcached
MemcacheThis adapter uses Memcache to store the table metadata. You can specify the lifetime of the metadata with options. (Recommended for Production)Phalcon\Mvc\Model\MetaData\MEmcache
MemoryThis adapter is the default. The metadata is cached only during the request. When the request is completed, the metadata are released as part of the normal memory of the request. (Recommended for Development)Phalcon\Mvc\Model\MetaData\Memory
RedisThis adapter uses Redis to store the table metadata. The server parameters as well as the cache lifetime are specified in the options. (Recommended for Production).Phalcon\Mvc\Model\MetaData\Redis
SessionThis adapter stores metadata in the $_SESSION superglobal. This adapter is recommended only when the application is actually using a small number of models. The metadata are refreshed every time a new session starts. This also requires the use of session_start() to start the session before using any models.Phalcon\Mvc\Model\MetaData\Session
XCacheThis adapter uses XCache to store the table metadata. You can specify the lifetime of the metadata with options. This is one of the recommended ways to store metadata when the application is in production.Phalcon\Mvc\Model\MetaData\Xcache

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

  1. <?php
  2. use Phalcon\Mvc\Model\MetaData\Apc as ApcMetaData;
  3. $di['modelsMetadata'] = function () {
  4. // Create a metadata manager with APC
  5. $metadata = new ApcMetaData(
  6. [
  7. 'lifetime' => 86400,
  8. 'prefix' => 'my-prefix',
  9. ]
  10. );
  11. return $metadata;
  12. };

Metadata Strategies

As mentioned above the default strategy to obtain the model’s metadata is database introspection. In this strategy, the information schema is used to know the fields in a table, its primary key, nullable fields, data types, etc.

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

  1. <?php
  2. use Phalcon\Mvc\Model\MetaData\Apc as ApcMetaData;
  3. $di['modelsMetadata'] = function () {
  4. // Instantiate a metadata adapter
  5. $metadata = new ApcMetaData(
  6. [
  7. 'lifetime' => 86400,
  8. 'prefix' => 'my-prefix',
  9. ]
  10. );
  11. // Set a custom metadata introspection strategy
  12. $metadata->setStrategy(
  13. new MyIntrospectionStrategy()
  14. );
  15. return $metadata;
  16. };

Database Introspection Strategy

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

Annotations Strategy

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

  1. <?php
  2. use Phalcon\Mvc\Model;
  3. class Robots extends Model
  4. {
  5. /**
  6. * @Primary
  7. * @Identity
  8. * @Column(type='integer', nullable=false)
  9. */
  10. public $id;
  11. /**
  12. * @Column(type='string', length=70, nullable=false)
  13. */
  14. public $name;
  15. /**
  16. * @Column(type='string', length=32, nullable=false)
  17. */
  18. public $type;
  19. /**
  20. * @Column(type='integer', nullable=false)
  21. */
  22. public $year;
  23. }

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

The following annotations are supported:

NameDescription
PrimaryMark the field as part of the table’s primary key
IdentityThe field is an auto_increment/serial column
ColumnThis marks an attribute as a mapped column

The annotation @Column supports the following parameters:

NameDescription
columnReal column name
typeThe column’s types: varchar/string (default), text, char, json, tinyblob, blob, mediumblob, longblob, integer, biginteger, float, decimal, date, datetime, timestamp, boolean
lengthThe column’s length if any
nullableSet whether the column accepts null values or not
skip_on_insertSkip this column on insert
skip_on_updateSkip this column on updates
allow_empty_stringColumn allow empty strings
defaultDefault value

The annotations strategy could be set up this way:

  1. <?php
  2. use Phalcon\Mvc\Model\MetaData\Apc as ApcMetaData;
  3. use Phalcon\Mvc\Model\MetaData\Strategy\Annotations as StrategyAnnotations;
  4. $di['modelsMetadata'] = function () {
  5. // Instantiate a metadata adapter
  6. $metadata = new ApcMetaData(
  7. [
  8. 'lifetime' => 86400,
  9. 'prefix' => 'my-prefix',
  10. ]
  11. );
  12. // Set a custom metadata database introspection
  13. $metadata->setStrategy(
  14. new StrategyAnnotations()
  15. );
  16. return $metadata;
  17. };

Manual Metadata

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.

The following example shows how to define the metadata manually:

  1. <?php
  2. use Phalcon\Mvc\Model;
  3. use Phalcon\Db\Column;
  4. use Phalcon\Mvc\Model\MetaData;
  5. class Robots extends Model
  6. {
  7. public function metaData()
  8. {
  9. return array(
  10. // Every column in the mapped table
  11. MetaData::MODELS_ATTRIBUTES => [
  12. 'id',
  13. 'name',
  14. 'type',
  15. 'year',
  16. ],
  17. // Every column part of the primary key
  18. MetaData::MODELS_PRIMARY_KEY => [
  19. 'id',
  20. ],
  21. // Every column that isn't part of the primary key
  22. MetaData::MODELS_NON_PRIMARY_KEY => [
  23. 'name',
  24. 'type',
  25. 'year',
  26. ],
  27. // Every column that doesn't allows null values
  28. MetaData::MODELS_NOT_NULL => [
  29. 'id',
  30. 'name',
  31. 'type',
  32. ],
  33. // Every column and their data types
  34. MetaData::MODELS_DATA_TYPES => [
  35. 'id' => Column::TYPE_INTEGER,
  36. 'name' => Column::TYPE_VARCHAR,
  37. 'type' => Column::TYPE_VARCHAR,
  38. 'year' => Column::TYPE_INTEGER,
  39. ],
  40. // The columns that have numeric data types
  41. MetaData::MODELS_DATA_TYPES_NUMERIC => [
  42. 'id' => true,
  43. 'year' => true,
  44. ],
  45. // The identity column, use boolean false if the model doesn't have
  46. // an identity column
  47. MetaData::MODELS_IDENTITY_COLUMN => 'id',
  48. // How every column must be bound/casted
  49. MetaData::MODELS_DATA_TYPES_BIND => [
  50. 'id' => Column::BIND_PARAM_INT,
  51. 'name' => Column::BIND_PARAM_STR,
  52. 'type' => Column::BIND_PARAM_STR,
  53. 'year' => Column::BIND_PARAM_INT,
  54. ],
  55. // Fields that must be ignored from INSERT SQL statements
  56. MetaData::MODELS_AUTOMATIC_DEFAULT_INSERT => [
  57. 'year' => true,
  58. ],
  59. // Fields that must be ignored from UPDATE SQL statements
  60. MetaData::MODELS_AUTOMATIC_DEFAULT_UPDATE => [
  61. 'year' => true,
  62. ],
  63. // Default values for columns
  64. MetaData::MODELS_DEFAULT_VALUES => [
  65. 'year' => '2015',
  66. ],
  67. // Fields that allow empty strings
  68. MetaData::MODELS_EMPTY_STRING_VALUES => [
  69. 'name' => true,
  70. ],
  71. );
  72. }
  73. }