doctrine/orm 3.0.0-beta1

on GitHub

BC BREAK: AUTO keyword for identity generation defaults to IDENTITY for PostgreSQL now

When using the AUTO strategy to let Doctrine determine the identity generation mecehanism for
an entity, PostgreSQL now uses IDENTITY instead of SEQUENCE. When upgrading from ORM 2.x
and preference is on keeping the SEQUENCE based identity generation, then configure the ORM
this way:

use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
use Doctrine\ORM\Configuration;
use Doctrine\ORM\Mapping\ClassMetadata;

assert($configuration instanceof Configuration);
$configuration->setIdentityGenerationPreferences([
    PostgreSQLPlatform::CLASS => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
]);

BC BREAK: Throw exceptions when using illegal attributes on Embeddable

There are only a few attributes allowed on an embeddable such as #[Column] or
#[Embedded]. Previously all others that target entity classes where ignored,
now they throw an exception.

BC BREAK: Partial objects are removed

• The PARTIAL keyword in DQL no longer exists.
• Doctrine\ORM\Query\AST\PartialObjectExpressionis removed.
• Doctrine\ORM\Query\SqlWalker::HINT_PARTIAL and
  Doctrine\ORM\Query::HINT_FORCE_PARTIAL_LOAD are removed.
• Doctrine\ORM\EntityManager*::getPartialReference() is removed.

BC BREAK: Doctrine\ORM\Persister\Entity\EntityPersister::executeInserts() return type changed to void

Implementors should adapt to the new signature, and should call
UnitOfWork::assignPostInsertId() for each entry in the previously returned
array.

BC BREAK: Doctrine\ORM\Proxy\ProxyFactory no longer extends abstract factory from doctrine/common

It is no longer possible to call methods, constants or properties inherited
from that class on a ProxyFactory instance.

Doctrine\ORM\Proxy\ProxyFactory::createProxyDefinition() and
Doctrine\ORM\Proxy\ProxyFactory::resetUninitializedProxy() are removed as well.

BC BREAK: lazy ghosts are enabled unconditionally

Doctrine\ORM\Configuration::setLazyGhostObjectEnabled() and
Doctrine\ORM\Configuration::isLazyGhostObjectEnabled() are now no-ops and
will be deprecated in 3.1.0

BC BREAK: collisions in identity map are unconditionally rejected

Doctrine\ORM\Configuration::setRejectIdCollisionInIdentityMap() and
Doctrine\ORM\Configuration::isRejectIdCollisionInIdentityMapEnabled() are now
no-ops and will be deprecated in 3.1.0.

BC BREAK: Lifecycle callback mapping on embedded classes is now explicitly forbidden

Lifecycle callback mapping on embedded classes produced no effect, and is now
explicitly forbidden to point out mistakes.

BC BREAK: The NOTIFY change tracking policy is removed

You should use DEFERRED_EXPLICIT instead.

BC BREAK: Mapping\Driver\XmlDriver::__construct() third argument is now a no-op

The third argument to
Doctrine\ORM\Mapping\Driver\XmlDriver::__construct() was introduced to
let users opt-in to XML validation, that is now always enabled, regardless of
the value of that argument.

As a consequence, the same goes for
Doctrine\ORM\Mapping\Driver\SimplifiedXmlDriver, and for
Doctrine\ORM\ORMSetup::createXMLMetadataConfiguration().

BC BREAK: Mapping\Driver\AttributeDriver::__construct() second argument is now a no-op

The second argument to
Doctrine\ORM\Mapping\Driver\AttributeDriver::__construct() was introduced to
let users opt-in to a new behavior, that is now always enforced, regardless of
the value of that argument.

BC BREAK: Query::setDQL() and Query::setFirstResult() no longer accept null

The $dqlQuery argument of Doctrine\ORM\Query::setDQL() must always be a
string.

The $firstResult argument of Doctrine\ORM\Query::setFirstResult() must
always be an integer.

BC BREAK: orm:schema-tool:update option --complete is now a no-op

orm:schema-tool:update now behaves as if --complete was provided,
regardless of whether it is provided or not.

