Add doc about traits

Author: Tigrov

docs/create-model.md

@@ -273,6 +273,8 @@ $orders = $user->getOrders();
 
 For more information on defining relations, see [Define Relations](define-relations.md).
 
-Also see [Using Dependency Injection With Active Record Model](using-di.md).
+Also see
+- [Using Dependency Injection With Active Record Model](using-di.md);
+- [Extending functionality with traits](traits/traits.md).
 
 Back to [README](../README.md)

docs/traits/arrayable.md

@@ -0,0 +1,36 @@
+# ArrayableTrait
+
+This trait provides methods to convert an `ActiveRecord` instance to an array format, using the `fields()`
+and `extraFields()` methods to determine which properties and relations should be included in the output.
+
+## Methods
+
+The following methods are provided by the `ArrayableTrait`:
+- `extraFields()` returns an associative array of relation names that can be included in the array representation 
+  of the record, with keys equal to values.
+- `fields()` returns an associative array of the record's property names, with keys equal to values.
+- `toArray()` converts the `ActiveRecord` instance to an array using the defined fields and extra fields.
+
+## Usage
+
+```php
+use Yiisoft\ActiveRecord\ActiveRecord;
+use Yiisoft\ActiveRecord\Trait\ArrayableTrait;
+
+class User extends ActiveRecord
+{
+    use ArrayableTrait;
+
+    // implement your own fields() and extraFields() if needed
+}
+
+$user = new User();
+$data = $user->toArray(); // Converts the user instance to an array
+```
+
+## Overrides
+
+You can override the `fields()` and `extraFields()` methods in your `ActiveRecord` class to customize which fields
+and relations are included in the array representation.
+
+Both `fields()` and `extraFields()` may return values that are either strings or `Closure` instances.

docs/traits/traits.md

@@ -0,0 +1,20 @@
+# Traits
+
+The library provides several traits that can be used to extend the functionality of `ActiveRecord` models.
+These traits can be included in your model classes to add specific behaviors or features.
+
+- [ArrayableTrait](arrayable.md) provides `toArray()` method to convert a model to an array format;
+- `ArrayAccessTrait` allows accessing model properties and relations using array syntax;
+- `ArrayIteratorTrait` allows accessing model properties and relations iteratively;
+- `CustomConnectionTrait` allows using a custom database connection for a model;
+- `CustomTableNameTrait` allows using a custom table name for a model;
+- `FactoryTrait` allows creating models and relations using [yiisoft/factory](https://github.com/yiisoft/factory);
+- `MagicPropertiesTrait` stores properties in a private property and provides magic getters
+  and setters for accessing the model properties and relations;
+- `MagicRelationsTrait` allows using methods with prefix `get` and suffix `Query` to define
+  relations (e.g. `getOrdersQuery()` for `orders` relation);
+- `PrivateProopertiesTrait` allows using [private properties](../create-model.md#private-properties) 
+  in a model;
+- `RepositoryTrait` provides methods to interact with a model as a repository.
+
+Back to [Create Active Record Model](../create-model.md)

src/Trait/ArrayableTrait.php

@@ -7,6 +7,7 @@
 use Closure;
 use Yiisoft\ActiveRecord\AbstractActiveRecord;
 use Yiisoft\ActiveRecord\ActiveRecordInterface;
+use Yiisoft\Arrays\ArrayableInterface;
 
 use function array_combine;
 use function array_keys;
@@ -19,14 +20,29 @@
  *
  * @method array relatedRecords()
  * @see AbstractActiveRecord::relatedRecords()
+ *
+ * @psalm-import-type FieldsArray from ArrayableInterface
  */
 trait ArrayableTrait
 {
     use \Yiisoft\Arrays\ArrayableTrait;
 
     /**
-     * @return array The default implementation returns the names of the relations that have been populated into this
-     * record.
+     * Returns the list of fields that can be expanded further and returned by {@see toArray()}.
+     *
+     * This method is similar to {@see fields()} except that the list of fields returned by this method are not returned
+     * by default by {@see toArray()}. Only when field names to be expanded are explicitly specified when calling
+     * {@see toArray()}, will their values be exported.
+     *
+     * The default implementation returns the names of the relations defined in this `ActiveRecord` class indexed by
+     * themselves.
+     *
+     * You may override this method to return a list of expandable fields.
+     *
+     * @return (string|Closure)[] The list of expandable field names or field definitions. Please refer
+     * to {@see fields()} on the format of the return value.
+     *
+     * @psalm-return FieldsArray
      */
     public function extraFields(): array
     {
@@ -36,7 +52,50 @@ public function extraFields(): array
     }
 
     /**
-     * @psalm-return array<string, string|Closure>
+     * Returns the list of fields that should be returned by default by {@see toArray()}.
+     *
+     * A field is a named element in the returned array by {@see toArray()}.
+     *
+     * This method should return an array of field names or field definitions.
+     * If the former, the field name will be treated as an object property name whose value will be used
+     * as the field value. If the latter, the array key should be the field name while the array value should be
+     * the corresponding field definition, which can be either an object property name or a PHP callable
+     * returning the corresponding field value. The signature of the callable should be:
+     *
+     * ```php
+     * function ($model, $field) {
+     *     // return field value
+     * }
+     * ```
+     *
+     * For example, the following code declares four fields:
+     *
+     * - `email`: the field name is the same as the property name `email`;
+     * - `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their
+     *   values are obtained from the `first_name` and `last_name` properties;
+     * - `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name`
+     *   and `last_name`.
+     *
+     * ```php
+     * return [
+     *     'email',
+     *     'firstName' => 'first_name',
+     *     'lastName' => 'last_name',
+     *     'fullName' => function () {
+     *         return $this->first_name . ' ' . $this->last_name;
+     *     },
+     * ];
+     * ```
+     *
+     * In this method, you may also want to return different lists of fields based on some context
+     * information. For example, depending on the privilege of the current application user,
+     * you may return different sets of visible fields or filter out some fields.
+     *
+     * The default implementation returns the names of the properties of this record indexed by themselves.
+     *
+     * @return (string|Closure)[] The list of field names or field definitions.
+     *
+     * @psalm-return FieldsArray
      */
     public function fields(): array
     {