You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d7ada46
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/models/entities.md
+28-28Lines changed: 28 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -785,16 +785,18 @@ For objects and arrays, the Entity JSON-encodes and normalizes the values for co
785
785
786
786
!!! success "Available from version 4.8.0"
787
787
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.
789
789
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`.
791
791
792
-
By default, with the `$mergeAttributesOnInject = false` you will get errors because by initialized properties are overwritten in `injectRawData()`.
793
-
794
-
<!-- lint-ignore -->
795
792
```php
796
793
<?php
797
794
795
+
namespace App\Entities;
796
+
797
+
use CodeIgniter\Entity\Entity;
798
+
use stdClass;
799
+
798
800
class User extends Entity
799
801
{
800
802
protected $attributes = [
@@ -806,60 +808,58 @@ class User extends Entity
806
808
public function __construct(?array $data = null)
807
809
{
808
810
parent::__construct($data);
809
-
$this->attributes['profile'] = new \stdClass();
811
+
$this->attributes['profile'] = new stdClass();
810
812
}
811
813
}
812
814
813
-
// Manual user creation
815
+
// $mergeAttributesOnInject = false
816
+
// 1. Manual user creation
814
817
$user = new User();
815
818
816
819
// The initial values are exactly there
817
820
var_dump(
821
+
$user->role, // 'user'
818
822
$user->isBanned, // '0'
819
823
$user->toArray()['isBanned'], // '0'
820
824
$user->profile instanceof stdClass, // true
821
825
$user->hasChanged(), // true
822
826
);
823
827
824
-
// The result does not contain these values: "isBanned", "profile"
828
+
// 2. The result does not contain these values: "isBanned", "profile"
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([
847
846
'id' => 15,
848
-
'role' => 'user',
847
+
'role' => 'admin',
849
848
]);
850
849
851
850
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
856
856
);
857
857
```
858
858
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
861
862
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`.
863
864
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