Моделі
======

Моделі є частиною архітектури [MVC](http://uk.wikipedia.org/wiki/Модель-вид-контролер).
Це об’єкти, які представляють бізнес-дані, бізнес-правила та бізнес-логіку.

Ви можете створювати класи моделей шляхом розширення класу [[yii\base\Model]] або його нащадків. Базовий клас
[[yii\base\Model]] підтримує багато корисних можливостей:

* [Атрибути](#attributes): представляють бізнес-дані та можуть бути доступними як звичайні властивості об’єкту
  або як елементи масиву;
* [Мітки атрибутів](#attribute-labels): визначають мітки, які використовуються при відображенні атрибутів;
* [Масове призначення](#massive-assignment): підтримується заповнення декількох атрибутів одним кроком;
* [Правила перевірки](#validation-rules): забезпечують ввід даних на основі оголошених правил перевірки;
* [Експортування даних](#data-exporting): дозволяє даним моделі бути експортованими у масиви з налаштуванням форматів.

Клас `Model` також є базовим класом для більш розширених моделей, таких як [Active Record](db-active-record.md).
Будь ласка, зверніться до відповідної документації для більш детальної інформації про ці розширені моделі.

> Інформація: Не обов’язково створювати класи моделей на базі класу [[yii\base\Model]]. Однак, оскільки багато компонентів Yii
  побудовані так, щоб підтримувати [[yii\base\Model]], краще використовувати його як базовий клас для моделей.


## Атрибути <span id="attributes"></span>

Моделі представляють бізнес-дані у вигляді *атрибутів*. Кожний атрибут є публічно доступною властивістю
моделі. Метод [[yii\base\Model::attributes()]] визначає, які атрибути має клас моделі.

Ви можете отримати доступ до атрибута як до звичайної властивості об’єкту:

```php
$model = new \app\models\ContactForm;

// "name" - це атрибут моделі ContactForm
$model->name = 'example';
echo $model->name;
```

Ви також можете отримувати доступ до атрибутів як до елементів масиву, завдяки підтримці
[ArrayAccess](http://php.net/manual/en/class.arrayaccess.php) та [ArrayIterator](http://php.net/manual/en/class.arrayiterator.php)
у класі [[yii\base\Model]]:

```php
$model = new \app\models\ContactForm;

// доступ до атрибутів як до елементів масиву
$model['name'] = 'example';
echo $model['name'];

// перебір атрибутів
foreach ($model as $name => $value) {
    echo "$name: $value\n";
}
```


### Визначення атрибутів <span id="defining-attributes"></span>

За замовчуванням, якщо ваш клас моделі успадкований безпосередньо від [[yii\base\Model]], усі його *не статичні публічні*
змінні є атрибутами. Наприклад, клас моделі `ContactForm`, наведений нижче, має чотири атрибути: `name`, `email`,
`subject` і `body`. Модель `ContactForm` використовується для презентування вхідних даних, отриманих з HTML-форми.

```php
namespace app\models;

use yii\base\Model;

class ContactForm extends Model
{
    public $name;
    public $email;
    public $subject;
    public $body;
}
```


Ви можете перевизначити метод [[yii\base\Model::attributes()]] для визначення атрибутів в інший спосіб. Метод повинен
повертати імена атрибутів у моделі. Наприклад, [[yii\db\ActiveRecord]] повертає
імена колонок відповідної таблиці бази даних як імена атрибутів. Також можливо знадобиться перевизначити
магічні методи, такі як `__get()` і `__set()`, щоб атрибути могли бути доступними як
звичайні властивості об’єкту.


### Мітки атрибутів <span id="attribute-labels"></span>

При відображенні значень чи при отриманні вводу для атрибутів, часто необхідно відобразити деякі написи, пов’язані з
атрибутами. Наприклад, якщо атрибут має ім’я `firstName`, ви можете відобразити мітку `First Name`, яка є більш зручною
для користувача при відображенні кінцевим користувачам у таких місцях як поля форми чи повідомлення про помилки.

Ви можете отримати мітку атрибуту викликом методу [[yii\base\Model::getAttributeLabel()]]. Наприклад,

```php
$model = new \app\models\ContactForm;

// відобразить "Name"
echo $model->getAttributeLabel('name');
```

За замовчуванням мітки атрибутів генеруються автоматично з імен атрибутів. Генерація виконується
методом [[yii\base\Model::generateAttributeLabel()]]. Він перетворить імена змінних зі стилю "camel-case" у
декілька слів з першою літерою у кожному слові у верхньому регістрі. Наприклад, `username` стане `Username`,
а `firstName` стане `First Name`.

Якщо ви не хочете використовувати автоматично згенеровані мітки, ви можете перевизначити [[yii\base\Model::attributeLabels()]]
для точного визначення міток атрибутів. Наприклад,

```php
namespace app\models;

use yii\base\Model;

class ContactForm extends Model
{
    public $name;
    public $email;
    public $subject;
    public $body;

    public function attributeLabels()
    {
        return [
            'name' => 'Your name',
            'email' => 'Your email address',
            'subject' => 'Subject',
            'body' => 'Content',
        ];
    }
}
```

Для додатків, що підтримують декілька мов, ви можливо захочете перекласти мітки атрибутів. Це можливо зробити
у методі [[yii\base\Model::attributeLabels()|attributeLabels()]] також, як показано нижче:

```php
public function attributeLabels()
{
    return [
        'name' => \Yii::t('app', 'Your name'),
        'email' => \Yii::t('app', 'Your email address'),
        'subject' => \Yii::t('app', 'Subject'),
        'body' => \Yii::t('app', 'Content'),
    ];
}
```

Ви можете навіть умовно визначати мітки атрибутів. Наприклад, на основі [сценарію](#scenarios), в якому модель
використовується, ви можете повертати різні мітки для одного й того ж атрибуту.

> Інформація: Строго кажучи, мітки атрибутів є частиною [представлень](structure-views.md). Але оголошення міток
  у моделях є часто дуже зручним та призводить до чистоти коду та можливості його повторного використання.


## Сценарії <span id="scenarios"></span>

Модель може бути використана у різних *сценаріях*. Наприклад, модель `User` може бути використана для збору вводу при вході користувача,
але також вона може бути використана з метою реєстрації користувача. У різних сценаріях модель може використовувати різні
бізнес-правила та бізнес-логіку. Наприклад, атрибут `email` може бути обов’язковим у процесі реєстрації користувача,
але не потрібним у процесі входу користувача.

Модель використовує властивість [[yii\base\Model::scenario]] для того, щоб відслідковувати сценарій, в якому вона використовується.
За замовчуванням модель підтримує тільки один сценарій іменований `default`. Наступний код показує два шляхи
призначення сценарію моделі:

```php
// сценарій призначено як властивість
$model = new User;
$model->scenario = 'login';

// сценарій призначено через конфігурацію
$model = new User(['scenario' => 'login']);
```

За замовчуванням сценарії, які підтримуються моделлю, обумовлюються [правилами перевірки](#validation-rules) оголошеними
у моделі. Однак, ви можете змінити цю поведінку, перевизначивши метод [[yii\base\Model::scenarios()]]
як показано нижче:

```php
namespace app\models;

use yii\db\ActiveRecord;

class User extends ActiveRecord
{
    public function scenarios()
    {
        return [
            'login' => ['username', 'password'],
            'register' => ['username', 'email', 'password'],
        ];
    }
}
```

> Інформація: У вищенаведеному та у наступних прикладах класи моделей успадковані від [[yii\db\ActiveRecord]],
  тому що використання декількох сценаріїв зазвичай відбувається з класами [Active Record](db-active-record.md).

Метод `scenarios()` повертає масив, ключами якого є імена сценаріїв, а значеннями - відповідні
*активні атрибути*. Активні атрибути можуть бути [масово призначеними](#massive-assignment) та підлягають
[перевірці](#validation-rules). У вищенаведеному прикладі, атрибути `username` і `password` є активними
у сценарії `login`; в той час як у сценарії `register`, також активним є атрибут `email` разом з `username` і `password`.

Стандартна реалізація методу `scenarios()` повертає усі сценарії, знайдені у правилах перевірки, оголошених
методом [[yii\base\Model::rules()]]. При перевизначенні методу `scenarios()`, якщо ви хочете ввести нові сценарії
на додачу до тих сценаріїв, необхідно написати код подібний до наступного:

```php
namespace app\models;

use yii\db\ActiveRecord;

class User extends ActiveRecord
{
    public function scenarios()
    {
        $scenarios = parent::scenarios();
        $scenarios['login'] = ['username', 'password'];
        $scenarios['register'] = ['username', 'email', 'password'];
        return $scenarios;
    }
}
```

Можливості сценаріїв в основному використовуються при [перевірці](#validation-rules) та [масовому призначенні](#massive-assignment) атрибутів.
Однак, ви можете використовувати їх для інших цілей. Наприклад, ви можете оголошувати [мітки атрибутів](#attribute-labels)
по-різному, в залежності від поточного сценарію.


## Правила перевірки <span id="validation-rules"></span>

Дані для моделі, які отримуються від кінцевих користувачів, повинні пройти перевірку, щоб пересвідчитись, що вони задовольняють
певні правила (названі *правилами перевірки*, також відомі як *бізнес-правила*). Наприклад, дано модель `ContactForm`,
ви, можливо, хочете пересвідчитись, що всі атрибути заповнені та атрибут `email` містить коректну адресу електронної пошти.
Якщо значення для деяких атрибутів не задовольняють відповідні бізнес-правила, то будуть відображенні належні
повідомлення про помилки, щоб допомогти користувачу виправити їх.

Ви можете викликати [[yii\base\Model::validate()]] для перевірки отриманих даних. Даний метод використає
правила перевірки, оголошені у [[yii\base\Model::rules()]], для перевірки кожного необхідного атрибуту. При відсутності
помилок він поверне true. В іншому випадку, він збереже помилки у властивості [[yii\base\Model::errors]]
та поверне false. Наприклад:

```php
$model = new \app\models\ContactForm;

// заповнення атрибутів моделі даними від користувача
$model->attributes = \Yii::$app->request->post('ContactForm');

if ($model->validate()) {
    // усі дані є коректними
} else {
    // невдала перевірка: $errors - масив, що містить повідомлення про помилки
    $errors = $model->errors;
}
```


Для оголошення правил перевірки, пов’язаних з моделлю, необхідно перевизначити метод [[yii\base\Model::rules()]], повернувши
правила, які атрибути моделі повинні задовольнити. Наступний приклад показує правила перевірки, оголошені
для моделі `ContactForm`:

```php
public function rules()
{
    return [
        // атрибути name, email, subject і body є обов’язковими
        [['name', 'email', 'subject', 'body'], 'required'],

        // атрибут email повинен бути коректною адресою електронної пошти
        ['email', 'email'],
    ];
}
```

Правило може використовуватись для перевірки одного або кількох атрибутів, також атрибут може перевірятись одним або кількома правилами.
Будь ласка, зверніться до розділу [Перевірка вводу](input-validation.md) для більш детальної інформації про те, як оголошувати
правила перевірки.

Іноді необхідно, щоб правила застосовувались лише у певних [сценаріях](#scenarios). Для цього ви можете
визначати властивість `on` для правила, як наведено нижче:

```php
public function rules()
{
    return [
        // username, email і password є обов’язковими у сценарії "register"
        [['username', 'email', 'password'], 'required', 'on' => 'register'],

        // username і password є обов’язковими у сценарії "login"
        [['username', 'password'], 'required', 'on' => 'login'],
    ];
}
```

Якщо ви не визначите властивість `on`, то правило буде застосоване у всіх сценаріях. Правило називається
*активним правилом*, якщо воно може бути застосоване у поточному [[yii\base\Model::scenario|сценарії]].

Атрибут буде перевірятись тоді й лише тоді, якщо він є активним атрибутом, оголошеним у `scenarios()` і
пов’язаний з одним або кількома активними правилами, оголошеними у `rules()`.


## Масове призначення <span id="massive-assignment"></span>

Масове призначення - це зручний спосіб заповнення моделі даними, введеними користувачем, використовуючи один рядок коду.
Атрибути моделі заповнюються шляхом призначення вхідних даних безпосередньо властивості [[yii\base\Model::$attributes]].
Наступні два приклади коду є еквівалентними, обидва намагаються призначити дані з форми, представлені кінцевими користувачами,
атрибутам моделі `ContactForm`. Явно, що перший приклад, який використовує масове призначення, є набагато чистішим
й менш схильним до помилок, ніж другий:

```php
$model = new \app\models\ContactForm;
$model->attributes = \Yii::$app->request->post('ContactForm');
```

```php
$model = new \app\models\ContactForm;
$data = \Yii::$app->request->post('ContactForm', []);
$model->name = isset($data['name']) ? $data['name'] : null;
$model->email = isset($data['email']) ? $data['email'] : null;
$model->subject = isset($data['subject']) ? $data['subject'] : null;
$model->body = isset($data['body']) ? $data['body'] : null;
```


### Безпечні атрибути <span id="safe-attributes"></span>

Масові призначення застосовуються лише до, так званих *безпечних атрибутів*, які є атрибутами, що перелічені у
[[yii\base\Model::scenarios()]] для поточного [[yii\base\Model::scenario|сценарію]] моделі.
Наприклад, якщо модель `User` має нижченаведене оголошення сценарію, потім, коли поточним сценарієм
буде `login`, лише `username` і `password` можуть бути масово призначеними. Усі інші атрибути
будуть проігноровані.

```php
public function scenarios()
{
    return [
        'login' => ['username', 'password'],
        'register' => ['username', 'email', 'password'],
    ];
}
```

> Інформація: Причиною того, що масове призначення застосовується лише для безпечних атрибутів є необхідність
  контролювати те, які атрибути можуть змінюватись даними від кінцевого користувача. Наприклад, якщо модель `User`
  має атрибут `permission`, який визначає дозволи призначені користувачу, то необхідно бути впевненим,
  що цей атрибут може змінюватись лише адміністраторами через back-end інтерфейс.

Стандартна реалізація методу [[yii\base\Model::scenarios()]] повертає усі сценарії та атрибути,
знайдені у [[yii\base\Model::rules()]], якщо ви не перевизначили цей метод. Це означає, що атрибут є безпечним поки
знаходиться в одному із активних правил перевірки.

З цієї причини, надається спеціальний валідатор з псевдонімом `safe`, що дозволяє оголошувати атрибут
безпечним без фактичної його перевірки. Наприклад, наступне правило оголошує обидва атрибути `title`
і `description` безпечними:

```php
public function rules()
{
    return [
        [['title', 'description'], 'safe'],
    ];
}
```


### Небезпечні атрибути <span id="unsafe-attributes"></span>

Як описано вище, метод [[yii\base\Model::scenarios()]] слугує двом цілям: вирішенню, які атрибути
повинні бути перевірені, і вирішенню, які атрибути є безпечними. У деяких рідких випадках, існує необхідність перевірити
атрибут, але не позначати його безпечним. Цього можна досягнути за допомогою префіксу знак оклику `!` у імені
атрибуту при його оголошені в `scenarios()`, як у атрибута `secret` в наведеному прикладі:

```php
public function scenarios()
{
    return [
        'login' => ['username', 'password', '!secret'],
    ];
}
```

Коли модель буде присутня у сценарії `login`, усі три атрибути будуть перевірені. Однак, лише атрибути
`username` і `password` можуть бути масово призначеними. Для призначення атрибуту `secret` вхідного значення
необхідно зробити це явно, як наведено нижче:

```php
$model->secret = $secret;
```


## Експортування даних <span id="data-exporting"></span>

Часто існує потреба експортувати моделі у різні формати. Наприклад, може виникнути необхідність в перетворенні набору
моделей у формат JSON або Excel. Процес експортування може бути розділений на два незалежні кроки.
Першим кроком, моделі перетворюються у масиви; другим кроком, масиви перетворюються у
відповідні формати. Ви можете зосередитись лише на першому кроці, оскільки другий крок можна виконати за допомогою
загальних форматтерів даних, одним з яких є [[yii\web\JsonResponseFormatter]].

Найпростіший спосіб перетворення моделі у масив - це використання властивості [[yii\base\Model::$attributes]].
Наприклад:

```php
$post = \app\models\Post::findOne(100);
$array = $post->attributes;
```

За замовчуванням властивість [[yii\base\Model::$attributes]] поверне значення *усіх* атрибутів,
оголошених у [[yii\base\Model::attributes()]].

Більш гнучкий та потужний спосіб перетворення моделі в масив - використання методу [[yii\base\Model::toArray()]].
Його типова поведінка така ж як у [[yii\base\Model::$attributes]]. Однак, він дозволяє обирати,
які елементи даних, що називаються *полями*, включати до масиву та як вони повинні бути форматовані.
Насправді, це стандартний спосіб експортування моделей при розробці веб-сервісів RESTful, як описано у
розділі [Форматування відповіді](rest-response-formatting.md).


### Поля <span id="fields"></span>

Поле - це просто іменований елемент у масиві, отриманому через виклик методу [[yii\base\Model::toArray()]]
моделі.

За замовчуванням імена полів є еквівалентними іменам атрибутів. Однак, можливо змінити цю поведінку за допомогою перевизначення
методів [[yii\base\Model::fields()|fields()]] і/або [[yii\base\Model::extraFields()|extraFields()]]. Обидва методи
повинні повертати перелік визначень полів. Поля, визначені у `fields()` є полями за замовчуванням, це означає, що
`toArray()` повертатиме ці поля за замовчуванням. Метод `extraFields()` визначає додатково доступні поля,
які також можуть бути повернутими через `toArray()`, якщо будуть зазначені у параметрі `$expand`. Наприклад,
наступний код буде повертати усі поля, визначені у `fields()`, а також поля `prettyName` і `fullAddress`,
якщо вони визначені у `extraFields()`:

```php
$array = $model->toArray([], ['prettyName', 'fullAddress']);
```

Ви можете перевизначити `fields()`, щоб додати, видалити, перейменувати або перевизначити поля. Значенням, яке повертатиме `fields()`,
повинен бути масив. Ключами масиву є імена полів, а значеннями масиву - відповідні
визначення полів, які можуть бути або іменами властивостей/атрибутів, або анонімними функціями, що повертають
відповідні значення полів. В окремому випадку, коли ім’я поля збігається з ім’ям його атрибуту,
ви можете пропустити ключ масиву. Наприклад:

```php
// точний перелік кожного поля найкраще використовувати тоді, коли ви хочете бути впевненим, що зміни
// у вашій таблиці БД або у атрибутах моделі не викликають змін ваших полів (для збереження зворотної сумісності API)
public function fields()
{
    return [
        // ім’я поля збігається з ім’ям атрибуту
        'id',

        // ім’я поля - "email", ім’я відповідного атрибуту - "email_address"
        'email' => 'email_address',

        // ім’я поля - "name", його значення визначене за допомогою анонімної PHP-функції
        'name' => function () {
            return $this->first_name . ' ' . $this->last_name;
        },
    ];
}

// відфільтровування деяких полів найкраще використовувати тоді, коли ви хочете
// успадкувати батьківську реалізацію та виключити деякі "чутливі" поля
public function fields()
{
    $fields = parent::fields();

    // вилучити поля, які містять конфіденційну інформацію
    unset($fields['auth_key'], $fields['password_hash'], $fields['password_reset_token']);

    return $fields;
}
```

> Попередження: Оскільки за замовчуванням усі атрибути моделі будуть включені до масиву, що експортується, ви повинні
> перевірити ваші дані, щоб бути впевненим, що вони не містять конфіденційної інформації. Якщо ж така інформація присутня,
> вам потрібно перевизначити метод `fields()` та відфільтрувати її. У вищенаведеному прикладі були
> відфільтровані поля `auth_key`, `password_hash` і `password_reset_token`.


## Кращі практики <span id="best-practices"></span>

Моделі є центральним місцем презентування бізнес-даних, бізнес-правил і бізнес-логіки. Вони часто потребують повторного
використання у різних місцях. В добре організованому додатку моделі зазвичай набагато більші, ніж
[контролери](structure-controllers.md).

В цілому, моделі

* можуть містити атрибути для презентування бізнес-даних;
* можуть містити правила перевірки для забезпечення коректності та цілісності даних;
* можуть містити методи, які реалізують бізнес-логіку;
* НЕ повинні безпосередньо отримувати доступ до запиту, сесії або будь-яких інших даних середовища. Ці дані повинні бути введені
  у моделі за допомогою [контролерів](structure-controllers.md);
* повинні уникати вкладеного HTML- або іншого презентаційного коду - це краще робити у [представленнях](structure-views.md);
* мають уникати завеликої кількості [сценаріїв](#scenarios) в одній моделі.

Як правило, ви можете враховувати останню рекомендацію, з наведених вище, тоді, коли розробляєте великі складні системи.
У цих системах моделі можуть бути дуже великими, оскільки вони використовуються у багатьох місцях й тому можуть містити
багато наборів правил і бізнес-логіки. Це часто перетворюється у кошмар під час супроводу коду моделі,
через те, що невелика зміна коду може зачіпати декілька різних місць. Щоб полегшити супровід коду моделі,
вам необхідно дотримуватися наступної стратегії:

* Визначити набір базових класів моделей, які є спільними для різних [додатків](structure-applications.md) або
  [модулів](structure-modules.md). Ці класи моделей повинні містити мінімальний набір правил та логіки, які
  є загальними для усіх додатків та модулів, які їх використовують.
* У кожному [додатку](structure-applications.md) або [модулі](structure-modules.md), який використовує модель,
  визначити конкретний клас моделі, що розширює відповідний базовий клас моделі. Конкретні класи моделей
  повинні містити правила та логіку, які є специфічними для додатка чи модуля.

Наприклад, у [розширеному шаблоні проекту](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide-uk/README.md), ви можете визначати базовий клас
моделі `common\models\Post`. Потім для front-end додатку ви визначаєте та використовуєте конкретний клас моделі
`frontend\models\Post`, який розширює клас `common\models\Post`. Аналогічно для back-end додатку,
ви визначаєте `backend\models\Post`. Подібна стратегія дає вам впевненість в тому, що код у `frontend\models\Post`
є специфічним тільки для front-end додатку, та якщо ви внесете будь-які зміни до нього, то не має потреби турбуватись, що
зміни можуть порушити back-end додаток.