Skip to content

HTTPS clone URL

Subversion checkout URL

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