metadata-drivers.rst 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194
  1. Metadata Drivers
  2. ================
  3. The heart of an object relational mapper is the mapping information
  4. that glues everything together. It instructs the EntityManager how
  5. it should behave when dealing with the different entities.
  6. Core Metadata Drivers
  7. ---------------------
  8. Doctrine provides a few different ways for you to specify your
  9. metadata:
  10. - **XML files** (XmlDriver)
  11. - **Class DocBlock Annotations** (AnnotationDriver)
  12. - **YAML files** (YamlDriver)
  13. - **PHP Code in files or static functions** (PhpDriver)
  14. Something important to note about the above drivers is they are all
  15. an intermediate step to the same end result. The mapping
  16. information is populated to ``Doctrine\ORM\Mapping\ClassMetadata``
  17. instances. So in the end, Doctrine only ever has to work with the
  18. API of the ``ClassMetadata`` class to get mapping information for
  19. an entity.
  20. .. note::
  21. The populated ``ClassMetadata`` instances are also cached
  22. so in a production environment the parsing and populating only ever
  23. happens once. You can configure the metadata cache implementation
  24. using the ``setMetadataCacheImpl()`` method on the
  25. ``Doctrine\ORM\Configuration`` class:
  26. .. code-block:: php
  27. <?php
  28. $em->getConfiguration()->setMetadataCacheImpl(new ApcCache());
  29. If you want to use one of the included core metadata drivers you
  30. just need to configure it. All the drivers are in the
  31. ``Doctrine\ORM\Mapping\Driver`` namespace:
  32. .. code-block:: php
  33. <?php
  34. $driver = new \Doctrine\ORM\Mapping\Driver\XmlDriver('/path/to/mapping/files');
  35. $em->getConfiguration()->setMetadataDriverImpl($driver);
  36. Implementing Metadata Drivers
  37. -----------------------------
  38. In addition to the included metadata drivers you can very easily
  39. implement your own. All you need to do is define a class which
  40. implements the ``Driver`` interface:
  41. .. code-block:: php
  42. <?php
  43. namespace Doctrine\ORM\Mapping\Driver;
  44. use Doctrine\ORM\Mapping\ClassMetadataInfo;
  45. interface Driver
  46. {
  47. /**
  48. * Loads the metadata for the specified class into the provided container.
  49. *
  50. * @param string $className
  51. * @param ClassMetadataInfo $metadata
  52. */
  53. function loadMetadataForClass($className, ClassMetadataInfo $metadata);
  54. /**
  55. * Gets the names of all mapped classes known to this driver.
  56. *
  57. * @return array The names of all mapped classes known to this driver.
  58. */
  59. function getAllClassNames();
  60. /**
  61. * Whether the class with the specified name should have its metadata loaded.
  62. * This is only the case if it is either mapped as an Entity or a
  63. * MappedSuperclass.
  64. *
  65. * @param string $className
  66. * @return boolean
  67. */
  68. function isTransient($className);
  69. }
  70. If you want to write a metadata driver to parse information from
  71. some file format we've made your life a little easier by providing
  72. the ``AbstractFileDriver`` implementation for you to extend from:
  73. .. code-block:: php
  74. <?php
  75. class MyMetadataDriver extends AbstractFileDriver
  76. {
  77. /**
  78. * {@inheritdoc}
  79. */
  80. protected $_fileExtension = '.dcm.ext';
  81. /**
  82. * {@inheritdoc}
  83. */
  84. public function loadMetadataForClass($className, ClassMetadataInfo $metadata)
  85. {
  86. $data = $this->_loadMappingFile($file);
  87. // populate ClassMetadataInfo instance from $data
  88. }
  89. /**
  90. * {@inheritdoc}
  91. */
  92. protected function _loadMappingFile($file)
  93. {
  94. // parse contents of $file and return php data structure
  95. }
  96. }
  97. .. note::
  98. When using the ``AbstractFileDriver`` it requires that you
  99. only have one entity defined per file and the file named after the
  100. class described inside where namespace separators are replaced by
  101. periods. So if you have an entity named ``Entities\User`` and you
  102. wanted to write a mapping file for your driver above you would need
  103. to name the file ``Entities.User.dcm.ext`` for it to be
  104. recognized.
  105. Now you can use your ``MyMetadataDriver`` implementation by setting
  106. it with the ``setMetadataDriverImpl()`` method:
  107. .. code-block:: php
  108. <?php
  109. $driver = new MyMetadataDriver('/path/to/mapping/files');
  110. $em->getConfiguration()->setMetadataDriverImpl($driver);
  111. ClassMetadata
  112. -------------
  113. The last piece you need to know and understand about metadata in
  114. Doctrine 2 is the API of the ``ClassMetadata`` classes. You need to
  115. be familiar with them in order to implement your own drivers but
  116. more importantly to retrieve mapping information for a certain
  117. entity when needed.
  118. You have all the methods you need to manually specify the mapping
  119. information instead of using some mapping file to populate it from.
  120. The base ``ClassMetadataInfo`` class is responsible for only data
  121. storage and is not meant for runtime use. It does not require that
  122. the class actually exists yet so it is useful for describing some
  123. entity before it exists and using that information to generate for
  124. example the entities themselves. The class ``ClassMetadata``
  125. extends ``ClassMetadataInfo`` and adds some functionality required
  126. for runtime usage and requires that the PHP class is present and
  127. can be autoloaded.
  128. You can read more about the API of the ``ClassMetadata`` classes in
  129. the PHP Mapping chapter.
  130. Getting ClassMetadata Instances
  131. -------------------------------
  132. If you want to get the ``ClassMetadata`` instance for an entity in
  133. your project to programmatically use some mapping information to
  134. generate some HTML or something similar you can retrieve it through
  135. the ``ClassMetadataFactory``:
  136. .. code-block:: php
  137. <?php
  138. $cmf = $em->getMetadataFactory();
  139. $class = $cmf->getMetadataFor('MyEntityName');
  140. Now you can learn about the entity and use the data stored in the
  141. ``ClassMetadata`` instance to get all mapped fields for example and
  142. iterate over them:
  143. .. code-block:: php
  144. <?php
  145. foreach ($class->fieldMappings as $fieldMapping) {
  146. echo $fieldMapping['fieldName'] . "\n";
  147. }