limitations-and-known-issues.rst 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189
  1. Limitations and Known Issues
  2. ============================
  3. We try to make using Doctrine2 a very pleasant experience.
  4. Therefore we think it is very important to be honest about the
  5. current limitations to our users. Much like every other piece of
  6. software Doctrine2 is not perfect and far from feature complete.
  7. This section should give you an overview of current limitations of
  8. Doctrine 2 as well as critical known issues that you should know
  9. about.
  10. Current Limitations
  11. -------------------
  12. There is a set of limitations that exist currently which might be
  13. solved in the future. Any of this limitations now stated has at
  14. least one ticket in the Tracker and is discussed for future
  15. releases.
  16. Join-Columns with non-primary keys
  17. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. It is not possible to use join columns pointing to non-primary keys. Doctrine will think these are the primary
  19. keys and create lazy-loading proxies with the data, which can lead to unexpected results. Doctrine can for performance
  20. reasons not validate the correctness of this settings at runtime but only through the Validate Schema command.
  21. Mapping Arrays to a Join Table
  22. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23. Related to the previous limitation with "Foreign Keys as
  24. Identifier" you might be interested in mapping the same table
  25. structure as given above to an array. However this is not yet
  26. possible either. See the following example:
  27. .. code-block:: sql
  28. CREATE TABLE product (
  29. id INTEGER,
  30. name VARCHAR,
  31. PRIMARY KEY(id)
  32. );
  33. CREATE TABLE product_attributes (
  34. product_id INTEGER,
  35. attribute_name VARCHAR,
  36. attribute_value VARCHAR,
  37. PRIMARY KEY (product_id, attribute_name)
  38. );
  39. This schema should be mapped to a Product Entity as follows:
  40. .. code-block:: php
  41. class Product
  42. {
  43. private $id;
  44. private $name;
  45. private $attributes = array();
  46. }
  47. Where the ``attribute_name`` column contains the key and
  48. ``attribute_value`` contains the value of each array element in
  49. ``$attributes``.
  50. The feature request for persistence of primitive value arrays
  51. `is described in the DDC-298 ticket <http://www.doctrine-project.org/jira/browse/DDC-298>`_.
  52. Value Objects
  53. ~~~~~~~~~~~~~
  54. There is currently no native support value objects in Doctrine
  55. other than for ``DateTime`` instances or if you serialize the
  56. objects using ``serialize()/deserialize()`` which the DBAL Type
  57. "object" supports.
  58. The feature request for full value-object support
  59. `is described in the DDC-93 ticket <http://www.doctrine-project.org/jira/browse/DDC-93>`_.
  60. Cascade Merge with Bi-directional Associations
  61. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  62. There are two bugs now that concern the use of cascade merge in combination with bi-directional associations.
  63. Make sure to study the behavior of cascade merge if you are using it:
  64. - `DDC-875 <http://www.doctrine-project.org/jira/browse/DDC-875>`_ Merge can sometimes add the same entity twice into a collection
  65. - `DDC-763 <http://www.doctrine-project.org/jira/browse/DDC-763>`_ Cascade merge on associated entities can insert too many rows through "Persistence by Reachability"
  66. Custom Persisters
  67. ~~~~~~~~~~~~~~~~~
  68. A Persister in Doctrine is an object that is responsible for the
  69. hydration and write operations of an entity against the database.
  70. Currently there is no way to overwrite the persister implementation
  71. for a given entity, however there are several use-cases that can
  72. benefit from custom persister implementations:
  73. - `Add Upsert Support <http://www.doctrine-project.org/jira/browse/DDC-668>`_
  74. - `Evaluate possible ways in which stored-procedures can be used <http://www.doctrine-project.org/jira/browse/DDC-445>`_
  75. - The previous Filter Rules Feature Request
  76. Persist Keys of Collections
  77. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78. PHP Arrays are ordered hash-maps and so should be the
  79. ``Doctrine\Common\Collections\Collection`` interface. We plan to
  80. evaluate a feature that optionally persists and hydrates the keys
  81. of a Collection instance.
  82. `Ticket DDC-213 <http://www.doctrine-project.org/jira/browse/DDC-213>`_
  83. Mapping many tables to one entity
  84. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  85. It is not possible to map several equally looking tables onto one
  86. entity. For example if you have a production and an archive table
  87. of a certain business concept then you cannot have both tables map
  88. to the same entity.
  89. Behaviors
  90. ~~~~~~~~~
  91. Doctrine 2 will **never** include a behavior system like Doctrine 1
  92. in the core library. We don't think behaviors add more value than
  93. they cost pain and debugging hell. Please see the many different
  94. blog posts we have written on this topics:
  95. - `Doctrine2 "Behaviors" in a Nutshell <http://www.doctrine-project.org/blog/doctrine2-behaviours-nutshell>`_
  96. - `A re-usable Versionable behavior for Doctrine2 <http://www.doctrine-project.org/blog/doctrine2-versionable>`_
  97. - `Write your own ORM on top of Doctrine2 <http://www.doctrine-project.org/blog/your-own-orm-doctrine2>`_
  98. - `Doctrine 2 Behavioral Extensions <http://www.doctrine-project.org/blog/doctrine2-behavioral-extensions>`_
  99. - `Doctrator <https://github.com/pablodip/doctrator`>_
  100. Doctrine 2 has enough hooks and extension points so that **you** can
  101. add whatever you want on top of it. None of this will ever become
  102. core functionality of Doctrine2 however, you will have to rely on
  103. third party extensions for magical behaviors.
  104. Nested Set
  105. ~~~~~~~~~~
  106. NestedSet was offered as a behavior in Doctrine 1 and will not be
  107. included in the core of Doctrine 2. However there are already two
  108. extensions out there that offer support for Nested Set with
  109. Doctrine 2:
  110. - `Doctrine2 Hierarchical-Structural Behavior <http://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
  111. - `Doctrine2 NestedSet <http://github.com/blt04/doctrine2-nestedset>`_
  112. Known Issues
  113. ------------
  114. The Known Issues section describes critical/blocker bugs and other
  115. issues that are either complicated to fix, not fixable due to
  116. backwards compatibility issues or where no simple fix exists (yet).
  117. We don't plan to add every bug in the tracker there, just those
  118. issues that can potentially cause nightmares or pain of any sort.
  119. See the Open Bugs on Jira for more details on `bugs, improvement and feature
  120. requests
  121. <http://www.doctrine-project.org/jira/secure/IssueNavigator.jspa?reset=true&mode=hide&pid=10032&resolution=-1&sorter/field=updated&sorter/order=DESC>`_.
  122. Identifier Quoting and Legacy Databases
  123. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  124. For compatibility reasons between all the supported vendors and
  125. edge case problems Doctrine 2 does **NOT** do automatic identifier
  126. quoting. This can lead to problems when trying to get
  127. legacy-databases to work with Doctrine 2.
  128. - You can quote column-names as described in the
  129. :doc:`Basic-Mapping <basic-mapping>` section.
  130. - You cannot quote join column names.
  131. - You cannot use non [a-zA-Z0-9\_]+ characters, they will break
  132. several SQL statements.
  133. Having problems with these kind of column names? Many databases
  134. support all CRUD operations on views that semantically map to
  135. certain tables. You can create views for all your problematic
  136. tables and column names to avoid the legacy quoting nightmare.
  137. Microsoft SQL Server and Doctrine "datetime"
  138. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  139. Doctrine assumes that you use ``DateTime2`` data-types. If your legacy database contains DateTime
  140. datatypes then you have to add your own data-type (see Basic Mapping for an example).