docs: Note of hidden properties (codeigniter4#9754)

* docs: Note of hidden properties

* fix: Apply suggestions

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
     {

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,21 @@ 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
+=================
+
+An Entity may have hidden attributes - their names start with an underscore (``_``). By default, these hidden properties
+are not included when you call ``toArray()``. However, you can still access them directly if needed.
+
+If you want hidden properties to appear in the ``toArray()`` output, you'll need to use the ``datamap`` feature - it makes
+those properties "visible".
+
+Keep in mind that the smart ``__get()`` and ``__set()`` methods (described in the next section)  ignore leading underscores
+in property names. This means that two attributes with the same name (one starting with ``_`` and one without) will both use
+the same getter and setter, so you have to choose which one to handle by default.
+
+.. literalinclude:: entities/028.php
+
 ***********************
 Handling Business Logic
 ***********************

user_guide_src/source/models/entities/028.php

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