Skip to content

Latest commit

 

History

History
229 lines (196 loc) · 11.5 KB

UPGRADE-2.0.md

File metadata and controls

229 lines (196 loc) · 11.5 KB

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.

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.

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.

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

  • 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 $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.

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.
  • 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.

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.