Split combined getter/setter EntityInterface::isNew().

isNew() now only acts as getter and new method setNew() has been added as setter.

src/Datasource/EntityInterface.php

@@ -41,6 +41,7 @@ use JsonSerializable;
  * @method array extractOriginal(array $properties)
  * @method array extractOriginalChanged(array $properties)
  * @method array getVisible()
+ * @method $this setNew($new)
  *
  * @property mixed $id Alias for commonly used primary key.
  */

src/Datasource/EntityTrait.php

@@ -884,32 +884,41 @@ trait EntityTrait
     }
 
     /**
-     * Returns whether or not this entity has already been persisted.
-     * This method can return null in the case there is no prior information on
-     * the status of this entity.
+     * Set the status of this entity.
      *
-     * If called with a boolean it will set the known status of this instance,
-     * true means that the instance is not yet persisted in the database, false
-     * that it already is.
+     * Using `true` means that the entity has not been persisted in the database,
+     * `false` that it already is.
      *
-     * @param bool|null $new true if it is known this instance was not yet persisted
-     * @return bool Whether or not the entity has been persisted.
+     * @param bool $new Indicate whether or not this entity has been persisted.
+     * @return $this
      */
-    public function isNew($new = null)
+    public function setNew($new)
     {
-        if ($new === null) {
-            return $this->_new;
-        }
-
-        $new = (bool)$new;
-
         if ($new) {
             foreach ($this->_properties as $k => $p) {
                 $this->_dirty[$k] = true;
             }
         }
 
-        return $this->_new = $new;
+        $this->_new = $new;
+
+        return $this;
+    }
+
+    /**
+     * Returns whether or not this entity has already been persisted.
+     *
+     * @param bool|null $new true if it is known this instance was not yet persisted.
+     * This will be deprecated in 4.0, use `setNew()` instead.
+     * @return bool Whether or not the entity has been persisted.
+     */
+    public function isNew($new = null): bool
+    {
+        if ($new !== null) {
+            $this->setNew($new);
+        }
+
+        return $this->_new;
     }
 
     /**

src/ORM/Association/BelongsToMany.php

@@ -844,7 +844,7 @@ class BelongsToMany extends Association
             // as new, we let save() sort out whether or not we have a new link
             // or if we are updating an existing link.
             if ($changedKeys) {
-                $joint->isNew(true);
+                $joint->setNew(true);
                 $joint->unsetProperty($junction->getPrimaryKey())
                     ->set(array_merge($sourceKeys, $targetKeys), ['guard' => false]);
             }

src/ORM/Entity.php

@@ -60,7 +60,7 @@ class Entity implements EntityInterface, InvalidPropertyInterface
         }
 
         if ($options['markNew'] !== null) {
-            $this->isNew($options['markNew']);
+            $this->setNew($options['markNew']);
         }
 
         if (!empty($properties) && $options['markClean'] && !$options['useSetters']) {

src/ORM/Table.php

@@ -1940,7 +1940,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
             }
             if ($options['atomic'] || $options['_primary']) {
                 $entity->clean();
-                $entity->isNew(false);
+                $entity->setNew(false);
                 $entity->setSource($this->getRegistryAlias());
             }
         }
@@ -1988,7 +1988,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
             foreach ($entity->extract($primaryColumns) as $k => $v) {
                 $conditions["$alias.$k"] = $v;
             }
-            $entity->isNew(!$this->exists($conditions));
+            $entity->setNew(!$this->exists($conditions));
         }
 
         $mode = $entity->isNew() ? RulesChecker::CREATE : RulesChecker::UPDATE;
@@ -2029,7 +2029,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
 
         if (!$success && $isNew) {
             $entity->unsetProperty($this->getPrimaryKey());
-            $entity->isNew(true);
+            $entity->setNew(true);
         }
 
         return $success ? $entity : false;
@@ -2066,7 +2066,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
 
         if (!$options['atomic'] && !$options['_primary']) {
             $entity->clean();
-            $entity->isNew(false);
+            $entity->setNew(false);
             $entity->setSource($this->getRegistryAlias());
         }
 
@@ -2236,7 +2236,7 @@ class Table implements RepositoryInterface, EventListenerInterface, EventDispatc
             foreach ($entities as $key => $entity) {
                 if (isset($isNew[$key]) && $isNew[$key]) {
                     $entity->unsetProperty($this->getPrimaryKey());
-                    $entity->isNew(true);
+                    $entity->setNew(true);
                 }
             }
         };

tests/TestCase/ORM/Behavior/TimestampBehaviorTest.php

@@ -141,7 +141,7 @@ class TimestampBehaviorTest extends TestCase
 
         $event = new Event('Model.beforeSave');
         $entity = new Entity(['name' => 'Foo']);
-        $entity->isNew(false);
+        $entity->setNew(false);
 
         $return = $this->Behavior->handleEvent($event, $entity);
         $this->assertTrue($return, 'Handle Event is expected to always return true');
@@ -163,7 +163,7 @@ class TimestampBehaviorTest extends TestCase
 
         $event = new Event('Model.beforeSave');
         $entity = new Entity(['name' => 'Foo']);
-        $entity->isNew(false);
+        $entity->setNew(false);
 
         $return = $this->Behavior->handleEvent($event, $entity);
         $this->assertTrue($return, 'Handle Event is expected to always return true');
@@ -188,7 +188,7 @@ class TimestampBehaviorTest extends TestCase
         $existingValue = new \DateTime('2011-11-11');
         $entity = new Entity(['name' => 'Foo', 'modified' => $existingValue]);
         $entity->clean();
-        $entity->isNew(false);
+        $entity->setNew(false);
 
         $return = $this->Behavior->handleEvent($event, $entity);
         $this->assertTrue($return, 'Handle Event is expected to always return true');

tests/TestCase/ORM/EntityTest.php

@@ -922,13 +922,10 @@ class EntityTest extends TestCase
         $entity = new Entity($data);
         $this->assertTrue($entity->isNew());
 
-        $entity->isNew(true);
+        $entity->setNew(true);
         $this->assertTrue($entity->isNew());
 
-        $entity->isNew('derpy');
-        $this->assertTrue($entity->isNew());
-
-        $entity->isNew(false);
+        $entity->setNew(false);
         $this->assertFalse($entity->isNew());
     }
 
@@ -961,18 +958,18 @@ class EntityTest extends TestCase
      */
     public function testConstructorWithMarkNew()
     {
-        $entity = $this->getMockBuilder('\Cake\ORM\Entity')
-            ->setMethods(['isNew', 'clean'])
+        $entity = $this->getMockBuilder('Cake\ORM\Entity')
+            ->setMethods(['setNew', 'clean'])
             ->disableOriginalConstructor()
             ->getMock();
         $entity->expects($this->never())->method('clean');
         $entity->__construct(['a' => 'b', 'c' => 'd']);
 
-        $entity = $this->getMockBuilder('\Cake\ORM\Entity')
-            ->setMethods(['isNew'])
+        $entity = $this->getMockBuilder('Cake\ORM\Entity')
+            ->setMethods(['setNew'])
             ->disableOriginalConstructor()
             ->getMock();
-        $entity->expects($this->once())->method('isNew');
+        $entity->expects($this->once())->method('setNew');
         $entity->__construct(['a' => 'b', 'c' => 'd'], ['markNew' => true]);
     }
 