BC BREAK: Removed Doctrine\ORM\Proxy\Proxy interface.

Use Doctrine\Persistence\Proxy instead to check whether proxies are initialized.

BC BREAK: Overriding fields or associations declared in other than mapped superclasses

As stated in the documentation, fields and associations may only be overridden when being inherited
from mapped superclasses. Overriding them for parent entity classes now throws a MappingException.

BC BREAK: Undeclared entity inheritance now throws a MappingException

As soon as an entity class inherits from another entity class, inheritance has to
be declared by adding the appropriate configuration for the root entity.

Removed getEntityManager() in Doctrine\ORM\Event\OnClearEventArgs and Doctrine\ORM\Event\*FlushEventArgs

Use getObjectManager() instead.

BC BREAK: Removed Doctrine\ORM\Mapping\ClassMetadataInfo class

Use Doctrine\ORM\Mapping\ClassMetadata instead.

BC BREAK: Removed Doctrine\ORM\Event\LifecycleEventArgs class.

Use one of the dedicated event classes instead:

• Doctrine\ORM\Event\PrePersistEventArgs
• Doctrine\ORM\Event\PreUpdateEventArgs
• Doctrine\ORM\Event\PreRemoveEventArgs
• Doctrine\ORM\Event\PostPersistEventArgs
• Doctrine\ORM\Event\PostUpdateEventArgs
• Doctrine\ORM\Event\PostRemoveEventArgs
• Doctrine\ORM\Event\PostLoadEventArgs

BC BREAK: Removed AttributeDriver::$entityAnnotationClasses and AttributeDriver::getReader()

• If you need to change the behavior of AttributeDriver::isTransient(),
  override that method instead.
• The attribute reader is internal to the driver and should not be accessed from outside.

BC BREAK: Removed Doctrine\ORM\Query\AST\InExpression

The AST parser will create a InListExpression or a InSubselectExpression when
encountering an IN () DQL expression instead of a generic InExpression.

As a consequence, SqlWalker::walkInExpression() has been replaced by
SqlWalker::walkInListExpression() and SqlWalker::walkInSubselectExpression().

BC BREAK: Changed EntityManagerInterface#refresh($entity), EntityManagerDecorator#refresh($entity) and UnitOfWork#refresh($entity) signatures

The new signatures of these methods add an optional LockMode|int|null $lockMode
param with default null value (no lock).

BC Break: Removed AnnotationDriver

The annotation driver and anything related to annotation has been removed.
Please migrate to another mapping driver.

The Doctrine\ORM\Mapping\Annotation maker interface has been removed in favor of the new
Doctrine\ORM\Mapping\MappingAttribute interface.

BC BREAK: Removed EntityManager::create()

The constructor of EntityManager is now public and must be used instead of the create() method.
However, the constructor expects a Connection while create() accepted an array with connection parameters.
You can pass that array to DBAL's Doctrine\DBAL\DriverManager::getConnection() method to bootstrap the
connection.

BC BREAK: Removed QueryBuilder methods and constants.

The following QueryBuilder constants and methods have been removed:

1. SELECT,
2. DELETE,
3. UPDATE,
4. STATE_DIRTY,
5. STATE_CLEAN,
6. getState(),
7. getType().

BC BREAK: Omitting only the alias argument for QueryBuilder::update and QueryBuilder::delete is not supported anymore

When building an UPDATE or DELETE query and when passing a class/type to the function, the alias argument must not be omitted.

Before

$qb = $em->createQueryBuilder()
    ->delete('User u')
    ->where('u.id = :user_id')
    ->setParameter('user_id', 1);

After

$qb = $em->createQueryBuilder()
    ->delete('User', 'u')
    ->where('u.id = :user_id')
    ->setParameter('user_id', 1);

BC BREAK: Split output walkers and tree walkers

SqlWalker and its child classes don't implement the TreeWalker interface
anymore.

The following methods have been removed from the TreeWalker interface and
from the TreeWalkerAdapter and TreeWalkerChain classes:

