створення команд
На додаток до стандартних командам Artisan ви можете також створювати свої власні команди. Зазвичай команди зберігаються в папці app / Console / Commands. але ви можете помістити їх в будь-яке інше місце, в якому їх зможе знайти і завантажити Composer.
генерування команд
Для створення нової команди використовуйте Artisan-команду sh make: command. Ця команда створить новий клас команди в папці app / Console / Commands. Якщо цій папці не існує, вона буде створена при першому запуску команди sh make: command. Згенерована команда буде містити стандартний набір властивостей і методів, притаманних усім командам:
Потім вам треба зареєструвати команду. тоді вона зможе бути запущена через командний інтерфейс Artisan.
Для створення нової команди можна використовувати Artisan-команду sh make: console. яка створить заглушку, з якої ви можете почати працювати.
Ця команда створить клас в app / Console / Commands / SendEmails.php. При створенні команди може бути використаний ключ sh --command для призначення імені команди в терміналі:
структура команди
Після генерування команди, вам потрібно заповнити властивості signature і description в її класі, які використовуються при відображенні вашої команди в списку команд (sh list). Коли Ви телефонуєте вашої команди буде викликаний метод PHP handle (). У нього ви можете помістити необхідну вам логіку.
Для поліпшення коду, з точки зору його повторного використання, корисно зберігати ваші консольні команди простими і використовувати в них сервіси самого додатка для виконання їх завдань. Зверніть увагу, що в наведеному прикладі ми впроваджуємо клас сервісу для виконання «трудомісткою» завдання відправки листів.
Давайте подивимося на приклад команди. Ми можемо впровадити будь-які необхідні залежності в конструкторі команди. Сервіс-контейнер Laravel автоматично запровадить всі зазначені в конструкторі залежності:
команди замикання
Команди на основі замикань є альтернативою визначенням консольних команд у вигляді класів, подібно до того, як замикання маршрутів є альтернативою контролерам. У методі PHP commands () файлу app / Console / Kernel.php Laravel завантажує файл routes / console.php:
Не дивлячись на те, що цей файл не визначає HTTP-маршрути, він визначає консольні вхідні точки (маршрути) в вашу програму. У цьому файлі ви можете визначити всі свої маршрути на основі замикань за допомогою методу PHP Artisan. command (). Метод PHP command () приймає два аргументи: сигнатуру команди і замикання, яке отримує аргументи і ключі команди:
Замикання прив'язане до лежачого в основі примірнику команди, тому у вас є повний доступ до всіх допоміжних методів, які зазвичай доступні вам в повному класі команди.
Вказівка типів залежностей
Крім отримання аргументів і ключів вашої команди в замиканнях команд можна вказувати типи додаткових залежностей, які вам необхідно отримати з сервіс-контейнера:
При визначенні команд на основі замикань ви можете використовувати метод PHP describe () для додавання опису команди. Це опис буде виводиться при виконанні команд sh php artisan list або sh php artisan help:
Визначення очікувань введення
При створенні консольних команд часто необхідно отримувати введення від користувача через аргументи або ключі. У Laravel дуже зручно визначити очікуваний від користувача введення, використовуючи властивість signature вашої команди. Це властивість дозволяє задати ім'я, аргументи і ключі для команди в єдиному, виразному, маршрут-подібному синтаксисі.
Все що вводяться користувачем аргументи і ключі полягають у фігурні дужки. У наступному прикладі команда визначає один необхідний аргумент user:
Ви можете зробити аргумент необов'язковим і визначити значення за замовчуванням для аргументів:
Ключі, як і аргументи, є формою призначеного для користувача введення. Вони позначаються префіксом з двох дефісів (-). Існує два типи ключів: приймаючі значення і не беруть. Ключі, які не приймають значення, служать логічними «перемикачами». Давайте подивимося на такий тип ключів:
У цьому прикладі при виклику Artisan-команди може бути зазначений ключ sh --queue. Якщо буде переданий ключ sh --queue. то його значення буде true. інакше false:
Тепер подивимося на ключі, які очікують значення. Необхідність введення значення для ключа задається за допомогою знака рівності (=):
У цьому прикладі користувач може передати значення для ключа ось так:
Для ключів можна задати значення за замовчуванням, вказавши його після імені ключа. Це значення буде використано, якщо користувач не вкаже значення ключа:
Щоб задати скорочення при визначенні ключа, ви можете вказати його перед ім'ям ключа і відокремити його символом вертикальної риски (|):
введення масивів
Якщо ви хочете вказати, що аргументи або ключі будуть приймати на вхід масиви, використовуйте символ *. Спочатку подивимося на приклад вказівки аргументу масиву:
При виклику цієї команди в командний рядок можна передати аргументи user по порядку. Наприклад, наступна команда встановить значення user однакову [ 'foo', 'bar']:
При визначенні ключа, який буде приймати на вхід масив, кожне передане в команду значення ключа повинно мати префікс у вигляді імені ключа:
Щоб дізнатися як вводити
Ви можете задати опис для аргументів і ключів, відокремивши їх двокрапкою. Якщо вам необхідно трохи більше місця для визначення вашої команди, ви можете розділити опис на кілька рядків:
Введення / висновок команд
читання введення
Під час виконання команди вам, звичайно, буде потрібно доступ до аргументів і ключам, які були передані їй на вхід. Для цього ви можете використовувати методи PHP argument () і PHP option ().
Для читання значення аргументу використовуйте метод PHP argument ():
Якщо вам необхідно прочитати всі аргументи у вигляді масиву, викличте метод PHP arguments () (для версії 5.2 і раніше - метод PHP argument () без аргументів):
Ключі можна прочитати так само легко, як аргументи, використовуючи метод PHP option (). Щоб отримати масив всіх ключів, викличте метод PHP options () (для версії 5.2 і раніше - метод PHP option () без аргументів):
Якщо аргумент або ключа не існує, буде повернуто PHP null.
запит введення
На додаток до відображення виводу ви можете запитати у користувача дані під час виконання команди. Метод PHP ask () виведе запит, прийме введені дані, а потім поверне їх вашій команді:
Метод PHP secret () схожий на метод PHP ask (). але він не відображає вводяться користувачем дані в консолі. Цей метод корисний при запиті секретної інформації, такої як пароль:
Для отримання від користувача простого підтвердження можна використовувати метод PHP confirm (). За замовчуванням цей метод повертає false. Але якщо користувач введе y або yes у відповідь на запит, то метод поверне true:
Метод PHP anticipate () можна використовувати для надання користувачеві можливих варіантів для вибору. Незалежно від наявності цих варіантів користувач може вказати свій варіант.
Питання з декількома варіантами відповідей
Для надання користувачеві певного набору варіантів можна використовувати метод PHP choice (). Можна задати значення за замовчуванням, на випадок якщо варіант не обраний:
Для виведення ви можете використовувати методи PHP line (). PHP info (). PHP comment (). PHP question () і PHP error (). Кожен з них буде використовувати підходящі за змістом кольору ANSI для відображенні тексту. Давайте для прикладу виведемо інформаційне повідомлення для користувача. Зазвичай метод PHP info () виводить в консоль текст зеленого кольору:
Для виведення повідомлення про помилку використовуйте метод PHP error (). Він виводить в консоль текст червоного кольору:
Для простого перегляду тексту в консоль без використання спеціальних кольорів використовуйте метод PHP line ():
Метод PHP table () дозволяє легко форматувати кілька рядків / стовпців даних. Просто передайте в нього заголовки і рядки. Ширина і висота буде динамічно визначена на основі переданих даних:
Для тривалих завдань буває корисно вивести індикатор процесу. Використовуючи об'єкт виведення ми можемо запустити, пересунути і зупинити індикатор. Спочатку визначте загальне число кроків, за якими буде йти процес. Потім наведіть індикатор після виконання кожного кроку:
Вказівка імені середовища для виконання команди
Ви можете вказати середовище, яке буде використовуватися при виконанні команди, за допомогою ключа sh --env:
Висновок вашої поточної версії Laravel
Ви також можете дізнатися версію поточної установки Laravel за допомогою ключа sh --version:
Реєстрація команд
Коли ваша команда написана, вам потрібно зареєструвати її в Artisan. Всі команди реєструються у файлі app / Console / Kernel.php. У ньому ви знайдете список команд у властивості commands. Щоб зареєструвати свою команду, просто додайте ім'я класу команди в цей список. Коли Artisan завантажується, всі перераховані в цій властивості команди будуть включені в сервіс-контейнер і зареєстровані в Artisan:
Програмне виконання команд
Іноді необхідно виконати команду ззовні командного рядка. Наприклад, коли ви хочете запустити команду з маршруту або контролера. Для цього можна використовувати метод PHP call () фасаду Artisan. Цей метод приймає першим аргументом ім'я команди, а другим - масив аргументів команди. Буде повернуто код виходу:
За допомогою методу PHP queue () можна навіть поставити команди в чергу, тоді вони будуть оброблені в тлі за допомогою ваших оброблювачів черзі. Перш ніж використовувати цей метод, переконайтеся в тому, що ви налаштували вашу чергу, і що слухач черзі запущений:
Коли потрібно вказати значення ключа, який не приймає строкове значення, наприклад, прапор sh --force команди sh migrate: refresh. ви можете передати значення true або false:
Виклик команд з інших команд
Іноді необхідно викликати іншу команду зі своєї. Для цього використовуйте метод PHP call (). Він приймає ім'я команди і масив її аргументів:
Якщо ви хочете викликати іншу команду і заборонити її висновок в консоль, використовуйте метод PHP callSilent (). Цей метод приймає ті ж аргументи, що і метод PHP call ():
Планування команд Artisan
Даний розділ статті актуальний тільки для версії 5.0 і був
Погодження версії 5.1.
Раніше розробникам доводилося створювати Cron-завдання для кожної консольної команди, яку вони хотіли запланувати. Це втомлює. Для планування консольних команд тепер не ведеться контроль версій, і для додавання Cron-завдань вам необхідно підключатися до сервера по SSH. Давайте спростимо нам життя. Планувальник команд Laravel дозволяє вам гнучко і виразно задавати план команд в самому Laravel, а на сервері потрібна тільки одна Cron-завдання.
Ваш план команд зберігається у файлі app / Console / Kernel.php. В цьому класі ви знайдете метод PHP schedule. Щоб допомогти вам розібратися, в метод включений простий приклад. Ви можете додавати в об'єкт PHP Schedule стільки запланованих завдань, скільки забажаєте. А на сервері вам треба додати єдину Cron-завдання:
Це завдання буде щохвилини викликати планувальник команд Laravel. А той у свою чергу буде перевіряти наявні в плані завдання і виконувати необхідні. Простіше нікуди!
Ще приклади планування
Давайте розглянемо ще кілька прикладів планування.
Планування термінальних команд