Merge pull request #2012 from alcaeus/document-more-bc-breaks

Document more BC breaks

Author: alcaeus

UPGRADE-1.3.md

@@ -1,5 +1,71 @@
 # UPGRADE FROM 1.2 TO 1.3
 
+## Aggregation builder
+
+ * The `debug`, `maxDistance` and `minDistance` methods in
+   `Doctrine\ODM\MongoDB\Aggregation\Stage\Match` have been deprecated and will
+   be removed in 2.0.
+ * The `Doctrine\ODM\MongoDB\Aggregation\Expr::ensureArray` method will be
+   private in 2.0.
+ * The `Doctrine\ODM\MongoDB\Aggregation\Stage\Bucket::convertExpression` method
+   will be private in 2.0.
+ * The `Doctrine\ODM\MongoDB\Aggregation\Stage\BucketAuto::convertExpression`
+   method will be private in 2.0.
+ * The following methods in `Doctrine\ODM\MongoDB\Aggregation\Stage\GraphLookup`
+   will be private in 2.0: `convertExpression`, `convertTargetFieldName`.
+ * The `Doctrine\ODM\MongoDB\Aggregation\Stage\ReplaceRoot::convertExpression`
+   method will be private in 2.0.
+ * Calling `Doctrine\MongoDB\Aggregation\Stage\Match::geoWithinPolygon` with
+   fewer than 3 arguments was deprecated and will cause errors in 2.0. A polygon
+   must have at least 3 edges to be considered valid.
+
+## Configuration
+
+ * The following methods in `Doctrine\ODM\MongoDB\Configuration` have been
+   deprecated and will be removed in MongoDB ODM 2.0: `getLoggerCallable`,
+   `getMongoCmd`, `getRetryConnect`, `getRetryQuery`, `setLoggerCallable`,
+   `setMongoCmd`, `setRetryConnect`, `setRetryQuery`.
+ * The `attributes` property will be private in MongoDB ODM 2.0 - if you are
+   extending the configuration class you should no longer rely on it.
+ * The `getDefaultRepositoryClassName` and `setDefaultRepositoryClassName`
+   methods in `Doctrine\ODM\MongoDB\Configuration` have been deprecated in favor
+   of `getDefaultDocumentRepositoryClassName` and
+   `setDefaultDocumentRepositoryClassName`, respectively.
+
+## Cursors
+
+ * The `Doctrine\ODM\MongoDB\Cursor`, `Doctrine\ODM\MongoDB\CommandCursor`, and
+   `Doctrine\ODM\MongoDB\EagerCursor` classes have been deprecated and will be
+   removed in 2.0. Their functionality will be covered by basic iterators. To
+   typehint an ODM specific iterator, use the new
+   `Doctrine\ODM\MongoDB\Iterator\Iterator` interface.
+
+## Document Class Generation
+
+Functionality regarding generation of document and repository classes was
+deprecated and will be dropped in 2.0. The following classes related to this
+functionality have been deprecated:
+ * `Doctrine\ODM\MongoDB\Query\FieldExtractor`
+ * `Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateDocumentsCommand`
+ * `Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateRepositoriesCommand`
+ * `Doctrine\ODM\MongoDB\Tools\DisconnectedClassMetadataFactory`
+ * `Doctrine\ODM\MongoDB\Tools\DocumentGenerator`
+ * `Doctrine\ODM\MongoDB\Tools\DocumentRepositoryGenerator`
+
+## Document Manager
+
+ * The `Doctrine\ODM\MongoDB\DocumentManager::createDBRef` method was deprecated
+   in favor of `createReference`. It will be dropped in 2.0.
+ * The `Doctrine\ODM\MongoDB\DocumentManager::getConnection` method was
+   deprecated and will be dropped in 2.0. The replacement, `getClient` will
+   return a `MongoDB\Client` instance, but is not available in 1.x.
+
+## Document Persister
+
+ * The `Doctrine\ODM\MongoDB\Persisters\DocumentPersister::prepareSortOrProjection`
+   method was deprecated and will be dropped in 2.0. Use `prepareSort` or
+   `prepareProjection` accordingly.
+
 ## Events
 
 ### `onClassMetadataNotFound` event added
