Повний посібник (v2) Контролери - Українська спільнота Yii Framework

Контролери є частиною архітектури MVC. Це об'єкти класів, успадкованих від yii \ base \ Controller, що відповідають за обробку запиту і генерування відповіді. По суті, після обробки запиту додатками, контролери проаналізують вхідні дані, передадуть їх у моделі, вставлять результати моделі в уявлення, і зрештою згенерують вихідні відповіді.

Контролери складаються з дій, які є основними блоками, до яких може звертатися кінцевий користувач та вимагати виконання того чи іншого функціоналу. У контролері може бути одна або кілька дій.

Наступний приклад показує post контролер із двома діями: view і create :

У дії view (визначеному методом actionView() ), код спочатку завантажує модель згідно з запитаним ID моделі; Якщо модель успішно завантажена, код відобразить її за допомогою подання під назвою view . В іншому випадку буде кинуто виняток.

У дії create (визначеному методом actionCreate() ) код аналогічний. Він спочатку намагається завантажити модель за допомогою даних із запиту та зберегти модель. Якщо все пройшло успішно, код перенаправляє браузер на дію view з ID щойно створеної моделі. В іншому випадку він відобразить уявлення create, через яке користувач може заповнити потрібні дані.

Кінцеві користувачі звертаються до дій через так звані маршрути. Маршрут це рядок, що складається з наступних частин:

ID модуля: він існує, тільки якщо контролер належить додатку, а модулю;
ID контролера: рядок, який унікально ідентифікує контролер серед усіх інших контролерів одного і того ж додатка (або одного модуля, якщо контролер належитьмодулю);
ID дії: рядок, який унікально ідентифікує дію серед усіх інших дій одного й того ж контролера.

Маршрути можуть мати такий формат:

або наступний формат, якщо контролер належить модулю:

Таким чином, якщо користувач запитує URL http://hostname/index.php?r=site/index , то index дію в site контролері буде викликано. Секція Маршрутизація містить більш детальну інформацію про те, як маршрути порівнюються з діями.

Створення контролерів

У Веб-додатках, контролери повинні бути успадковані від yii\web\Controller або його нащадків. Аналогічно для консольних додатків, контролери повинні бути успадковані від yii \ console \ Controller або його нащадків. Наступний код визначає site контролер:

Зазвичай контролер зроблено в такий спосіб, що він має обробляти запити, пов'язані з певним ресурсом. Саме з цих причин ID контролерів зазвичай є іменники, що посилаються на ресурс, який вони обробляють. Наприклад, ви можете використовувати article як ID контролера, який відповідає за обробку даних статей.

За замовчуванням, ID контролерів повинні містити лише такі символи: Англійські літери в нижньому регістрі, цифри, підкреслення, тире та слеш. Наприклад, обидва article і post-comment є допустимими ID контролерів, у той час як article? , PostComment , admin\post є такими.

ID контролерів також можуть містити префікс підпапки. Наприклад, в admin/article частина article є контролером у підпапці admin у просторі імен контролерів. Допустимими символами для префіксів підпапок є: Англійські літери в нижньому та верхньому регістрі, символи підкреслення та слеш, де слеш використовується вяк розмежувач для багатовкладених підпапок (наприклад panels/admin ).

Правила найменування класів контролерів

Назви класів контролерів можуть бути отримані з ID контролерів такими способами:

Привести у верхній регістр перший символ у кожному слові, поділеному дефісами. Зверніть увагу, якщо ID контролера містить слеш, то це правило поширюється тільки на частину після останнього слеша в ID контролера;
Прибрати дефіси та замінити будь-який прямий слеш на зворотний;
Додати суфікс Controller;
Додати на початок простір імен контролерів.

Нижче наведено кілька прикладів, з урахуванням того, що простір імен контролерів має значення за промовчанням, що дорівнює app\controllers :

article відповідає app\controllers\ArticleController;
post-comment відповідає app\controllers\PostCommentController;
admin/post-comment відповідає app\controllers\admin\PostCommentController;
adminPanels/post-comment відповідає app\controllers\adminPanels\PostCommentController .

