php-mapping.rst 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310
  1. PHP Mapping
  2. ===========
  3. Doctrine 2 also allows you to provide the ORM metadata in the form
  4. of plain PHP code using the ``ClassMetadata`` API. You can write
  5. the code in PHP files or inside of a static function named
  6. ``loadMetadata($class)`` on the entity class itself.
  7. PHP Files
  8. ---------
  9. If you wish to write your mapping information inside PHP files that
  10. are named after the entity and included to populate the metadata
  11. for an entity you can do so by using the ``PHPDriver``:
  12. .. code-block:: php
  13. <?php
  14. $driver = new PHPDriver('/path/to/php/mapping/files');
  15. $em->getConfiguration()->setMetadataDriverImpl($driver);
  16. Now imagine we had an entity named ``Entities\User`` and we wanted
  17. to write a mapping file for it using the above configured
  18. ``PHPDriver`` instance:
  19. .. code-block:: php
  20. <?php
  21. namespace Entities;
  22. class User
  23. {
  24. private $id;
  25. private $username;
  26. }
  27. To write the mapping information you just need to create a file
  28. named ``Entities.User.php`` inside of the
  29. ``/path/to/php/mapping/files`` folder:
  30. .. code-block:: php
  31. <?php
  32. // /path/to/php/mapping/files/Entities.User.php
  33. $metadata->mapField(array(
  34. 'id' => true,
  35. 'fieldName' => 'id',
  36. 'type' => 'integer'
  37. ));
  38. $metadata->mapField(array(
  39. 'fieldName' => 'username',
  40. 'type' => 'string'
  41. ));
  42. Now we can easily retrieve the populated ``ClassMetadata`` instance
  43. where the ``PHPDriver`` includes the file and the
  44. ``ClassMetadataFactory`` caches it for later retrieval:
  45. .. code-block:: php
  46. <?php
  47. $class = $em->getClassMetadata('Entities\User');
  48. // or
  49. $class = $em->getMetadataFactory()->getMetadataFor('Entities\User');
  50. Static Function
  51. ---------------
  52. In addition to the PHP files you can also specify your mapping
  53. information inside of a static function defined on the entity class
  54. itself. This is useful for cases where you want to keep your entity
  55. and mapping information together but don't want to use annotations.
  56. For this you just need to use the ``StaticPHPDriver``:
  57. .. code-block:: php
  58. <?php
  59. $driver = new StaticPHPDriver('/path/to/entities');
  60. $em->getConfiguration()->setMetadataDriverImpl($driver);
  61. Now you just need to define a static function named
  62. ``loadMetadata($metadata)`` on your entity:
  63. .. code-block:: php
  64. <?php
  65. namespace Entities;
  66. use Doctrine\ORM\Mapping\ClassMetadata;
  67. class User
  68. {
  69. // ...
  70. public static function loadMetadata(ClassMetadata $metadata)
  71. {
  72. $metadata->mapField(array(
  73. 'id' => true,
  74. 'fieldName' => 'id',
  75. 'type' => 'integer'
  76. ));
  77. $metadata->mapField(array(
  78. 'fieldName' => 'username',
  79. 'type' => 'string'
  80. ));
  81. }
  82. }
  83. ClassMetadataBuilder
  84. --------------------
  85. To ease the use of the ClassMetadata API (which is very raw) there is a ``ClassMetadataBuilder`` that you can use.
  86. .. code-block:: php
  87. <?php
  88. namespace Entities;
  89. use Doctrine\ORM\Mapping\ClassMetadata;
  90. use Doctrine\ORM\Mapping\Builder\ClassMetadataBuilder;
  91. class User
  92. {
  93. // ...
  94. public static function loadMetadata(ClassMetadata $metadata)
  95. {
  96. $builder = new ClassMetadataBuilder($metadata);
  97. $builder->createField('id', 'integer')->isPrimaryKey()->generatedValue()->build();
  98. $builder->addField('username', 'string');
  99. }
  100. }
  101. The API of the ClassMetadataBuilder has the following methods with a fluent interface:
  102. - ``addField($name, $type, array $mapping)``
  103. - ``setMappedSuperclass()``
  104. - ``setReadOnly()``
  105. - ``setCustomRepositoryClass($className)``
  106. - ``setTable($name)``
  107. - ``addIndex(array $columns, $indexName)``
  108. - ``addUniqueConstraint(array $columns, $constraintName)``
  109. - ``addNamedQuery($name, $dqlQuery)``
  110. - ``setJoinedTableInheritance()``
  111. - ``setSingleTableInheritance()``
  112. - ``setDiscriminatorColumn($name, $type = 'string', $length = 255)``
  113. - ``addDiscriminatorMapClass($name, $class)``
  114. - ``setChangeTrackingPolicyDeferredExplicit()``
  115. - ``setChangeTrackingPolicyNotify()``
  116. - ``addLifecycleEvent($methodName, $event)``
  117. - ``addManyToOne($name, $targetEntity, $inversedBy = null)``
  118. - ``addInverseOneToOne($name, $targetEntity, $mappedBy)``
  119. - ``addOwningOneToOne($name, $targetEntity, $inversedBy = null)``
  120. - ``addOwningManyToMany($name, $targetEntity, $inversedBy = null)``
  121. - ``addInverseManyToMany($name, $targetEntity, $mappedBy)``
  122. - ``addOneToMany($name, $targetEntity, $mappedBy)``
  123. It also has several methods that create builders (which are necessary for advanced mappings):
  124. - ``createField($name, $type)`` returns a ``FieldBuilder`` instance
  125. - ``createManyToOne($name, $targetEntity)`` returns an ``AssociationBuilder`` instance
  126. - ``createOneToOne($name, $targetEntity)`` returns an ``AssociationBuilder`` instance
  127. - ``createManyToMany($name, $targetEntity)`` returns an ``ManyToManyAssociationBuilder`` instance
  128. - ``createOneToMany($name, $targetEntity)`` returns an ``OneToManyAssociationBuilder`` instance
  129. ClassMetadataInfo API
  130. ---------------------
  131. The ``ClassMetadataInfo`` class is the base data object for storing
  132. the mapping metadata for a single entity. It contains all the
  133. getters and setters you need populate and retrieve information for
  134. an entity.
  135. General Setters
  136. ~~~~~~~~~~~~~~~
  137. - ``setTableName($tableName)``
  138. - ``setPrimaryTable(array $primaryTableDefinition)``
  139. - ``setCustomRepositoryClass($repositoryClassName)``
  140. - ``setIdGeneratorType($generatorType)``
  141. - ``setIdGenerator($generator)``
  142. - ``setSequenceGeneratorDefinition(array $definition)``
  143. - ``setChangeTrackingPolicy($policy)``
  144. - ``setIdentifier(array $identifier)``
  145. Inheritance Setters
  146. ~~~~~~~~~~~~~~~~~~~
  147. - ``setInheritanceType($type)``
  148. - ``setSubclasses(array $subclasses)``
  149. - ``setParentClasses(array $classNames)``
  150. - ``setDiscriminatorColumn($columnDef)``
  151. - ``setDiscriminatorMap(array $map)``
  152. Field Mapping Setters
  153. ~~~~~~~~~~~~~~~~~~~~~
  154. - ``mapField(array $mapping)``
  155. - ``mapOneToOne(array $mapping)``
  156. - ``mapOneToMany(array $mapping)``
  157. - ``mapManyToOne(array $mapping)``
  158. - ``mapManyToMany(array $mapping)``
  159. Lifecycle Callback Setters
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  161. - ``addLifecycleCallback($callback, $event)``
  162. - ``setLifecycleCallbacks(array $callbacks)``
  163. Versioning Setters
  164. ~~~~~~~~~~~~~~~~~~
  165. - ``setVersionMapping(array &$mapping)``
  166. - ``setVersioned($bool)``
  167. - ``setVersionField()``
  168. General Getters
  169. ~~~~~~~~~~~~~~~
  170. - ``getTableName()``
  171. - ``getTemporaryIdTableName()``
  172. Identifier Getters
  173. ~~~~~~~~~~~~~~~~~~
  174. - ``getIdentifierColumnNames()``
  175. - ``usesIdGenerator()``
  176. - ``isIdentifier($fieldName)``
  177. - ``isIdGeneratorIdentity()``
  178. - ``isIdGeneratorSequence()``
  179. - ``isIdGeneratorTable()``
  180. - ``isIdentifierNatural()``
  181. - ``getIdentifierFieldNames()``
  182. - ``getSingleIdentifierFieldName()``
  183. - ``getSingleIdentifierColumnName()``
  184. Inheritance Getters
  185. ~~~~~~~~~~~~~~~~~~~
  186. - ``isInheritanceTypeNone()``
  187. - ``isInheritanceTypeJoined()``
  188. - ``isInheritanceTypeSingleTable()``
  189. - ``isInheritanceTypeTablePerClass()``
  190. - ``isInheritedField($fieldName)``
  191. - ``isInheritedAssociation($fieldName)``
  192. Change Tracking Getters
  193. ~~~~~~~~~~~~~~~~~~~~~~~
  194. - ``isChangeTrackingDeferredExplicit()``
  195. - ``isChangeTrackingDeferredImplicit()``
  196. - ``isChangeTrackingNotify()``
  197. Field & Association Getters
  198. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  199. - ``isUniqueField($fieldName)``
  200. - ``isNullable($fieldName)``
  201. - ``getColumnName($fieldName)``
  202. - ``getFieldMapping($fieldName)``
  203. - ``getAssociationMapping($fieldName)``
  204. - ``getAssociationMappings()``
  205. - ``getFieldName($columnName)``
  206. - ``hasField($fieldName)``
  207. - ``getColumnNames(array $fieldNames = null)``
  208. - ``getTypeOfField($fieldName)``
  209. - ``getTypeOfColumn($columnName)``
  210. - ``hasAssociation($fieldName)``
  211. - ``isSingleValuedAssociation($fieldName)``
  212. - ``isCollectionValuedAssociation($fieldName)``
  213. Lifecycle Callback Getters
  214. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  215. - ``hasLifecycleCallbacks($lifecycleEvent)``
  216. - ``getLifecycleCallbacks($event)``
  217. ClassMetadata API
  218. -----------------
  219. The ``ClassMetadata`` class extends ``ClassMetadataInfo`` and adds
  220. the runtime functionality required by Doctrine. It adds a few extra
  221. methods related to runtime reflection for working with the entities
  222. themselves.
  223. - ``getReflectionClass()``
  224. - ``getReflectionProperties()``
  225. - ``getReflectionProperty($name)``
  226. - ``getSingleIdReflectionProperty()``
  227. - ``getIdentifierValues($entity)``
  228. - ``setIdentifierValues($entity, $id)``
  229. - ``setFieldValue($entity, $field, $value)``
  230. - ``getFieldValue($entity, $field)``