Skip to content

Commit d7ada46

Browse files
committed
fix: Update docs
1 parent f168ab0 commit d7ada46

1 file changed

Lines changed: 28 additions & 28 deletions

File tree

‎docs/models/entities.md‎

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -785,16 +785,18 @@ For objects and arrays, the Entity JSON-encodes and normalizes the values for co
785785

786786
!!! success "Available from version 4.8.0"
787787

788-
Your entity can have the initial state and contains all the necessary keys in the `$attributes`. When working with objects, you can rely on the fact that all properties are available. However, attributes missing from the query result are dropped, so reading them later fails or returns `null`.
788+
When a model loads a row into an entity, it calls `injectRawData()` with the selected columns. By default, this replaces the entity's attributes. In the example below, loading only `id` and `role` would drop both the `isBanned` default and the `profile` object created by the constructor.
789789

790-
Suppose there is no `isBanned` field in the table and the `profile` property is virtual and filled in another way.
790+
Set `$mergeAttributesOnInject` to `true` on your entity class to keep existing values for keys the row omits. For keys the row supplies, the incoming value takes precedence, including `null`. The entity also accepts incoming keys that were never declared in `$attributes`.
791791

792-
By default, with the `$mergeAttributesOnInject = false` you will get errors because by initialized properties are overwritten in `injectRawData()`.
793-
794-
<!-- lint-ignore -->
795792
```php
796793
<?php
797794

795+
namespace App\Entities;
796+
797+
use CodeIgniter\Entity\Entity;
798+
use stdClass;
799+
798800
class User extends Entity
799801
{
800802
protected $attributes = [
@@ -806,60 +808,58 @@ class User extends Entity
806808
public function __construct(?array $data = null)
807809
{
808810
parent::__construct($data);
809-
$this->attributes['profile'] = new \stdClass();
811+
$this->attributes['profile'] = new stdClass();
810812
}
811813
}
812814

813-
// Manual user creation
815+
// $mergeAttributesOnInject = false
816+
// 1. Manual user creation
814817
$user = new User();
815818

816819
// The initial values are exactly there
817820
var_dump(
821+
$user->role, // 'user'
818822
$user->isBanned, // '0'
819823
$user->toArray()['isBanned'], // '0'
820824
$user->profile instanceof stdClass, // true
821825
$user->hasChanged(), // true
822826
);
823827

824-
// The result does not contain these values: "isBanned", "profile"
828+
// 2. The result does not contain these values: "isBanned", "profile"
825829
$user2 = model(UserModel::class)->select('`id`, `role`')->find(10);
826830
// or manually
827831
$user2 = (new User())->injectRawData([
828832
'id' => 10,
829-
'role' => 'user',
833+
'role' => 'admin',
830834
]);
831835

832836
var_dump(
837+
$user2->role, // 'admin'
833838
$user2->isBanned, // null
834839
array_key_exists('isBanned', $user2->toArray()), // false
835-
$user2->profile instanceof \stdClass, // false
840+
$user2->profile instanceof stdClass, // false
836841
$user2->hasChanged(), // false
837842
);
838-
```
839843

840-
Setting the `$mergeAttributesOnInject = true` flag changes the behavior — it keeps the defaults from `$attributes`.
841-
After `injectRawData()`, the entire merged state becomes the entity's original state, including retained defaults. Consequently, `hasChanged()` returns `false` immediately after injection, even if an injected value differs from the default declared in `$attributes`.
842-
843-
<!-- lint-ignore -->
844-
```php
845-
<?php
846-
$user = (new User())->injectRawData([
844+
// $mergeAttributesOnInject = true
845+
$user3 = (new User())->injectRawData([
847846
'id' => 15,
848-
'role' => 'user',
847+
'role' => 'admin',
849848
]);
850849

851850
var_dump(
852-
$user->isBanned, // '0'
853-
$user->toArray()['isBanned'], // '0'
854-
$user->profile instanceof \stdClass, // true
855-
$user->hasChanged() // false
851+
$user3->role, // 'admin'
852+
$user3->isBanned, // '0'
853+
$user3->toArray()['isBanned'], // '0'
854+
$user3->profile instanceof stdClass, // true
855+
$user3->hasChanged(), // false
856856
);
857857
```
858858

859-
!!! note "Note"
860-
The flag does not matter if you have not defined the keys in `$attributes`.
859+
The direct call to `injectRawData()` illustrates what happens when a model configured to return `User` entities loads a row containing only `id` and `role`. The entity keeps the `isBanned` default and the `profile` object. It records the merged attributes as its original state, so `hasChanged()` returns `false` immediately after loading, even though the incoming role differs from the default.
860+
861+
### Updating a Partially Loaded Entity
861862

862-
Enabling this option also affects saving partially loaded entities. Suppose the entity defines `'isBanned' => '0'`, but the database row contains `'isBanned' = '1'`. If the model selects only `id` and `name`, the hydrated entity retains the default `'isBanned' = '0'`. With `Model::$updateOnlyChanged = false` and `isBanned` included in `$allowedFields`, changing `name` and saving this entity also overwrites the database `isBanned` with `'0'`, even though that column was never selected.
863+
An attribute retained after loading may differ from the value stored in the database. For example, suppose the `isBanned` column contains `'1'`. If the query selects only `id` and `role`, the loaded entity retains its default of `'0'` for `isBanned`.
863864

864-
In both cases, all additional keys that are passed in will still be accessible on the
865-
entity object, even if they are not listed in `$attributes`.
865+
With [`$updateOnlyChanged`](model.md#updateonlychanged) enabled (the default), changing `role` and updating the entity leaves the stored `isBanned` value alone. With `$updateOnlyChanged` disabled, the same update can also write `'0'` to `isBanned` if the field is in [`$allowedFields`](model.md#allowedfields). To update just the role, pass `['role' => $newRole]` to the model's `update()` method.

0 commit comments

Comments
 (0)