Note about upgrading: Doctrine uses static and runtime mechanisms to raise awareness about deprecated code.
- Use of
@deprecateddocblock that is detected by IDEs (like PHPStorm) or Static Analysis tools (like Psalm, phpstan) - Use of our low-overhead runtime deprecation API, details: https://github.com/doctrine/deprecations/
The interface Doctrine\Persistence\Mapping\ClassMetadata has two new methods:
getFieldValue(object $object, string $field)setFieldValue(object $object, string $field, mixed $value): void
Not implementing these methods is deprecated. They will be required in 5.0.
The following classes are now marked with @final and should not be extended:
Doctrine\Persistence\Mapping\Driver\DefaultFileLocatorDoctrine\Persistence\Mapping\Driver\MappingDriverChainDoctrine\Persistence\Mapping\Driver\PHPDriverDoctrine\Persistence\Mapping\Driver\StaticPHPDriverDoctrine\Persistence\Mapping\Driver\SymfonyFileLocatorDoctrine\Persistence\Mapping\RuntimeReflectionServiceDoctrine\Persistence\Reflection\EnumReflectionPropertyDoctrine\Persistence\Reflection\TypedNoDefaultReflectionProperty
These classes were not designed for extension and will be marked with the final
keyword in 5.0.
Additionally, Doctrine\Persistence\Reflection\RuntimeReflectionProperty is marked
with @phpstan-sealed to restrict extension to only TypedNoDefaultReflectionProperty.
Extending this class in your code is not supported.
Relying on the $metadata variable directly in PHP mapping files is deprecated.
Instead, wrap the code in a closure that is returned by the configuration file.
Before:
<?php // mappings/App.Entity.User.php
$metadata->name = \App\Entity\User::class;After:
<?php // mappings/App.Entity.User.php
use Doctrine\Persistence\Mapping\ClassMetadata;
return function (ClassMetadata $metadata): void {
$metadata->name = \App\Entity\User::class;
};The constructor of StaticPHPDriver now accepts a ClassLocator instance
in addition to a path or array of paths:
$driver = new StaticPHPDriver(new ClassNames([MyEntity::class, AnotherEntity::class]));Using a ClassLocator implementation is recommended instead of relying
on directory scanning.
With PHP 8.4 native lazy objects, you don't need to pass any proxy interface to
AbstractManagerRegistry. The class of the lazy objects is the class being mapped.
The class Doctrine\Persistence\Mapping\StaticReflectionService is removed
without replacement.
The return type of ReflectionService::getClass() has been narrowed so that
null is no longer a valid return value.
Classes implementing Doctrine\Persistence\ObjectManager must implement this
new method.
The code base is now fully typed, meaning properties, parameters and return type declarations have been added to all types.
Proxy objects implementing the Doctrine\Common\Proxy\Proxy interface are not
supported anymore. Implement Doctrine\Persistence\Proxy instead.
Deprecated classes have been removed:
Doctrine\Persistence\Reflection\RuntimePublicReflectionPropertyDoctrine\Persistence\Reflection\TypedNoDefaultRuntimePublicReflectionProperty
The class Doctrine\Persistence\Mapping\StaticReflectionService is deprecated
without replacement.
Classes implementing Doctrine\Persistence\ObjectManager should implement the new
method. This method will be added to the interface in 4.0.
Use RuntimeReflectionProperty instead.
These methods only make sense when partially clearing the object manager, which
is no longer possible.
The second argument of the constructor of OnClearEventArgs is removed as well.
Implement active record style functionality directly in your application, by
using a postLoad event.
Use ColocatedMappingDriver instead.
Use MappingException::pathRequiredForDriver() instead.
Use LifecycleEventArgs::getObject() instead.
AbstractClassMetadataFactory::getFqcnFromAlias()is removed.ClassMetadataFactorymethods now require their$classNameargument to be an actual FQCN.
ObjectManagerDecorator::merge() is removed without replacement.
Removed support for using doctrine/cache for metadata caching. The
setCacheDriver and getCacheDriver methods have been removed from
Doctrine\Persistence\Mapping\AbstractMetadata. Please use getCache and
setCache with a PSR-6 implementation instead.
$objectName has been dropped from the signature of ObjectManager::clear().
- public function clear($objectName = null)
+ public function clear(): voidAlso, native parameter type declarations have been added on all public APIs. Native return type declarations have not been added so that it is possible to implement types compatible with both 2.x and 3.x.
Please implement this functionality directly in your application if you want ActiveRecord style functionality.
These methods only make sense when partially clearing the object manager, which
is deprecated.
Passing a second argument to the constructor of OnClearEventArgs is
deprecated as well.
Along with deprecating PersistentObject, deprecating ObjectManagerAware
means deprecating support for active record, which already came with a word of
warning. Please implement this directly in your application with a postLoad
event if you need active record style functionality.
MappingException::pathRequiredForDriver() should be used instead.
Since attributes were introduced in PHP 8.0, annotations are deprecated.
AnnotationDriver is an abstract class that is used when implementing concrete
annotation drivers in dependent packages. It is deprecated in favor of using
ColocatedMappingDriver to implement both annotation and attribute based
drivers. This will involve implementing isTransient() as well as
__construct() and getReader() to retain backward compatibility.
Before:
$objectManager->find('MyPackage:MyClass', $id);
$objectManager->createQuery('SELECT u FROM MyPackage:MyClass');After:
$objectManager->find(MyClass::class, $id);
$objectManager->createQuery('SELECT u FROM '. MyClass::class);The setCacheDriver and getCacheDriver methods in
Doctrine\Persistence\Mapping\AbstractMetadata have been deprecated. Please
use getCache and setCache with a PSR-6 implementation instead. Note that
even after switching to PSR-6, getCacheDriver will return a cache instance
that wraps the PSR-6 cache. Note that if you use a custom implementation of
doctrine/cache, the library may not be able to provide a forward compatibility
layer. The cache implementation MUST extend the
Doctrine\Common\Cache\CacheProvider class.
Please handle merge operations in your application, and use
ObjectManager::clear() instead.
Please implement this functionality directly in your application if you want ActiveRecord style functionality.