• setQueryComponent()
• walkSelectClause()
• walkFromClause()
• walkFunction()
• walkOrderByClause()
• walkOrderByItem()
• walkHavingClause()
• walkJoin()
• walkSelectExpression()
• walkQuantifiedExpression()
• walkSubselect()
• walkSubselectFromClause()
• walkSimpleSelectClause()
• walkSimpleSelectExpression()
• walkAggregateExpression()
• walkGroupByClause()
• walkGroupByItem()
• walkDeleteClause()
• walkUpdateClause()
• walkUpdateItem()
• walkWhereClause()
• walkConditionalExpression()
• walkConditionalTerm()
• walkConditionalFactor()
• walkConditionalPrimary()
• walkExistsExpression()
• walkCollectionMemberExpression()
• walkEmptyCollectionComparisonExpression()
• walkNullComparisonExpression()
• walkInExpression()
• walkInstanceOfExpression()
• walkLiteral()
• walkBetweenExpression()
• walkLikeExpression()
• walkStateFieldPathExpression()
• walkComparisonExpression()
• walkInputParameter()
• walkArithmeticExpression()
• walkArithmeticTerm()
• walkStringPrimary()
• walkArithmeticFactor()
• walkSimpleArithmeticExpression()
• walkPathExpression()
• walkResultVariable()
• getExecutor()

The following changes have been made to the abstract TreeWalkerAdapter class:

• The method setQueryComponent() is now protected.
• The method _getQueryComponents() has been removed in favor of
  getQueryComponents().

BC BREAK: Removed identity columns emulation through sequences

If the platform you are using does not support identity columns, you should
switch to the SEQUENCE strategy.

BC BREAK: Made setters parameters mandatory

The following methods require an argument when being called. Pass null
instead of omitting the argument.

• Doctrine\ORM\Event\OnClassMetadataNotFoundEventArgs::setFoundMetadata()
• Doctrine\ORM\AbstractQuery::setHydrationCacheProfile()
• Doctrine\ORM\AbstractQuery::setResultCache()
• Doctrine\ORM\AbstractQuery::setResultCacheProfile()

BC BREAK: New argument to NamingStrategy::joinColumnName()

Before

<?php
class MyStrategy implements NamingStrategy
{
    /**
     * @param string $propertyName A property name.
     */
    public function joinColumnName($propertyName): string
    {
        // …
    }
}

After

The class-string type for $className can be inherited from the signature of
the interface.

<?php
class MyStrategy implements NamingStrategy
{
    /**
     * {@inheritdoc}
     */
    public function joinColumnName(string $propertyName, string $className): string
    {
        // …
    }
}

BC BREAK: Remove StaticPHPDriver and DriverChain

Use Doctrine\Persistence\Mapping\Driver\StaticPHPDriver and
Doctrine\Persistence\Mapping\Driver\MappingDriverChain from
doctrine/persistence instead.

BC BREAK: UnderscoreNamingStrategy is number aware only

The second argument to UnderscoreNamingStrategy::__construct() was dropped,
the strategy can no longer be unaware of numbers.

BC BREAK: Remove Doctrine\ORM\Proxy\Autoloader

Use Doctrine\Common\Proxy\Autoloader instead.

BC BREAK: Remove Doctrine\ORM\Tools\DisconnectedClassMetadataFactory

No replacement is provided.

BC BREAK: Remove support for Type::canRequireSQLConversion()

This feature was deprecated in DBAL 3.3.0 and will be removed in DBAL 4.0.
The value conversion methods are now called regardless of the type.

The MappingException::sqlConversionNotAllowedForIdentifiers() method has been removed
as no longer relevant.

BC Break: Removed the doctrine binary.

The documentation explains how the console tools can be bootstrapped for
standalone usage:

https://www.doctrine-project.org/projects/doctrine-orm/en/stable/reference/tools.html

The method ConsoleRunner::printCliConfigTemplate() has been removed as well
because it was only useful in the context of the doctrine binary.

BC Break: Removed EntityManagerHelper and related logic