Класи контролерів мають бути автозавантажуваними. Саме з цієї причини, у наведеному вище прикладі, контролер article повинен бути збережений у файл, псевдонім якого @app/controllers/ArticleController.php ; в той час, як контролер admin/post-comment повинен знаходитися у файлі @app/controllers/admin/PostCommentController.php .

Карта контролерів

Ви можете налаштувати карту контролерів для того, щоб подолати описані вище обмеження іменування ID контролерів та назв класів. В основному це дуже зручно, коли ви використовуєте сторонні контролери, які ви не можете контролювати.

Ви можетеконфігурувати карту контролерів у налаштуваннях програми таким чином:

Контролер за замовчуванням #

Кожна програма має контролер за замовчуванням, вказаний через властивість yii\base\Application::defaultRoute. Якщо у запиті не вказаний маршрут, тоді буде використаний маршрут, зазначений у даній властивості. Для Веб-додатків, це значення 'site' , в той час як для консольних додатків, це 'help' . Таким чином, якщо встановлено URL http://hostname/index.php , це означає, що контролер site виконає обробку запиту.

Ви можете змінити контролер за замовчуванням в налаштуваннях програми:

Створення дій #

В основному дія розробляється для конкретної обробки ресурсу. З цієї причини, ID дій в основному є дієсловами, такими як view, update, і т.д.

За замовчуванням, ID дії має містити лише такі символи: Англійські літери в нижньому регістрі, цифри, підкреслення та дефіси. Дефіси в ID дій використовуються для поділу слів. Наприклад, view , update2 , comment-post є допустимими ID дій, тоді як view? , Update не є такими.

Ви можете створювати дії двома способами: вбудовані дії та окремі дії. Вбудована дія є методом, визначеним у класі контролера, тоді як окрема дія є екземпляром класу, успадкованого від yii\base\Action або його нащадків. Вбудовані дії вимагають менше зусиль для створення і в основному використовуються, якщо у вас немає потреби в повторному використанні дій. p align="justify"> Окремі дії, з іншого боку, в основному створюються для використання в різних контролерах або при використанні в розширеннях.

Вбудовані дії #

ВбудованіПодії це ті дії, які визначені в рамках методів контролера, як ми вже обговорили.

Назви методів дій можуть бути отримані з ID дій таким чином:

Привести перший символ кожного слова до ID дії у верхній регістр;
Забрати дефіси;
Додати префікс action.

Наприклад, index відповідає actionIndex , а hello-world відповідає actionHelloWorld .

Note: Назви імен дій є реєстрозалежними. Якщо у вас є метод ActionIndex , він не буде врахований як метод дії, таким чином, запит до дії index призведе до викиду виключення. Також слід врахувати, що методи дій повинні мати сферу видимості public. Методи, що мають область видимості private або protected НЕ визначають методи вбудованих дій.

Вбудовані дії в основному використовуються, тому що для їх створення не потрібно багато зусиль. Проте, якщо ви плануєте повторно використовувати деякі дії в різних місцях, або якщо ви хочете перерозподілити дії, ви повинні визначити її як окрему дію.

Окремі дії #

Окремі дії визначаються як класи, успадковані від yii\base\Action або його нащадків. Наприклад, в релізах Yii, присутні yii\web\ViewAction і yii\web\ErrorAction, обидва з яких є окремими діями.

Для використання окремої дії, ви повинні вказати його в карті дій, за допомогою перевизначення методу yii\base\Controller::actions() у вашому класі контролера, так:

Як можна бачити, метод actions() повинен повернути масив, ключами якого є ID дій, а значеннями - відповідні назви класу дії чи конфігурація. На відміну відвбудованих дій, ID окремих дій можуть містити довільні символи, доки вони визначені методом actions() .

Для створення окремої дії, ви повинні успадковуватися від класу yii \ base \ Action або його нащадків, і реалізувати метод run () з областю видимості public. Роль методу run() аналогічна до інших методів дій. Наприклад,

Результати дій #

