Add doc for CustomConnectionTrait and CustomTableNameTrait (#457)

Author: Tigrov

docs/traits/array-access.md

@@ -32,4 +32,4 @@ unset($user['username']); // Unset the property or set it to null using array sy
 isset($user['username']); // Check if the property exists and is not null using array syntax
 ```
 
-Back to [Extending with traits](traits.md).
+Back to [Extending Functionality With Traits](traits.md).

docs/traits/array-iterator.md

@@ -31,4 +31,4 @@ foreach ($user as $property => $value) {
 }
 ```
 
-Back to [Extending with traits](traits.md).
+Back to [Extending Functionality With Traits](traits.md).

docs/traits/arrayable.md

@@ -38,4 +38,4 @@ 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).
+Back to [Extending Functionality With Traits](traits.md).

docs/traits/custom-connection.md

@@ -0,0 +1,34 @@
+# CustomConnectionTrait
+
+`CustomConnectionTrait` allows using a custom database connection for a model class.
+
+## Methods
+
+The following method is provided by the `CustomConnectionTrait`:
+
+- `withConnectionName()` clones the current instance of Active Record then sets the connection name for the new instance
+  and returns the new instance.
+
+## Usage
+
+```php
+use Yiisoft\ActiveRecord\ActiveRecord;
+use Yiisoft\ActiveRecord\Trait\CustomConnectionTrait;
+
+final class User extends ActiveRecord
+{
+    use CustomConnectionTrait;
+}
+
+$user = new User();
+$users = $user->createQuery()->all(); // Uses 'default' connection
+$users = $user->withConnectionName('db2')->createQuery()->all(); // Uses 'db2' connection
+```
+
+Before using `db2` connection name, it should be configured in the application using
+`\Yiisoft\ActiveRecord\ConnectionProvider::set($db2Connection, 'db2')` method where `$db2Connection` is an instance of 
+`\Yiisoft\Db\Connection\ConnectionInterface`.
+
+See how to [Define the Database Connection for Active Record](../define-connection.md).
+
+Back to [Extending Functionality With Traits](traits.md).

docs/traits/custom-table-name.md

@@ -0,0 +1,28 @@
+# CustomTableNameTrait
+
+`CustomTableNameTrait` allows using a custom table name for a model class.
+
+## Methods
+
+The following method is provided by the `CustomTableNameTrait`:
+
+- `withTableName()` clones the current instance of Active Record then sets the table name for the new instance
+  and returns the new instance.
+
+## Usage
+
+```php
+use Yiisoft\ActiveRecord\ActiveRecord;
+use Yiisoft\ActiveRecord\Trait\CustomTableNameTrait;
+
+final class User extends ActiveRecord
+{
+    use CustomTableNameTrait;
+}
+
+$user = new User();
+$users = $user->createQuery()->all(); // Selects data from 'user' table
+$users = $user->withTableName('custom_user_table')->createQuery()->all(); // Selects data from 'custom_user_table' table
+```
+
+Back to [Extending Functionality With Traits](traits.md).

docs/traits/traits.md

@@ -6,8 +6,9 @@ These traits can be included in your model classes to add specific behaviors or
 - [ArrayableTrait](arrayable.md) provides `toArray()` method to convert a model to an array format;
 - [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;
+- [CustomConnectionTrait](custom-connection.md) allows using a custom database connection for a model;
+- [CustomTableNameTrait](custom-table-name.md) allows using a custom table name for a model;
+- `EventsTrait` allows using event handlers for model events;
 - `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;

src/Trait/CustomConnectionTrait.php

@@ -9,7 +9,7 @@
 use Yiisoft\Db\Connection\ConnectionInterface;
 
 /**
- * Trait to implement custom connection name for ActiveRecord.
+ * Trait to implement a custom connection name for ActiveRecord.
  *
  * @see AbstractActiveRecord::db()
  */

src/Trait/CustomTableNameTrait.php

@@ -5,7 +5,7 @@
 namespace Yiisoft\ActiveRecord\Trait;
 
 /**
- * Trait to implement custom table name for ActiveRecord.
+ * Trait to implement a custom table name for ActiveRecord.
  *
  * @see ActiveRecordInterface::tableName()
  */