UPGRADE-2.0.md

UPGRADE FROM 1.x to 2.0

PHP requirements

• MongoDB ODM 2.0 requires PHP 7.2 or newer. If you're not running PHP 7.2 yet, it's recommended that you upgrade to PHP 7.2 before upgrading ODM. You can use alcaeus/mongo-php-adapter to use ODM 1.x with PHP 7.
• Most methods have been updated to include type hints where applicable. Please check your extension points to make sure the function signatures are correct.
• All files in ODM 2.0 use strict typing. Please make sure to not rely on type coercion.

MongoDB driver change

• MongoDB ODM 2.0 now requires the new MongoDB extension, ext-mongodb. If you've been using alcaeus/mongo-php-adapter you can remove it completely and use ODM 2.0 directly.
• doctrine/mongodb is no longer used by ODM. If you've been relying on its functionality, please update accordingly. Most utility classes from doctrine/mongodb have been merged into their ODM counterparts. Classes handling connections to MongoDB servers are being replaced by the MongoDB library (mongodb/mongodb).
• The constructor signature of Doctrine\ODM\MongoDB\DocumentManager as well as the create, getClient, getDocumentDatabase, getDocumentCollection, and getDocumentCollections methods have been updated to handle classes from mongodb/mongodb instead of doctrine/mongodb.

Commands

• The --depth option in the odm:query command was dropped without replacement.
• The --timeout option for all schema commands was dropped. You should use the --maxTimeMs option instead.

Aggregation builder

• The debug method in Doctrine\ODM\MongoDB\Aggregation\Stage\Match was dropped without replacement.

Configuration

• The setDefaultRepositoryClassName and getDefaultRepositoryClassName methods in Doctrine\ODM\MongoDB\Configuration have been renamed to setDefaultDocumentRepositoryClassName and getDefaultDocumentRepositoryClassName respectively.
• The setAutoGenerateProxyClasses and setAutoGenerateHydratorClasses methods no longer accept bool arguments. Use one of the AUTOGENERATE_* constants from the Configuration class instead.
• The setRetryConnect and setRetryQuery methods have been dropped without replacement. You should implement proper error handling instead of simply re-running queries or connection attempts.
• The AUTOGENERATE_ALWAYS and AUTOGENERATE_NEVER generation strategies for proxy objects have been removed. Use AUTOGENERATE_EVAL and AUTOGENERATE_FILE_NOT_EXISTS instead. This does not affect hydrator or collection generation strategies.

Cursor changes

• Methods that previously returned a MongoCursor instance no longer return a cursor directly but rather compose the cursor in iterators implementing the Doctrine\ODM\MongoDB\Iterator\Iterator interface. This class provides a toArray method in addition to the methods provided in PHP core's Iterator interface.
• The Doctrine\ODM\MongoDB\Cursor, Doctrine\ODM\MongoDB\EagerCursor, and Doctrine\ODM\MongoDB\CommandCursor classes has been dropped without replacement. You should always use the iterator interface mentioned above in type hints.

Document manager

• The flush method in Doctrine\ODM\MongoDB\DocumentManager no longer takes a $document as its first argument. Flushing single documents has been removed. If you don't want to implicitly flush changes in all documents to the database, consider using a different changeset computation strategy (e.g. explicit).
• The createDBRef method has been dropped in favor of createReference. This new method handles the creation of different kinds of references, not only DBRef.
• The $id argument in Doctrine\ODM\MongoDB\DocumentPersister::refresh has been dropped as it was never used.

GridFS

GridFS support has been adapted to the new GridFS specification. The following are no longer possible:

• Metadata must be stored in a metadata embedded document. Storing additional metadata in the root document is no longer supported. If you have documents that store metadata in the root document, migrate those documents to the new format.
• New files are no longer persisted by flushing the DocumentManager. Instead, they are uploaded using special methods in the new Doctrine\ODM\MongoDB\Repository\GridFSRepository class.
• The mapping of GridFS files has changed significantly: GridFS files are no longer mapped as documents but as files and there are specific annotations for the GridFS metadata fields.
• The file's binary data can be downloaded by using special methods in the Doctrine\ODM\MongoDB\Repository\GridFSRepository class. It is no longer directly accessible from the document.

