Remove ActiveRecord::updateProperties() (#419)

Author: Tigrov

src/AbstractActiveRecord.php

@@ -675,9 +675,9 @@ public function assignOldValues(array|null $propertyValues = null): void
         $this->oldValues = $propertyValues;
     }
 
-    public function update(array|null $propertyNames = null): int
+    public function update(array|null $properties = null): int
     {
-        return $this->updateInternal($propertyNames);
+        return $this->updateInternal($properties);
     }
 
     public function updateAll(array $propertyValues, array|string $condition = [], array $params = []): int
@@ -689,32 +689,6 @@ public function updateAll(array $propertyValues, array|string $condition = [], a
         return $command->execute();
     }
 
-    public function updateProperties(array $properties): int
-    {
-        $names = [];
-
-        foreach ($properties as $name => $value) {
-            if (is_int($name)) {
-                $names[] = $value;
-            } else {
-                $this->set($name, $value);
-                $names[] = $name;
-            }
-        }
-
-        $values = $this->newValues($names);
-
-        if (empty($values) || $this->getIsNewRecord()) {
-            return 0;
-        }
-
-        $rows = $this->updateAll($values, $this->getOldPrimaryKey(true));
-
-        $this->oldValues = array_merge($this->oldValues ?? [], $values);
-
-        return $rows;
-    }
-
     /**
      * Updates the whole table using the provided counters and condition.
      *
@@ -1121,17 +1095,36 @@ protected function refreshInternal(array|ActiveRecordInterface|null $record = nu
     /**
      * {@see update()}
      *
-     * @param array|null $propertyNames Property names to update.
+     * @param array|null $properties Property names or name-values pairs to update, `null` means all properties.
      *
      * @throws Exception
      * @throws NotSupportedException
      * @throws StaleObjectException
      *
      * @return int The number of rows affected.
      */
-    protected function updateInternal(array|null $propertyNames = null): int
+    protected function updateInternal(array|null $properties = null): int
     {
-        $values = $this->newValues($propertyNames);
+        if ($this->getIsNewRecord()) {
+            throw new InvalidCallException('The record is new and cannot be updated.');
+        }
+
+        if ($properties === null) {
+            $names = $this->propertyNames();
+        } else {
+            $names = [];
+
+            foreach ($properties as $name => $value) {
+                if (is_int($name)) {
+                    $names[] = $value;
+                } else {
+                    $this->set($name, $value);
+                    $names[] = $name;
+                }
+            }
+        }
+
+        $values = $this->newValues($names);
 
         if (empty($values)) {
             return 0;

src/ActiveRecordInterface.php

@@ -10,7 +10,6 @@
 use Yiisoft\Db\Exception\Exception;
 use Yiisoft\Db\Exception\InvalidArgumentException;
 use Yiisoft\Db\Exception\InvalidConfigException;
-use Yiisoft\Db\Exception\NotSupportedException;
 
 interface ActiveRecordInterface
 {
@@ -390,6 +389,10 @@ public function set(string $propertyName, mixed $value): void;
 
     /**
      * Saves the changes to this active record into the associated database table.
+     * You may specify the properties to be updated as list of name or name-value pairs.
+     * If name-value pair specified, the corresponding property values will be modified.
+     *
+     * The method will then save the specified properties into a database.
      *
      * Only the {@see newValues() changed property values} will be saved into a database.
      *
@@ -402,6 +405,13 @@ public function set(string $propertyName, mixed $value): void;
      * $customer->update();
      * ```
      *
+     * To update a customer record with specific properties:
+     *
+     * ```php
+     *  $customer = new Customer();
+     *  $customer->update(['name' => $name, 'email' => $email]);
+     *  ```
+     *
      * Note that it's possible the update doesn't affect any row in the table.
      * In this case, this method will return 0.
      * For this reason, you should use the following code to check if update() is successful or not:
@@ -414,16 +424,16 @@ public function set(string $propertyName, mixed $value): void;
      * }
      * ```
      *
-     * @param array|null $propertyNames List of property names that need to be saved. Defaults to `null`, meaning all
-     * changed property values will be saved.
+     * @param array|null $properties List of property names or name-values pairs that need to be saved.
+     * Defaults to `null`, meaning all changed property values will be saved.
      *
      * @throws OptimisticLockException If the instance implements {@see OptimisticLockInterface} and the data being
      * updated is outdated.
      * @throws Throwable In case update failed.
      *
      * @return int The number of rows affected.
      */
-    public function update(array|null $propertyNames = null): int;
+    public function update(array|null $properties = null): int;
 
     /**
      * Updates the whole table using the provided property values and conditions.
@@ -461,27 +471,6 @@ public function update(array|null $propertyNames = null): int;
      */
     public function updateAll(array $propertyValues, array|string $condition = [], array $params = []): int;
 
-    /**
-     * Updates the specified properties.
-     *
-     * This method is a shortcut to {@see update()} when only a small set of properties need to be updated.
-     *
-     * You may specify the properties to be updated as name list or name-value pairs.
-     * If the latter, the corresponding property values will be modified so.
-     *
-     * The method will then save the specified properties into a database.
-     *
-     * Note that this method will **not** perform data validation and will **not** trigger events.
-     *
-     * @param array $properties The properties (names or name-value pairs) to be updated.
-     *
-     * @throws Exception
-     * @throws NotSupportedException
-     *
-     * @return int The number of rows affected.
-     */
-    public function updateProperties(array $properties): int;
-
     /**
      * Destroys the relationship between two records.
      *

tests/ActiveQueryTest.php

@@ -1919,20 +1919,31 @@ public function testUpdateProperties(): void
         $orderQuery = new ActiveQuery(Order::class);
         $order = $orderQuery->findByPk(1);
         $newTotal = 978;
-        $this->assertSame(1, $order->updateProperties(['total' => $newTotal]));
+        $this->assertSame(1, $order->update(['total' => $newTotal]));
         $this->assertEquals($newTotal, $order->getTotal());
 
-        $order = $orderQuery->findByPk(1);
+        $order->refresh();
         $this->assertEquals($newTotal, $order->getTotal());
 
+        // update only one property
+        $this->assertSame(1, $order->getCustomerId());
+
+        $order->set('total', 1000);
+        $order->set('customer_id', 2);
+
+        $this->assertSame(1, $order->update(['total']));
+        $order->refresh();
+        $this->assertEquals(1000, $order->getTotal());
+        $this->assertSame(1, $order->getCustomerId());
+
         /** @see https://github.com/yiisoft/yii2/issues/12143 */
         $newOrder = new Order();
         $this->assertTrue($newOrder->getIsNewRecord());
 
-        $newTotal = 200;
-        $this->assertSame(0, $newOrder->updateProperties(['total' => $newTotal]));
-        $this->assertTrue($newOrder->getIsNewRecord());
-        $this->assertEquals($newTotal, $newOrder->getTotal());
+        $this->expectException(InvalidCallException::class);
+        $this->expectExceptionMessage('The record is new and cannot be updated.');
+
+        $this->assertSame(0, $newOrder->update(['total' => 200]));
     }
 
     /**