All console commands require a $entityManagerProvider to be passed via the
constructor. Commands won't try to get the entity manager from a previously
registered em console helper.

The following classes have been removed:

• Doctrine\ORM\Tools\Console\EntityManagerProvider\HelperSetManagerProvider
• Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper

The following breaking changes have been applied to Doctrine\ORM\Tools\Console\ConsoleRunner:

• The method createHelperSet() has been removed.
• The methods run() and createApplication() don't accept an instance of
  HelperSet as first argument anymore.
• The method addCommands() requires an instance of EntityManagerProvider
  as second argument now.

BC Break: Exception\ORMException is no longer a class, but an interface

All methods in Doctrine\ORM\ORMException have been extracted to dedicated exceptions.

• missingMappingDriverImpl() => Exception\MissingMappingDriverImplementation::create()
• unrecognizedField() => Persisters\Exception\UnrecognizedField::byName()
• unexpectedAssociationValue() => Exception\UnexpectedAssociationValue::create()
• invalidOrientation() => Persisters\Exception\InvalidOrientation::fromClassNameAndField()
• entityManagerClosed() => Exception\EntityManagerClosed::create()
• invalidHydrationMode() => Exception\InvalidHydrationMode::fromMode()
• mismatchedEventManager() => Exception\MismatchedEventManager::create()
• findByRequiresParameter() => Repository\Exception\InvalidMagicMethodCall::onMissingParameter()
• invalidMagicCall() => Repository\Exception\InvalidMagicMethodCall::becauseFieldNotFoundIn()
• invalidFindByInverseAssociation() => Repository\Exception\InvalidFindByCall::fromInverseSideUsage()
• invalidResultCacheDriver() => Cache\Exception\InvalidResultCacheDriver::create()
• notSupported() => Exception\NotSupported::create()
• queryCacheNotConfigured() => QueryCacheNotConfigured::create()
• metadataCacheNotConfigured() => Cache\Exception\MetadataCacheNotConfigured::create()
• queryCacheUsesNonPersistentCache() => Cache\Exception\QueryCacheUsesNonPersistentCache::fromDriver()
• metadataCacheUsesNonPersistentCache() => Cache\Exception\MetadataCacheUsesNonPersistentCache::fromDriver()
• proxyClassesAlwaysRegenerating() => Exception\ProxyClassesAlwaysRegenerating::create()
• invalidEntityRepository() => Exception\InvalidEntityRepository::fromClassName()
• missingIdentifierField() => Exception\MissingIdentifierField::fromFieldAndClass()
• unrecognizedIdentifierFields() => Exception\UnrecognizedIdentifierFields::fromClassAndFieldNames()
• cantUseInOperatorOnCompositeKeys() => Persisters\Exception\CantUseInOperatorOnCompositeKeys::create()

BC Break: CacheException is no longer a class, but an interface

All methods in Doctrine\ORM\Cache\CacheException have been extracted to dedicated exceptions.

• updateReadOnlyCollection() => Cache\Exception\CannotUpdateReadOnlyCollection::fromEntityAndField()
• updateReadOnlyEntity() => Cache\Exception\CannotUpdateReadOnlyEntity::fromEntity()
• nonCacheableEntity() => Cache\Exception\NonCacheableEntity::fromEntity()
• nonCacheableEntityAssociation() => Cache\Exception\NonCacheableEntityAssociation::fromEntityAndField()

BC Break: Missing type declaration added for identifier generators

Although undocumented, it was possible to configure a custom repository
class that implements ObjectRepository but does not extend the
EntityRepository base class. Repository classes have to extend
EntityRepository now.

BC BREAK: Removed support for entity namespace alias

• EntityManager::getRepository() no longer accepts the entity namespace alias
  notation.
• Configuration::addEntityNamespace() and
  Configuration::getEntityNamespace() have been removed.

BC BREAK: Remove helper methods from AbstractCollectionPersister

The following protected methods of
Doctrine\ORM\Cache\Persister\Collection\AbstractCollectionPersister
have been removed.

• evictCollectionCache()
• evictElementCache()