@@ -1667,7 +1664,7 @@ class EntityTest extends TestCase
         $this->assertFalse($entity->isDirty());
 
         $cloned = clone $entity;
-        $cloned->isNew(true);
+        $cloned->setNew(true);
 
         $this->assertTrue($cloned->isDirty());
         $this->assertTrue($cloned->isDirty('a'));

tests/TestCase/ORM/MarshallerTest.php

@@ -1326,7 +1326,7 @@ class MarshallerTest extends TestCase
             'body' => 'My Content'
         ]);
         $entity->setAccess('*', true);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $entity->clean();
         $result = $marshall->merge($entity, $data, []);
 
@@ -1355,7 +1355,7 @@ class MarshallerTest extends TestCase
             'body' => 'My Content'
         ]);
         $entity->setAccess('*', false);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $entity->clean();
         $result = $marshall->merge($entity, $data, ['accessibleFields' => ['body' => true]]);
 
@@ -1413,7 +1413,7 @@ class MarshallerTest extends TestCase
             'body' => null
         ]);
         $entity->setAccess('*', true);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $entity->clean();
         $result = $marshall->merge($entity, $data, []);
 
@@ -1439,7 +1439,7 @@ class MarshallerTest extends TestCase
         ]);
         $entity->setAccess('*', false);
         $entity->setAccess('author_id', true);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $entity->clean();
 
         $result = $marshall->merge($entity, $data, []);
