docs: Note of hidden properties

Author: neznaika0

tests/system/Entity/EntityTest.php

@@ -46,7 +46,7 @@ public function testSetStringToPropertyNamedAttributes(): void
     }
 
     /**
-     * @see https://github.com/codeigniter4/CodeIgniter4/issues
+     * @see https://github.com/codeigniter4/CodeIgniter4/issues/5762
      */
     public function testSetArrayToPropertyNamedAttributes(): void
     {
@@ -1094,6 +1094,52 @@ public function testJsonSerializableEntity(): void
         $this->assertSame(json_encode($entity->toArray()), json_encode($entity));
     }
 
+    public function testInjectRawArray(): void
+    {
+        $entity = new class () extends Entity {
+            // The "user" property is not for DB
+            protected $attributes = [
+                'type'    => 'Normal',
+                'limit'   => 10,
+                'user'    => 'John',
+                '_secure' => 'High',
+            ];
+            protected $original = [
+                'type'    => 'None',
+                'limit'   => 0,
+                'user'    => null,
+                '_secure' => 'Low',
+            ];
+        };
+
+        $entity->injectRawData([
+            'type'    => 'High',
+            'limit'   => 15,
+            '_secure' => 'Normal',
+            'extra'   => 'undefined',
+        ]);
+
+        $this->assertSame(
+            [
+                'type'    => 'High',
+                'limit'   => 15,
+                'user'    => 'John',
+                '_secure' => 'Normal',
+                'extra'   => 'undefined',
+            ],
+            $entity->toRawArray(),
+        );
+        $this->assertSame(
+            [
+                'type'  => 'High',
+                'limit' => 15,
+                'user'  => 'John',
+                'extra' => 'undefined',
+            ],
+            $entity->toArray(),
+        );
+    }
+
     private function getEntity(): object
     {
         return new class () extends Entity {

user_guide_src/source/models/entities.rst

@@ -40,7 +40,7 @@ Assume you have a database table named ``users`` that has the following schema::
     password    - string
     created_at  - datetime
 
-.. important:: ``attributes`` is a reserved word for internal use. If you use it as a column name, the Entity does not work correctly.
+.. important:: ``attributes`` is a reserved word for internal use. Prior to v4.4.0, if you use it as a column name, the Entity does not work correctly.
 
 Create the Entity Class
 =======================
@@ -118,6 +118,14 @@ Using the raw version will bypass magic "getter" methods and casts. Both methods
 to specify whether returned values should be filtered by those that have changed, and a boolean final parameter to
 make the method recursive, in case of nested Entities.
 
+Hidden properties
+=================
+
+It is possible to set properties that are only available in raw form. The property must start with an underscore. Casting cannot be applied to such fields.
+This is created so that we allow our magic methods a chance to do their thing, but you can use it in another way.
+
+.. literalinclude:: entities/028.php
+
 ***********************
 Handling Business Logic
 ***********************

user_guide_src/source/models/entities/028.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Entities;
+
+use CodeIgniter\Entity\Entity;
+
+class User extends Entity
+{
+    protected $attributes = [
+        '__secure' => 'On',
+        'about'    => '',
+    ];
+}
+
+$user = new User(['__secure' => 'Off', 'about' => 'Hi, I am John!']);
+
+print_r($user->toArray());
+print_r($user->toRawArray());
+
+/**
+ * Output:
+ * (
+ *     [about] => Hi, I am John!
+ * )
+ * Array
+ * (
+ *     [__secure] => Off
+ *     [about]   => Hi, I am John!
+ * )
+ */