Skip to content

HTTPS clone URL

Subversion checkout URL

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