@@ -2708,7 +2708,7 @@ class MarshallerTest extends TestCase
             'author_id' => 2
         ]);
         $entity->setAccess('*', false);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $entity->clean();
         $result = $marshall->merge($entity, $data, ['fields' => ['title', 'body']]);
 
@@ -3141,7 +3141,7 @@ class MarshallerTest extends TestCase
         $this->assertEmpty($entity->getInvalid());
 
         $entity->setAccess('*', true);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $entity->clean();
 
         $this->articles->getValidator()
@@ -3183,7 +3183,7 @@ class MarshallerTest extends TestCase
             'author_id' => 1
         ]);
         $entity->setAccess('*', true);
-        $entity->isNew(true);
+        $entity->setNew(true);
         $entity->clean();
 
         $this->articles->getValidator()
@@ -3197,7 +3197,7 @@ class MarshallerTest extends TestCase
         $this->assertEmpty($result->getError('thing'));
 
         $entity->clean();
-        $entity->isNew(false);
+        $entity->setNew(false);
         $result = $marshall->merge($entity, $data, []);
         $this->assertNotEmpty($result->getError('author_id'));
         $this->assertNotEmpty($result->getError('thing'));

tests/TestCase/ORM/ResultSetTest.php

@@ -140,7 +140,7 @@ class ResultSetTest extends TestCase
         // Use a loop to test Iterator implementation
         foreach ($results as $i => $row) {
             $expected = new Entity($this->fixtureData[$i]);
-            $expected->isNew(false);
+            $expected->setNew(false);
             $expected->setSource($this->table->getAlias());
             $expected->clean();
             $this->assertEquals($expected, $row, "Row $i does not match");

tests/TestCase/ORM/TableTest.php

@@ -3076,7 +3076,7 @@ class TableTest extends TestCase
             ));
 
         $table = $this->getTableLocator()->get('users', ['eventManager' => $mock]);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $table->delete($entity, ['checkRules' => false]);
     }
 
@@ -3160,7 +3160,7 @@ class TableTest extends TestCase
             }));
 
         $table = $this->getTableLocator()->get('users', ['eventManager' => $mock]);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $result = $table->delete($entity, ['checkRules' => false]);
         $this->assertNull($result);
     }
@@ -3184,7 +3184,7 @@ class TableTest extends TestCase
             }));
 
         $table = $this->getTableLocator()->get('users', ['eventManager' => $mock]);
-        $entity->isNew(false);
+        $entity->setNew(false);
         $result = $table->delete($entity, ['checkRules' => false]);
         $this->assertEquals('got stopped', $result);
     }
@@ -3205,7 +3205,7 @@ class TableTest extends TestCase
         $table->expects($this->never())
             ->method('query');
 
-        $entity->isNew(true);
+        $entity->setNew(true);
         $result = $table->delete($entity);
         $this->assertFalse($result);
     }
@@ -4041,10 +4041,10 @@ class TableTest extends TestCase
                 ]
             ]),
         ]);
-        $entity->isNew(true);
-        $entity->author->isNew(true);
-        $entity->author->supervisor->isNew(true);
-        $entity->author->tags[0]->isNew(true);
+        $entity->setNew(true);
+        $entity->author->setNew(true);
+        $entity->author->supervisor->setNew(true);
+        $entity->author->tags[0]->setNew(true);
 
         $articles->expects($this->once())
             ->method('_insert')
@@ -6217,7 +6217,7 @@ class TableTest extends TestCase
 
         $cloned = clone $article;
         $cloned->unsetProperty('id');
-        $cloned->isNew(true);
+        $cloned->setNew(true);
         $this->assertSame($cloned, $table->save($cloned));
         $this->assertEquals(
             $article->extract(['title', 'author_id']),