Merge pull request #1950 from alcaeus/deprecate-gridfs

[1.3] Deprecate GridFS mappings

UPGRADE-1.3.md

@@ -1,5 +1,13 @@
 # UPGRADE FROM 1.2 TO 1.3
 
+## GridFS
+
+GridFS support will be rewritten for 2.0 and was deprecated in its current form.
+A forward compatible layer cannot be provided due to differences in the
+underlying API.
+ * The `Doctrine\ODM\MongoDB\Mapping\Annotations\File` annotation was deprecated
+   and will be changed to a class-level annotation in 2.0.
+
 ## Mapping changes
 
 ### Yaml driver deprecated

doctrine-mongo-mapping.xsd

@@ -90,6 +90,7 @@
     <xs:attribute name="fieldName" type="xs:NMTOKEN" />
     <xs:attribute name="field-name" type="xs:NMTOKEN" />
     <xs:attribute name="embed" type="xs:boolean" />
+    <!-- deprecated -->
     <xs:attribute name="file" type="xs:boolean" />
     <xs:attribute name="distance" type="xs:boolean" />
     <xs:attribute name="reference" type="xs:boolean" />

lib/Doctrine/ODM/MongoDB/Mapping/Annotations/File.php

@@ -19,6 +19,8 @@
 
 namespace Doctrine\ODM\MongoDB\Mapping\Annotations;
 
+use function sprintf;
+
 /**
  * Maps a field as GridFS file and instructs ODM to store the entire document in
  * a GridFS collection.
@@ -29,4 +31,14 @@ final class File extends AbstractField
 {
     public $type = 'file';
     public $file = true;
+
+    public function getDeprecationMessage()
+    {
+        return sprintf('The "%s" annotation is deprecated and will be removed in 2.0. Please read the upgrade notes for GridFS.', self::class);
+    }
+
+    public function isDeprecated()
+    {
+        return true;
+    }
 }

lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php

@@ -219,6 +219,8 @@ class ClassMetadata implements BaseClassMetadata
     /**
      * READ-ONLY: The field that stores a file reference and indicates the
      * document is a file and should be stored on the MongoGridFS.
+     *
+     * @deprecated Will be dropped in 2.0. Please read the upgrade notes for GridFS.
      */
     public $file;
 
@@ -1274,6 +1276,8 @@ public function isMappedToCollection()
      * Returns TRUE if this Document is a file to be stored on the MongoGridFS FALSE otherwise.
      *
      * @return boolean
+     *
+     * @deprecated Will be dropped in 2.0. Please read the upgrade notes for GridFS.
      */
     public function isFile()
     {
@@ -1284,6 +1288,8 @@ public function isFile()
      * Returns the file field name.
      *
      * @return string $file The file field name.
+     *
+     * @deprecated Will be dropped in 2.0. Please read the upgrade notes for GridFS.
      */
     public function getFile()
     {
@@ -1294,6 +1300,8 @@ public function getFile()
      * Set the field name that stores the grid file.
      *
      * @param string $file
+     *
+     * @deprecated Will be dropped in 2.0. Please read the upgrade notes for GridFS.
      */
     public function setFile($file)
     {
@@ -1406,6 +1414,7 @@ public function mapField(array $mapping)
             $mapping['strategy'] = self::STORAGE_STRATEGY_INCREMENT;
         }
         if (isset($mapping['file']) && $mapping['file'] === true) {
+            @trigger_error(sprintf('The field "%s" for class "%s" is mapped as file. This is deprecated and will not be possible in 2.0. Please read the upgrade notes for GridFS.', $mapping['fieldName'], $this->getName()), E_USER_DEPRECATED);
             $this->file = $mapping['fieldName'];
             $mapping['name'] = 'file';
         }
@@ -1598,9 +1607,13 @@ private function applyStorageStrategy(array &$mapping)
      * Map a MongoGridFSFile.
      *
      * @param array $mapping The mapping information.
+     *
+     * @deprecated Will be dropped in 2.0. Please read the upgrade notes for GridFS.
      */
     public function mapFile(array $mapping)
     {
+        @trigger_error(sprintf('The "%s" method is deprecated and will be dropped in 2.0. Please read the upgrade notes for GridFS.', __METHOD__), E_USER_DEPRECATED);
+
         $mapping['file'] = true;
         $mapping['type'] = 'file';
         $this->mapField($mapping);

lib/Doctrine/ODM/MongoDB/Mapping/Driver/XmlDriver.php

@@ -188,6 +188,9 @@ public function loadMetadataForClass($className, ClassMetadata $class)
                     }
                 }
 
+                if (! empty($mapping['file'])) {
+                    @trigger_error('The "file" attribute to map GridFS files is deprecated and will be removed in 2.0. Please read the upgrade notes for GridFS.', E_USER_DEPRECATED);
+                }
 
                 if (isset($mapping['id']) && $mapping['id'] === true) {
                     @trigger_error(sprintf('Using the "id" attribute to denote identifiers in the XML mapping for class "%s" is deprecated and will be removed in 2.0. Please map your identifiers using the "id" element.', $class->getName()), E_USER_DEPRECATED);

lib/Doctrine/ODM/MongoDB/Types/FileType.php

@@ -23,6 +23,7 @@
  * The File type.
  *
  * @since       1.0
+ * @deprecated Will be dropped in 2.0. Please read the upgrade notes for GridFS.
  */
 class FileType extends Type
 {