Консольні додатки головним чином використовуються для виконання вторинних або фонових завдань, таких як генерація коду, компіляція пошукового індексу, відправлення повідомлень електронної пошти і т.д. Yii надає інструмент для розробки консольних додатків, дотримуючись об'єктно-орієнтованого підходу. Він дозволяє консольного додатку отримати доступ до ресурсів, які використовує основне веб-додаток (наприклад, до бази даних).
1. Огляд ¶
Кожна консольная завдання представлена в Yii як команда. Консольна команда описується в класі, успадковане від CConsoleCommand.
Після використання yiic webapp для створення початкового прототипу додатку, в protected будуть два файли:
- yiic - скрипт для Linux / Unix;
- yiic.bat - скрипт для Windows.
В консолі можна ввести наступні команди:
Після введення буде відображений список всіх доступних на даний момент команд. За замовчуванням це команди, які надаються Yii (так звані системні команди) і команди, розроблені для конкретних додатків (так звані призначені для користувача команди).
Для отримання довідки по команді можна запустити
Для запуску команди використовується наступний формат:
2. Створення команд ¶
Консольні команди знаходяться в файлах з класами в папці, зазначеної в CConsoleApplication :: commandPath. За замовчуванням це protected / commands.
Клас консольної команди повинен бути успадкований від CConsoleCommand. Ім'я класу має бути виду XyzCommand. де Xyz відповідає імені команди, перша буква якого приведена до верхнього регістру. Наприклад, команда sitemap повинна використовувати клас SitemapCommand. Імена консольних команд чутливі до регістру.
Підказка: конфігуруємо CConsoleApplication :: commandMap. можна при бажанні змінити порядок іменування і розташування класів команд.
Для створення нової команди необхідно або реалізувати метод CConsoleCommand :: run (). або одне або кілька дій (будуть описані далі).
При введенні консольної команди додаток запускає метод CConsoleCommand :: run (). Параметри методу передаються відповідно до наступним заголовком:
де $ args - додаткові параметри, передані з командного рядка.
Усередині консольної команди для отримання доступу до примірника консольного застосування можна використовувати Yii :: app (). Через одержаний примірник можна звертатися до різних компонентів, таким як з'єднання з базою даних (Yii :: app () -> db). Наскільки можна судити, це дуже схоже на звичайне веб-додаток.
Інформація: Починаючи з версії 1.1.1 можна створювати глобальні команди, які використовуються усіма додатками. Для цього визначається змінна оточення YII_CONSOLE_COMMANDS і в її значення записується шлях до директорії з класами глобальних консольних команд.
3. Дія консольної команди ¶
Примітка: Дана можливість доступна починаючи з версії 1.1.5.
Часто в консольної команді потрібно працювати з різними параметрами. Частина з них можуть бути обов'язковими, а частина немає. Також може знадобитися реалізувати субкоманди для виконання різних підзадач. Все це спрощується при використанні дій.
Дія консольної команди - метод в її класі. Ім'я методу повинно бути виду actionXyz. де Xyz відповідає імені дії і першою літерою, наведеної до верхнього регістру. Наприклад, метод actionIndex задає дію з ім'ям index.
Для того, щоб запустити певну дію, використовується наступний формат команди:
Додаткові пари ім'я-значення передаються методу дії як іменовані параметри. Значення опції xyz відповідає параметру $ xyz методу дії. Наприклад, якщо ми визначимо наступний клас команди:
То все наступні консольні команди викличуть actionIndex ( 'News', 5):
Якщо значення опції не вказано (тобто --type замість --type = News), відповідному параметру дії буде присвоєно значення true.
Примітка: Альтернативні формати вказівки опцій, такі як --type News або -t News не підтримуються.
Якщо оголосити параметр як масив, він зможе прийняти масив значень:
Щоб передати масив значень необхідно вказати одну і ту ж опцію кілька разів:
Команда, наведена вище, запустить actionIndex (array ( 'News', 'Article')).
Починаючи з версії 1.1.6, Yii дозволяє використовувати анонімні параметри дій і глобальні опції.
Анонімні параметри - це параметри командного рядка, які не є опціями. Наприклад, в команді yiic sitemap index --limit = 5 News зустрічається анонімний параметр із значенням News. Іменований параметр (опція) limit приймає значення, рівне 5.
Для того, щоб використовувати анонімні параметри, дія повинна описати параметр з ім'ям $ args:
У масиві $ args будуть міститися всі доступні значення анонімних параметрів.
Глобальні опції - це параметри командного рядка, загальні для всіх дій команди. Наприклад, нам може знадобитися для команди з декількома діями завести загальну опцію verbose. Звичайно, можна визначити параметр $ verbose для кожної дії, але краще задати його public властивістю класу команди, що автоматично зробить verbose глобальної опцією:
Наведений код дозволяє використовувати опцію verbose:
4. Код повернення ¶
Примітка: можливість вказати код повернення в консольної команді з'явилася у версії 1.1.11.
При автоматичному запуску консольних команд, наприклад, по cron або скористатись службою безперервної інтеграції, важливо знати, завершилося Чи виконання команди з помилкою або успішно. Якраз для цього і призначені коди повернення.
Дані коди є цілочисельними значеннями від 0 до 254 (даний інтервал заданий в PHP), де 0 повертається в разі успіху, а всі інші значення використовуються для різних помилок.
Як в методі run (). так і в діях команди ви можете повернути ціле число. Воно буде використано в якості коду повернення.
Якщо консольна команда нічого не повертає, додаток завершується з кодом 0.
5. Налаштування консольного додатка ¶
За замовчуванням, якщо додаток створюється з використанням yiic webapp. конфігурація консольного застосування знаходиться в protected / config / console.php. Як і конфігурація веб-додатки, даний файл є PHP-скриптом, що повертає масив з початковими значеннями примірника консольного застосування. Тобто в даному файлі можна задати будь-public властивість CConsoleApplication.
Так як консольні команди часто створюються для підтримки веб-додатки, потрібно використовувати ті ж ресурси (такі, як з'єднання з БД), що використовуються в веб-додатку. Це можна зробити налаштувавши відповідні компоненти в конфігурації консольного застосування:
Формат конфігурації дуже схожий на той, що використовується в веб-додатку, так як і CConsoleApplication і CWebApplication успадковують один і той же базовий клас.