Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 672 lines (457 sloc) 30.472 kb
3d12920 @flack Add note about changed behaviour
flack authored
1 # Upgrade to 2.5
2
efa375a @Ocramius #1257 DDC-3300 DDC-3503 - providing upgrade notes for the breaking ch…
Ocramius authored
3 ## Minor BC BREAK: discriminator map must now include all non-transient classes
4
5 It is now required that you declare the root of an inheritance in the
6 discriminator map.
7
8 When declaring an inheritance map, it was previously possible to skip the root
9 of the inheritance in the discriminator map. This was actually a validation
10 mistake by Doctrine2 and led to problems when trying to persist instances of
11 that class.
12
13 If you don't plan to persist instances some classes in your inheritance, then
14 either:
15
16 - make those classes `abstract`
17 - map those classes as `MappedSuperclass`
18
efe9e3a @Ocramius #1209 DDC-3427 - documenting s/`EntityManager`/`EntityManagerInterfac…
Ocramius authored
19 ## Minor BC BREAK: ``EntityManagerInterface`` instead of ``EntityManager`` in type-hints
20
21 As of 2.5, classes requiring the ``EntityManager`` in any method signature will now require
22 an ``EntityManagerInterface`` instead.
23 If you are extending any of the following classes, then you need to check following
24 signatures:
25
26 - ``Doctrine\ORM\Tools\DebugUnitOfWorkListener#dumpIdentityMap(EntityManagerInterface $em)``
27 - ``Doctrine\ORM\Mapping\ClassMetadataFactory#setEntityManager(EntityManagerInterface $em)``
28
21437bb @guilhermeblanco Heavily simplified code on simple object hydrator. Code cleanup on co…
guilhermeblanco authored
29 ## Minor BC BREAK: Custom Hydrators API change
30
f52a512 @bakura10 Add UPGRADE note
bakura10 authored
31 As of 2.5, `AbstractHydrator` does not enforce the usage of cache as part of
21437bb @guilhermeblanco Heavily simplified code on simple object hydrator. Code cleanup on co…
guilhermeblanco authored
32 API, and now provides you a clean API for column information through the method
33 `hydrateColumnInfo($column)`.
f52a512 @bakura10 Add UPGRADE note
bakura10 authored
34 Cache variable being passed around by reference is no longer needed since
21437bb @guilhermeblanco Heavily simplified code on simple object hydrator. Code cleanup on co…
guilhermeblanco authored
35 Hydrators are per query instantiated since Doctrine 2.4.
36
1cd0b26 @guilhermeblanco DDC-3068 EntityManager clear() calls now follow cascade detach config…
guilhermeblanco authored
37 ## Minor BC BREAK: Entity based ``EntityManager#clear()`` calls follow cascade detach
38
f52a512 @bakura10 Add UPGRADE note
bakura10 authored
39 Whenever ``EntityManager#clear()`` method gets called with a given entity class
40 name, until 2.4, it was only detaching the specific requested entity.
41 As of 2.5, ``EntityManager`` will follow configured cascades, providing a better
1cd0b26 @guilhermeblanco DDC-3068 EntityManager clear() calls now follow cascade detach config…
guilhermeblanco authored
42 memory management since associations will be garbage collected, optimizing
43 resources consumption on long running jobs.
44
79ba8c6 @beberlei Add Changelog/Migration to 2.5 documentation chapter.
beberlei authored
45 ## BC BREAK: NamingStrategy interface changes
46
47 1. A new method ``embeddedFieldToColumnName($propertyName, $embeddedColumnName)``
20fb827 @schmittjoh make use of NamingStrategy for columns of embedded fields
schmittjoh authored
48
49 This method generates the column name for fields of embedded objects. If you implement your custom NamingStrategy, you
50 now also need to implement this new method.
51
79ba8c6 @beberlei Add Changelog/Migration to 2.5 documentation chapter.
beberlei authored
52 2. A change to method ``joinColumnName()`` to include the $className
53
3d12920 @flack Add note about changed behaviour
flack authored
54 ## Updates on entities scheduled for deletion are no longer processed
55
56 In Doctrine 2.4, if you modified properties of an entity scheduled for deletion, UnitOfWork would
57 produce an UPDATE statement to be executed right before the DELETE statement. The entity in question
58 was therefore present in ``UnitOfWork#entityUpdates``, which means that ``preUpdate`` and ``postUpdate``
59 listeners were (quite pointlessly) called. In ``preFlush`` listeners, it used to be possible to undo
60 the scheduled deletion for updated entities (by calling ``persist()`` if the entity was found in both
61 ``entityUpdates`` and ``entityDeletions``). This does not work any longer, because the entire changeset
62 calculation logic is optimized away.
63
a6c8ab8 @deeky666 make lock mode usage consistent
deeky666 authored
64 ## Minor BC BREAK: Default lock mode changed from LockMode::NONE to null in method signatures
65
66 A misconception concerning default lock mode values in method signatures lead to unexpected behaviour
67 in SQL statements on SQL Server. With a default lock mode of ``LockMode::NONE`` throughout the
68 method signatures in ORM, the table lock hint ``WITH (NOLOCK)`` was appended to all locking related
69 queries by default. This could result in unpredictable results because an explicit ``WITH (NOLOCK)``
70 table hint tells SQL Server to run a specific query in transaction isolation level READ UNCOMMITTED
71 instead of the default READ COMMITTED transaction isolation level.
72 Therefore there now is a distinction between ``LockMode::NONE`` and ``null`` to be able to tell
73 Doctrine whether to add table lock hints to queries by intention or not. To achieve this, the following
74 method signatures have been changed to declare ``$lockMode = null`` instead of ``$lockMode = LockMode::NONE``:
75
76 - ``Doctrine\ORM\Cache\Persister\AbstractEntityPersister#getSelectSQL()``
77 - ``Doctrine\ORM\Cache\Persister\AbstractEntityPersister#load()``
78 - ``Doctrine\ORM\Cache\Persister\AbstractEntityPersister#refresh()``
79 - ``Doctrine\ORM\Decorator\EntityManagerDecorator#find()``
80 - ``Doctrine\ORM\EntityManager#find()``
81 - ``Doctrine\ORM\EntityRepository#find()``
82 - ``Doctrine\ORM\Persisters\BasicEntityPersister#getSelectSQL()``
83 - ``Doctrine\ORM\Persisters\BasicEntityPersister#load()``
84 - ``Doctrine\ORM\Persisters\BasicEntityPersister#refresh()``
85 - ``Doctrine\ORM\Persisters\EntityPersister#getSelectSQL()``
86 - ``Doctrine\ORM\Persisters\EntityPersister#load()``
87 - ``Doctrine\ORM\Persisters\EntityPersister#refresh()``
88 - ``Doctrine\ORM\Persisters\JoinedSubclassPersister#getSelectSQL()``
89
90 You should update signatures for these methods if you have subclassed one of the above classes.
91 Please also check the calling code of these methods in your application and update if necessary.
92
93 **Note:**
94 This in fact is really a minor BC BREAK and should not have any affect on database vendors
95 other than SQL Server because it is the only one that supports and therefore cares about
96 ``LockMode::NONE``. It's really just a FIX for SQL Server environments using ORM.
97
10b801d @Ocramius Adding note about a minor BC break: d2 does not call `__clone` on new…
Ocramius authored
98 ## Minor BC BREAK: `__clone` method not called anymore when entities are instantiated via metadata API
99
100 As of PHP 5.6, instantiation of new entities is deferred to the
101 [`doctrine/instantiator`](https://github.com/doctrine/instantiator) library, which will avoid calling `__clone`
102 or any public API on instantiated objects.
a6c8ab8 @deeky666 make lock mode usage consistent
deeky666 authored
103
b61496a @Ocramius #1159 - adding `UPGRADE.md` notes for `Doctrine\ORM\Repository\Defaul…
Ocramius authored
104 ## BC BREAK: `Doctrine\ORM\Repository\DefaultRepositoryFactory` is now `final`
105
106 Please implement the `Doctrine\ORM\Repository\RepositoryFactory` interface instead of extending
107 the `Doctrine\ORM\Repository\DefaultRepositoryFactory`.
108
c49b079 @guilhermeblanco Update UPGRADE.md
guilhermeblanco authored
109 ## BC BREAK: New object expression DQL queries now respects user provided aliasing and not return consumed fields
110
111 When executing DQL queries with new object expressions, instead of returning DTOs numerically indexes, it will now respect user provided aliases. Consider the following query:
112
113 SELECT new UserDTO(u.id,u.name) as user,new AddressDTO(a.street,a.postalCode) as address, a.id as addressId FROM User u INNER JOIN u.addresses a WITH a.isPrimary = true
114
115 Previously, your result would be similar to this:
116
117 array(
118 0=>array(
119 0=>{UserDTO object},
120 1=>{AddressDTO object},
121 2=>{u.id scalar},
122 3=>{u.name scalar},
123 4=>{a.street scalar},
124 5=>{a.postalCode scalar},
125 'addressId'=>{a.id scalar},
126 ),
127 ...
128 )
129
130 From now on, the resultset will look like this:
131
132 array(
133 0=>array(
134 'user'=>{UserDTO object},
135 'address'=>{AddressDTO object},
136 'addressId'=>{a.id scalar}
137 ),
138 ...
139 )
140
512a001 @beberlei DDC-2173 - Add Test for new OnFlush or PreFlush behavior and update U…
beberlei authored
141 # Upgrade to 2.4
142
dc674f8 @beberlei Mention BC BREAK in PersistentCollection#matching() more prominently.
beberlei authored
143 ## BC BREAK: Compatibility Bugfix in PersistentCollection#matching()
144
145 In Doctrine 2.3 it was possible to use the new ``matching($criteria)``
146 functionality by adding constraints for assocations based on ID:
147
148 Criteria::expr()->eq('association', $assocation->getId());
149
150 This functionality does not work on InMemory collections however, because
151 in memory criteria compares object values based on reference.
152 As of 2.4 the above code will throw an exception. You need to change
153 offending code to pass the ``$assocation`` reference directly:
154
155 Criteria::expr()->eq('association', $assocation);
156
673323f @Ocramius Adding warnings about deprecation of GIT, TAR and PEAR autoloading
Ocramius authored
157 ## Composer is now the default autoloader
158
159 The test suite now runs with composer autoloading. Support for PEAR, and tarball autoloading is deprecated.
160 Support for GIT submodules is removed.
161
0b2d3d4 @beberlei DDC-2173 - Correct issue is about "postFlush" not "preFlush" and add …
beberlei authored
162 ## OnFlush and PostFlush event always called
512a001 @beberlei DDC-2173 - Add Test for new OnFlush or PreFlush behavior and update U…
beberlei authored
163
0b2d3d4 @beberlei DDC-2173 - Correct issue is about "postFlush" not "preFlush" and add …
beberlei authored
164 Before 2.4 the postFlush and onFlush events were only called when there were
512a001 @beberlei DDC-2173 - Add Test for new OnFlush or PreFlush behavior and update U…
beberlei authored
165 actually entities that changed. Now these events are called no matter if there
166 are entities in the UoW or changes are found.
167
8109db0 @FabioBatSilva Document Parenthesis BC break.
FabioBatSilva authored
168 ## Parenthesis are now considered in arithmetic expression
169
170 Before 2.4 parenthesis are not considered in arithmetic primary expression.
171 That's conceptually wrong, since it might result in wrong values. For example:
172
173 The DQL:
174
2ad6565 @FabioBatSilva Fix parenthesis example
FabioBatSilva authored
175 SELECT 100 / ( 2 * 2 ) FROM MyEntity
8109db0 @FabioBatSilva Document Parenthesis BC break.
FabioBatSilva authored
176
177 Before 2.4 it generates the SQL:
178
2ad6565 @FabioBatSilva Fix parenthesis example
FabioBatSilva authored
179 SELECT 100 / 2 * 2 FROM my_entity
8109db0 @FabioBatSilva Document Parenthesis BC break.
FabioBatSilva authored
180
181 Now parenthesis are considered, the previous DQL will generate:
182
2ad6565 @FabioBatSilva Fix parenthesis example
FabioBatSilva authored
183 SELECT 100 / (2 * 2) FROM my_entity
8109db0 @FabioBatSilva Document Parenthesis BC break.
FabioBatSilva authored
184
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
185 # Upgrade to 2.3
186
5fc7e65 @beberlei Update UPGRADE.md notes with BC mention.
beberlei authored
187 ## Auto Discriminator Map breaks userland implementations with Listener
188
189 The new feature to detect discriminator maps automatically when none
190 are provided breaks userland implementations doing this with a
191 listener in ``loadClassMetadata`` event.
192
95334e9 @beberlei Clarify BC break in DDC-2156
beberlei authored
193 ## EntityManager#find() not calls EntityRepository#find() anymore
194
195 Previous to 2.3, calling ``EntityManager#find()`` would be delegated to
196 ``EntityRepository#find()``. This has lead to some unexpected behavior in the
197 core of Doctrine when people have overwritten the find method in their
198 repositories. That is why this behavior has been reversed in 2.3, and
199 ``EntityRepository#find()`` calls ``EntityManager#find()`` instead.
200
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
201 ## EntityGenerator add*() method generation
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
202
203 When generating an add*() method for a collection the EntityGenerator will now not
204 use the Type-Hint to get the singular for the collection name, but use the field-name
205 and strip a trailing "s" character if there is one.
206
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
207 ## Merge copies non persisted properties too
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
208
209 When merging an entity in UoW not only mapped properties are copied, but also others.
210
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
211 ## Query, QueryBuilder and NativeQuery parameters *BC break*
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
212
213 From now on, parameters in queries is an ArrayCollection instead of a simple array.
214 This affects heavily the usage of setParameters(), because it will not append anymore
215 parameters to query, but will actually override the already defined ones.
216 Whenever you are retrieving a parameter (ie. $query->getParameter(1)), you will
217 receive an instance of Query\Parameter, which contains the methods "getName",
218 "getValue" and "getType". Parameters are also only converted to when necessary, and
219 not when they are set.
220
221 Also, related functions were affected:
222
223 * execute($parameters, $hydrationMode) the argument $parameters can be either an key=>value array or an ArrayCollection instance
224 * iterate($parameters, $hydrationMode) the argument $parameters can be either an key=>value array or an ArrayCollection instance
225 * setParameters($parameters) the argument $parameters can be either an key=>value array or an ArrayCollection instance
226 * getParameters() now returns ArrayCollection instead of array
227 * getParameter($key) now returns Parameter instance instead of parameter value
228
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
229 ## Query TreeWalker method renamed
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
230
231 Internal changes were made to DQL and SQL generation. If you have implemented your own TreeWalker,
232 you probably need to update it. The method walkJoinVariableDeclaration is now named walkJoin.
233
afdb92f @chives Added note about new methods in UPGRADE.md
chives authored
234 ## New methods in TreeWalker interface *BC break*
235
236 Two methods getQueryComponents() and setQueryComponent() were added to the TreeWalker interface and all its implementations
237 including TreeWalkerAdapter, TreeWalkerChain and SqlWalker. If you have your own implementation not inheriting from one of the
238 above you must implement these new methods.
239
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
240 ## Metadata Drivers
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
241
242 Metadata drivers have been rewritten to reuse code from Doctrine\Common. Anyone who is using the
243 `Doctrine\ORM\Mapping\Driver\Driver` interface should instead refer to
244 `Doctrine\Common\Persistence\Mapping\Driver\MappingDriver`. Same applies to
245 `Doctrine\ORM\Mapping\Driver\AbstractFileDriver`: you should now refer to
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
246 `Doctrine\Common\Persistence\Mapping\Driver\FileDriver`.
247
75276e4 @Ocramius Restoring class names extending the Doctrine\Common implementation fo…
Ocramius authored
248 Also, following mapping drivers have been deprecated, please use their replacements in Doctrine\Common as listed:
915da58 @Ocramius Adding upgrade notes about the BC Break
Ocramius authored
249
250 * `Doctrine\ORM\Mapping\Driver\DriverChain` => `Doctrine\Common\Persistence\Mapping\Driver\MappingDriverChain`
251 * `Doctrine\ORM\Mapping\Driver\PHPDriver` => `Doctrine\Common\Persistence\Mapping\Driver\PHPDriver`
252 * `Doctrine\ORM\Mapping\Driver\StaticPHPDriver` => `Doctrine\Common\Persistence\Mapping\Driver\StaticPHPDriver`
253
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
254 # Upgrade to 2.2
255
256 ## ResultCache implementation rewritten
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
257
258 The result cache is completely rewritten and now works on the database result level, not inside the ORM AbstractQuery
259 anymore. This means that for result cached queries the hydration will now always be performed again, regardless of
260 the hydration mode. Affected areas are:
261
262 1. Fixes the problem that entities coming from the result cache were not registered in the UnitOfWork
263 leading to problems during EntityManager#flush. Calls to EntityManager#merge are not necessary anymore.
264 2. Affects the array hydrator which now includes the overhead of hydration compared to caching the final result.
265
266 The API is backwards compatible however most of the getter methods on the `AbstractQuery` object are now
267 deprecated in favor of calling AbstractQuery#getQueryCacheProfile(). This method returns a `Doctrine\DBAL\Cache\QueryCacheProfile`
268 instance with access to result cache driver, lifetime and cache key.
269
270
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
271 ## EntityManager#getPartialReference() creates read-only entity
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
272
273 Entities returned from EntityManager#getPartialReference() are now marked as read-only if they
274 haven't been in the identity map before. This means objects of this kind never lead to changes
275 in the UnitOfWork.
276
277
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
278 ## Fields omitted in a partial DQL query or a native query are never updated
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
279
280 Fields of an entity that are not returned from a partial DQL Query or native SQL query
281 will never be updated through an UPDATE statement.
282
283
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
284 ## Removed support for onUpdate in @JoinColumn
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
285
286 The onUpdate foreign key handling makes absolutely no sense in an ORM. Additionally Oracle doesn't even support it. Support for it is removed.
287
288
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
289 ## Changes in Annotation Handling
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
290
291 There have been some changes to the annotation handling in Common 2.2 again, that affect how people with old configurations
292 from 2.0 have to configure the annotation driver if they don't use `Configuration::newDefaultAnnotationDriver()`:
293
294 // Register the ORM Annotations in the AnnotationRegistry
295 AnnotationRegistry::registerFile('path/to/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php');
296
297 $reader = new \Doctrine\Common\Annotations\SimpleAnnotationReader();
298 $reader->addNamespace('Doctrine\ORM\Mapping');
299 $reader = new \Doctrine\Common\Annotations\CachedReader($reader, new ArrayCache());
300
301 $driver = new AnnotationDriver($reader, (array)$paths);
302
303 $config->setMetadataDriverImpl($driver);
304
305
a2cd0f5 @pborreli Fixed typos
pborreli authored
306 ## Scalar mappings can now be omitted from DQL result
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
307
308 You are now allowed to mark scalar SELECT expressions as HIDDEN an they are not hydrated anymore.
309 Example:
310
311 SELECT u, SUM(a.id) AS HIDDEN numArticles FROM User u LEFT JOIN u.Articles a ORDER BY numArticles DESC HAVING numArticles > 10
312
313 Your result will be a collection of Users, and not an array with key 0 as User object instance and "numArticles" as the number of articles per user
314
315
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
316 ## Map entities as scalars in DQL result
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
317
318 When hydrating to array or even a mixed result in object hydrator, previously you had the 0 index holding you entity instance.
319 You are now allowed to alias this, providing more flexibility for you code.
320 Example:
321
322 SELECT u AS user FROM User u
323
324 Will now return a collection of arrays with index "user" pointing to the User object instance.
325
326
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
327 ## Performance optimizations
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
328
329 Thousands of lines were completely reviewed and optimized for best performance.
330 Removed redundancy and improved code readability made now internal Doctrine code easier to understand.
331 Also, Doctrine 2.2 now is around 10-15% faster than 2.1.
332
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
333 ## EntityManager#find(null)
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
334
335 Previously EntityManager#find(null) returned null. It now throws an exception.
336
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
337 # Upgrade to 2.1
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
338
339 ## Interface for EntityRepository
340
341 The EntityRepository now has an interface Doctrine\Common\Persistence\ObjectRepository. This means that your classes that override EntityRepository and extend find(), findOneBy() or findBy() must be adjusted to follow this interface.
342
343 ## AnnotationReader changes
344
345 The annotation reader was heavily refactored between 2.0 and 2.1-RC1. In theory the operation of the new reader should be backwards compatible, but it has to be setup differently to work that way:
346
347 // new call to the AnnotationRegistry
348 \Doctrine\Common\Annotations\AnnotationRegistry::registerFile('/doctrine-src/lib/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php');
349
350 $reader = new \Doctrine\Common\Annotations\AnnotationReader();
351 $reader->setDefaultAnnotationNamespace('Doctrine\ORM\Mapping\\');
352 // new code necessary starting here
353 $reader->setIgnoreNotImportedAnnotations(true);
354 $reader->setEnableParsePhpImports(false);
355 $reader = new \Doctrine\Common\Annotations\CachedReader(
356 new \Doctrine\Common\Annotations\IndexedReader($reader), new ArrayCache()
357 );
358
359 This is already done inside the ``$config->newDefaultAnnotationDriver``, so everything should automatically work if you are using this method. You can verify if everything still works by executing a console command such as schema-validate that loads all metadata into memory.
360
361 # Update from 2.0-BETA3 to 2.0-BETA4
362
363 ## XML Driver <change-tracking-policy /> element demoted to attribute
364
365 We changed how the XML Driver allows to define the change-tracking-policy. The working case is now:
366
367 <entity change-tracking-policy="DEFERRED_IMPLICT" />
368
369 # Update from 2.0-BETA2 to 2.0-BETA3
370
371 ## Serialization of Uninitialized Proxies
372
373 As of Beta3 you can now serialize uninitialized proxies, an exception will only be thrown when
374 trying to access methods on the unserialized proxy as long as it has not been re-attached to the
375 EntityManager using `EntityManager#merge()`. See this example:
376
377 $proxy = $em->getReference('User', 1);
378
379 $serializedProxy = serialize($proxy);
380 $detachedProxy = unserialized($serializedProxy);
381
382 echo $em->contains($detachedProxy); // FALSE
383
384 try {
385 $detachedProxy->getId(); // uninitialized detached proxy
386 } catch(Exception $e) {
387
388 }
389 $attachedProxy = $em->merge($detachedProxy);
390 echo $attackedProxy->getId(); // works!
391
392 ## Changed SQL implementation of Postgres and Oracle DateTime types
393
394 The DBAL Type "datetime" included the Timezone Offset in both Postgres and Oracle. As of this version they are now
395 generated without Timezone (TIMESTAMP WITHOUT TIME ZONE instead of TIMESTAMP WITH TIME ZONE).
396 See [this comment to Ticket DBAL-22](http://www.doctrine-project.org/jira/browse/DBAL-22?focusedCommentId=13396&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_13396)
397 for more details as well as migration issues for PostgreSQL and Oracle.
398
399 Both Postgres and Oracle will throw Exceptions during hydration of Objects with "DateTime" fields unless migration steps are taken!
400
401 ## Removed multi-dot/deep-path expressions in DQL
402
403 The support for implicit joins in DQL through the multi-dot/Deep Path Expressions
404 was dropped. For example:
405
406 SELECT u FROM User u WHERE u.group.name = ?1
407
408 See the "u.group.id" here is using multi dots (deep expression) to walk
409 through the graph of objects and properties. Internally the DQL parser
410 would rewrite these queries to:
411
412 SELECT u FROM User u JOIN u.group g WHERE g.name = ?1
413
414 This explicit notation will be the only supported notation as of now. The internal
415 handling of multi-dots in the DQL Parser was very complex, error prone in edge cases
416 and required special treatment for several features we added. Additionally
417 it had edge cases that could not be solved without making the DQL Parser
418 even much more complex. For this reason we will drop the support for the
419 deep path expressions to increase maintainability and overall performance
420 of the DQL parsing process. This will benefit any DQL query being parsed,
421 even those not using deep path expressions.
422
423 Note that the generated SQL of both notations is exactly the same! You
424 don't loose anything through this.
425
426 ## Default Allocation Size for Sequences
427
428 The default allocation size for sequences has been changed from 10 to 1. This step was made
429 to not cause confusion with users and also because it is partly some kind of premature optimization.
430
431 # Update from 2.0-BETA1 to 2.0-BETA2
432
433 There are no backwards incompatible changes in this release.
434
435 # Upgrade from 2.0-ALPHA4 to 2.0-BETA1
436
437 ## EntityRepository deprecates access to protected variables
438
439 Instead of accessing protected variables for the EntityManager in
440 a custom EntityRepository it is now required to use the getter methods
441 for all the three instance variables:
442
443 * `$this->_em` now accessible through `$this->getEntityManager()`
444 * `$this->_class` now accessible through `$this->getClassMetadata()`
445 * `$this->_entityName` now accessible through `$this->getEntityName()`
446
447 Important: For Beta 2 the protected visibility of these three properties will be
448 changed to private!
449
450 ## Console migrated to Symfony Console
451
452 The Doctrine CLI has been replaced by Symfony Console Configuration
453
454 Instead of having to specify:
455
456 [php]
457 $cliConfig = new CliConfiguration();
458 $cliConfig->setAttribute('em', $entityManager);
459
460 You now have to configure the script like:
461
462 [php]
463 $helperSet = new \Symfony\Components\Console\Helper\HelperSet(array(
464 'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($em->getConnection()),
465 'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em)
466 ));
467
468 ## Console: No need for Mapping Paths anymore
469
470 In previous versions you had to specify the --from and --from-path options
471 to show where your mapping paths are from the console. However this information
472 is already known from the Mapping Driver configuration, so the requirement
473 for this options were dropped.
474
475 Instead for each console command all the entities are loaded and to
476 restrict the operation to one or more sub-groups you can use the --filter flag.
477
478 ## AnnotationDriver is not a default mapping driver anymore
479
480 In conjunction with the recent changes to Console we realized that the
481 annotations driver being a default metadata driver lead to lots of glue
482 code in the console components to detect where entities lie and how to load
483 them for batch updates like SchemaTool and other commands. However the
484 annotations driver being a default driver does not really help that much
485 anyways.
486
a2cd0f5 @pborreli Fixed typos
pborreli authored
487 Therefore we decided to break backwards compatibility in this issue and drop
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
488 the support for Annotations as Default Driver and require our users to
489 specify the driver explicitly (which allows us to ask for the path to all
490 entities).
491
492 If you are using the annotations metadata driver as default driver, you
493 have to add the following lines to your bootstrap code:
494
495 $driverImpl = $config->newDefaultAnnotationDriver(array(__DIR__."/Entities"));
496 $config->setMetadataDriverImpl($driverImpl);
497
498 You have to specify the path to your entities as either string of a single
499 path or array of multiple paths
500 to your entities. This information will be used by all console commands to
501 access all entities.
502
503 Xml and Yaml Drivers work as before!
504
505
506 ## New inversedBy attribute
507
508 It is now *mandatory* that the owning side of a bidirectional association specifies the
509 'inversedBy' attribute that points to the name of the field on the inverse side that completes
510 the association. Example:
511
512 [php]
513 // BEFORE (ALPHA4 AND EARLIER)
514 class User
515 {
516 //...
517 /** @OneToOne(targetEntity="Address", mappedBy="user") */
518 private $address;
519 //...
520 }
521 class Address
522 {
523 //...
524 /** @OneToOne(targetEntity="User") */
525 private $user;
526 //...
527 }
fc00d5f @Ocramius Updating upgrade docs and fixes suggested by @beberlei
Ocramius authored
528
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
529 // SINCE BETA1
530 // User class DOES NOT CHANGE
531 class Address
532 {
533 //...
534 /** @OneToOne(targetEntity="User", inversedBy="address") */
535 private $user;
536 //...
537 }
fc00d5f @Ocramius Updating upgrade docs and fixes suggested by @beberlei
Ocramius authored
538
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
539 Thus, the inversedBy attribute is the counterpart to the mappedBy attribute. This change
540 was necessary to enable some simplifications and further performance improvements. We
541 apologize for the inconvenience.
542
543 ## Default Property for Field Mappings
544
545 The "default" option for database column defaults has been removed. If desired, database column defaults can
a2cd0f5 @pborreli Fixed typos
pborreli authored
546 be implemented by using the columnDefinition attribute of the @Column annotation (or the appropriate XML and YAML equivalents).
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
547 Prefer PHP default values, if possible.
548
549 ## Selecting Partial Objects
550
551 Querying for partial objects now has a new syntax. The old syntax to query for partial objects
552 now has a different meaning. This is best illustrated by an example. If you previously
553 had a DQL query like this:
554
555 [sql]
556 SELECT u.id, u.name FROM User u
fc00d5f @Ocramius Updating upgrade docs and fixes suggested by @beberlei
Ocramius authored
557
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
558 Since BETA1, simple state field path expressions in the select clause are used to select
559 object fields as plain scalar values (something that was not possible before).
560 To achieve the same result as previously (that is, a partial object with only id and name populated)
561 you need to use the following, explicit syntax:
562
563 [sql]
564 SELECT PARTIAL u.{id,name} FROM User u
565
566 ## XML Mapping Driver
567
568 The 'inheritance-type' attribute changed to take last bit of ClassMetadata constant names, i.e.
569 NONE, SINGLE_TABLE, INHERITANCE_TYPE_JOINED
570
571 ## YAML Mapping Driver
572
573 The way to specify lifecycle callbacks in YAML Mapping driver was changed to allow for multiple callbacks
574 per event. The Old syntax ways:
575
576 [yaml]
577 lifecycleCallbacks:
578 doStuffOnPrePersist: prePersist
579 doStuffOnPostPersist: postPersist
580
581 The new syntax is:
582
583 [yaml]
584 lifecycleCallbacks:
585 prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersistToo ]
586 postPersist: [ doStuffOnPostPersist ]
587
588 ## PreUpdate Event Listeners
589
590 Event Listeners listening to the 'preUpdate' event can only affect the primitive values of entity changesets
591 by using the API on the `PreUpdateEventArgs` instance passed to the preUpdate listener method. Any changes
592 to the state of the entitys properties won't affect the database UPDATE statement anymore. This gives drastic
593 performance benefits for the preUpdate event.
594
595 ## Collection API
596
597 The Collection interface in the Common package has been updated with some missing methods
598 that were present only on the default implementation, ArrayCollection. Custom collection
599 implementations need to be updated to adhere to the updated interface.
600
601 # Upgrade from 2.0-ALPHA3 to 2.0-ALPHA4
602
603 ## CLI Controller changes
604
605 CLI main object changed its name and namespace. Renamed from Doctrine\ORM\Tools\Cli to Doctrine\Common\Cli\CliController.
606 Doctrine\Common\Cli\CliController now only deals with namespaces. Ready to go, Core, Dbal and Orm are available and you can subscribe new tasks by retrieving the namespace and including new task. Example:
607
608 [php]
609 $cli->getNamespace('Core')->addTask('my-example', '\MyProject\Tools\Cli\Tasks\MyExampleTask');
610
611
612 ## CLI Tasks documentation
613
614 Tasks have implemented a new way to build documentation. Although it is still possible to define the help manually by extending the basicHelp and extendedHelp, they are now optional.
615 With new required method AbstractTask::buildDocumentation, its implementation defines the TaskDocumentation instance (accessible through AbstractTask::getDocumentation()), basicHelp and extendedHelp are now not necessary to be implemented.
616
617 ## Changes in Method Signatures
618
619 * A bunch of Methods on both Doctrine\DBAL\Platforms\AbstractPlatform and Doctrine\DBAL\Schema\AbstractSchemaManager
620 have changed quite significantly by adopting the new Schema instance objects.
621
622 ## Renamed Methods
623
624 * Doctrine\ORM\AbstractQuery::setExpireResultCache() -> expireResultCache()
625 * Doctrine\ORM\Query::setExpireQueryCache() -> expireQueryCache()
626
627 ## SchemaTool Changes
628
629 * "doctrine schema-tool --drop" now always drops the complete database instead of
630 only those tables defined by the current database model. The previous method had
a2cd0f5 @pborreli Fixed typos
pborreli authored
631 problems when foreign keys of orphaned tables pointed to tables that were scheduled
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
632 for deletion.
633 * Use "doctrine schema-tool --update" to get a save incremental update for your
634 database schema without deleting any unused tables, sequences or foreign keys.
635 * Use "doctrine schema-tool --complete-update" to do a full incremental update of
636 your schema.
637 # Upgrade from 2.0-ALPHA2 to 2.0-ALPHA3
638
639 This section details the changes made to Doctrine 2.0-ALPHA3 to make it easier for you
fc00d5f @Ocramius Updating upgrade docs and fixes suggested by @beberlei
Ocramius authored
640 to upgrade your projects to use this version.
baae40c @beberlei Concatenate UPGRADE files into new UPGRADE.md
beberlei authored
641
642 ## CLI Changes
643
644 The $args variable used in the cli-config.php for configuring the Doctrine CLI has been renamed to $globalArguments.
645
646 ## Proxy class changes
647
648 You are now required to make supply some minimalist configuration with regards to proxy objects. That involves 2 new configuration options. First, the directory where generated proxy classes should be placed needs to be specified. Secondly, you need to configure the namespace used for proxy classes. The following snippet shows an example:
649
650 [php]
651 // step 1: configure directory for proxy classes
652 // $config instanceof Doctrine\ORM\Configuration
653 $config->setProxyDir('/path/to/myproject/lib/MyProject/Generated/Proxies');
654 $config->setProxyNamespace('MyProject\Generated\Proxies');
655
656 Note that proxy classes behave exactly like any other classes when it comes to class loading. Therefore you need to make sure the proxy classes can be loaded by some class loader. If you place the generated proxy classes in a namespace and directory under your projects class files, like in the example above, it would be sufficient to register the MyProject namespace on a class loader. Since the proxy classes are contained in that namespace and adhere to the standards for class loading, no additional work is required.
657 Generating the proxy classes into a namespace within your class library is the recommended setup.
658
659 Entities with initialized proxy objects can now be serialized and unserialized properly from within the same application.
660
661 For more details refer to the Configuration section of the manual.
662
663 ## Removed allowPartialObjects configuration option
664
665 The allowPartialObjects configuration option together with the `Configuration#getAllowPartialObjects` and `Configuration#setAllowPartialObjects` methods have been removed.
666 The new behavior is as if the option were set to FALSE all the time, basically disallowing partial objects globally. However, you can still use the `Query::HINT_FORCE_PARTIAL_LOAD` query hint to force a query to return partial objects for optimization purposes.
667
668 ## Renamed Methods
669
670 * Doctrine\ORM\Configuration#getCacheDir() to getProxyDir()
5adc8be @beberlei Cleanup UPDATE.md chapter mess a bit
beberlei authored
671 * Doctrine\ORM\Configuration#setCacheDir($dir) to setProxyDir($dir)
Something went wrong with that request. Please try again.