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 4e7f9af
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/changelogs/v4.8.0.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -341,6 +341,7 @@ Release Date: Unreleased
341
341
### Others
342
342
343
343
-**Config:** Added optional `CodeIgniter\Config\Merge` directives for [Registrars](../general/configuration.md#registrars) to control replacing, deep merging, and ordered list additions. Existing registrar merge behavior is unchanged. See [Controlling how values are merged](../general/configuration.md#controlling-how-values-are-merged).
344
+
-**Entity:** Added a new `CodeIgniter\Entity\Entity::$mergeAttributesOnInject` property. See [Merging Attributes During Injection](../models/entities.md#merging-attributes-during-injection).
344
345
-**Float and Double Casting:** Added support for precision and rounding mode when casting to float or double in entities.
345
346
- Added `CodeIgniter\Input\InputData`, `ValidatedInput`, and `InputDataFactory` for reusable typed input data objects.
346
347
- Float and Double casting now throws `CastException::forInvalidFloatRoundingMode()` if a rounding mode other than up, down, even, or odd is provided.
Copy file name to clipboardExpand all lines: docs/models/entities.md
+85Lines changed: 85 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -780,3 +780,88 @@ For scalar values (strings, integers, floats, booleans, null), the Entity uses d
780
780
#### Objects and Arrays
781
781
782
782
For objects and arrays, the Entity JSON-encodes and normalizes the values for comparison. This means that modifications to nested structures, object properties, array elements, nested entities (using `toRawArray()`), enums (`BackedEnum` and `UnitEnum`), datetime objects (`DateTimeInterface`), collections (`Traversable`), value objects with `__toString()`, and objects implementing `JsonSerializable` or `toArray()` will be properly detected.
783
+
784
+
## Merging Attributes During Injection
785
+
786
+
!!! success "Available from version 4.8.0"
787
+
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
+
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
+
792
+
```php
793
+
<?php
794
+
795
+
namespace App\Entities;
796
+
797
+
use CodeIgniter\Entity\Entity;
798
+
use stdClass;
799
+
800
+
class User extends Entity
801
+
{
802
+
protected $attributes = [
803
+
'id' => null,
804
+
'role' => 'user',
805
+
'isBanned' => '0',
806
+
'profile' => null,
807
+
];
808
+
public function __construct(?array $data = null)
809
+
{
810
+
parent::__construct($data);
811
+
$this->attributes['profile'] = new stdClass();
812
+
}
813
+
}
814
+
815
+
// $mergeAttributesOnInject = false
816
+
// 1. Manual user creation
817
+
$user = new User();
818
+
819
+
// The initial values are exactly there
820
+
var_dump(
821
+
$user->role, // 'user'
822
+
$user->isBanned, // '0'
823
+
$user->toArray()['isBanned'], // '0'
824
+
$user->profile instanceof stdClass, // true
825
+
$user->hasChanged(), // true
826
+
);
827
+
828
+
// 2. The result does not contain these values: "isBanned", "profile"
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
862
+
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`.
864
+
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.
866
+
867
+
When `$skipValidation = false` and [`$cleanValidationRules = false`](model.md#cleanvalidationrules), `BaseModel::transformDataToArray()` extracts all attributes regardless of `$updateOnlyChanged`. Retained defaults can therefore overwrite omitted database columns even with `$updateOnlyChanged = true`.
0 commit comments