faq.rst 9.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  1. Frequently Asked Questions
  2. ==========================
  3. .. note::
  4. This FAQ is a work in progress. We will add lots of questions and not answer them right away just to remember
  5. what is often asked. If you stumble across an unanswered question please write a mail to the mailing-list or
  6. join the #doctrine channel on Freenode IRC.
  7. Database Schema
  8. ---------------
  9. How do I set the charset and collation for MySQL tables?
  10. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  11. You can't set these values inside the annotations, yml or xml mapping files. To make a database
  12. work with the default charset and collation you should configure MySQL to use it as default charset,
  13. or create the database with charset and collation details. This way they get inherited to all newly
  14. created database tables and columns.
  15. Entity Classes
  16. --------------
  17. I access a variable and its null, what is wrong?
  18. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  19. If this variable is a public variable then you are violating one of the criteria for entities.
  20. All properties have to be protected or private for the proxy object pattern to work.
  21. How can I add default values to a column?
  22. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23. Doctrine does not support to set the default values in columns through the "DEFAULT" keyword in SQL.
  24. This is not necessary however, you can just use your class properties as default values. These are then used
  25. upon insert:
  26. .. code-block:: php
  27. class User
  28. {
  29. const STATUS_DISABLED = 0;
  30. const STATUS_ENABLED = 1;
  31. private $algorithm = "sha1";
  32. private $status = self:STATUS_DISABLED;
  33. }
  34. .
  35. Mapping
  36. -------
  37. Why do I get exceptions about unique constraint failures during ``$em->flush()``?
  38. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39. Doctrine does not check if you are re-adding entities with a primary key that already exists
  40. or adding entities to a collection twice. You have to check for both conditions yourself
  41. in the code before calling ``$em->flush()`` if you know that unique constraint failures
  42. can occur.
  43. In `Symfony2 <http://www.symfony.com>`_ for example there is a Unique Entity Validator
  44. to achieve this task.
  45. For collections you can check with ``$collection->contains($entity)`` if an entity is already
  46. part of this collection. For a FETCH=LAZY collection this will initialize the collection,
  47. however for FETCH=EXTRA_LAZY this method will use SQL to determine if this entity is already
  48. part of the collection.
  49. Associations
  50. ------------
  51. What is wrong when I get an InvalidArgumentException "A new entity was found through the relationship.."?
  52. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53. This exception is thrown during ``EntityManager#flush()`` when there exists an object in the identity map
  54. that contains a reference to an object that Doctrine does not know about. Say for example you grab
  55. a "User"-entity from the database with a specific id and set a completely new object into one of the associations
  56. of the User object. If you then call ``EntityManager#flush()`` without letting Doctrine know about
  57. this new object using ``EntityManager#persist($newObject)`` you will see this exception.
  58. You can solve this exception by:
  59. * Calling ``EntityManager#persist($newObject)`` on the new object
  60. * Using cascade=persist on the association that contains the new object
  61. How can I filter an association?
  62. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63. Natively you can't filter associations in 2.0 and 2.1. You should use DQL queries to query for the filtered set of entities.
  64. I call clear() on a One-To-Many collection but the entities are not deleted
  65. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  66. This is an expected behavior that has to do with the inverse/owning side handling of Doctrine.
  67. By definition a One-To-Many association is on the inverse side, that means changes to it
  68. will not be recognized by Doctrine.
  69. If you want to perform the equivalent of the clear operation you have to iterate the
  70. collection and set the owning side many-to-one reference to NULL as well to detach all entities
  71. from the collection. This will trigger the appropriate UPDATE statements on the database.
  72. How can I add columns to a many-to-many table?
  73. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74. The many-to-many association is only supporting foreign keys in the table definition
  75. To work with many-to-many tables containing extra columns you have to use the
  76. foreign keys as primary keys feature of Doctrine introduced in version 2.1.
  77. See :doc:`the tutorial on composite primary keys for more information<../tutorials/composite-primary-keys>`.
  78. How can i paginate fetch-joined collections?
  79. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80. If you are issuing a DQL statement that fetches a collection as well you cannot easily iterate
  81. over this collection using a LIMIT statement (or vendor equivalent).
  82. Doctrine does not offer a solution for this out of the box but there are several extensions
  83. that do:
  84. * `DoctrineExtensions <http://github.com/beberlei/DoctrineExtensions>`_
  85. * `Pagerfanta <http://github.com/whiteoctober/pagerfanta>`_
  86. Why does pagination not work correctly with fetch joins?
  87. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88. Pagination in Doctrine uses a LIMIT clause (or vendor equivalent) to restrict the results.
  89. However when fetch-joining this is not returning the correct number of results since joining
  90. with a one-to-many or many-to-many association multiplies the number of rows by the number
  91. of associated entities.
  92. See the previous question for a solution to this task.
  93. Inheritance
  94. -----------
  95. Can I use Inheritance with Doctrine 2?
  96. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  97. Yes, you can use Single- or Joined-Table Inheritance in Doctrine 2.
  98. See the documentation chapter on :doc:`inheritance mapping <inheritance-mapping>` for
  99. the details.
  100. Why does Doctrine not create proxy objects for my inheritance hierarchy?
  101. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  102. If you set a many-to-one or one-to-one association target-entity to any parent class of
  103. an inheritance hierarchy Doctrine does not know what PHP class the foreign is actually of.
  104. To find this out it has to execute a SQL query to look this information up in the database.
  105. EntityGenerator
  106. ---------------
  107. Why does the EntityGenerator not do X?
  108. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  109. The EntityGenerator is not a full fledged code-generator that solves all tasks. Code-Generation
  110. is not a first-class priority in Doctrine 2 anymore (compared to Doctrine 1). The EntityGenerator
  111. is supposed to kick-start you, but not towards 100%.
  112. Why does the EntityGenerator not generate inheritance correctly?
  113. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  114. Just from the details of the discriminator map the EntityGenerator cannot guess the inheritance hierarchy.
  115. This is why the generation of inherited entities does not fully work. You have to adjust some additional
  116. code to get this one working correctly.
  117. Performance
  118. -----------
  119. Why is an extra SQL query executed every time I fetch an entity with a one-to-one relation?
  120. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  121. If Doctrine detects that you are fetching an inverse side one-to-one association
  122. it has to execute an additional query to load this object, because it cannot know
  123. if there is no such object (setting null) or if it should set a proxy and which id this proxy has.
  124. To solve this problem currently a query has to be executed to find out this information.
  125. Doctrine Query Language
  126. -----------------------
  127. What is DQL?
  128. ~~~~~~~~~~~~
  129. DQL stands for Doctrine Query Language, a query language that very much looks like SQL
  130. but has some important benefits when using Doctrine:
  131. - It uses class names and fields instead of tables and columns, separating concerns between backend and your object model.
  132. - It utilizes the metadata defined to offer a range of shortcuts when writing. For example you do not have to specify the ON clause of joins, since Doctrine already knows about them.
  133. - It adds some functionality that is related to object management and transforms them into SQL.
  134. It also has some drawbacks of course:
  135. - The syntax is slightly different to SQL so you have to learn and remember the differences.
  136. - To be vendor independent it can only implement a subset of all the existing SQL dialects. Vendor specific functionality and optimizations cannot be used through DQL unless implemented by you explicitly.
  137. - For some DQL constructs subselects are used which are known to be slow in MySQL.
  138. Can I sort by a function (for example ORDER BY RAND()) in DQL?
  139. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  140. No, it is not supported to sort by function in DQL. If you need this functionality you should either
  141. use a native-query or come up with another solution. As a side note: Sorting with ORDER BY RAND() is painfully slow
  142. starting with 1000 rows.
  143. A Query fails, how can I debug it?
  144. ----------------------------------
  145. First, if you are using the QueryBuilder you can use
  146. ``$queryBuilder->getDQL()`` to get the DQL string of this query. The
  147. corresponding SQL you can get from the Query instance by calling
  148. ``$query->getSQL()``.
  149. .. code-block:: php
  150. <?php
  151. $dql = "SELECT u FROM User u";
  152. $query = $entityManager->createQuery($dql);
  153. var_dump($query->getSQL());
  154. $qb = $entityManager->createQueryBuilder();
  155. $qb->select('u')->from('User', 'u');
  156. var_dump($qb->getDQL());