Add doc about ArrayAccessTrait and ArrayIteratorTrait (#456)

Author: Tigrov

README.md

@@ -178,8 +178,13 @@ $email = $user->get('email');
 
 ## Documentation
 
-- [Optimistic Locking](docs/optimistic-locking.md)
-- [Internals](docs/internals.md)
+- [Define the Database Connection for Active Record](docs/define-connection.md);
+- [Create Active Record Model](docs/create-model.md);
+- [Define Active Record Relations](docs/define-relations.md);
+- [Extending Functionality With Traits](docs/traits/traits.md);
+- [Using Dependency Injection With Active Record Model](docs/using-di.md);
+- [Optimistic Locking](docs/optimistic-locking.md);
+- [Internals](docs/internals.md).
 
 If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
 You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).

docs/create-model.md

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

docs/define-connection.md

@@ -1,4 +1,4 @@
-# Define the database connection for Active Record
+# Define the Database Connection for Active Record
 
 To use the Active Record, you need to define the DB connection in one of the following ways:
 

docs/define-relations.md

@@ -1,4 +1,4 @@
-# Active Record Relations
+# Define Active Record Relations
 
 ```mermaid
 erDiagram

docs/traits/array-access.md

@@ -0,0 +1,35 @@
+# ArrayAccessTrait
+
+`ArrayAccessTrait` implements [ArrayAccess](https://www.php.net/manual/en/class.arrayaccess.php) interface and allows accessing model properties and relations using array
+syntax.
+
+## Methods
+
+The following methods are provided by the `ArrayAccessTrait`:
+
+- `offsetExists($offset)` checks if the specified property or relation exists and is not null;
+- `offsetGet($offset)` retrieves the value of the specified property or relation;
+- `offsetSet($offset, $value)` sets the value of the specified property or relation;
+- `offsetUnset($offset)` unsets or sets to null the specified property or relation.
+
+## Usage
+
+```php
+use Yiisoft\ActiveRecord\ActiveRecord;
+use Yiisoft\ActiveRecord\Trait\ArrayAccessTrait;
+
+final class User extends ActiveRecord implements ArrayAccess
+{
+    use ArrayAccessTrait;
+    
+    protected string $username;
+}
+
+$user = new User();
+$user['username'] = 'admin'; // Set the property value using array syntax
+echo $user['username']; // Get the property value using array syntax
+unset($user['username']); // Unset the property or set it to null using array syntax
+isset($user['username']); // Check if the property exists and is not null using array syntax
+```
+
+Back to [Extending with traits](traits.md).

docs/traits/array-iterator.md

@@ -0,0 +1,34 @@
+# ArrayIteratorTrait
+
+`ArrayIteratorTrait` implements [IteratorAggregate](https://www.php.net/manual/en/class.iteratoraggregate.php) interface and allows accessing model properties iteratively.
+
+## Methods
+
+The following method is provided by the `ArrayIteratorTrait`:
+
+- `getIterator()` returns an `ArrayIterator` instance that allows iterating over the model's properties.
+
+## Usage
+
+```php
+use Yiisoft\ActiveRecord\ActiveRecord;
+use Yiisoft\ActiveRecord\Trait\ArrayIteratorTrait;
+
+final class User extends ActiveRecord implements IteratorAggregate
+{
+    use ArrayIteratorTrait;
+
+    public string $username;
+    public string $email;
+}
+
+$user = new User();
+$user->username = 'admin';
+$user->email = '[email protected]';
+
+foreach ($user as $property => $value) {
+    echo "$property: $value\n"; // Iterates over the model's properties
+}
+```
+
+Back to [Extending with traits](traits.md).

docs/traits/arrayable.md

@@ -1,23 +1,26 @@
 # 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.
+`ArrayableTrait` implements the [\Yiisoft\Arrays\ArrayableInterface](https://github.com/yiisoft/arrays/blob/master/src/ArrayableInterface.php) interface and 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.
+  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;
+use Yiisoft\Arrays\ArrayableInterface;
 
-class User extends ActiveRecord
+final class User extends ActiveRecord implements ArrayableInterface
 {
     use ArrayableTrait;
 
@@ -34,3 +37,5 @@ You can override the `fields()` and `extraFields()` methods in your `ActiveRecor
 and relations are included in the array representation.
 
 Both `fields()` and `extraFields()` may return values that are either strings or `Closure` instances.
+
+Back to [Extending with traits](traits.md).

docs/traits/traits.md

@@ -1,11 +1,11 @@
-# Extending with traits
+# Extending Functionality With 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;
+- [ArrayAccessTrait](array-access.md) allows accessing model properties and relations using array syntax;
+- [ArrayIteratorTrait](array-iterator.md) 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);
@@ -17,4 +17,4 @@ These traits can be included in your model classes to add specific behaviors or
   in a model;
 - `RepositoryTrait` provides methods to interact with a model as a repository.
 
-Back to [Create Active Record Model](../create-model.md)
+Back to [README](../../README.md)

src/Trait/ArrayableTrait.php

@@ -13,7 +13,7 @@
 use function array_keys;
 
 /**
- * Trait to implement {@see \Yiisoft\Arrays\ArrayableInterface} interface for ActiveRecord.
+ * Trait to implement {@see ArrayableInterface} interface for ActiveRecord.
  *
  * @method string[] propertyNames()
  * @see ActiveRecordInterface::propertyNames()