architecture.rst 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197
  1. Architecture
  2. ============
  3. This chapter gives an overview of the overall architecture,
  4. terminology and constraints of Doctrine 2. It is recommended to
  5. read this chapter carefully.
  6. Using an Object-Relational Mapper
  7. ---------------------------------
  8. As the term ORM already hints at, Doctrine 2 aims to simplify the
  9. translation between database rows and the PHP object model. The
  10. primary use case for Doctrine are therefore applications that
  11. utilize the Object-Oriented Programming Paradigm. For applications
  12. that not primarily work with objects Doctrine 2 is not suited very
  13. well.
  14. Requirements
  15. ------------
  16. Doctrine 2 requires a minimum of PHP 5.3.0. For greatly improved
  17. performance it is also recommended that you use APC with PHP.
  18. Doctrine 2 Packages
  19. -------------------
  20. Doctrine 2 is divided into three main packages.
  21. - Common
  22. - DBAL (includes Common)
  23. - ORM (includes DBAL+Common)
  24. This manual mainly covers the ORM package, sometimes touching parts
  25. of the underlying DBAL and Common packages. The Doctrine code base
  26. is split in to these packages for a few reasons and they are to...
  27. - ...make things more maintainable and decoupled
  28. - ...allow you to use the code in Doctrine Common without the ORM
  29. or DBAL
  30. - ...allow you to use the DBAL without the ORM
  31. The Common Package
  32. ~~~~~~~~~~~~~~~~~~
  33. The Common package contains highly reusable components that have no
  34. dependencies beyond the package itself (and PHP, of course). The
  35. root namespace of the Common package is ``Doctrine\Common``.
  36. The DBAL Package
  37. ~~~~~~~~~~~~~~~~
  38. The DBAL package contains an enhanced database abstraction layer on
  39. top of PDO but is not strongly bound to PDO. The purpose of this
  40. layer is to provide a single API that bridges most of the
  41. differences between the different RDBMS vendors. The root namespace
  42. of the DBAL package is ``Doctrine\DBAL``.
  43. The ORM Package
  44. ~~~~~~~~~~~~~~~
  45. The ORM package contains the object-relational mapping toolkit that
  46. provides transparent relational persistence for plain PHP objects.
  47. The root namespace of the ORM package is ``Doctrine\ORM``.
  48. Terminology
  49. -----------
  50. Entities
  51. ~~~~~~~~
  52. An entity is a lightweight, persistent domain object. An entity can
  53. be any regular PHP class observing the following restrictions:
  54. - An entity class must not be final or contain final methods.
  55. - All persistent properties/field of any entity class should
  56. always be private or protected, otherwise lazy-loading might not
  57. work as expected. In case you serialize entities (for example Session)
  58. properties should be protected (See Serialize section below).
  59. - An entity class must not implement ``__clone`` or
  60. :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
  61. - An entity class must not implement ``__wakeup`` or
  62. :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
  63. Also consider implementing
  64. `Serializable <http://de3.php.net/manual/en/class.serializable.php>`_
  65. instead.
  66. - Any two entity classes in a class hierarchy that inherit
  67. directly or indirectly from one another must not have a mapped
  68. property with the same name. That is, if B inherits from A then B
  69. must not have a mapped field with the same name as an already
  70. mapped field that is inherited from A.
  71. - An entity cannot make use of func_get_args() to implement variable parameters.
  72. Generated proxies do not support this for performance reasons and your code might
  73. actually fail to work when violating this restriction.
  74. Entities support inheritance, polymorphic associations, and
  75. polymorphic queries. Both abstract and concrete classes can be
  76. entities. Entities may extend non-entity classes as well as entity
  77. classes, and non-entity classes may extend entity classes.
  78. .. note::
  79. The constructor of an entity is only ever invoked when
  80. *you* construct a new instance with the *new* keyword. Doctrine
  81. never calls entity constructors, thus you are free to use them as
  82. you wish and even have it require arguments of any type.
  83. Entity states
  84. ~~~~~~~~~~~~~
  85. An entity instance can be characterized as being NEW, MANAGED,
  86. DETACHED or REMOVED.
  87. - A NEW entity instance has no persistent identity, and is not yet
  88. associated with an EntityManager and a UnitOfWork (i.e. those just
  89. created with the "new" operator).
  90. - A MANAGED entity instance is an instance with a persistent
  91. identity that is associated with an EntityManager and whose
  92. persistence is thus managed.
  93. - A DETACHED entity instance is an instance with a persistent
  94. identity that is not (or no longer) associated with an
  95. EntityManager and a UnitOfWork.
  96. - A REMOVED entity instance is an instance with a persistent
  97. identity, associated with an EntityManager, that will be removed
  98. from the database upon transaction commit.
  99. .. _architecture_persistent_fields:
  100. Persistent fields
  101. ~~~~~~~~~~~~~~~~~
  102. The persistent state of an entity is represented by instance
  103. variables. An instance variable must be directly accessed only from
  104. within the methods of the entity by the entity instance itself.
  105. Instance variables must not be accessed by clients of the entity.
  106. The state of the entity is available to clients only through the
  107. entity’s methods, i.e. accessor methods (getter/setter methods) or
  108. other business methods.
  109. Collection-valued persistent fields and properties must be defined
  110. in terms of the ``Doctrine\Common\Collections\Collection``
  111. interface. The collection implementation type may be used by the
  112. application to initialize fields or properties before the entity is
  113. made persistent. Once the entity becomes managed (or detached),
  114. subsequent access must be through the interface type.
  115. Serializing entities
  116. ~~~~~~~~~~~~~~~~~~~~
  117. Serializing entities can be problematic and is not really
  118. recommended, at least not as long as an entity instance still holds
  119. references to proxy objects or is still managed by an
  120. EntityManager. If you intend to serialize (and unserialize) entity
  121. instances that still hold references to proxy objects you may run
  122. into problems with private properties because of technical
  123. limitations. Proxy objects implement ``__sleep`` and it is not
  124. possible for ``__sleep`` to return names of private properties in
  125. parent classes. On the other hand it is not a solution for proxy
  126. objects to implement ``Serializable`` because Serializable does not
  127. work well with any potential cyclic object references (at least we
  128. did not find a way yet, if you did, please contact us).
  129. The EntityManager
  130. ~~~~~~~~~~~~~~~~~
  131. The ``EntityManager`` class is a central access point to the ORM
  132. functionality provided by Doctrine 2. The ``EntityManager`` API is
  133. used to manage the persistence of your objects and to query for
  134. persistent objects.
  135. Transactional write-behind
  136. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  137. An ``EntityManager`` and the underlying ``UnitOfWork`` employ a
  138. strategy called "transactional write-behind" that delays the
  139. execution of SQL statements in order to execute them in the most
  140. efficient way and to execute them at the end of a transaction so
  141. that all write locks are quickly released. You should see Doctrine
  142. as a tool to synchronize your in-memory objects with the database
  143. in well defined units of work. Work with your objects and modify
  144. them as usual and when you're done call ``EntityManager#flush()``
  145. to make your changes persistent.
  146. The Unit of Work
  147. ~~~~~~~~~~~~~~~~
  148. Internally an ``EntityManager`` uses a ``UnitOfWork``, which is a
  149. typical implementation of the
  150. `Unit of Work pattern <http://martinfowler.com/eaaCatalog/unitOfWork.html>`_,
  151. to keep track of all the things that need to be done the next time
  152. ``flush`` is invoked. You usually do not directly interact with a
  153. ``UnitOfWork`` but with the ``EntityManager`` instead.