Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 91 lines (69 sloc) 3.603 kb
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
1 Partial Objects
2 ===============
3
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
4 A partial object is an object whose state is not fully initialized
5 after being reconstituted from the database and that is
6 disconnected from the rest of its data. The following section will
7 describe why partial objects are problematic and what the approach
8 of Doctrine2 to this problem is.
9
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
10 .. note::
11
12 The partial object problem in general does not apply to
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
13 methods or queries where you do not retrieve the query result as
14 objects. Examples are: ``Query#getArrayResult()``,
15 ``Query#getScalarResult()``, ``Query#getSingleScalarResult()``,
16 etc.
17
6d4337f Benjamin Eberlei More details on partial objects
beberlei authored
18 .. warning::
19
20 Use of partial objects is tricky. Fields that are not retrieved
21 from the database will not be updated by the UnitOfWork even if they
22 get changed in your objects. You can only promote a partial object
23 to a fully-loaded object by calling ``EntityManager#refresh()``
24 or a DQL query with the refresh flag.
25
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
26
27 What is the problem?
28 --------------------
29
30 In short, partial objects are problematic because they are usually
31 objects with broken invariants. As such, code that uses these
32 partial objects tends to be very fragile and either needs to "know"
33 which fields or methods can be safely accessed or add checks around
34 every field access or method invocation. The same holds true for
35 the internals, i.e. the method implementations, of such objects.
36 You usually simply assume the state you need in the method is
37 available, after all you properly constructed this object before
38 you pushed it into the database, right? These blind assumptions can
39 quickly lead to null reference errors when working with such
40 partial objects.
41
42 It gets worse with the scenario of an optional association (0..1 to
43 1). When the associated field is NULL, you don't know whether this
44 object does not have an associated object or whether it was simply
45 not loaded when the owning object was loaded from the database.
46
47 These are reasons why many ORMs do not allow partial objects at all
48 and instead you always have to load an object with all its fields
49 (associations being proxied). One secure way to allow partial
50 objects is if the programming language/platform allows the ORM tool
51 to hook deeply into the object and instrument it in such a way that
52 individual fields (not only associations) can be loaded lazily on
53 first access. This is possible in Java, for example, through
54 bytecode instrumentation. In PHP though this is not possible, so
55 there is no way to have "secure" partial objects in an ORM with
56 transparent persistence.
57
58 Doctrine, by default, does not allow partial objects. That means,
59 any query that only selects partial object data and wants to
60 retrieve the result as objects (i.e. ``Query#getResult()``) will
61 raise an exception telling you that partial objects are dangerous.
62 If you want to force a query to return you partial objects,
63 possibly as a performance tweak, you can use the ``partial``
64 keyword as follows:
65
4698346 Benjamin Eberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
66 .. code-block:: php
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
67
68 <?php
69 $q = $em->createQuery("select partial u.{id,name} from MyApp\Domain\User u");
70
6d4337f Benjamin Eberlei More details on partial objects
beberlei authored
71 You can also get a partial reference instead of a proxy reference by
72 calling:
73
74 .. code-block:: php
75
76 <?php
77 $reference = $em->getPartialReference('MyApp\Domain\User', 1);
78
79 Partial references are objects with only the identifiers set as they
80 are passed to the second argument of the ``getPartialReference()`` method.
81 All other fields are null.
82
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
83 When should I force partial objects?
84 ------------------------------------
85
86 Mainly for optimization purposes, but be careful of premature
87 optimization as partial objects lead to potentially more fragile
88 code.
89
90
Something went wrong with that request. Please try again.