@@ -80,6 +146,16 @@ The `Doctrine\ODM\MongoDB\Mapping\ClassMetadataInfo` class has been deprecated
 in favor of `Doctrine\ODM\MongoDB\Mapping\ClassMetadata` and will be dropped in
 2.0.
 
+### Obsolete features deprecated
+
+ * The following methods in `Doctrine\ODM\MongoDB\Mapping\ClassMetadata` were
+   deprecated and will be removed in 2.0: `getDistance`, `getFile`,
+   `getNamespace`, `isFile`, `mapFile`, `setDistance`, `setFile`,
+   `setRequireIndexes`, `setSlaveOkay`.
+ * The following properties `Doctrine\ODM\MongoDB\Mapping\ClassMetadata` were
+   deprecated and will be removed in 2.0: `distance`, `file`, `namespace`,
+   `requireIndexes`, `slaveOkay`.
+
 ### Annotation mappings
 
  * The `@NotSaved` annotation was deprecated and will be dropped in 2.0. Use the
@@ -91,6 +167,10 @@ in favor of `Doctrine\ODM\MongoDB\Mapping\ClassMetadata` and will be dropped in
  * The `dropDups` option on the `@Index` annotation was deprecated and will be 
    dropped without replacement in 2.0. This functionality is no longer
    available.
+ * The `simple` option on the `@ReferenceOne` and `@ReferenceMany` annotations
+   was deprecated and will be dropped in 2.0. Use `storeAs="id"` instead.
+ * The `@Distance` annotation was deprecated and will be dropped in 2.0. GeoNear
+   queries will no longer be supported, use the aggregation pipeline instead.
 
 ### XML mappings
 
@@ -101,7 +181,7 @@ in favor of `Doctrine\ODM\MongoDB\Mapping\ClassMetadata` and will be dropped in
  * The `drop-dups` attribute in the `index` element was deprecated and will be
    dropped without replacement in 2.0. This functionality is no longer
    available.
-   
+
 ### Full discriminator maps required
 
 When using a discriminator map on a reference or embedded relationship,
@@ -147,6 +227,40 @@ set.
  * The following methods in `Doctrine\ODM\MongoDB\Query\Builder` were deprecated
    and will be dropped in 2.0: `mapReduce`, `map`, `reduce`, `finalize`, `out`,
    `mapReduceOptions`, `distanceMultiplier`, `geoNear`, `spherical`.
+ * The following properties in `Doctrine\ODM\MongoDB\Query\Builder` will be
+   private in MongoDB ODM 2.0: `collection`, `expr`, `query`.
+ * The following properties in `Doctrine\ODM\MongoDB\Query\Expr` will be private
+   in MongoDB ODM 2.0: `currentField`, `newObj`, `query`.
+ * The `addManyToSet` and `pushAll` methods in
+   `Doctrine\ODM\MongoDB\Query\Builder` and `Doctrine\ODM\MongoDB\Query\Expr`
+   were deprecated and will be removed in 2.0. Use `each` in combination with
+   `addToSet` and `push` respectively.
+ * The following methods from `Doctrine\ODM\MongoDB\Query\Builder` and
+   `Doctrine\ODM\MongoDB\Query\Expr` were deprecated and will be removed in 2.0:
+   `maxDistance`, `minDistance`, `withinBox`, `withinCenter`,
+   `withinCenterSphere`, `withinPolygon`.
+ * The `Doctrine\MongoDB\Query\Query::count` method was deprecated and will be
+   removed in MongoDB ODM 2.0. Iterators will not be countable in 2.0. Users
+   should run separate count queries instead.
+ * The `Doctrine\MongoDB\Query\Query::iterate` method was deprecated and will be
+   removed in MongoDB ODM 2.0. Use `Doctrine\MongoDB\Query\Query::getIterator`
+   instead.
+ * The following properties in `Doctrine\ODM\MongoDB\Query\Query` will be
+   private in MongoDB ODM 2.0: `iterator`, `options`, `query`.
+ * The following constants in `Doctrine\ODM\MongoDB\Query\Query` will be removed
+   in MongoDB ODM 2.0: `HINT_READ_PREFERENCE_TAGS`, `HINT_SLAVE_OKAY`,
+   `TYPE_GEO_NEAR`.
+ * The `Doctrine\ODM\MongoDB\Query\Query::prepareCursor` method will be removed
+   in MongoDB ODM 2.0. You should wrap the returned cursor instead.
+ * Calling `Doctrine\MongoDB\Query\Builder::geoWithinPolygon` and
+   `Doctrine\MongoDB\Query\Expr::geoWithinPolygon` with fewer than 3 arguments
+   was deprecated and will cause errors in 2.0. A polygon must have at least 3
+   edges to be considered valid.
+
+## Repositories
+ * The `Doctrine\ODM\MongoDB\DocumentRepository` class was deprecated in favor
+   of `Doctrine\ODM\MongoDB\Repository\DocumentRepository` and will be dropped
+   in 2.0.
 
 ## Schema manager
 
