docs: add Hidden attribute documentation

Author: xHeaven

docs/1-essentials/03-database.md

@@ -447,6 +447,57 @@ final class Book
 }
 ```
 
+### Hidden properties
+
+Sensitive properties can be marked with the {b`#[Tempest\Mapper\Hidden]`} attribute to exclude them from SELECT queries. This is useful for properties like passwords, API keys, or other sensitive data that should not be fetched or exposed by default.
+
+```php
+use Tempest\Database\IsDatabaseModel;
+use Tempest\Mapper\Hidden;
+
+final class User
+{
+    use IsDatabaseModel;
+
+    public string $email;
+
+    #[Hidden]
+    public string $password;
+
+    #[Hidden]
+    public ?string $apiKey = null;
+}
+```
+
+Hidden properties are still included in INSERT and UPDATE queries, allowing them to be persisted to the database.
+
+To explicitly include hidden fields in a query, use the `include()` method on the query builder:
+
+```php
+// Password is not included in the query
+$user = User::select()->where('email', $email)->first();
+
+// Password is explicitly included
+$user = User::select()
+    ->include('password')
+    ->where('email', $email)
+    ->first();
+
+// Multiple hidden fields can be included
+$user = User::select()
+    ->include('password', 'apiKey')
+    ->where('email', $email)
+    ->first();
+```
+
+:::info
+Unlike {b`#[Virtual]`} which marks computed properties that don't exist in the database, {b`#[Hidden]`} is for real database columns that should be protected from accidental exposure.
+:::
+
+:::info
+The {b`#[Hidden]`} attribute also excludes properties from serialization. See the [mapper documentation](../2-features/01-mapper.md#hiding-properties-from-serialization) for more information.
+:::
+
 ### The `IsDatabaseModel` trait
 
 The {b`Tempest\Database\IsDatabaseModel`} trait provides an active record pattern. This trait enables database interaction via static methods on the model class itself.

docs/2-features/01-mapper.md

@@ -71,6 +71,40 @@ $array = map($book)->toArray();
 $json = map($book)->toJson();
 ```
 
+### Hiding properties from serialization
+
+Properties marked with the {b`#[Tempest\Mapper\Hidden]`} attribute are excluded from serialization. This is useful for sensitive data like passwords or API keys that should never be exposed in arrays or JSON responses.
+
+```php
+use Tempest\Mapper\Hidden;
+
+final class User
+{
+    public string $email;
+
+    #[Hidden]
+    public string $password;
+}
+```
+
+When serializing, hidden properties are automatically excluded:
+
+```php
+$user = new User();
+$user->email = 'user@example.com';
+$user->password = 'secret';
+
+$array = map($user)->toArray();
+// ['email' => 'user@example.com']
+
+$json = map($user)->toJson();
+// {"email":"user@example.com"}
+```
+
+:::info
+The {b`#[Hidden]`} attribute also excludes properties from database SELECT queries. See the [database documentation](../1-essentials/03-database.md#hidden-properties) for more information.
+:::
+
 ### Overriding field names
 
 When mapping from an array to an object, Tempest uses the property names of the target class to map the data. If a property name doesn't match a key in the source array, use the {b`#[Tempest\Mapper\MapFrom]`} attribute to specify the source key to map to the property.