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

Консольні програми головним чином використовуються для виконання вторинних або фонових завдань, таких як генерація коду, компіляція пошукового індексу, надсилання електронних листів і т.д. Yii надає інструмент для розробки консольних програм, дотримуючись об'єктно-орієнтованого підходу. Він дозволяє консольній програмі отримати доступ до ресурсів, які використовує основний веб-додаток (наприклад, до бази даних).

Кожна консольна задача представлена ​​у Yii як команда. Консольна команда описується в класі, успадкованому від CConsoleCommand.

Після використання yiic webapp для створення початкового прототипу програми, в protected будуть два файли:

• yiic – скрипт для Linux/Unix;
• yiic.bat – скрипт для Windows.

У консолі можна ввести такі команди:

Після введення буде відображено список усіх доступних команд. За замовчуванням це команди, що надаються Yii (так званісистемні команди ) та команди, розроблені для конкретних додатків (так званікористувацькі команди ).

Для отримання довідки по команді можна запустити

Для запуску команди використовується наступний формат:

Створення команд #

Консольні команди знаходяться у файлах із класами в папці, вказаній у 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 і її значення записується шлях до директорії з класами глобальних консольних команд.

Дія консольної команди #

Примітка: Ця можливість доступна з версії 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:

Код повернення #

Примітка: можливість вказати код повернення консольної команді з'явилася у версії 1.1.11.

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

Дані коди є цілими значеннями від 0 до 254 (даний інтервал заданий в PHP), де 0 повертається у разі успіху, а всі інші значення використовуються для різних помилок.

Як у методі run() , і у діях команди ви можете повернути ціле число. Воно буде використано як код повернення.

Якщо консольна команда нічого не повертає, програма завершується з кодом 0.

Налаштування консольної програми #

За замовчуванням, якщо програма створюється за допомогою yiic webapp , конфігурація консольної програми знаходиться в protected/config/console.php . Як і конфігурація веб-програми, цей файл є PHP-скриптом, що повертає масив з початковими значеннями екземпляра консольної програми. Тобто в даному файлі можна задати будь-яку public властивість CConsoleApplication.

Так як консольні команди часто створюються для підтримки веб-програми, потрібно використовувати ті ж ресурси (такі, як з'єднання з БД), що використовуються у веб-застосунку. Це можна зробити налаштувавши відповідні компоненти в конфігурації консольної програми:

Формат конфігурації дуже схожий на той, що використовується у веб-застосунку, так як і CConsoleApplication і CWebApplication успадковують один і той же базовий клас.

---