Make the `$cleanProperty` argument part of `$options`.

src/ORM/Association/BelongsToMany.php

@@ -698,8 +698,16 @@ class BelongsToMany extends Association
      * target entities. This method assumes that all passed objects are already persisted
      * in the database and that each of them contain a primary key value.
      *
-     * By default this method will also unset each of the entity objects stored inside
-     * the source entity.
+     * ### Options
+     *
+     * Additionally to the default options accepted by `Table::delete()`, the following
+     * keys are supported:
+     *
+     * - cleanProperty: Whether or not to remove all the objects in `$targetEntities` that
+     * are stored in `$sourceEntity` (default: true)
+     *
+     * By default this method will unset each of the entity objects stored inside the
+     * source entity.
      *
      * ### Example:
      *
@@ -715,15 +723,22 @@ class BelongsToMany extends Association
      * this association
      * @param array $targetEntities list of entities persisted in the target table for
      * this association
-     * @param bool $cleanProperty whether or not to remove all the objects in $targetEntities
-     * that are stored in $sourceEntity
-     * @param array $options list of options to be passed to the internal `delete` call
+     * @param array|bool $options list of options to be passed to the internal `delete` call,
+     * or a `boolean`
      * @throws \InvalidArgumentException if non persisted entities are passed or if
      * any of them is lacking a primary key value
      * @return void
      */
-    public function unlink(EntityInterface $sourceEntity, array $targetEntities, $cleanProperty = true, array $options = [])
+    public function unlink(EntityInterface $sourceEntity, array $targetEntities, $options = [])
     {
+        if (is_bool($options)) {
+            $options = [
+                'cleanProperty' => $options
+            ];
+        } else {
+            $options += ['cleanProperty' => true];
+        }
+
         $this->_checkPersistenceStatus($sourceEntity, $targetEntities);
         $property = $this->property();
 
@@ -737,7 +752,7 @@ class BelongsToMany extends Association
         );
 
         $existing = $sourceEntity->get($property) ?: [];