BC BREAK: Doctrine\ORM\Query\TreeWalkerChainIterator

This class has been removed without replacement.

BC BREAK: Remove quoting methods from ClassMetadata

The following methods have been removed from the class metadata because
quoting is handled by implementations of Doctrine\ORM\Mapping\QuoteStrategy:

• getQuotedIdentifierColumnNames()
• getQuotedColumnName()
• getQuotedTableName()
• getQuotedJoinTableName()

BC BREAK: Remove ability to merge detached entities

Merge semantics was a poor fit for the PHP "share-nothing" architecture.
In addition to that, merging caused multiple issues with data integrity
in the managed entity graph, which was constantly spawning more edge-case
bugs/scenarios.

The method UnitOfWork::merge() has been removed. The method
EntityManager::merge() will throw an exception on each call.

BC BREAK: Removed ability to partially flush/commit entity manager and unit of work

The following methods don't accept a single entity or an array of entities anymore:

• Doctrine\ORM\EntityManager::flush()
• Doctrine\ORM\Decorator\EntityManagerDecorator::flush()
• Doctrine\ORM\UnitOfWork::commit()

The semantics of flush() and commit() will remain the same, but the change
tracking will be performed on all entities managed by the unit of work, and not
just on the provided entities, as the parameter is now completely ignored.

BC BREAK: Removed ability to partially clear entity manager and unit of work

• Passing an argument other than null to EntityManager::clear() will raise
  an exception.
• The unit of work cannot be cleared partially anymore. Passing an argument to
  UnitOfWork::clear() does not have any effect anymore; the unit of work is
  cleared completely.
• The method EntityRepository::clear() has been removed.
• The methods getEntityClass() and clearsAllEntities() have been removed
  from OnClearEventArgs.

BC BREAK: Remove support for Doctrine Cache

The Doctrine Cache library is not supported anymore. The following methods
have been removed from Doctrine\ORM\Configuration:

• getQueryCacheImpl()
• setQueryCacheImpl()
• getHydrationCacheImpl()
• setHydrationCacheImpl()
• getMetadataCacheImpl()
• setMetadataCacheImpl()

The methods have been replaced by PSR-6 compatible counterparts
(just strip the Impl suffix from the old name to get the new one).

BC BREAK: Remove Doctrine\ORM\Configuration::newDefaultAnnotationDriver

This functionality has been moved to the new DoctrineSetup class. Call
Doctrine\ORM\Tools\DoctrineSetup::createDefaultAnnotationDriver() to create
a new annotation driver.

BC BREAK: Remove Doctrine\ORM\Tools\Setup

In our effort to migrate from Doctrine Cache to PSR-6, the Setup class which
accepted a Doctrine Cache instance in each method has been removed.

The replacement is Doctrine\ORM\Tools\DoctrineSetup which accepts a PSR-6
cache instead.

BC BREAK: Removed named queries

All APIs related to named queries have been removed.

BC BREAK: Remove old cache accessors and mutators from query classes

The following methods have been removed from AbstractQuery:

• setResultCacheDriver()
• getResultCacheDriver()
• useResultCache()
• getResultCacheLifetime()
• getResultCacheId()

The following methods have been removed from Query:

• setQueryCacheDriver()
• getQueryCacheDriver()

BC BREAK: Remove Doctrine\ORM\Cache\MultiGetRegion

The interface has been merged into Doctrine\ORM\Cache\Region.

BC BREAK: Rename AbstractIdGenerator::generate() to generateId()

• Implementations of AbstractIdGenerator have to implement the method
  generateId().
• The method generate() has been removed from AbstractIdGenerator.

BC BREAK: Remove cache settings inspection

Doctrine does not provide its own cache implementation anymore and relies on
the PSR-6 standard instead. As a consequence, we cannot determine anymore
whether a given cache adapter is suitable for a production environment.
Because of that, functionality that aims to do so has been removed:

• Configuration::ensureProductionSettings()
• the orm:ensure-production-settings console command

BC BREAK: PSR-6-based second level cache

