From 7be559b9d5378f120178cbed9ffc45dd4f07f165 Mon Sep 17 00:00:00 2001 From: Tigrov Date: Fri, 1 May 2026 08:56:43 +0700 Subject: [PATCH] Update doc for insert, update and save methods --- src/ActiveRecordInterface.php | 31 +++++++++++++------------------ src/Event/BeforeInsert.php | 6 ++++-- src/Event/BeforePopulate.php | 4 ++-- src/Event/BeforeSave.php | 6 ++++-- src/Event/BeforeUpdate.php | 6 ++++-- src/Event/BeforeUpsert.php | 2 +- 6 files changed, 28 insertions(+), 27 deletions(-) diff --git a/src/ActiveRecordInterface.php b/src/ActiveRecordInterface.php index 8ad87bfae..c68bb9098 100644 --- a/src/ActiveRecordInterface.php +++ b/src/ActiveRecordInterface.php @@ -174,7 +174,7 @@ public function primaryKeyOldValue(): float|int|string|null; /** * Returns the old values of the primary key as an array with property names as keys and property values as values. * - * This refers to the primary key values that is populated into the record after data is retrieved from the database + * This refers to the primary key values that are populated into the record after data is retrieved from the database * by an instance of {@see ActiveQueryInterface}. * * The value remains unchanged while the record will not be {@see ActiveRecordInterface::update() updated}. @@ -342,11 +342,9 @@ public function hasMany(self|string $modelClass, array $link): ActiveQueryInterf public function hasOne(self|string $modelClass, array $link): ActiveQueryInterface; /** - * Inserts a row into the associated database table using the property values of this record. - * You may specify the properties to be inserted as list of name or name-value pairs. - * If name-value pair specified, the corresponding property values will be modified. + * Inserts a new row into the associated database table using the property values of this record. * - * Only the {@see ActiveRecordInterface::newValues()} changed property values will be inserted into a database. + * Only the {@see ActiveRecordInterface::newValues()} changed property values will be inserted into the database. * * If the table's primary key is auto incremental and is `null` during insertion, it will be populated with the * actual value after insertion. @@ -366,8 +364,9 @@ public function hasOne(self|string $modelClass, array $link): ActiveQueryInterfa * $customer->insert(['name' => $name, 'email' => $email]); * ``` * - * @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. + * @param array|null $properties List of property names or name-values pairs that need to be inserted. + * If name-value pairs are specified, the corresponding property values will be modified before insertion. + * Defaults to `null`, meaning all changed property values will be inserted. * * @throws InvalidCallException If the record {@see ActiveRecordInterface::isNew() is not new}. * @throws InvalidConfigException @@ -526,10 +525,8 @@ public function resetRelation(string $name): 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. * - * Only the {@see ActiveRecordInterface::newValues()} changed property values will be saved into a database. + * Only the {@see ActiveRecordInterface::newValues()} changed property values will be saved into the database. * * This method will call {@see ActiveRecordInterface::insert()} when {@see ActiveRecordInterface::isNew()} * is true, or {@see ActiveRecordInterface::update()} when {@see ActiveRecordInterface::isNew()} is false. @@ -550,6 +547,7 @@ public function resetRelation(string $name): void; * ``` * * @param array|null $properties List of property names or name-values pairs that need to be saved. + * If name-value pairs are specified, the corresponding property values will be modified before saving. * Defaults to `null`, meaning all changed property values will be saved. */ public function save(?array $properties = null): void; @@ -582,13 +580,9 @@ public function markAsNew(): void; public function markAsExisting(): 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. + * Updates the changes to this active record into the associated database table. * - * The method will then save the specified properties into a database. - * - * Only the {@see ActiveRecordInterface::newValues()} changed property values will be saved into a database. + * Only the {@see ActiveRecordInterface::newValues()} changed property values will be updated into the database. * * For example, to update a customer record: * @@ -617,8 +611,9 @@ public function markAsExisting(): void; * } * ``` * - * @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. + * @param array|null $properties List of property names or name-values pairs that need to be updated. + * If name-value pairs are specified, the corresponding property values will be modified before updating. + * Defaults to `null`, meaning all changed property values will be updated. * * @throws InvalidCallException If the record {@see ActiveRecordInterface::isNew() is new}. * @throws OptimisticLockException If the instance implements {@see OptimisticLockInterface} and the data being diff --git a/src/Event/BeforeInsert.php b/src/Event/BeforeInsert.php index 0ea2d878a..a8747bd34 100644 --- a/src/Event/BeforeInsert.php +++ b/src/Event/BeforeInsert.php @@ -8,7 +8,7 @@ /** * Event triggered before a new record is inserted into the database. - * It allows to modify properties that will be used for {@see ActiveRecordInterface::insert()} operation. + * It allows modifying properties that will be used for {@see ActiveRecordInterface::insert()} operation. * * @see ActiveRecordInterface::insert() */ @@ -16,7 +16,9 @@ final class BeforeInsert extends AbstractEvent { /** * @param ActiveRecordInterface $model The model that is being inserted. - * @param array|null &$properties The properties that will be used for the insert operation. + * @param array|null &$properties List of property names or name-values pairs that need to be inserted. + * If name-value pairs are specified, the values will be used for insertion. + * If `null`, the properties will be taken from the model. */ public function __construct(ActiveRecordInterface $model, public ?array &$properties) { diff --git a/src/Event/BeforePopulate.php b/src/Event/BeforePopulate.php index 3e5c8a0c0..8a6bd4500 100644 --- a/src/Event/BeforePopulate.php +++ b/src/Event/BeforePopulate.php @@ -8,7 +8,7 @@ /** * Event triggered before the model is populated with data. - * It allows to modify the data that will be used for {@see ActiveRecordInterface::populateRecord()} operation. + * It allows modifying the data that will be used for {@see ActiveRecordInterface::populateRecord()} operation. * * @see ActiveRecordInterface::populateRecord() */ @@ -16,7 +16,7 @@ final class BeforePopulate extends AbstractEvent { /** * @param ActiveRecordInterface $model The model that will be populated. - * @param array &$data The data that will be used to populate the model. + * @param array &$data Property values (name => value) to be assigned to the model. */ public function __construct(ActiveRecordInterface $model, public array &$data) { diff --git a/src/Event/BeforeSave.php b/src/Event/BeforeSave.php index 5b2528479..6715beb2a 100644 --- a/src/Event/BeforeSave.php +++ b/src/Event/BeforeSave.php @@ -8,7 +8,7 @@ /** * Event triggered before the model is saved (inserted or updated) to the database. - * It allows to modify properties that will be used for {@see ActiveRecordInterface::save()} operation. + * It allows modifying properties that will be used for {@see ActiveRecordInterface::save()} operation. * * @see ActiveRecordInterface::save() */ @@ -16,7 +16,9 @@ final class BeforeSave extends AbstractEvent { /** * @param ActiveRecordInterface $model The model that is being saved. - * @param array|null &$properties The properties that will be used for the save operation. + * @param array|null &$properties List of property names or name-values pairs that need to be saved. + * If name-value pairs are specified, the values will be used for saving. + * If `null`, the properties will be taken from the model. */ public function __construct(ActiveRecordInterface $model, public ?array &$properties) { diff --git a/src/Event/BeforeUpdate.php b/src/Event/BeforeUpdate.php index 376a8923b..e107be0b1 100644 --- a/src/Event/BeforeUpdate.php +++ b/src/Event/BeforeUpdate.php @@ -8,7 +8,7 @@ /** * Event triggered before the record is updated in the database. - * It allows to modify properties that will be used for {@see ActiveRecordInterface::update()} operation. + * It allows modifying properties that will be used for {@see ActiveRecordInterface::update()} operation. * * @see ActiveRecordInterface::update() */ @@ -16,7 +16,9 @@ final class BeforeUpdate extends AbstractEvent { /** * @param ActiveRecordInterface $model The model being updated. - * @param array|null &$properties The properties that will be used for the update operation. + * @param array|null &$properties List of property names or name-values pairs that need to be updated. + * If name-value pairs are specified, the values will be used for update. + * If `null`, the properties will be taken from the model. */ public function __construct(ActiveRecordInterface $model, public ?array &$properties) { diff --git a/src/Event/BeforeUpsert.php b/src/Event/BeforeUpsert.php index b9bfd94d8..399caf5fa 100644 --- a/src/Event/BeforeUpsert.php +++ b/src/Event/BeforeUpsert.php @@ -8,7 +8,7 @@ /** * Event triggered before the model is upserted (inserted or updated) in the database. - * It allows to modify properties that will be used for {@see ActiveRecordInterface::upsert()} operation. + * It allows modifying properties that will be used for {@see ActiveRecordInterface::upsert()} operation. * * @see ActiveRecordInterface::upsert() */