Skip to content
This repository
Newer
Older
100644 88 lines (69 sloc) 3.603 kb
a5a0dfa9 » beberlei
2010-11-01 Converted ORM Docs into ReST
1 Partial Objects
2 ===============
3
1bfeaf3e » beberlei
2010-11-01 Initial conversion from Markdown to ReST - Finalized Cookbook
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
a5a0dfa9 » beberlei
2010-11-01 Converted ORM Docs into ReST
10 .. note::
11
12 The partial object problem in general does not apply to
1bfeaf3e » beberlei
2010-11-01 Initial conversion from Markdown to ReST - Finalized Cookbook
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
6d4337fc » beberlei
2011-10-15 More details on partial objects
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
1bfeaf3e » beberlei
2010-11-01 Initial conversion from Markdown to ReST - Finalized Cookbook
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
46983465 » beberlei
2010-12-03 Finialized ReST doc changes, merged changes from latest Markdown docs.
66 .. code-block:: php
1bfeaf3e » beberlei
2010-11-01 Initial conversion from Markdown to ReST - Finalized Cookbook
67
68 <?php
69 $q = $em->createQuery("select partial u.{id,name} from MyApp\Domain\User u");
70
6d4337fc » beberlei
2011-10-15 More details on partial objects
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
1bfeaf3e » beberlei
2010-11-01 Initial conversion from Markdown to ReST - Finalized Cookbook
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.