Книга: «Laravel. Полное руководство. 3-е издание»16.05.2024 16:15

Как видите, определить сигнатуру команды, текст справки, отображаемый в списках команд, и поведение команды при выполнении (handle ()) совсем не сложно.

Пример команды

Мы еще не рассмотрели почту или Eloquent в этой главе (почта описана в главе 15, а Eloquent — в главе 5), но образец метода handle () в примере 8.2 должен читаться довольно четко.

Пример 8.2. Образец метода handle () для команды Artisan

...
class WelcomeNewUsers extends Command
{
    public function handle(): void
    {
        User::signedUpThisWeek()->each(function ($user) {
            Mail::to($user)->send(new WelcomeEmail);
        });
    }

Теперь каждый раз при запуске php artisan email: newusers эта команда будет находить всех подписавшихся на этой неделе пользователей и отправлять им приветственные письма.

Если вы предпочитаете внедрять свои почтовые и пользовательские зависимости вместо использования фасадов, можно указать их тип в конструкторе команды. И контейнер Laravel внедрит их при создании экземпляра команды.

Взгляните на пример 8.3 — так может выглядеть пример 8.2, но с внедрением зависимостей и переносом поведения в отдельный вспомогательный класс.

Пример 8.3. Та же команда, рефакторинг

...
class WelcomeNewUsers extends Command
{
    public function __construct(UserMailer $userMailer)
    {
        parent::__construct();

        $this->userMailer = $userMailer
    }