Mapping

General mapping changes

• The Doctrine\ODM\MongoDB\Mapping\ClassMetadataInfo class was dropped and its functionality integrated into Doctrine\ODM\MongoDB\Mapping\ClassMetadata.
• The safe option for index creation has been dropped without replacement as this is no longer applicable to current versions of MongoDB.
• Combining repositoryMethod with sort or limit options on inverse references is no longer supported due to changes in the MongoDB driver.
• Repository methods used with repositoryMethod in inverse references now have to return an iterator of type Doctrine\ODM\MongoDB\Iterator\Iterator instead of a cursor.
• References use dbref as the default type when storing references instead of dbRefWithDB. This omits the $db key in the DBRef object when possible. This only has implications if you consume documents outside of ODM and require the $db key to be set or if you are using multiple databases to store data.
• The dropDups option on indexes has been dropped without replacement since it is no longer respected by MongoDB.

YAML mapping

The YAML mapping drivers have been removed. Please map your documents using XML or annotations. To migrate away from YAML mappings, first update to MongoDB ODM 1.3 and convert your mappings using the provided command.

XML mapping

• The XML driver validates the schema before applying the mapping. If your XML mapping file is invalid, ODM will not load it and throw an exception.
• Most mapping types now use choice instead of sequence, allowing you to map your documents in the order you prefer.
• The writeConcern attribute in the document element has been renamed to write-concern for consistency with other attributes.
• The require-indexes attribute in the document element has been dropped without replacement.
• The slave-okay attribute in the document element has been dropped. Use the read-preference element for more fine-grained read control.
• The field element no longer supports mapping identifiers. Use the id element instead. The id and id-generator-options attributes of field have been dropped in the process.
• The file attribute of field has been dropped. More information on this is available in the GridFS update chapter.
• The distance attribute of field has been dropped without replacement. If you've been using geoNear queries, you should refactor them to use the aggregation framework and $geoNear pipeline operator.
• The fieldName attribute of the field, embed-one, embed-many, reference-one, and reference-many elements has been renamed to field-name for consistency.
• The field, embed-one, embed-many, reference-one, and reference-many elements now support the not-saved, nullable, and also-load mapping options.
• The strategy attribute for embed-one and reference-one has been dropped. It was never used and does not apply to single-document relationships.
• The cascade element for documents now supports cascading detach operations to related documents.
• The safe attribute of index has been dropped without replacement.

Annotation mapping

• Combining @Document, @EmbeddedDocument, @File, @MappedSuperclass and @QueryResultDocument annotations on a single class will result in a MappingException.
• The $safe property in the @Index and @UniqueIndesx annotations has been dropped without replacement.
• The following annotation classes have been dropped in favor of specifying the type attribute in the Field annotation: Bin, BinCustom, BinFunc, BinMD5, BinUUID, BinUUIDRFC4122, Bool, Boolean, Collection, Date, Float, Hash, Increment, Int, Integer, Key, ObjectId, Raw, String, Timestamp.
• The NotSaved annotation has been dropped in favor of the notSaved attribute on the Field annotation. The notSaved attribute can also be applied to reference and embed mappings.
• The $name and $fieldName properties in the DiscriminatorField annotation class have been dropped. The field name is now passed via the default $value property.
• The Distance annotation class has been dropped without replacement. If you've been using geoNear queries, you should refactor them to use the aggregation framework and $geoNear pipeline operator.
• The DoctrineAnnotations.php loader has been removed. You should register a class loader in the AnnotationRegistry instead if you are using the ODM without a framework integration (e.g. doctrine/mongodb-odm-bundle).
• The requireIndexes option in the Document annotation has been dropped without replacement.
• The slaveOkay option in the Document annotation has been dropped. Use a ReadPreference annotation for more fine-grained read control.
• The File annotation class is no longer a field-level annotation but now used on a class. More information on this is available in the GridFS update chapter.
• The simple option for ReferenceOne and ReferenceMany annotations has been dropped. Use the storeAs option with an appropriate value instead.
• The registerAnnotationClasses method in Doctrine\ODM\MongoDB\Mapping\Driver\AnnotationDriver has been dropped without replacement. You should register a class loader in the AnnotationRegistry instead.

