annotations-reference.rst 31 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114
  1. Annotations Reference
  2. =====================
  3. In this chapter a reference of every Doctrine 2 Annotation is given
  4. with short explanations on their context and usage.
  5. Index
  6. -----
  7. - :ref:`@Column <annref_column>`
  8. - :ref:`@ColumnResult <annref_column_result>`
  9. - :ref:`@ChangeTrackingPolicy <annref_changetrackingpolicy>`
  10. - :ref:`@DiscriminatorColumn <annref_discriminatorcolumn>`
  11. - :ref:`@DiscriminatorMap <annref_discriminatormap>`
  12. - :ref:`@Entity <annref_entity>`
  13. - :ref:`@EntityResult <annref_entity_result>`
  14. - :ref:`@FieldResult <annref_field_result>`
  15. - :ref:`@GeneratedValue <annref_generatedvalue>`
  16. - :ref:`@HasLifecycleCallbacks <annref_haslifecyclecallbacks>`
  17. - :ref:`@Index <annref_index>`
  18. - :ref:`@Id <annref_id>`
  19. - :ref:`@InheritanceType <annref_inheritancetype>`
  20. - :ref:`@JoinColumn <annref_joincolumn>`
  21. - :ref:`@JoinColumns <annref_joincolumns>`
  22. - :ref:`@JoinTable <annref_jointable>`
  23. - :ref:`@ManyToOne <annref_manytoone>`
  24. - :ref:`@ManyToMany <annref_manytomany>`
  25. - :ref:`@MappedSuperclass <annref_mappedsuperclass>`
  26. - :ref:`@NamedNativeQuery <annref_named_native_query>`
  27. - :ref:`@OneToOne <annref_onetoone>`
  28. - :ref:`@OneToMany <annref_onetomany>`
  29. - :ref:`@OrderBy <annref_orderby>`
  30. - :ref:`@PostLoad <annref_postload>`
  31. - :ref:`@PostPersist <annref_postpersist>`
  32. - :ref:`@PostRemove <annref_postremove>`
  33. - :ref:`@PostUpdate <annref_postupdate>`
  34. - :ref:`@PrePersist <annref_prepersist>`
  35. - :ref:`@PreRemove <annref_preremove>`
  36. - :ref:`@PreUpdate <annref_preupdate>`
  37. - :ref:`@SequenceGenerator <annref_sequencegenerator>`
  38. - :ref:`@SqlResultSetMapping <annref_sql_resultset_mapping>`
  39. - :ref:`@Table <annref_table>`
  40. - :ref:`@UniqueConstraint <annref_uniqueconstraint>`
  41. - :ref:`@Version <annref_version>`
  42. Reference
  43. ---------
  44. .. _annref_column:
  45. @Column
  46. ~~~~~~~
  47. Marks an annotated instance variable as "persistent". It has to be
  48. inside the instance variables PHP DocBlock comment. Any value hold
  49. inside this variable will be saved to and loaded from the database
  50. as part of the lifecycle of the instance variables entity-class.
  51. Required attributes:
  52. - **type**: Name of the Doctrine Type which is converted between PHP
  53. and Database representation.
  54. Optional attributes:
  55. - **name**: By default the property name is used for the database
  56. column name also, however the 'name' attribute allows you to
  57. determine the column name.
  58. - **length**: Used by the "string" type to determine its maximum
  59. length in the database. Doctrine does not validate the length of a
  60. string values for you.
  61. - **precision**: The precision for a decimal (exact numeric) column
  62. (Applies only for decimal column)
  63. - **scale**: The scale for a decimal (exact numeric) column (Applies
  64. only for decimal column)
  65. - **unique**: Boolean value to determine if the value of the column
  66. should be unique across all rows of the underlying entities table.
  67. - **nullable**: Determines if NULL values allowed for this column.
  68. - **columnDefinition**: DDL SQL snippet that starts after the column
  69. name and specifies the complete (non-portable!) column definition.
  70. This attribute allows to make use of advanced RMDBS features.
  71. However you should make careful use of this feature and the
  72. consequences. SchemaTool will not detect changes on the column correctly
  73. anymore if you use "columnDefinition".
  74. Additionally you should remember that the "type"
  75. attribute still handles the conversion between PHP and Database
  76. values. If you use this attribute on a column that is used for
  77. joins between tables you should also take a look at
  78. :ref:`@JoinColumn <annref_joincolumn>`.
  79. Examples:
  80. .. code-block:: php
  81. <?php
  82. /**
  83. * @Column(type="string", length=32, unique=true, nullable=false)
  84. */
  85. protected $username;
  86. /**
  87. * @Column(type="string", columnDefinition="CHAR(2) NOT NULL")
  88. */
  89. protected $country;
  90. /**
  91. * @Column(type="decimal", precision=2, scale=1)
  92. */
  93. protected $height;
  94. .. _annref_column_result:
  95. @ColumnResult
  96. ~~~~~~~~~~~~~~
  97. References name of a column in the SELECT clause of a SQL query.
  98. Scalar result types can be included in the query result by specifying this annotation in the metadata.
  99. Required attributes:
  100. - **name**: The name of a column in the SELECT clause of a SQL query
  101. .. _annref_changetrackingpolicy:
  102. @ChangeTrackingPolicy
  103. ~~~~~~~~~~~~~~~~~~~~~
  104. The Change Tracking Policy annotation allows to specify how the
  105. Doctrine 2 UnitOfWork should detect changes in properties of
  106. entities during flush. By default each entity is checked according
  107. to a deferred implicit strategy, which means upon flush UnitOfWork
  108. compares all the properties of an entity to a previously stored
  109. snapshot. This works out of the box, however you might want to
  110. tweak the flush performance where using another change tracking
  111. policy is an interesting option.
  112. The :doc:`details on all the available change tracking policies <change-tracking-policies>`
  113. can be found in the configuration section.
  114. Example:
  115. .. code-block:: php
  116. <?php
  117. /**
  118. * @Entity
  119. * @ChangeTrackingPolicy("DEFERRED_IMPLICIT")
  120. * @ChangeTrackingPolicy("DEFERRED_EXPLICIT")
  121. * @ChangeTrackingPolicy("NOTIFY")
  122. */
  123. class User {}
  124. .. _annref_discriminatorcolumn:
  125. @DiscriminatorColumn
  126. ~~~~~~~~~~~~~~~~~~~~~
  127. This annotation is a required annotation for the topmost/super
  128. class of an inheritance hierarchy. It specifies the details of the
  129. column which saves the name of the class, which the entity is
  130. actually instantiated as.
  131. Required attributes:
  132. - **name**: The column name of the discriminator. This name is also
  133. used during Array hydration as key to specify the class-name.
  134. Optional attributes:
  135. - **type**: By default this is string.
  136. - **length**: By default this is 255.
  137. .. _annref_discriminatormap:
  138. @DiscriminatorMap
  139. ~~~~~~~~~~~~~~~~~~~~~
  140. The discriminator map is a required annotation on the
  141. top-most/super class in an inheritance hierarchy. It takes an array
  142. as only argument which defines which class should be saved under
  143. which name in the database. Keys are the database value and values
  144. are the classes, either as fully- or as unqualified class names
  145. depending if the classes are in the namespace or not.
  146. .. code-block:: php
  147. <?php
  148. /**
  149. * @Entity
  150. * @InheritanceType("JOINED")
  151. * @DiscriminatorColumn(name="discr", type="string")
  152. * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
  153. */
  154. class Person
  155. {
  156. // ...
  157. }
  158. .. _annref_entity:
  159. @Entity
  160. ~~~~~~~
  161. Required annotation to mark a PHP class as Entity. Doctrine manages
  162. the persistence of all classes marked as entity.
  163. Optional attributes:
  164. - **repositoryClass**: Specifies the FQCN of a subclass of the
  165. EntityRepository. Use of repositories for entities is encouraged to keep
  166. specialized DQL and SQL operations separated from the Model/Domain
  167. Layer.
  168. - **readOnly**: (>= 2.1) Specifies that this entity is marked as read only and not
  169. considered for change-tracking. Entities of this type can be persisted
  170. and removed though.
  171. Example:
  172. .. code-block:: php
  173. <?php
  174. /**
  175. * @Entity(repositoryClass="MyProject\UserRepository")
  176. */
  177. class User
  178. {
  179. //...
  180. }
  181. .. _annref_entity_result:
  182. @EntityResult
  183. ~~~~~~~~~~~~~~
  184. References an entity in the SELECT clause of a SQL query.
  185. If this annotation is used, the SQL statement should select all of the columns that are mapped to the entity object.
  186. This should include foreign key columns to related entities.
  187. The results obtained when insufficient data is available are undefined.
  188. Required attributes:
  189. - **entityClass**: The class of the result.
  190. Optional attributes:
  191. - **fields**: Array of @FieldResult, Maps the columns specified in the SELECT list of the query to the properties or fields of the entity class.
  192. - **discriminatorColumn**: Specifies the column name of the column in the SELECT list that is used to determine the type of the entity instance.
  193. .. _annref_field_result:
  194. @FieldResult
  195. ~~~~~~~~~~~~~
  196. Is used to map the columns specified in the SELECT list of the query to the properties or fields of the entity class.
  197. Required attributes:
  198. - **name**: Name of the persistent field or property of the class.
  199. Optional attributes:
  200. - **column**: Name of the column in the SELECT clause.
  201. .. _annref_generatedvalue:
  202. @GeneratedValue
  203. ~~~~~~~~~~~~~~~~~~~~~
  204. Specifies which strategy is used for identifier generation for an
  205. instance variable which is annotated by :ref:`@Id <annref_id>`. This
  206. annotation is optional and only has meaning when used in
  207. conjunction with @Id.
  208. If this annotation is not specified with @Id the NONE strategy is
  209. used as default.
  210. Required attributes:
  211. - **strategy**: Set the name of the identifier generation strategy.
  212. Valid values are AUTO, SEQUENCE, TABLE, IDENTITY, UUID, CUSTOM and NONE.
  213. Example:
  214. .. code-block:: php
  215. <?php
  216. /**
  217. * @Id
  218. * @Column(type="integer")
  219. * @GeneratedValue(strategy="IDENTITY")
  220. */
  221. protected $id = null;
  222. .. _annref_haslifecyclecallbacks:
  223. @HasLifecycleCallbacks
  224. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  225. Annotation which has to be set on the entity-class PHP DocBlock to
  226. notify Doctrine that this entity has entity life-cycle callback
  227. annotations set on at least one of its methods. Using @PostLoad,
  228. @PrePersist, @PostPersist, @PreRemove, @PostRemove, @PreUpdate or
  229. @PostUpdate without this marker annotation will make Doctrine
  230. ignore the callbacks.
  231. Example:
  232. .. code-block:: php
  233. <?php
  234. /**
  235. * @Entity
  236. * @HasLifecycleCallbacks
  237. */
  238. class User
  239. {
  240. /**
  241. * @PostPersist
  242. */
  243. public function sendOptinMail() {}
  244. }
  245. .. _annref_index:
  246. @Index
  247. ~~~~~~~
  248. Annotation is used inside the :ref:`@Table <annref_table>` annotation on
  249. the entity-class level. It allows to hint the SchemaTool to
  250. generate a database index on the specified table columns. It only
  251. has meaning in the SchemaTool schema generation context.
  252. Required attributes:
  253. - **name**: Name of the Index
  254. - **columns**: Array of columns.
  255. Example:
  256. .. code-block:: php
  257. <?php
  258. /**
  259. * @Entity
  260. * @Table(name="ecommerce_products",indexes={@Index(name="search_idx", columns={"name", "email"})})
  261. */
  262. class ECommerceProduct
  263. {
  264. }
  265. .. _annref_id:
  266. @Id
  267. ~~~~~~~
  268. The annotated instance variable will be marked as entity
  269. identifier, the primary key in the database. This annotation is a
  270. marker only and has no required or optional attributes. For
  271. entities that have multiple identifier columns each column has to
  272. be marked with @Id.
  273. Example:
  274. .. code-block:: php
  275. <?php
  276. /**
  277. * @Id
  278. * @Column(type="integer")
  279. */
  280. protected $id = null;
  281. .. _annref_inheritancetype:
  282. @InheritanceType
  283. ~~~~~~~~~~~~~~~~~~~~~
  284. In an inheritance hierarchy you have to use this annotation on the
  285. topmost/super class to define which strategy should be used for
  286. inheritance. Currently Single Table and Class Table Inheritance are
  287. supported.
  288. This annotation has always been used in conjunction with the
  289. :ref:`@DiscriminatorMap <annref_discriminatormap>` and
  290. :ref:`@DiscriminatorColumn <annref_discriminatorcolumn>` annotations.
  291. Examples:
  292. .. code-block:: php
  293. <?php
  294. /**
  295. * @Entity
  296. * @InheritanceType("SINGLE_TABLE")
  297. * @DiscriminatorColumn(name="discr", type="string")
  298. * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
  299. */
  300. class Person
  301. {
  302. // ...
  303. }
  304. /**
  305. * @Entity
  306. * @InheritanceType("JOINED")
  307. * @DiscriminatorColumn(name="discr", type="string")
  308. * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
  309. */
  310. class Person
  311. {
  312. // ...
  313. }
  314. .. _annref_joincolumn:
  315. @JoinColumn
  316. ~~~~~~~~~~~~~~
  317. This annotation is used in the context of relations in
  318. :ref:`@ManyToOne <annref_manytoone>`, :ref:`@OneToOne <annref_onetoone>` fields
  319. and in the Context of :ref:`@JoinTable <annref_jointable>` nested inside
  320. a @ManyToMany. This annotation is not required. If its not
  321. specified the attributes *name* and *referencedColumnName* are
  322. inferred from the table and primary key names.
  323. Required attributes:
  324. - **name**: Column name that holds the foreign key identifier for
  325. this relation. In the context of @JoinTable it specifies the column
  326. name in the join table.
  327. - **referencedColumnName**: Name of the primary key identifier that
  328. is used for joining of this relation.
  329. Optional attributes:
  330. - **unique**: Determines if this relation exclusive between the
  331. affected entities and should be enforced so on the database
  332. constraint level. Defaults to false.
  333. - **nullable**: Determine if the related entity is required, or if
  334. null is an allowed state for the relation. Defaults to true.
  335. - **onDelete**: Cascade Action (Database-level)
  336. - **columnDefinition**: DDL SQL snippet that starts after the column
  337. name and specifies the complete (non-portable!) column definition.
  338. This attribute allows to make use of advanced RMDBS features. Using
  339. this attribute on @JoinColumn is necessary if you need slightly
  340. different column definitions for joining columns, for example
  341. regarding NULL/NOT NULL defaults. However by default a
  342. "columnDefinition" attribute on :ref:`@Column <annref_column>` also sets
  343. the related @JoinColumn's columnDefinition. This is necessary to
  344. make foreign keys work.
  345. Example:
  346. .. code-block:: php
  347. <?php
  348. /**
  349. * @OneToOne(targetEntity="Customer")
  350. * @JoinColumn(name="customer_id", referencedColumnName="id")
  351. */
  352. private $customer;
  353. .. _annref_joincolumns:
  354. @JoinColumns
  355. ~~~~~~~~~~~~~~
  356. An array of @JoinColumn annotations for a
  357. :ref:`@ManyToOne <annref_manytoone>` or :ref:`@OneToOne <annref_onetoone>`
  358. relation with an entity that has multiple identifiers.
  359. .. _annref_jointable:
  360. @JoinTable
  361. ~~~~~~~~~~~~~~
  362. Using :ref:`@OneToMany <annref_onetomany>` or
  363. :ref:`@ManyToMany <annref_manytomany>` on the owning side of the relation
  364. requires to specify the @JoinTable annotation which describes the
  365. details of the database join table. If you do not specify
  366. @JoinTable on these relations reasonable mapping defaults apply
  367. using the affected table and the column names.
  368. Required attributes:
  369. - **name**: Database name of the join-table
  370. - **joinColumns**: An array of @JoinColumn annotations describing the
  371. join-relation between the owning entities table and the join table.
  372. - **inverseJoinColumns**: An array of @JoinColumn annotations
  373. describing the join-relation between the inverse entities table and
  374. the join table.
  375. Example:
  376. .. code-block:: php
  377. <?php
  378. /**
  379. * @ManyToMany(targetEntity="Phonenumber")
  380. * @JoinTable(name="users_phonenumbers",
  381. * joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
  382. * inverseJoinColumns={@JoinColumn(name="phonenumber_id", referencedColumnName="id", unique=true)}
  383. * )
  384. */
  385. public $phonenumbers;
  386. .. _annref_manytoone:
  387. @ManyToOne
  388. ~~~~~~~~~~~~~~
  389. Defines that the annotated instance variable holds a reference that
  390. describes a many-to-one relationship between two entities.
  391. Required attributes:
  392. - **targetEntity**: FQCN of the referenced target entity. Can be the
  393. unqualified class name if both classes are in the same namespace.
  394. *IMPORTANT:* No leading backslash!
  395. Optional attributes:
  396. - **cascade**: Cascade Option
  397. - **fetch**: One of LAZY or EAGER
  398. - inversedBy - The inversedBy attribute designates the field in
  399. the entity that is the inverse side of the relationship.
  400. Example:
  401. .. code-block:: php
  402. <?php
  403. /**
  404. * @ManyToOne(targetEntity="Cart", cascade={"all"}, fetch="EAGER")
  405. */
  406. private $cart;
  407. .. _annref_manytomany:
  408. @ManyToMany
  409. ~~~~~~~~~~~~~~
  410. Defines an instance variable holds a many-to-many relationship
  411. between two entities. :ref:`@JoinTable <annref_jointable>` is an
  412. additional, optional annotation that has reasonable default
  413. configuration values using the table and names of the two related
  414. entities.
  415. Required attributes:
  416. - **targetEntity**: FQCN of the referenced target entity. Can be the
  417. unqualified class name if both classes are in the same namespace.
  418. *IMPORTANT:* No leading backslash!
  419. Optional attributes:
  420. - **mappedBy**: This option specifies the property name on the
  421. targetEntity that is the owning side of this relation. Its a
  422. required attribute for the inverse side of a relationship.
  423. - **inversedBy**: The inversedBy attribute designates the field in the
  424. entity that is the inverse side of the relationship.
  425. - **cascade**: Cascade Option
  426. - **fetch**: One of LAZY, EXTRA_LAZY or EAGER
  427. - **indexBy**: Index the collection by a field on the target entity.
  428. .. note::
  429. For ManyToMany bidirectional relationships either side may
  430. be the owning side (the side that defines the @JoinTable and/or
  431. does not make use of the mappedBy attribute, thus using a default
  432. join table).
  433. Example:
  434. .. code-block:: php
  435. <?php
  436. /**
  437. * Owning Side
  438. *
  439. * @ManyToMany(targetEntity="Group", inversedBy="features")
  440. * @JoinTable(name="user_groups",
  441. * joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
  442. * inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
  443. * )
  444. */
  445. private $groups;
  446. /**
  447. * Inverse Side
  448. *
  449. * @ManyToMany(targetEntity="User", mappedBy="groups")
  450. */
  451. private $features;
  452. .. _annref_mappedsuperclass:
  453. @MappedSuperclass
  454. ~~~~~~~~~~~~~~~~~~~~~
  455. An mapped superclass is an abstract or concrete class that provides
  456. persistent entity state and mapping information for its subclasses,
  457. but which is not itself an entity. This annotation is specified on
  458. the Class docblock and has no additional attributes.
  459. The @MappedSuperclass annotation cannot be used in conjunction with
  460. @Entity. See the Inheritance Mapping section for
  461. :doc:`more details on the restrictions of mapped superclasses <inheritance-mapping>`.
  462. Optional attributes:
  463. - **repositoryClass**: (>= 2.2) Specifies the FQCN of a subclass of the EntityRepository.
  464. That will be inherited for all subclasses of that Mapped Superclass.
  465. Example:
  466. .. code-block:: php
  467. <?php
  468. /**
  469. * @MappedSuperclass
  470. */
  471. class MappedSuperclassBase
  472. {
  473. // ... fields and methods
  474. }
  475. /**
  476. * @Entity
  477. */
  478. class EntitySubClassFoo extends MappedSuperclassBase
  479. {
  480. // ... fields and methods
  481. }
  482. .. _annref_named_native_query:
  483. @NamedNativeQuery
  484. ~~~~~~~~~~~~~~~~~
  485. Is used to specify a native SQL named query.
  486. The NamedNativeQuery annotation can be applied to an entity or mapped superclass.
  487. Required attributes:
  488. - **name**: The name used to refer to the query with the EntityManager methods that create query objects.
  489. - **query**: The SQL query string.
  490. Optional attributes:
  491. - **resultClass**: The class of the result.
  492. - **resultSetMapping**: The name of a SqlResultSetMapping, as defined in metadata.
  493. Example:
  494. .. code-block:: php
  495. <?php
  496. /**
  497. * @NamedNativeQueries({
  498. * @NamedNativeQuery(
  499. * name = "fetchJoinedAddress",
  500. * resultSetMapping= "mappingJoinedAddress",
  501. * query = "SELECT u.id, u.name, u.status, a.id AS a_id, a.country, a.zip, a.city FROM cms_users u INNER JOIN cms_addresses a ON u.id = a.user_id WHERE u.username = ?"
  502. * ),
  503. * })
  504. * @SqlResultSetMappings({
  505. * @SqlResultSetMapping(
  506. * name = "mappingJoinedAddress",
  507. * entities= {
  508. * @EntityResult(
  509. * entityClass = "__CLASS__",
  510. * fields = {
  511. * @FieldResult(name = "id"),
  512. * @FieldResult(name = "name"),
  513. * @FieldResult(name = "status"),
  514. * @FieldResult(name = "address.zip"),
  515. * @FieldResult(name = "address.city"),
  516. * @FieldResult(name = "address.country"),
  517. * @FieldResult(name = "address.id", column = "a_id"),
  518. * }
  519. * )
  520. * }
  521. * )
  522. * })
  523. */
  524. class User
  525. {
  526. /** @Id @Column(type="integer") @GeneratedValue */
  527. public $id;
  528. /** @Column(type="string", length=50, nullable=true) */
  529. public $status;
  530. /** @Column(type="string", length=255, unique=true) */
  531. public $username;
  532. /** @Column(type="string", length=255) */
  533. public $name;
  534. /** @OneToOne(targetEntity="Address") */
  535. public $address;
  536. // ....
  537. }
  538. .. _annref_onetoone:
  539. @OneToOne
  540. ~~~~~~~~~~~~~~
  541. The @OneToOne annotation works almost exactly as the
  542. :ref:`@ManyToOne <annref_manytoone>` with one additional option that can
  543. be specified. The configuration defaults for
  544. :ref:`@JoinColumn <annref_joincolumn>` using the target entity table and
  545. primary key column names apply here too.
  546. Required attributes:
  547. - **targetEntity**: FQCN of the referenced target entity. Can be the
  548. unqualified class name if both classes are in the same namespace.
  549. *IMPORTANT:* No leading backslash!
  550. Optional attributes:
  551. - **cascade**: Cascade Option
  552. - **fetch**: One of LAZY or EAGER
  553. - **orphanRemoval**: Boolean that specifies if orphans, inverse
  554. OneToOne entities that are not connected to any owning instance,
  555. should be removed by Doctrine. Defaults to false.
  556. - **inversedBy**: The inversedBy attribute designates the field in the
  557. entity that is the inverse side of the relationship.
  558. Example:
  559. .. code-block:: php
  560. <?php
  561. /**
  562. * @OneToOne(targetEntity="Customer")
  563. * @JoinColumn(name="customer_id", referencedColumnName="id")
  564. */
  565. private $customer;
  566. .. _annref_onetomany:
  567. @OneToMany
  568. ~~~~~~~~~~~~~~
  569. Required attributes:
  570. - **targetEntity**: FQCN of the referenced target entity. Can be the
  571. unqualified class name if both classes are in the same namespace.
  572. *IMPORTANT:* No leading backslash!
  573. Optional attributes:
  574. - **cascade**: Cascade Option
  575. - **orphanRemoval**: Boolean that specifies if orphans, inverse
  576. OneToOne entities that are not connected to any owning instance,
  577. should be removed by Doctrine. Defaults to false.
  578. - **mappedBy**: This option specifies the property name on the
  579. targetEntity that is the owning side of this relation. Its a
  580. required attribute for the inverse side of a relationship.
  581. - **fetch**: One of LAZY, EXTRA_LAZY or EAGER.
  582. - **indexBy**: Index the collection by a field on the target entity.
  583. Example:
  584. .. code-block:: php
  585. <?php
  586. /**
  587. * @OneToMany(targetEntity="Phonenumber", mappedBy="user", cascade={"persist", "remove", "merge"}, orphanRemoval=true)
  588. */
  589. public $phonenumbers;
  590. .. _annref_orderby:
  591. @OrderBy
  592. ~~~~~~~~~~~~~~
  593. Optional annotation that can be specified with a
  594. :ref:`@ManyToMany <annref_manytomany>` or :ref:`@OneToMany <annref_onetomany>`
  595. annotation to specify by which criteria the collection should be
  596. retrieved from the database by using an ORDER BY clause.
  597. This annotation requires a single non-attributed value with an DQL
  598. snippet:
  599. Example:
  600. .. code-block:: php
  601. <?php
  602. /**
  603. * @ManyToMany(targetEntity="Group")
  604. * @OrderBy({"name" = "ASC"})
  605. */
  606. private $groups;
  607. The DQL Snippet in OrderBy is only allowed to consist of
  608. unqualified, unquoted field names and of an optional ASC/DESC
  609. positional statement. Multiple Fields are separated by a comma (,).
  610. The referenced field names have to exist on the ``targetEntity``
  611. class of the ``@ManyToMany`` or ``@OneToMany`` annotation.
  612. .. _annref_postload:
  613. @PostLoad
  614. ~~~~~~~~~~~~~~
  615. Marks a method on the entity to be called as a @PostLoad event.
  616. Only works with @HasLifecycleCallbacks in the entity class PHP
  617. DocBlock.
  618. .. _annref_postpersist:
  619. @PostPersist
  620. ~~~~~~~~~~~~~~
  621. Marks a method on the entity to be called as a @PostPersist event.
  622. Only works with @HasLifecycleCallbacks in the entity class PHP
  623. DocBlock.
  624. .. _annref_postremove:
  625. @PostRemove
  626. ~~~~~~~~~~~~~~
  627. Marks a method on the entity to be called as a @PostRemove event.
  628. Only works with @HasLifecycleCallbacks in the entity class PHP
  629. DocBlock.
  630. .. _annref_postupdate:
  631. @PostUpdate
  632. ~~~~~~~~~~~~~~
  633. Marks a method on the entity to be called as a @PostUpdate event.
  634. Only works with @HasLifecycleCallbacks in the entity class PHP
  635. DocBlock.
  636. .. _annref_prepersist:
  637. @PrePersist
  638. ~~~~~~~~~~~~~~
  639. Marks a method on the entity to be called as a @PrePersist event.
  640. Only works with @HasLifecycleCallbacks in the entity class PHP
  641. DocBlock.
  642. .. _annref_preremove:
  643. @PreRemove
  644. ~~~~~~~~~~~~~~
  645. Marks a method on the entity to be called as a @PreRemove event.
  646. Only works with @HasLifecycleCallbacks in the entity class PHP
  647. DocBlock.
  648. .. _annref_preupdate:
  649. @PreUpdate
  650. ~~~~~~~~~~~~~~
  651. Marks a method on the entity to be called as a @PreUpdate event.
  652. Only works with @HasLifecycleCallbacks in the entity class PHP
  653. DocBlock.
  654. .. _annref_sequencegenerator:
  655. @SequenceGenerator
  656. ~~~~~~~~~~~~~~~~~~~~~
  657. For the use with @generatedValue(strategy="SEQUENCE") this
  658. annotation allows to specify details about the sequence, such as
  659. the increment size and initial values of the sequence.
  660. Required attributes:
  661. - **sequenceName**: Name of the sequence
  662. Optional attributes:
  663. - **allocationSize**: Increment the sequence by the allocation size
  664. when its fetched. A value larger than 1 allows to optimize for
  665. scenarios where you create more than one new entity per request.
  666. Defaults to 10
  667. - **initialValue**: Where does the sequence start, defaults to 1.
  668. Example:
  669. .. code-block:: php
  670. <?php
  671. /**
  672. * @Id
  673. * @GeneratedValue(strategy="SEQUENCE")
  674. * @Column(type="integer")
  675. * @SequenceGenerator(sequenceName="tablename_seq", initialValue=1, allocationSize=100)
  676. */
  677. protected $id = null;
  678. .. _annref_sql_resultset_mapping:
  679. @SqlResultSetMapping
  680. ~~~~~~~~~~~~~~~~~~~~
  681. The SqlResultSetMapping annotation is used to specify the mapping of the result of a native SQL query.
  682. The SqlResultSetMapping annotation can be applied to an entity or mapped superclass.
  683. Required attributes:
  684. - **name**: The name given to the result set mapping, and used to refer to it in the methods of the Query API.
  685. Optional attributes:
  686. - **entities**: Array of @EntityResult, Specifies the result set mapping to entities.
  687. - **columns**: Array of @ColumnResult, Specifies the result set mapping to scalar values.
  688. Example:
  689. .. code-block:: php
  690. <?php
  691. /**
  692. * @NamedNativeQueries({
  693. * @NamedNativeQuery(
  694. * name = "fetchUserPhonenumberCount",
  695. * resultSetMapping= "mappingUserPhonenumberCount",
  696. * query = "SELECT id, name, status, COUNT(phonenumber) AS numphones FROM cms_users INNER JOIN cms_phonenumbers ON id = user_id WHERE username IN (?) GROUP BY id, name, status, username ORDER BY username"
  697. * ),
  698. * @NamedNativeQuery(
  699. * name = "fetchMultipleJoinsEntityResults",
  700. * resultSetMapping= "mappingMultipleJoinsEntityResults",
  701. * query = "SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM cms_users u INNER JOIN cms_addresses a ON u.id = a.user_id INNER JOIN cms_phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username"
  702. * ),
  703. * })
  704. * @SqlResultSetMappings({
  705. * @SqlResultSetMapping(
  706. * name = "mappingUserPhonenumberCount",
  707. * entities= {
  708. * @EntityResult(
  709. * entityClass = "User",
  710. * fields = {
  711. * @FieldResult(name = "id"),
  712. * @FieldResult(name = "name"),
  713. * @FieldResult(name = "status"),
  714. * }
  715. * )
  716. * },
  717. * columns = {
  718. * @ColumnResult("numphones")
  719. * }
  720. * ),
  721. * @SqlResultSetMapping(
  722. * name = "mappingMultipleJoinsEntityResults",
  723. * entities= {
  724. * @EntityResult(
  725. * entityClass = "__CLASS__",
  726. * fields = {
  727. * @FieldResult(name = "id", column="u_id"),
  728. * @FieldResult(name = "name", column="u_name"),
  729. * @FieldResult(name = "status", column="u_status"),
  730. * }
  731. * ),
  732. * @EntityResult(
  733. * entityClass = "Address",
  734. * fields = {
  735. * @FieldResult(name = "id", column="a_id"),
  736. * @FieldResult(name = "zip", column="a_zip"),
  737. * @FieldResult(name = "country", column="a_country"),
  738. * }
  739. * )
  740. * },
  741. * columns = {
  742. * @ColumnResult("numphones")
  743. * }
  744. * )
  745. *})
  746. */
  747. class User
  748. {
  749. /** @Id @Column(type="integer") @GeneratedValue */
  750. public $id;
  751. /** @Column(type="string", length=50, nullable=true) */
  752. public $status;
  753. /** @Column(type="string", length=255, unique=true) */
  754. public $username;
  755. /** @Column(type="string", length=255) */
  756. public $name;
  757. /** @OneToMany(targetEntity="Phonenumber") */
  758. public $phonenumbers;
  759. /** @OneToOne(targetEntity="Address") */
  760. public $address;
  761. // ....
  762. }
  763. .. _annref_table:
  764. @Table
  765. ~~~~~~~
  766. Annotation describes the table an entity is persisted in. It is
  767. placed on the entity-class PHP DocBlock and is optional. If it is
  768. not specified the table name will default to the entities
  769. unqualified classname.
  770. Required attributes:
  771. - **name**: Name of the table
  772. Optional attributes:
  773. - **indexes**: Array of @Index annotations
  774. - **uniqueConstraints**: Array of @UniqueConstraint annotations.
  775. Example:
  776. .. code-block:: php
  777. <?php
  778. /**
  779. * @Entity
  780. * @Table(name="user",
  781. * uniqueConstraints={@UniqueConstraint(name="user_unique",columns={"username"})},
  782. * indexes={@Index(name="user_idx", columns={"email"})}
  783. * )
  784. */
  785. class User { }
  786. .. _annref_uniqueconstraint:
  787. @UniqueConstraint
  788. ~~~~~~~~~~~~~~~~~~~~~
  789. Annotation is used inside the :ref:`@Table <annref_table>` annotation on
  790. the entity-class level. It allows to hint the SchemaTool to
  791. generate a database unique constraint on the specified table
  792. columns. It only has meaning in the SchemaTool schema generation
  793. context.
  794. Required attributes:
  795. - **name**: Name of the Index
  796. - **columns**: Array of columns.
  797. Example:
  798. .. code-block:: php
  799. <?php
  800. /**
  801. * @Entity
  802. * @Table(name="ecommerce_products",uniqueConstraints={@UniqueConstraint(name="search_idx", columns={"name", "email"})})
  803. */
  804. class ECommerceProduct
  805. {
  806. }
  807. .. _annref_version:
  808. @Version
  809. ~~~~~~~~~~~~~~
  810. Marker annotation that defines a specified column as version
  811. attribute used in an optimistic locking scenario. It only works on
  812. :ref:`@Column <annref_column>` annotations that have the type integer or
  813. datetime. Combining @Version with :ref:`@Id <annref_id>` is not supported.
  814. Example:
  815. .. code-block:: php
  816. <?php
  817. /**
  818. * @Column(type="integer")
  819. * @Version
  820. */
  821. protected $version;