Deprecate legacy commit options

docs/en/reference/working-with-objects.rst

@@ -133,8 +133,8 @@ Flush Options
 -------------
 
 When committing your documents you can specify an array of options to the
-``flush`` method. With it you can send options to the underlying database
-like ``safe``, ``fsync``, etc.
+``flush`` method. You can use this to pass a write options to the underlying
+operations, e.g. a custom write concern.
 
 Example:
 
@@ -145,7 +145,7 @@ Example:
     $user = $dm->getRepository(User::class)->find($userId);
     // ...
     $user->setPassword('changeme');
-    $dm->flush(null, ['safe' => true, 'fsync' => true]);
+    $dm->flush(['writeConcern' => new \MongoDB\Driver\WriteConcern(1)]);
 
 You can configure the default flush options on your ``Configuration`` object
 if you want to set them globally for all flushes.
@@ -157,16 +157,9 @@ Example:
     <?php
 
     $config->setDefaultCommitOptions(
-      [
-        'safe' => true,
-        'fsync' => true
-      ]
+      ['writeConcern' => new \MongoDB\Driver\WriteConcern(1)]
     );
 
-.. note::
-
-    Safe is set to true by default for all writes when using the ODM.
-
 Removing documents
 ------------------
 

lib/Doctrine/ODM/MongoDB/Configuration.php

@@ -32,6 +32,7 @@
 use Psr\Cache\CacheItemPoolInterface;
 use ReflectionClass;
 
+use function array_key_exists;
 use function interface_exists;
 use function trigger_deprecation;
 use function trim;
@@ -449,6 +450,17 @@ public function getDefaultCommitOptions(): array
     /** @psalm-param CommitOptions $defaultCommitOptions */
     public function setDefaultCommitOptions(array $defaultCommitOptions): void
     {
+        foreach (UnitOfWork::DEPRECATED_WRITE_OPTIONS as $deprecatedOption) {
+            if (array_key_exists($deprecatedOption, $defaultCommitOptions)) {
+                trigger_deprecation(
+                    'doctrine/mongodb-odm',
+                    '2.6',
+                    'The "%s" commit option used in the configuration is deprecated.',
+                    $deprecatedOption,
+                );
+            }
+        }
+
         $this->attributes['defaultCommitOptions'] = $defaultCommitOptions;
     }
 

lib/Doctrine/ODM/MongoDB/UnitOfWork.php

@@ -31,6 +31,7 @@
 use UnexpectedValueException;
 
 use function array_filter;
+use function array_key_exists;
 use function assert;
 use function count;
 use function get_class;
@@ -42,6 +43,7 @@
 use function serialize;
 use function spl_object_hash;
 use function sprintf;
+use function trigger_deprecation;
 
 /**
  * The UnitOfWork is responsible for tracking changes to objects during an
@@ -88,6 +90,9 @@ final class UnitOfWork implements PropertyChangedListener
      */
     public const STATE_REMOVED = 4;
 
+    /** @internal */
+    public const DEPRECATED_WRITE_OPTIONS = ['fsync', 'safe', 'w'];
+
     /**
      * The identity map holds references to all managed documents.
      *
@@ -393,6 +398,19 @@ public function setDocumentPersister(string $documentName, Persisters\DocumentPe
      */
     public function commit(array $options = []): void
     {
+        foreach (self::DEPRECATED_WRITE_OPTIONS as $deprecatedOption) {
+            if (! array_key_exists($deprecatedOption, $options)) {
+                continue;
+            }
+
+            trigger_deprecation(
+                'doctrine/mongodb-odm',
+                '2.6',
+                'The "%s" commit option is deprecated.',
+                $deprecatedOption,
+            );
+        }
+
         // Raise preFlush
         $this->evm->dispatchEvent(Events::preFlush, new Event\PreFlushEventArgs($this->dm));
 

phpcs.xml.dist

@@ -42,6 +42,12 @@
         <exclude name="SlevomatCodingStandard.TypeHints.UnionTypeHintFormat.DisallowedShortNullable" />
     </rule>
 
+    <rule ref="SlevomatCodingStandard.ControlStructures.EarlyExit">
+        <properties>
+            <property name="ignoreStandaloneIfInScope" value="true"/>
+        </properties>
+    </rule>
+
     <rule ref="PSR1.Classes.ClassDeclaration.MissingNamespace">
         <exclude-pattern>tests/Doctrine/ODM/MongoDB/Tests/Mapping/Documents/GlobalNamespaceDocument.php</exclude-pattern>
     </rule>