Same-namespace resolution dropped

With same-namespace resolution, the metadata driver would look for a class of that name in the same namespace if the given class name didn't contain a namespace separator (\). This is no longer supported, use fully qualified class names or the ::class constant instead:

/**
 * @ODM\Document(repositoryClass=UserRepository::class)
 */
class User
{
    /**
     * @ODM\ReferenceMany(targetDocument=Group::class)
     */
    private $groups;
}

This affects the repositoryClass attribute in documents, targetDocument in references and embedded relationships as well as class names in discriminator maps.

Proxy objects

The proxy implementation no longer relies on Doctrine proxies but rather the Proxy Manager library by ocramius. If you are checking for proxies, the following changed:

• Proxies no longer implement Doctrine\ODM\MongoDB\Proxy\Proxy or any other Doctrine proxy interface. To check whether a returned object is a proxy, check for the ProxyManager\Proxy\GhostObjectInterface interface.
• The __load method has been replaced by initializeProxy.
• The __isInitialized method has been replaced by isProxyInitialized.
• To resolve the original class name for a proxy object, you can no longer use the Doctrine\Common\Util\ClassUtils class. Instead, fetch the class name resolver from the document manager:

  $dm->getClassNameResolver()->getRealClass($className);

• The return value of the getClassNameResolver method was updated in 2.0.0. The previously returned Doctrine\ODM\MongoDB\Proxy\ClassNameResolver class was dropped in favour of the Doctrine\ODM\MongoDB\Proxy\Resolver\ClassNameResolver interface. This BC break was necessary to mitigate a performance regression. The getClass method was dropped from the interface as it wasn't being used.

Repository

• The Doctrine\ODM\MongoDB\DocumentRepository class has been renamed to Doctrine\ODM\MongoDB\Repository\DocumentRepository.
• The findBy* and findOneBy* magic methods have been dropped. Please create explicit methods or use the findBy and findOneBy methods instead.
• The Doctrine\ODM\MongoDB\Repository\DefaultRepositoryFactory class has been made final.

Query

• The requireIndexes method in Doctrine\ODM\MongoDB\Query\Builder has been dropped without replacement. If you want to require indexes for queries, use the notablescan option in the MongoDB server.
• Running geoNear commands through the geoNear helper in the query builder is no longer supported. Please refactor your queries to use the aggregation framework and $geoNear pipeline operator.
• Running group and mapReduce commands through the query builder is no longer supported. Please either refactor your queries to use the aggregation framework or use the MongoDB library (mongodb/mongodb) to execute these commands.
• The Doctrine\ODM\MongoDB\Query\FieldExtractor class was dropped entirely.
• The getIterator method in Doctrine\ODM\MongoDB\Query\Query returns an iterator of type Doctrine\ODM\MongoDB\Iterator\Iterator instead of a MongoDB cursor.
• The execute method in Doctrine\ODM\MongoDB\Query\Query now returns an iterator of type Doctrine\ODM\MongoDB\Iterator\Iterator for find queries, and a plain array for distinct queries.
• The eagerCursor helper in Doctrine\ODM\MongoDB\Query\Builder and its logic have been removed entirely without replacement.
• Querying for a mapped superclass in a complex inheritance chain will now only return children of that specific class instead of all classes in the inheritance tree.

Schema manager

• The schema manager no longer implicitly creates indexes covering the shard key when sharding a collection. While MongoDB creates this index automatically when sharding an empty collection, it is recommended users explicitly map an index covering the shard key.
• The createDatabases and createDocumentDatabases methods have been removed from Doctrine\ODM\MongoDB\SchemaManager. Databases are created implicitly in MongoDB 3.0.
• The --db argument to the odm:schema:create console command has been removed.

Tools

• The Doctrine\ODM\MongoDB\Tools\DisconnectedClassMetadataFactory class has been dropped without replacement.
• Document and repository generation was removed completely.