The second level cache has been reworked to consume a PSR-6 cache. Using a
Doctrine Cache instance is not supported anymore.

• DefaultCacheFactory: The constructor expects a PSR-6 cache item pool as
  second argument now.
• DefaultMultiGetRegion: This class has been removed.
• DefaultRegion:
  • The constructor expects a PSR-6 cache item pool as second argument now.
  • The protected $cache property is removed.
  • The properties $name and $lifetime as well as the constant
    REGION_KEY_SEPARATOR and the method getCacheEntryKey() are
    private now.
  • The method getCache() has been removed.

BC Break: Remove Doctrine\ORM\Mapping\Driver\PHPDriver

Use StaticPHPDriver instead when you want to programmatically configure
entity metadata.

BC BREAK: Remove Doctrine\ORM\EntityManagerInterface#transactional()

This method has been replaced by Doctrine\ORM\EntityManagerInterface#wrapInTransaction().

BC BREAK: Removed support for schema emulation.

The ORM no longer attempts to emulate schemas on SQLite.

BC BREAK: Remove Setup::registerAutoloadDirectory()

Use Composer's autoloader instead.

BC BREAK: Remove YAML mapping drivers.

If your code relies on YamlDriver or SimpleYamlDriver, you MUST migrate to
attribute or XML drivers instead.

You can use the orm:convert-mapping command to convert your metadata mapping to XML
before upgrading to 3.0:

php doctrine orm:convert-mapping xml /path/to/mapping-path-converted-to-xml

BC BREAK: Remove code generators and related console commands

These console commands have been removed:

• orm:convert-d1-schema
• orm:convert-mapping
• orm:generate:entities
• orm:generate-repositories

These classes have been deprecated:

• Doctrine\ORM\Tools\ConvertDoctrine1Schema
• Doctrine\ORM\Tools\EntityGenerator
• Doctrine\ORM\Tools\EntityRepositoryGenerator

The entire Doctrine\ORM\Tools\Export namespace has been removed as well.

BC BREAK: Removed Doctrine\ORM\Version

Use Composer's runtime API if you really need to check the version of the ORM package at runtime.

BC BREAK: EntityRepository::count() signature change

The argument $criteria of Doctrine\ORM\EntityRepository::count() is now
optional. Overrides in child classes should be made compatible.

BC BREAK: changes in exception hierarchy

• Doctrine\ORM\ORMException has been removed
• Doctrine\ORM\Exception\ORMException is now an interface

Variadic methods now use native variadics

The following methods were using func_get_args() to simulate a variadic argument:

• Doctrine\ORM\Query\Expr#andX()
• Doctrine\ORM\Query\Expr#orX()
• Doctrine\ORM\QueryBuilder#select()
• Doctrine\ORM\QueryBuilder#addSelect()
• Doctrine\ORM\QueryBuilder#where()
• Doctrine\ORM\QueryBuilder#andWhere()
• Doctrine\ORM\QueryBuilder#orWhere()
• Doctrine\ORM\QueryBuilder#groupBy()
• Doctrine\ORM\QueryBuilder#andGroupBy()
• Doctrine\ORM\QueryBuilder#having()
• Doctrine\ORM\QueryBuilder#andHaving()
• Doctrine\ORM\QueryBuilder#orHaving()
  A variadic argument is now actually used in their signatures signature (...$x).
  Signatures of overridden methods should be changed accordingly

Minor BC BREAK: removed Doctrine\ORM\EntityManagerInterface#copy()

Method Doctrine\ORM\EntityManagerInterface#copy() never got its implementation and is removed in 3.0.

BC BREAK: Removed classes related to UUID and TABLE generator strategies

The following classes have been removed:

• Doctrine\ORM\Id\TableGenerator
• Doctrine\ORM\Id\UuidGenerator

Using the UUID strategy for generating identifiers is not supported anymore.

BC BREAK: Removed Query::iterate()

The deprecated method Query::iterate() has been removed along with the
following classes and methods:

• AbstractHydrator::iterate()
• AbstractHydrator::hydrateRow()
• IterableResult

Use toIterable() instead.