xml-mapping.rst 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747
  1. XML Mapping
  2. ===========
  3. The XML mapping driver enables you to provide the ORM metadata in
  4. form of XML documents.
  5. The XML driver is backed by an XML Schema document that describes
  6. the structure of a mapping document. The most recent version of the
  7. XML Schema document is available online at
  8. `http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd <http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd>`_.
  9. In order to point to the latest version of the document of a
  10. particular stable release branch, just append the release number,
  11. i.e.: doctrine-mapping-2.0.xsd The most convenient way to work with
  12. XML mapping files is to use an IDE/editor that can provide
  13. code-completion based on such an XML Schema document. The following
  14. is an outline of a XML mapping document with the proper xmlns/xsi
  15. setup for the latest code in trunk.
  16. .. code-block:: xml
  17. <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
  18. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  19. xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
  20. https://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
  21. ...
  22. </doctrine-mapping>
  23. The XML mapping document of a class is loaded on-demand the first
  24. time it is requested and subsequently stored in the metadata cache.
  25. In order to work, this requires certain conventions:
  26. - Each entity/mapped superclass must get its own dedicated XML
  27. mapping document.
  28. - The name of the mapping document must consist of the fully
  29. qualified name of the class, where namespace separators are
  30. replaced by dots (.). For example an Entity with the fully
  31. qualified class-name "MyProject" would require a mapping file
  32. "MyProject.Entities.User.dcm.xml" unless the extension is changed.
  33. - All mapping documents should get the extension ".dcm.xml" to
  34. identify it as a Doctrine mapping file. This is more of a
  35. convention and you are not forced to do this. You can change the
  36. file extension easily enough.
  37. -
  38. .. code-block:: php
  39. <?php
  40. $driver->setFileExtension('.xml');
  41. It is recommended to put all XML mapping documents in a single
  42. folder but you can spread the documents over several folders if you
  43. want to. In order to tell the XmlDriver where to look for your
  44. mapping documents, supply an array of paths as the first argument
  45. of the constructor, like this:
  46. .. code-block:: php
  47. <?php
  48. $config = new \Doctrine\ORM\Configuration();
  49. $driver = new \Doctrine\ORM\Mapping\Driver\XmlDriver(array('/path/to/files1', '/path/to/files2'));
  50. $config->setMetadataDriverImpl($driver);
  51. Simplified XML Driver
  52. ~~~~~~~~~~~~~~~~~~~~~
  53. The Symfony project sponsored a driver that simplifies usage of the XML Driver.
  54. The changes between the original driver are:
  55. 1. File Extension is .orm.xml
  56. 2. Filenames are shortened, "MyProject\Entities\User" will become User.orm.xml
  57. 3. You can add a global file and add multiple entities in this file.
  58. Configuration of this client works a little bit different:
  59. .. code-block:: php
  60. <?php
  61. $namespaces = array(
  62. 'MyProject\Entities' => '/path/to/files1',
  63. 'OtherProject\Entities' => '/path/to/files2'
  64. );
  65. $driver = new \Doctrine\ORM\Mapping\Driver\SimplifiedXmlDriver($namespaces);
  66. $driver->setGlobalBasename('global'); // global.orm.xml
  67. Example
  68. -------
  69. As a quick start, here is a small example document that makes use
  70. of several common elements:
  71. .. code-block:: xml
  72. // Doctrine.Tests.ORM.Mapping.User.dcm.xml
  73. <?xml version="1.0" encoding="UTF-8"?>
  74. <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
  75. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  76. xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
  77. http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
  78. <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
  79. <indexes>
  80. <index name="name_idx" columns="name"/>
  81. <index columns="user_email"/>
  82. </indexes>
  83. <unique-constraints>
  84. <unique-constraint columns="name,user_email" name="search_idx" />
  85. </unique-constraints>
  86. <lifecycle-callbacks>
  87. <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
  88. <lifecycle-callback type="prePersist" method="doOtherStuffOnPrePersistToo"/>
  89. <lifecycle-callback type="postPersist" method="doStuffOnPostPersist"/>
  90. </lifecycle-callbacks>
  91. <id name="id" type="integer" column="id">
  92. <generator strategy="AUTO"/>
  93. <sequence-generator sequence-name="tablename_seq" allocation-size="100" initial-value="1" />
  94. </id>
  95. <field name="name" column="name" type="string" length="50" nullable="true" unique="true" />
  96. <field name="email" column="user_email" type="string" column-definition="CHAR(32) NOT NULL" />
  97. <one-to-one field="address" target-entity="Address" inversed-by="user">
  98. <cascade><cascade-remove /></cascade>
  99. <join-column name="address_id" referenced-column-name="id" on-delete="CASCADE" on-update="CASCADE"/>
  100. </one-to-one>
  101. <one-to-many field="phonenumbers" target-entity="Phonenumber" mapped-by="user">
  102. <cascade>
  103. <cascade-persist/>
  104. </cascade>
  105. <order-by>
  106. <order-by-field name="number" direction="ASC" />
  107. </order-by>
  108. </one-to-many>
  109. <many-to-many field="groups" target-entity="Group">
  110. <cascade>
  111. <cascade-all/>
  112. </cascade>
  113. <join-table name="cms_users_groups">
  114. <join-columns>
  115. <join-column name="user_id" referenced-column-name="id" nullable="false" unique="false" />
  116. </join-columns>
  117. <inverse-join-columns>
  118. <join-column name="group_id" referenced-column-name="id" column-definition="INT NULL" />
  119. </inverse-join-columns>
  120. </join-table>
  121. </many-to-many>
  122. </entity>
  123. </doctrine-mapping>
  124. Be aware that class-names specified in the XML files should be
  125. fully qualified.
  126. XML-Element Reference
  127. ---------------------
  128. The XML-Element reference explains all the tags and attributes that
  129. the Doctrine Mapping XSD Schema defines. You should read the
  130. Basic-, Association- and Inheritance Mapping chapters to understand
  131. what each of this definitions means in detail.
  132. Defining an Entity
  133. ~~~~~~~~~~~~~~~~~~
  134. Each XML Mapping File contains the definition of one entity,
  135. specified as the ``<entity />`` element as a direct child of the
  136. ``<doctrine-mapping />`` element:
  137. .. code-block:: xml
  138. <doctrine-mapping>
  139. <entity name="MyProject\User" table="cms_users" repository-class="MyProject\UserRepository">
  140. <!-- definition here -->
  141. </entity>
  142. </doctrine-mapping>
  143. Required attributes:
  144. - name - The fully qualified class-name of the entity.
  145. Optional attributes:
  146. - **table** - The Table-Name to be used for this entity. Otherwise the
  147. Unqualified Class-Name is used by default.
  148. - **repository-class** - The fully qualified class-name of an
  149. alternative ``Doctrine\ORM\EntityRepository`` implementation to be
  150. used with this entity.
  151. - **inheritance-type** - The type of inheritance, defaults to none. A
  152. more detailed description follows in the
  153. *Defining Inheritance Mappings* section.
  154. - **read-only** - (>= 2.1) Specifies that this entity is marked as read only and not
  155. considered for change-tracking. Entities of this type can be persisted
  156. and removed though.
  157. Defining Fields
  158. ~~~~~~~~~~~~~~~
  159. Each entity class can contain zero to infinite fields that are
  160. managed by Doctrine. You can define them using the ``<field />``
  161. element as a children to the ``<entity />`` element. The field
  162. element is only used for primitive types that are not the ID of the
  163. entity. For the ID mapping you have to use the ``<id />`` element.
  164. .. code-block:: xml
  165. <entity name="MyProject\User">
  166. <field name="name" type="string" length="50" />
  167. <field name="username" type="string" unique="true" />
  168. <field name="age" type="integer" nullable="true" />
  169. <field name="isActive" column="is_active" type="boolean" />
  170. <field name="weight" type="decimal" scale="5" precision="2" />
  171. </entity>
  172. Required attributes:
  173. - name - The name of the Property/Field on the given Entity PHP
  174. class.
  175. Optional attributes:
  176. - type - The ``Doctrine\DBAL\Types\Type`` name, defaults to
  177. "string"
  178. - column - Name of the column in the database, defaults to the
  179. field name.
  180. - length - The length of the given type, for use with strings
  181. only.
  182. - unique - Should this field contain a unique value across the
  183. table? Defaults to false.
  184. - nullable - Should this field allow NULL as a value? Defaults to
  185. false.
  186. - version - Should this field be used for optimistic locking? Only
  187. works on fields with type integer or datetime.
  188. - scale - Scale of a decimal type.
  189. - precision - Precision of a decimal type.
  190. - column-definition - Optional alternative SQL representation for
  191. this column. This definition begin after the field-name and has to
  192. specify the complete column definition. Using this feature will
  193. turn this field dirty for Schema-Tool update commands at all
  194. times.
  195. Defining Identity and Generator Strategies
  196. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  197. An entity has to have at least one ``<id />`` element. For
  198. composite keys you can specify more than one id-element, however
  199. surrogate keys are recommended for use with Doctrine 2. The Id
  200. field allows to define properties of the identifier and allows a
  201. subset of the ``<field />`` element attributes:
  202. .. code-block:: xml
  203. <entity name="MyProject\User">
  204. <id name="id" type="integer" column="user_id" />
  205. </entity>
  206. Required attributes:
  207. - name - The name of the Property/Field on the given Entity PHP
  208. class.
  209. - type - The ``Doctrine\DBAL\Types\Type`` name, preferably
  210. "string" or "integer".
  211. Optional attributes:
  212. - column - Name of the column in the database, defaults to the
  213. field name.
  214. Using the simplified definition above Doctrine will use no
  215. identifier strategy for this entity. That means you have to
  216. manually set the identifier before calling
  217. ``EntityManager#persist($entity)``. This is the so called
  218. ``ASSIGNED`` strategy.
  219. If you want to switch the identifier generation strategy you have
  220. to nest a ``<generator />`` element inside the id-element. This of
  221. course only works for surrogate keys. For composite keys you always
  222. have to use the ``ASSIGNED`` strategy.
  223. .. code-block:: xml
  224. <entity name="MyProject\User">
  225. <id name="id" type="integer" column="user_id">
  226. <generator strategy="AUTO" />
  227. </id>
  228. </entity>
  229. The following values are allowed for the ``<generator />`` strategy
  230. attribute:
  231. - AUTO - Automatic detection of the identifier strategy based on
  232. the preferred solution of the database vendor.
  233. - IDENTITY - Use of a IDENTIFY strategy such as Auto-Increment IDs
  234. available to Doctrine AFTER the INSERT statement has been executed.
  235. - SEQUENCE - Use of a database sequence to retrieve the
  236. entity-ids. This is possible before the INSERT statement is
  237. executed.
  238. If you are using the SEQUENCE strategy you can define an additional
  239. element to describe the sequence:
  240. .. code-block:: xml
  241. <entity name="MyProject\User">
  242. <id name="id" type="integer" column="user_id">
  243. <generator strategy="SEQUENCE" />
  244. <sequence-generator sequence-name="user_seq" allocation-size="5" initial-value="1" />
  245. </id>
  246. </entity>
  247. Required attributes for ``<sequence-generator />``:
  248. - sequence-name - The name of the sequence
  249. Optional attributes for ``<sequence-generator />``:
  250. - allocation-size - By how much steps should the sequence be
  251. incremented when a value is retrieved. Defaults to 1
  252. - initial-value - What should the initial value of the sequence
  253. be.
  254. **NOTE**
  255. If you want to implement a cross-vendor compatible application you
  256. have to specify and additionally define the <sequence-generator />
  257. element, if Doctrine chooses the sequence strategy for a
  258. platform.
  259. Defining a Mapped Superclass
  260. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  261. Sometimes you want to define a class that multiple entities inherit
  262. from, which itself is not an entity however. The chapter on
  263. *Inheritance Mapping* describes a Mapped Superclass in detail. You
  264. can define it in XML using the ``<mapped-superclass />`` tag.
  265. .. code-block:: xml
  266. <doctrine-mapping>
  267. <mapped-superclass name="MyProject\BaseClass">
  268. <field name="created" type="datetime" />
  269. <field name="updated" type="datetime" />
  270. </mapped-superclass>
  271. </doctrine-mapping>
  272. Required attributes:
  273. - name - Class name of the mapped superclass.
  274. You can nest any number of ``<field />`` and unidirectional
  275. ``<many-to-one />`` or ``<one-to-one />`` associations inside a
  276. mapped superclass.
  277. Defining Inheritance Mappings
  278. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  279. There are currently two inheritance persistence strategies that you
  280. can choose from when defining entities that inherit from each
  281. other. Single Table inheritance saves the fields of the complete
  282. inheritance hierarchy in a single table, joined table inheritance
  283. creates a table for each entity combining the fields using join
  284. conditions.
  285. You can specify the inheritance type in the ``<entity />`` element
  286. and then use the ``<discriminator-column />`` and
  287. ``<discriminator-mapping />`` attributes.
  288. .. code-block:: xml
  289. <entity name="MyProject\Animal" inheritance-type="JOINED">
  290. <discriminator-column name="discr" type="string" />
  291. <discriminator-map>
  292. <discriminator-mapping value="cat" class="MyProject\Cat" />
  293. <discriminator-mapping value="dog" class="MyProject\Dog" />
  294. <discriminator-mapping value="mouse" class="MyProject\Mouse" />
  295. </discriminator-map>
  296. </entity>
  297. The allowed values for inheritance-type attribute are ``JOINED`` or
  298. ``SINGLE_TABLE``.
  299. .. note::
  300. All inheritance related definitions have to be defined on the root
  301. entity of the hierarchy.
  302. Defining Lifecycle Callbacks
  303. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  304. You can define the lifecycle callback methods on your entities
  305. using the ``<lifecycle-callbacks />`` element:
  306. .. code-block:: xml
  307. <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
  308. <lifecycle-callbacks>
  309. <lifecycle-callback type="prePersist" method="onPrePersist" />
  310. </lifecycle-callbacks>
  311. </entity>
  312. Defining One-To-One Relations
  313. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  314. You can define One-To-One Relations/Associations using the
  315. ``<one-to-one />`` element. The required and optional attributes
  316. depend on the associations being on the inverse or owning side.
  317. For the inverse side the mapping is as simple as:
  318. .. code-block:: xml
  319. <entity class="MyProject\User">
  320. <one-to-one field="address" target-entity="Address" mapped-by="user" />
  321. </entity>
  322. Required attributes for inverse One-To-One:
  323. - field - Name of the property/field on the entity's PHP class.
  324. - target-entity - Name of the entity associated entity class. If
  325. this is not qualified the namespace of the current class is
  326. prepended. *IMPORTANT:* No leading backslash!
  327. - mapped-by - Name of the field on the owning side (here Address
  328. entity) that contains the owning side association.
  329. For the owning side this mapping would look like:
  330. .. code-block:: xml
  331. <entity class="MyProject\Address">
  332. <one-to-one field="user" target-entity="User" inversed-by="address" />
  333. </entity>
  334. Required attributes for owning One-to-One:
  335. - field - Name of the property/field on the entity's PHP class.
  336. - target-entity - Name of the entity associated entity class. If
  337. this is not qualified the namespace of the current class is
  338. prepended. *IMPORTANT:* No leading backslash!
  339. Optional attributes for owning One-to-One:
  340. - inversed-by - If the association is bidirectional the
  341. inversed-by attribute has to be specified with the name of the
  342. field on the inverse entity that contains the back-reference.
  343. - orphan-removal - If true, the inverse side entity is always
  344. deleted when the owning side entity is. Defaults to false.
  345. - fetch - Either LAZY or EAGER, defaults to LAZY. This attribute
  346. makes only sense on the owning side, the inverse side *ALWAYS* has
  347. to use the ``FETCH`` strategy.
  348. The definition for the owning side relies on a bunch of mapping
  349. defaults for the join column names. Without the nested
  350. ``<join-column />`` element Doctrine assumes to foreign key to be
  351. called ``user_id`` on the Address Entities table. This is because
  352. the ``MyProject\Address`` entity is the owning side of this
  353. association, which means it contains the foreign key.
  354. The completed explicitly defined mapping is:
  355. .. code-block:: xml
  356. <entity class="MyProject\Address">
  357. <one-to-one field="user" target-entity="User" inversed-by="address">
  358. <join-column name="user_id" referenced-column-name="id" />
  359. </one-to-one>
  360. </entity>
  361. Defining Many-To-One Associations
  362. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  363. The many-to-one association is *ALWAYS* the owning side of any
  364. bidirectional association. This simplifies the mapping compared to
  365. the one-to-one case. The minimal mapping for this association looks
  366. like:
  367. .. code-block:: xml
  368. <entity class="MyProject\Article">
  369. <many-to-one field="author" target-entity="User" />
  370. </entity>
  371. Required attributes:
  372. - field - Name of the property/field on the entity's PHP class.
  373. - target-entity - Name of the entity associated entity class. If
  374. this is not qualified the namespace of the current class is
  375. prepended. *IMPORTANT:* No leading backslash!
  376. Optional attributes:
  377. - inversed-by - If the association is bidirectional the
  378. inversed-by attribute has to be specified with the name of the
  379. field on the inverse entity that contains the back-reference.
  380. - orphan-removal - If true the entity on the inverse side is
  381. always deleted when the owning side entity is and it is not
  382. connected to any other owning side entity anymore. Defaults to
  383. false.
  384. - fetch - Either LAZY or EAGER, defaults to LAZY.
  385. This definition relies on a bunch of mapping defaults with regards
  386. to the naming of the join-column/foreign key. The explicitly
  387. defined mapping includes a ``<join-column />`` tag nested inside
  388. the many-to-one association tag:
  389. .. code-block:: xml
  390. <entity class="MyProject\Article">
  391. <many-to-one field="author" target-entity="User">
  392. <join-column name="author_id" referenced-column-name="id" />
  393. </many-to-one>
  394. </entity>
  395. The join-column attribute ``name`` specifies the column name of the
  396. foreign key and the ``referenced-column-name`` attribute specifies
  397. the name of the primary key column on the User entity.
  398. Defining One-To-Many Associations
  399. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  400. The one-to-many association is *ALWAYS* the inverse side of any
  401. association. There exists no such thing as a uni-directional
  402. one-to-many association, which means this association only ever
  403. exists for bi-directional associations.
  404. .. code-block:: xml
  405. <entity class="MyProject\User">
  406. <one-to-many field="phonenumbers" target-entity="Phonenumber" mapped-by="user" />
  407. </entity>
  408. Required attributes:
  409. - field - Name of the property/field on the entity's PHP class.
  410. - target-entity - Name of the entity associated entity class. If
  411. this is not qualified the namespace of the current class is
  412. prepended. *IMPORTANT:* No leading backslash!
  413. - mapped-by - Name of the field on the owning side (here
  414. Phonenumber entity) that contains the owning side association.
  415. Optional attributes:
  416. - fetch - Either LAZY, EXTRA_LAZY or EAGER, defaults to LAZY.
  417. - index-by: Index the collection by a field on the target entity.
  418. Defining Many-To-Many Associations
  419. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  420. From all the associations the many-to-many has the most complex
  421. definition. When you rely on the mapping defaults you can omit many
  422. definitions and rely on their implicit values.
  423. .. code-block:: xml
  424. <entity class="MyProject\User">
  425. <many-to-many field="groups" target-entity="Group" />
  426. </entity>
  427. Required attributes:
  428. - field - Name of the property/field on the entity's PHP class.
  429. - target-entity - Name of the entity associated entity class. If
  430. this is not qualified the namespace of the current class is
  431. prepended. *IMPORTANT:* No leading backslash!
  432. Optional attributes:
  433. - mapped-by - Name of the field on the owning side that contains
  434. the owning side association if the defined many-to-many association
  435. is on the inverse side.
  436. - inversed-by - If the association is bidirectional the
  437. inversed-by attribute has to be specified with the name of the
  438. field on the inverse entity that contains the back-reference.
  439. - fetch - Either LAZY, EXTRA_LAZY or EAGER, defaults to LAZY.
  440. - index-by: Index the collection by a field on the target entity.
  441. The mapping defaults would lead to a join-table with the name
  442. "User\_Group" being created that contains two columns "user\_id"
  443. and "group\_id". The explicit definition of this mapping would be:
  444. .. code-block:: xml
  445. <entity class="MyProject\User">
  446. <many-to-many field="groups" target-entity="Group">
  447. <join-table name="cms_users_groups">
  448. <join-columns>
  449. <join-column name="user_id" referenced-column-name="id"/>
  450. </join-columns>
  451. <inverse-join-columns>
  452. <join-column name="group_id" referenced-column-name="id"/>
  453. </inverse-join-columns>
  454. </join-table>
  455. </many-to-many>
  456. </entity>
  457. Here both the ``<join-columns>`` and ``<inverse-join-columns>``
  458. tags are necessary to tell Doctrine for which side the specified
  459. join-columns apply. These are nested inside a ``<join-table />``
  460. attribute which allows to specify the table name of the
  461. many-to-many join-table.
  462. Cascade Element
  463. ~~~~~~~~~~~~~~~
  464. Doctrine allows cascading of several UnitOfWork operations to
  465. related entities. You can specify the cascade operations in the
  466. ``<cascade />`` element inside any of the association mapping
  467. tags.
  468. .. code-block:: xml
  469. <entity class="MyProject\User">
  470. <many-to-many field="groups" target-entity="Group">
  471. <cascade>
  472. <cascade-all/>
  473. </cascade>
  474. </many-to-many>
  475. </entity>
  476. Besides ``<cascade-all />`` the following operations can be
  477. specified by their respective tags:
  478. - ``<cascade-persist />``
  479. - ``<cascade-merge />``
  480. - ``<cascade-remove />``
  481. - ``<cascade-refresh />``
  482. Join Column Element
  483. ~~~~~~~~~~~~~~~~~~~
  484. In any explicitly defined association mapping you will need the
  485. ``<join-column />`` tag. It defines how the foreign key and primary
  486. key names are called that are used for joining two entities.
  487. Required attributes:
  488. - name - The column name of the foreign key.
  489. - referenced-column-name - The column name of the associated
  490. entities primary key
  491. Optional attributes:
  492. - unique - If the join column should contain a UNIQUE constraint.
  493. This makes sense for Many-To-Many join-columns only to simulate a
  494. one-to-many unidirectional using a join-table.
  495. - nullable - should the join column be nullable, defaults to true.
  496. - on-delete - Foreign Key Cascade action to perform when entity is
  497. deleted, defaults to NO ACTION/RESTRICT but can be set to
  498. "CASCADE".
  499. Defining Order of To-Many Associations
  500. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  501. You can require one-to-many or many-to-many associations to be
  502. retrieved using an additional ``ORDER BY``.
  503. .. code-block:: xml
  504. <entity class="MyProject\User">
  505. <many-to-many field="groups" target-entity="Group">
  506. <order-by>
  507. <order-by-field name="name" direction="ASC" />
  508. </order-by>
  509. </many-to-many>
  510. </entity>
  511. Defining Indexes or Unique Constraints
  512. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  513. To define additional indexes or unique constraints on the entities
  514. table you can use the ``<indexes />`` and
  515. ``<unique-constraints />`` elements:
  516. .. code-block:: xml
  517. <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
  518. <indexes>
  519. <index name="name_idx" columns="name"/>
  520. <index columns="user_email"/>
  521. </indexes>
  522. <unique-constraints>
  523. <unique-constraint columns="name,user_email" name="search_idx" />
  524. </unique-constraints>
  525. </entity>
  526. You have to specify the column and not the entity-class field names
  527. in the index and unique-constraint definitions.
  528. Derived Entities ID syntax
  529. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  530. If the primary key of an entity contains a foreign key to another entity we speak of a derived
  531. entity relationship. You can define this in XML with the "association-key" attribute in the ``<id>`` tag.
  532. .. code-block:: xml
  533. <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
  534. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  535. xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
  536. http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
  537. <entity name="Application\Model\ArticleAttribute">
  538. <id name="article" association-key="true" />
  539. <id name="attribute" type="string" />
  540. <field name="value" type="string" />
  541. <many-to-one field="article" target-entity="Article" inversed-by="attributes" />
  542. <entity>
  543. </doctrine-mapping>