Types

• The Doctrine\ODM\MongoDB\Types\FileType class was removed completely.
• The Doctrine\ODM\MongoDB\Types\IncrementType class was removed completely. Use an increment strategy on the field mapping for int and float fields instead.

Unit of work

• The commit method in Doctrine\ODM\MongoDB\UnitOfWork no longer takes a $document as its first argument. Flushing single documents has been removed. If you don't want to implicitly flush changes in all documents to the database, consider using a different changeset computation strategy (e.g. explicit).
• Triggering a commit while one is already in progress will now cause an exception. This would usually happen if you flushed the document manager from within a lifecycle event handler. Since data integrity can't be guaranteed, it is no longer allowed to nest flushes to the database.
• The isScheduledForDirtyCheck and scheduleForDirtyCheck methods have been renamed to isScheduledForSynchronization and scheduleForSynchronization, respectively.

Internal classes and methods

Number of public methods and classes saw an @internal annotation added. This marks places which are considered private to ODM but can not become ones due to language limitations. Those methods can still be used (at your own risk) however the backward compatibility promise for them is relaxed: we reserve the right to change internal method's signatures and/or remove them altogether in minor releases. Should such change be made, a note shall be included in the UPGRADE.md file describing changes contained in the release.

Final classes

Following classes have been made final:

• Doctrine\ODM\MongoDB\DocumentNotFoundException
• Doctrine\ODM\MongoDB\Event\DocumentNotFoundEventArgs
• Doctrine\ODM\MongoDB\Event\LoadClassMetadataEventArgs
• Doctrine\ODM\MongoDB\Event\OnClassMetadataNotFoundEventArgs
• Doctrine\ODM\MongoDB\Event\OnClearEventArgs
• Doctrine\ODM\MongoDB\Event\OnFlushEventArgs
• Doctrine\ODM\MongoDB\Event\PostCollectionLoadEventArgs
• Doctrine\ODM\MongoDB\Event\PostFlushEventArgs
• Doctrine\ODM\MongoDB\Event\PreFlushEventArgs
• Doctrine\ODM\MongoDB\Event\PreLoadEventArgs
• Doctrine\ODM\MongoDB\Event\PreUpdateEventArgs
• Doctrine\ODM\MongoDB\Hydrator\HydratorException
• Doctrine\ODM\MongoDB\Hydrator\HydratorFactory
• Doctrine\ODM\MongoDB\Id\AlnumGenerator
• Doctrine\ODM\MongoDB\Id\AutoGenerator
• Doctrine\ODM\MongoDB\Id\IncrementGenerator
• Doctrine\ODM\MongoDB\Id\UuidGenerator
• Doctrine\ODM\MongoDB\LockException
• Doctrine\ODM\MongoDB\LockMode
• Doctrine\ODM\MongoDB\Mapping\ClassMetadataFactory
• Doctrine\ODM\MongoDB\Mapping\MappingException
• Doctrine\ODM\MongoDB\PersistentCollection
• Doctrine\ODM\MongoDB\PersistentCollection\PersistentCollectionException
• Doctrine\ODM\MongoDB\Persisters\CollectionPersister
• Doctrine\ODM\MongoDB\Persisters\DocumentPersister
• Doctrine\ODM\MongoDB\Persisters\PersistenceBuilder
• Doctrine\ODM\MongoDB\Proxy\Factory\StaticProxyFactory
• Doctrine\ODM\MongoDB\Query\CriteriaMerger
• Doctrine\ODM\MongoDB\Query\FilterCollection
• Doctrine\ODM\MongoDB\Query\Query
• Doctrine\ODM\MongoDB\Query\QueryExpressionVisitor
• Doctrine\ODM\MongoDB\Query\ReferencePrimer
• Doctrine\ODM\MongoDB\SchemaManager
• Doctrine\ODM\MongoDB\UnitOfWork
• Doctrine\ODM\MongoDB\Utility\CollectionHelper
• Doctrine\ODM\MongoDB\Utility\LifecycleEventManager