Значення методів дій, що повертаються, або методу run() окремої дії дуже важливе. Воно є результатом виконання відповідної дії.

Значення, що повертається, може бути об'єктом response, який буде відісланий кінцевому користувачеві як відповідь.

Для Веб додатків, значення, що повертається також може бути довільними даними, які будуть присвоєні yii\web\Response::data, а потім зконвертовані в рядок, що представляє тіло відповіді.
Для Консольних додатків, значення, що повертається також може бути числом, що представляє статус виходу виконання команди.

У наведених вище прикладах, всі результати дій є рядками, які будуть використані як тіло відповіді, висланого користувачеві. Наступний приклад показує дію може перенаправити браузер користувача на новий URL, за допомогою повернення response об'єкта (т.к. redirect() метод повертає response об'єкт):

Параметри дій #

Методи дій для вбудованих дій і методи run() окремих дій можуть приймати параметри, звані параметри дій. Їхні значення беруться із запитів. Для Веб додатків значення кожного з параметрів дії береться з $_GET , використовуючи назву параметра як ключ; для консольних додатків вони відповідають аргументам командного рядка.

У наведеному нижчеНаприклад, дія view (вбудована дія) визначає два параметри: $ id і $ version .

Для різних запитів параметри дій будуть визначені таким чином:

Якщо ви хочете, щоб параметр дії приймав масив значень, ви повинні використовувати type-hint значення array , як показано нижче:

Тепер, якщо запит міститиме URL http://hostname/index.php?r=post/view& >, то $id прийме значення ['123'] . Якщо запит міститиме URL http://hostname/index.php?r=post/view& >, параметр $id все одно буде містити масив, тому що скалярне значення '123' буде автоматично конвертовано в масив.

Наведені вище приклади в основному показують як параметри дій працюють для Веб додатків. Більше інформації про параметри консольних програм представлено в секції Консольні команди.

Типова дія #

Кожен контролер має дію, вказану через властивість yii\base\Controller::defaultAction. Коли маршрут містить лише ID контролера, то мається на увазі, що дія контролера за замовчуванням була запрошена.

За замовчуванням, ця дія має значення index . Якщо ви хочете змінити це значення, просто перевизначте цю властивість у класі контролера наступним чином:

Життєвий цикл контролера #

При обробці запиту, програма створить контролер, ґрунтуючись на запитаному маршруті. Для виконання запиту контролер пройде через наступні етапи життєвого циклу:

Метод yii\base\Controller::init() буде викликаний після того, як контролер буде створений і налаштований;
Контролер створює об'єкт дії, ґрунтуючись на запитаному ID дії:
Якщо ID дії не вказано, то буде використано ID діїзамовчуванням;
Якщо ID дії знайдено в карті дій, то окрема дія буде створена;
Якщо ID дії відповідає методу дії, то вбудована дія буде створена;
В іншому випадку буде викинуто виняток yii\base\InvalidRouteException.
Контролер послідовно викликає метод beforeAction() додатка, модуля (якщо контролер належить модулю) та самого контролера.
Якщо один із методів повернув false , то інші, не викликані методи передвиконанням будуть пропущені, а виконання дії буде скасовано;
За промовчанням кожен виклик методу beforeAction() викликає подію beforeAction , на яку ви можете призначити обробники.
Контролер запускає дію:
Параметри дії будуть проаналізовані та заповнені з даних запиту.
Контролер послідовно викликає методи післядії контролера, модуля (якщо контролер належить модулю) і додатку.
За промовчанням кожен виклик методу afterAction() викликає подію afterAction , на яку ви можете призначити обробники.
Програма, отримавши результат виконання дії, привласнить його об'єкту response.

Кращі практики #

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

В цілому, контролери

можуть мати доступ до даних запиту;
можуть викликати методи моделей та інших компонентів системи з даними запиту;
можуть використовувати уявлення на формування відповіді;
не повинні займатися обробкою даних, це має відбуватися у шарімоделей;
повинні уникати використання HTML або іншої розмітки, краще це робити в уявленнях.