@@ -155,3 +269,17 @@ set.
    option instead.
  * The `indexOptions` argument in the `ensureSharding` and
    `ensureDocumentSharding` methods was deprecated and will be dropped in 2.0.
+
+## Types
+
+ * The following classes in the `Doctrine\ODM\MongoDB\Types` namespace were
+   deprecated and will be removed in 2.0: `FileType`, `IncrementType`.
+ * The `FILE` and `INCREMENT` constants in `Doctrine\ODM\MongoDB\Types\Type`
+   were deprecated and will be removed in 2.0.
+
+## UnitOfWork
+
+ * The `isScheduledForDirtyCheck` and `scheduleForDirtyCheck` methods in
+   `Doctrine\ODM\MongoDB\UnitOfWork` have been deprecated and will be dropped in
+   2.0. Use `isScheduledForSynchronization` and `scheduleForSynchronization`
+   instead.

lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php

@@ -186,7 +186,7 @@ public function sortByCount($expression)
     public function sort($fieldName, $order = null)
     {
         $fields = is_array($fieldName) ? $fieldName : [$fieldName => $order];
-        return parent::sort($this->getDocumentPersister()->prepareSortOrProjection($fields));
+        return parent::sort($this->getDocumentPersister()->prepareSort($fields));
     }
 
     /**

lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php

@@ -23,6 +23,9 @@
 use Doctrine\MongoDB\Aggregation\Expr as BaseExpr;
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Types\Type;
+use const E_USER_DEPRECATED;
+use function sprintf;
+use function trigger_error;
 
 /**
  * Fluent interface for building aggregation pipelines.
@@ -64,9 +67,15 @@ public function field($fieldName)
     /**
      * @param mixed|self $expression
      * @return mixed
+     *
+     * @internal This method will be private in MongoDB ODM 2.0.
      */
     protected function ensureArray($expression)
     {
+        if (self::class !== static::class) {
+            @trigger_error(sprintf('The "%s" method will be private in MongoDB ODM 2.0. You should not rely on calling this method.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         // Convert field names in expressions
         if (is_string($expression) && substr($expression, 0, 1) === '$') {
             return '$' . $this->getDocumentPersister()->prepareFieldName(substr($expression, 1));

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Bucket.php

@@ -47,6 +47,10 @@ public function __construct(Builder $builder, DocumentManager $documentManager,
 
     protected function convertExpression($expression)
     {
+        if (self::class !== static::class) {
+            @trigger_error(sprintf('The "%s" method will be private in MongoDB ODM 2.0. You should not rely on calling this method.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         if (is_array($expression)) {
             return array_map([$this, 'convertExpression'], $expression);
         } elseif (is_string($expression) && substr($expression, 0, 1) === '$') {

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/BucketAuto.php

@@ -47,6 +47,10 @@ public function __construct(Builder $builder, DocumentManager $documentManager,
 
     protected function convertExpression($expression)
     {
+        if (self::class !== static::class) {
+            @trigger_error(sprintf('The "%s" method will be private in MongoDB ODM 2.0. You should not rely on calling this method.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         if (is_array($expression)) {
             return array_map([$this, 'convertExpression'], $expression);
         } elseif (is_string($expression) && substr($expression, 0, 1) === '$') {

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/GraphLookup.php

@@ -155,6 +155,10 @@ private function fromReference($fieldName)
 
     protected function convertExpression($expression)
     {
+        if (self::class !== static::class) {
+            @trigger_error(sprintf('The "%s" method will be private in MongoDB ODM 2.0. You should not rely on calling this method.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         if (is_array($expression)) {
             return array_map([$this, 'convertExpression'], $expression);
         } elseif (is_string($expression) && substr($expression, 0, 1) === '$') {
@@ -166,6 +170,10 @@ protected function convertExpression($expression)
 
     protected function convertTargetFieldName($fieldName)
     {
+        if (self::class !== static::class) {
+            @trigger_error(sprintf('The "%s" method will be private in MongoDB ODM 2.0. You should not rely on calling this method.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         if (is_array($fieldName)) {
             return array_map([$this, 'convertTargetFieldName'], $fieldName);
         }

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/Match.php

@@ -20,6 +20,11 @@
 namespace Doctrine\ODM\MongoDB\Aggregation\Stage;
 
 use Doctrine\MongoDB\Aggregation\Stage as BaseStage;
+use const E_USER_DEPRECATED;
+use function sprintf;
+use function func_get_args;
+use function func_num_args;
+use function trigger_error;
 
 /**
  * Fluent interface for building aggregation pipelines.
@@ -47,4 +52,52 @@ public function includesReferenceTo($document)
 
         return $this;
     }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @deprecated This method is deprecated and will be removed in MongoDB ODM 2.0.
+     */
+    public function debug($name = null)
+    {
+        @trigger_error(sprintf('The "%s" method is deprecated and will be removed in MongoDB ODM 2.0.', __METHOD__), E_USER_DEPRECATED);
+
+        return parent::debug($name);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function geoWithinPolygon()
+    {
+        if (func_num_args() < 3) {
+            @trigger_error(sprintf('Calling "%s" with fewer than 3 arguments was deprecated in MongoDB ODM 1.3 and will require at least 3 arguments in 2.0.', __METHOD__), E_USER_DEPRECATED);
+        }
+
+        return parent::geoWithinPolygon(...func_get_args());
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @deprecated This method is deprecated and will be removed in MongoDB ODM 2.0.
+     */
+    public function maxDistance($maxDistance)
+    {
+        @trigger_error(sprintf('The "%s" method is deprecated and will be removed in MongoDB ODM 2.0.', __METHOD__), E_USER_DEPRECATED);
+
+        return parent::maxDistance($maxDistance);
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @deprecated This method is deprecated and will be removed in MongoDB ODM 2.0.
+     */
+    public function minDistance($minDistance)
+    {
+        @trigger_error(sprintf('The "%s" method is deprecated and will be removed in MongoDB ODM 2.0.', __METHOD__), E_USER_DEPRECATED);
+
+        return parent::minDistance($minDistance);
+    }
 }

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/ReplaceRoot.php

@@ -47,6 +47,10 @@ public function __construct(Builder $builder, DocumentManager $documentManager,
 
     protected function convertExpression($expression)
     {
+        if (self::class !== static::class) {
+            @trigger_error(sprintf('The "%s" method will be private in MongoDB ODM 2.0. You should not rely on calling this method.', __METHOD__), E_USER_DEPRECATED);
+        }
+
         if (is_array($expression)) {
             return array_map([$this, 'convertExpression'], $expression);
         } elseif (is_string($expression) && substr($expression, 0, 1) === '$') {

lib/Doctrine/ODM/MongoDB/CommandCursor.php

@@ -29,6 +29,7 @@
  *
  * @since  1.1
  * @author alcaeus <[email protected]>
+ * @deprecated This class is deprecated and will be removed in 2.0. You should typehint against the {@see Iterator} interface instead.
  */
 class CommandCursor implements Iterator
 {