-        if (!$cleanProperty || empty($existing)) {
+        if (!$options['cleanProperty'] || empty($existing)) {
             return;
         }
 

src/ORM/Association/HasMany.php

@@ -245,8 +245,16 @@ class HasMany extends Association
      * target entities. This method assumes that all passed objects are already persisted
      * in the database and that each of them contain a primary key value.
      *
-     * By default this method will also unset each of the entity objects stored inside
-     * the source entity.
+     * ### Options
+     *
+     * Additionally to the default options accepted by `Table::delete()`, the following
+     * keys are supported:
+     *
+     * - cleanProperty: Whether or not to remove all the objects in `$targetEntities` that
+     * are stored in `$sourceEntity` (default: true)
+     *
+     * By default this method will unset each of the entity objects stored inside the
+     * source entity.
      *
      * Changes are persisted in the database and also in the source entity.
      *
@@ -266,15 +274,21 @@ class HasMany extends Association
      * this association
      * @param array $targetEntities list of entities persisted in the target table for
      * this association
-     * @param bool $cleanProperty whether or not to remove all the objects in $targetEntities
-     * that are stored in $sourceEntity
      * @param array $options list of options to be passed to the internal `delete` call
      * @throws \InvalidArgumentException if non persisted entities are passed or if
      * any of them is lacking a primary key value
      * @return void
      */
-    public function unlink(EntityInterface $sourceEntity, array $targetEntities, $cleanProperty = true, array $options = [])
+    public function unlink(EntityInterface $sourceEntity, array $targetEntities, $options = [])
     {
+        if (is_bool($options)) {
+            $options = [
+                'cleanProperty' => $options
+            ];
+        } else {
+            $options += ['cleanProperty' => true];
+        }
+
         $foreignKey = (array)$this->foreignKey();
         $target = $this->target();
         $targetPrimaryKey = array_merge((array)$target->primaryKey(), $foreignKey);
@@ -290,7 +304,7 @@ class HasMany extends Association
 
         $this->_unlink($foreignKey, $target, $conditions, $options);
 
-        if ($cleanProperty) {
+        if ($options['cleanProperty']) {
             $sourceEntity->set(
                 $property,
                 (new Collection($sourceEntity->get($property)))

tests/TestCase/ORM/Association/BelongsToManyTest.php

@@ -656,7 +656,7 @@ class BelongsToManyTest extends TestCase
             ->method('delete')
             ->with($jointEntities[1]);
 
-        $assoc->unlink($entity, $tags, false);
+        $assoc->unlink($entity, $tags, ['cleanProperty' => false]);
         $this->assertEquals($tags, $entity->get('test'));
     }
 

tests/TestCase/ORM/TableTest.php

@@ -4120,7 +4120,7 @@ class TableTest extends TestCase
 
         $articlesToUnlink = [ $author->articles[0], $author->articles[1] ];
 
-        $authors->Articles->unlink($author, $articlesToUnlink, false);
+        $authors->Articles->unlink($author, $articlesToUnlink, ['cleanProperty' => false]);
 
         $this->assertCount($sizeArticles - count($articlesToUnlink), $authors->Articles->findAllByAuthorId($author->id));
         $this->assertCount($sizeArticles, $author->articles);
@@ -4611,13 +4611,14 @@ class TableTest extends TestCase
 
         $article = $articles->get(1);
 
-        $tags->unlink($article, [$tags->target()->get(2)], true, ['foo' => 'bar']);
+        $tags->unlink($article, [$tags->target()->get(2)], ['foo' => 'bar']);
 
         $expected = [
             '_primary' => true,
             'foo' => 'bar',
             'atomic' => true,
-            'checkRules' => true
+            'checkRules' => true,
+            'cleanProperty' => true
         ];
         $this->assertEquals($expected, $actualOptions);
     }
@@ -4783,13 +4784,14 @@ class TableTest extends TestCase
         $author->articles = [];
         $author->dirty('articles', true);
 
-        $articles->unlink($author, [$articles->target()->get(1)], true, ['foo' => 'bar']);
+        $articles->unlink($author, [$articles->target()->get(1)], ['foo' => 'bar']);
 
         $expected = [
             '_primary' => true,
             'foo' => 'bar',
             'atomic' => true,
-            'checkRules' => true
+            'checkRules' => true,
+            'cleanProperty' => true
         ];
         $this->assertEquals($expected, $actualOptions);
     }
@@ -4859,6 +4861,70 @@ class TableTest extends TestCase
     }
 
     /**
+     * Tests backwards compatibility of the the `$options` argument, formerly `$cleanProperty`.
+     *
+     * @return void
+     */
+    public function testBackwardsCompatibilityForBelongsToManyUnlinkCleanPropertyOption()
+    {
+        $articles = TableRegistry::get('Articles');
+        $tags = $articles->belongsToMany('Tags');
+
+        $actualOptions = null;
+        $tags->junction()->eventManager()->on(
+            'Model.beforeDelete',
+            function (Event $event, Entity $entity, ArrayObject $options) use (&$actualOptions) {
+                $actualOptions = $options->getArrayCopy();
+            }
+        );
+
+        $article = $articles->get(1);
+
+        $tags->unlink($article, [$tags->target()->get(1)], false);
+        $this->assertArrayHasKey('cleanProperty', $actualOptions);
+        $this->assertFalse($actualOptions['cleanProperty']);
+
+        $actualOptions = null;
+        $tags->unlink($article, [$tags->target()->get(2)]);
+        $this->assertArrayHasKey('cleanProperty', $actualOptions);
+        $this->assertTrue($actualOptions['cleanProperty']);
+    }
+
+    /**
+     * Tests backwards compatibility of the the `$options` argument, formerly `$cleanProperty`.
+     *
+     * @return void
+     */
+    public function testBackwardsCompatibilityForHasManyUnlinkCleanPropertyOption()
+    {
+        $authors = TableRegistry::get('Authors');
+        $articles = $authors->hasMany('Articles');
+        $articles->dependent(true);
+        $articles->cascadeCallbacks(true);
+
+        $actualOptions = null;
+        $articles->target()->eventManager()->on(
+            'Model.beforeDelete',
+            function (Event $event, Entity $entity, ArrayObject $options) use (&$actualOptions) {
+                $actualOptions = $options->getArrayCopy();
+            }
+        );
+
+        $author = $authors->get(1);
+        $author->articles = [];
+        $author->dirty('articles', true);
+
+        $articles->unlink($author, [$articles->target()->get(1)], false);
+        $this->assertArrayHasKey('cleanProperty', $actualOptions);
+        $this->assertFalse($actualOptions['cleanProperty']);
+
+        $actualOptions = null;
+        $articles->unlink($author, [$articles->target()->get(3)]);
+        $this->assertArrayHasKey('cleanProperty', $actualOptions);
+        $this->assertTrue($actualOptions['cleanProperty']);
+    }
+
+    /**
      * Tests that it is possible to call find with no arguments
      *
      * @return void