    public function handle()
    {
        $this->userMailer->welcomeNewUsers();
    }

НЕ УСЛОЖНЯЙТЕ

Команды Artisan доступны из остальной части вашего кода, поэтому их можно использовать для инкапсуляции логики приложения.

Однако в документации по Laravel рекомендуется упаковывать логику приложения в отдельный класс и внедрять его в вашу команду. Консольные команды похожи на контроллеры: они не являются предметными классами; они регулировщики, которые лишь правильно направляют поступающие запросы.

Аргументы и параметры

Свойство $signature новой команды выглядит так, будто оно может содержать только имя команды. Однако в действительности в нем также определяются аргументы и опции для команды. Существует специальный простой синтаксис, который можно использовать для добавления аргументов и параметров в ваши команды Artisan.

Прежде чем мы углубимся в этот синтаксис, взглянем на пример для некоторого контекста:

protected $signature = 'password:reset {userId} {--sendEmail}';

Аргументы: обязательные, необязательные и/или со значениями по умолчанию

Чтобы определить обязательный аргумент, поместите его в фигурные скобки:

password:reset {userId}

Для необязательного аргумента добавьте знак вопроса:

password:reset {userId?}

Чтобы сделать аргумент необязательным и задать значение по умолчанию, используйте следующую конструкцию:

password:reset {userId=1}

Опции: обязательные значения, значения по умолчанию и сокращенные формы

Опции похожи на аргументы, но имеют префикс — и могут использоваться без значения. Чтобы добавить простую опцию, заключите ее в фигурные скобки:

password:reset {userId} {--sendEmail}

Если опция требует значение — добавьте = к ее сигнатуре:

password:reset {userId} {--password=}

Если вы хотите передать значение по умолчанию, добавьте его после =:

password:reset {userId} {--queue=default}

Аргументы-массивы и опции-массивы

Чтобы позволить передавать массивы в аргументах и опциях, используйте символ *:

password:reset {userIds*}
password:reset {--ids=*}

В примере 8.4 показано, как передать массив в виде аргумента и опции.

Пример 8.4. Использование синтаксиса массива с командами Artisan

// Аргумент
php artisan password:reset 1 2 3

// Параметр
php artisan password:reset --ids=1 --ids=2 --ids=3

Аргумент-массив должен быть последним аргументом

Поскольку аргумент-массив захватывает все параметры после его определения и объединяет их в массив, такой аргумент должен быть последним в сигнатуре команды Artisan.

Описание ввода

Встроенные команды Artisan могут сообщать дополнительную информацию о своих параметрах, если использовать artisan help. Мы в своих командах тоже можем предоставить подобную информацию. Просто добавьте двоеточие и текст описания в фигурных скобках, как в примере 8.5.

Пример 8.5. Описание аргументов и опций Artisan

protected $signature = 'password:reset
                        {userId : The ID of the user}
                        {--sendEmail : Whether to send user an email}';

Использование ввода

Теперь, предусмотрев прием входных данных, мы должны как-то получить их в методе handle () нашей команды. Для этой цели существует два набора методов.

Методы argument () и arguments ()

$this→arguments () возвращает массив всех аргументов (первым элементом будет имя команды). $this→argument () при вызове без параметров вернет тот же ответ. Я предпочитаю метод с именем во множественном числе, который лучше читается в коде.

Чтобы получить значение только одного аргумента, передайте имя аргумента в качестве параметра в $this→argument (), как показано в примере 8.6.

Пример 8.6. Использование $this→arguments () в команде Artisan

// С определением "password:reset {userId}"
php artisan password:reset 5

// $this->arguments() возвращает этот массив
[
    "command": "password:reset",
    "userId": "5",
]

// $this->argument('userId') возвращает эту строку
"5"

Методы option () и options ()

$this→options () возвращает массив всех опций, включая те, что по умолчанию имеют значение false или null. $this→option () при вызове без параметров вернет тот же ответ. Я предпочитаю метод с именем во множественном числе, который лучше читается в коде.

Чтобы получить значение только одной опции, передайте ее имя в качестве параметра в $this→option (), как показано в примере 8.7.

Пример 8.7. Использование $this→options () в команде Artisan

// С определением "password:reset {--userId=}"
php artisan password:reset --userId=5

// $this->options() возвращает этот массив
[
    "userId" => "5",
    "help" => false,
    "quiet" => false,
    "verbose" => false,
    "version" => false,
    "ansi" => false,
    "no-ansi" => false,
    "no-interaction" => false,
    "env" => null,
]

// $this->option('userId') возвращает эту строку
"5"

В примере 8.8 показана команда Artisan, использующая argument () и option () в методе handle ().

Пример 8.8. Получение ввода в команде Artisan

public function handle()
{
    // Все аргументы, включая имя команды
    $arguments = $this->arguments();

    // Только аргумент 'userId'
    $userid = $this->argument('userId');

    // Все опции, включая некоторые по умолчанию вроде 'no-interaction' и 'env'
    $options = $this->options();

    // Только опция 'sendEmail'
    $sendEmail = $this->option('sendEmail');
}

Приглашения

Есть еще несколько способов получить пользовательский ввод внутри handle (), и все они предполагают интерактивный ввод информации пользователем во время выполнения вашей команды:

ask()

Предлагает пользователю ввести произвольный текст:

$email = $this->ask('What is your email address?');

secret()

Предлагает пользователю ввести произвольный текст, но скрывает ввод с помощью звездочек:

$password = $this->secret('What is the DB password?');

confirm()

Запрашивает у пользователя ответ «да/нет» и возвращает логическое значение:

if ($this->confirm('Do you want to truncate the tables?')) {
    //
}

Все ответы, кроме y или Y, будут рассматриваться как «нет».

anticipate()

Предлагает пользователю ввести произвольный текст и предоставляет варианты автозаполнения, но позволяет пользователю ввести все, что он захочет:

$album = $this->anticipate('What is the best album ever?', [
    "The Joshua Tree", "Pet Sounds", "What's Going On"
]);

choice()

Предлагает пользователю выбрать один из возможных вариантов. Последний параметр является значением по умолчанию, которое возвращается, если пользователь не сделал выбор:

$winner = $this->choice(
    'Who is the best football team?',
    ['Gators', 'Wolverines'],
    0
);

Последний параметр по умолчанию должен быть ключом массива. Поскольку мы передали неассоциативный массив, элементу Gators назначается ключ 0. При желании можно передать ассоциативный массив с ключами:

$winner = $this->choice(
    'Who is the best football team?',
    ['gators' => 'Gators', 'wolverines' => 'Wolverines'],
    'gators'
);

Вывод

Во время выполнения команды могут выводить сообщения пользователю. Например, вызов $this→info () выведет простой текст зеленого цвета:

$this->info('Your command has run successfully.');

Также доступны методы comment () (оранжевый), question () (жирный сине-зеленый), error () (жирный красный) и line () (черно-белый) и newLine () (черно-белый).

Обратите внимание, что точные цвета могут варьироваться от машины к машине, но все пытаются соответствовать стандартам для связи с конечным пользователем.

Табличный вывод

Метод table () упрощает создание таблиц ASCII, заполненных вашими данными. Посмотрите на пример 8.9.

Пример 8.9. Вывод таблиц в командах Artisan

$headers = ['Name', 'Email'];

$data = [
     ['Dhriti', 'dhriti@amrit.com'],
     ['Moses', 'moses@gutierez.com'],
];

// Данные можно получить из базы данных:
$data = App\User::all(['name', 'email'])->toArray();

$this->table($headers, $data);

В примере 8.9 есть два набора данных: заголовки и сами данные. Оба содержат две ячейки на строку. Первая ячейка в каждой строке — это имя, а вторая — адрес электронной почты. Таким образом, данные из вызова Eloquent (который ограничивается извлечением только имени и адреса электронной почты) совпадают с заголовками.

В примере 8.10 показан вывод таблицы.

Пример 8.10. Пример вывода таблицы Artisan

Индикаторы выполнения

Если вы когда-либо запускали npm install, то видели индикатор выполнения. Создадим один в примере 8.11.

Пример 8.11. Индикатор выполнения Artisan

$totalUnits = 350;
$this->output->progressStart($totalUnits);

for ($i = 0; $i < $totalUnits; $i++) {
    sleep(1);

    $this->output->progressAdvance();
}

$this->output->progressFinish();

Сначала мы сообщили системе, сколько единиц нам нужно обработать. Может быть, единица — это пользователь, а у вас 350 пользователей. Затем индикатор разделит всю ширину, доступную на вашем экране, на 350 и будет закрашивать 1/350 часть при каждом вызове progressAdvance (). Когда вы закончите, вызовите progressFinish (), чтобы индикатор знал, что должен прекратить отображаться.

Команды на основе замыканий

Для простоты команды можно определять не как классы, а как замыкания в routes/console.php. Все, о чем рассказывается в текущей главе, в равной степени применимо и к данному способу, с той лишь разницей, что команды определяются и регистрируются в этом файле за один шаг, как показано в примере 8.12.

Пример 8.12. Определение команды Artisan с использованием замыкания

// routes/console.php
Artisan::command(
    'password:reset {userId} {--sendEmail}',
    function ($userId, $sendEmail) {
         $userId = $this->argument('userId');
         // Некий код...
    }
);

Вызов команд Artisan в нормальном коде

Команды Artisan предназначены для запуска из командной строки, но их также можно вызывать из другого кода.

Самый простой способ — использовать фасад Artisan. Вызвать команду можно с помощью функции Artisan: call () (которая вернет код завершения команды), или поставить команду в очередь, использовав Artisan: queue ().

Обе функции принимают два параметра: консольную команду (password: reset) и массив параметров для нее. В примере 8.13 показана работа с аргументами и опциями.

Пример 8.13. Вызов команд Artisan из другого кода

Route::get('test-artisan', function () {
    $exitCode = Artisan::call('password:reset', [
        'userId' => 15,
        '--sendEmail' => true,
    ]);
});

Значения аргументов передаются вместе с их именами, а с опциями без значения можно передавать true или false.

Есть более простой способ вызова команд Artisan из кода. Передайте ту же строку, которую вы вводите в командной строке, в вызов Artisan: call ():

Artisan::call('password:reset 15 --sendEmail')

Команды Artisan можно вызывать из других команд, используя $this→call () (действует так же, как Artisan: call ()) или $this→callSilent () (действует аналогично, но подавляет вывод). Посмотрите на пример 8.14.

Пример 8.14. Вызов команд Artisan из других команд Artisan

public function handle()
{
    $this->callSilent('password:reset', [
        'userId' => 15,
    ]);
}

Наконец, можно внедрить экземпляр контракта Illuminate\Contracts\Console\Kernel и использовать его метод call ().

Tinker

Tinker — это интерактивная оболочка REPL, или «прочитать — выполнить — вывести результат — повторить». REPL выводит приглашение, похожее на приглашение командной строки, которое имитирует состояние ожидания вашего приложения. Вы вводите свои команды в REPL, нажимаете Return и ожидаете, пока команда выполнится и на экране появится ответ.

В примере 8.15 приводится короткая выдержка из сеанса работы с оболочкой REPL, чтобы вы могли получить представление о том, как она работает и насколько может быть полезной. После входа в REPL командой php artisan tinker мы получаем приглашение (>>>). Каждый ответ на наши команды выводится в строке, начинающейся с символов =>.

Пример 8.15. Использование Tinker

$ php artisan tinker

>>> $user = new App\User;
=> App\User: {}
>>> $user->email = ‘matt@mattstauffer.com’;
=> "matt@mattstauffer.com"
>>> $user->password = bcrypt(‘superSecret’);
=> "$2y$10$TWPGBC7e8d1bvJ1q5kv.VDUGfYDnE9gANl4mleuB3htIY2dxcQfQ5"
>>> $user->save();
=> true

Мы создали нового пользователя, установили некоторые данные (для безопасности хешировали пароль с помощью bcrypt ()) и сохранили их в базе данных. И это реально. Будь это производственное приложение, мы бы просто создали нового пользователя в системе.

Это делает Tinker отличным инструментом для выполнения простых операций с базой данных, апробации новых идей и запуска фрагментов кода, когда трудно найти место для размещения их в исходных файлах приложения.

Tinker работает на Psy Shell (http://psysh.org/). Загляните по этому адресу, чтобы узнать, что еще может предложить Tinker.

Сервер дампа Laravel

Одним из распространенных методов отладки состояния данных во время разработки является использование вспомогательной функции dump () Laravel, которая запускает более красивый var_dump () для всего, что вы ей передаете. Это хорошо, но часто чревато проблемами с представлениями.

В проектах Laravel можно включить сервер дампа Laravel, который будет перехватывать обращения к dump () и отображать вывод в консоли вместо страницы.

Чтобы запустить сервер дампа в локальной консоли, перейдите в корневой каталог проекта и запустите php artisan dump-server:

$ php artisan dump-server

Laravel Var Dump Server
=======================

  [OK] Server listening on tcp://127.0.0.1:9912

  // Остановить сервер можно нажатием CTRL+C

Теперь попробуйте использовать функцию dump () где-нибудь в вашем коде. Для пробы введите этот код в ваш файл route/web.php:

Route::get('/', function () {
    dump('Dumped Value');

    return 'Hello World';
});

Без сервера дампов вы увидите в браузере и дамп, и строку «Hello, World!». Но после запуска сервера дампов в браузере появится только строка «Hello, World!». В своей консоли вы увидите, что сервер дампа перехватил вызов dump (), и вы можете исследовать вывод там:

GET http://myapp.test/
--------------------

------------ ---------------------------------
 date         Tue, 18 Sep 2018 22:43:10 +0000
 controller   "Closure"
 source       web.php on line 20
 file         routes/web.php
------------ ---------------------------------

"Dumped Value"

Настройка шаблонов генератора

Любые команды Artisan, генерирующие файлы (например, make: model и make: controller), используют файлы-шаблоны, которые команда затем копирует и изменяет, чтобы создать новые файлы. Вы можете настроить эти шаблоны в своих приложениях.

Для этого запустите команду php artisan stub: publish — она опубликует файлы шаблонов в каталог stub/, где вы сможете их настроить.

Тестирование

Зная, как вызывать команды Artisan из кода, вы с легкостью сможете добавить их в свои тесты и проверить правильность любого ожидаемого поведения, как показано в примере 8.16. В наших тестах мы используем метод $this→artisan () вместо Artisan: call (), потому что он имеет тот же синтаксис, но добавляет несколько связанных с тестированием проверок.

Пример 8.16. Вызов команд Artisan из теста

public function test_empty_log_command_empties_logs_table()
{
    DB::table('logs')->insert(['message' => 'Did something']);
    $this->assertCount(1, DB::table('logs')->get());

    $this->artisan('logs:empty'); // То же, что и Artisan::call('logs:empty');
    $this->assertCount(0, DB::table('logs')->get());
}

При желании вы можете добавить цепочку проверок к вызову $this→artisan (). Это поможет упростить тестирование команд Artisan и понять не только какое влияние они оказывают на остальную часть вашего приложения, но и как они на самом деле работают. В примере 8.17 приведен образец такого синтаксиса.

Пример 8.17. Проверка ввода и вывода команд Artisan

public function testItCreatesANewUser()
{
    $this->artisan('myapp:create-user')
        ->expectsQuestion("What's the name of the new user?", "Wilbur Powery")
        ->expectsQuestion("What's the email of the new user?", "wilbur@thisbook.co")
        ->expectsQuestion("What's the password of the new user?", "secret")
        ->expectsOutput("User Wilbur Powery created!");

    $this->assertDatabaseHas('users', [
        'email' => 'wilbur@thisbook.co'
    ]);
}

Резюме

Команды Artisan являются инструментами командной строки Laravel. Laravel поставляется с несколькими готовыми командами Artisan, но их легко создавать и вызывать из командной строки или собственного кода.

Tinker — это интерактивная оболочка REPL, которая упрощает вход в среду вашего приложения и взаимодействие с реальными кодом и данными, а сервер дампа позволяет отлаживать код без остановки его выполнения.

Более подробно с книгой можно ознакомиться на сайте издательства:

» Оглавление
» Отрывок

По факту оплаты бумажной версии книги на e-mail высылается электронная книга.
Для Хаброжителей скидка 25% по купону — Laravel

Habrahabr.ru прочитано 3219 раз