partial-objects.rst 3.5 KB

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