Artisan Console

• Introduction
  • Tinker (REPL)
• Writing Commands
  • Generating Commands
  • Command Structure
  • Closure Commands
  • Isolatable Commands
• Defining Input Expectations
  • Arguments
  • Options
  • Input Arrays
  • Input Descriptions
  • Prompting for Missing Input
• Command I/O
  • Retrieving Input
  • Prompting for Input
  • Writing Output
• Registering Commands
• Programmatically Executing Commands
  • Calling Commands From Other Commands
• Signal Handling
• Stub Customization
• Events

Introduction

아티즌(Artisan)은 Laravel에 기본 포함된 명령줄 인터페이스입니다. 아티즌은 애플리케이션의 루트 디렉터리에 artisan 스크립트 파일로 존재하며, 애플리케이션을 개발할 때 유용하게 활용할 수 있는 여러 가지 명령어를 제공합니다. 사용 가능한 모든 아티즌 명령어 목록을 확인하려면 list 명령어를 사용할 수 있습니다.

php artisan list

각 명령어에는 해당 명령어에서 사용할 수 있는 인수와 옵션을 보여주고 설명하는 "도움말" 화면이 포함되어 있습니다. 명령어의 도움말을 확인하려면, 명령어 이름 앞에 help를 붙여 실행하면 됩니다.

php artisan help migrate

Laravel Sail

로컬 개발 환경으로 Laravel Sail을 사용하고 있다면, 아티즌 명령어를 실행할 때 sail 커맨드 라인을 이용해야 한다는 점을 기억하세요. Sail을 통해 실행하는 경우, 명령어는 애플리케이션의 Docker 컨테이너 내에서 동작합니다.

./vendor/bin/sail artisan list

Tinker (REPL)

Laravel Tinker는 Laravel 프레임워크에서 사용할 수 있는 강력한 REPL 환경으로, PsySH 패키지를 기반으로 동작합니다.

Installation

모든 Laravel 애플리케이션에는 기본적으로 Tinker가 포함되어 있습니다. 만약 Tinker를 제거했다면, Composer를 이용해 다시 설치할 수 있습니다.

composer require laravel/tinker

Laravel 애플리케이션을 조작할 때 핫 리로딩, 여러 줄 코드 편집, 자동 완성 기능이 필요하다면 Tinkerwell도 참고해 보세요!

Usage

Tinker를 이용하면 Eloquent 모델, 잡(jobs), 이벤트 등 Laravel 애플리케이션 전체를 명령줄에서 직접 조작할 수 있습니다. Tinker 환경에 진입하려면 tinker 아티즌 명령어를 실행하세요.

php artisan tinker

vendor:publish 명령어를 이용해 Tinker의 설정 파일을 공개(publish)할 수도 있습니다.

php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"

dispatch 헬퍼 함수와 Dispatchable 클래스의 dispatch 메서드는 잡을 큐에 넣기 위해 가비지 컬렉션에 의존합니다. 따라서 Tinker를 사용할 때는 잡을 큐에 추가할 때 Bus::dispatch 또는 Queue::push를 사용해야 합니다.

Command Allow List

Tinker는 쉘 안에서 어떤 아티즌 명령어를 실행할 수 있는지를 "허용 리스트"로 제한합니다. 기본적으로 clear-compiled, down, env, inspire, migrate, migrate:install, up, optimize 명령어를 실행할 수 있습니다. 만약 더 많은 명령어를 허용하고 싶다면, tinker.php 설정 파일의 commands 배열에 추가할 수 있습니다.

'commands' => [
    // App\Console\Commands\ExampleCommand::class,
],

Classes That Should Not Be Aliased

Tinker는 일반적으로 Tinker에서 사용되는 클래스에 자동으로 별칭을 지정합니다. 하지만 일부 클래스는 별칭으로 등록하고 싶지 않을 수 있습니다. 이럴 때는 tinker.php 설정 파일의 dont_alias 배열에 해당 클래스명을 추가하면 됩니다.

'dont_alias' => [
    App\Models\User::class,
],

Writing Commands

아티즌에 기본으로 내장된 명령어 외에도, 직접 커스텀 명령어를 만들어 사용할 수 있습니다. 명령어는 보통 app/Console/Commands 디렉터리에 저장하지만, Composer로 로딩할 수 있는 위치라면 어디든 자유롭게 저장할 수 있습니다.

Generating Commands

새로운 명령어를 만들려면 make:command 아티즌 명령어를 사용할 수 있습니다. 이 명령어를 실행하면 app/Console/Commands 디렉터리에 새 명령어 클래스가 생성됩니다. 해당 디렉터리가 없는 경우에도, make:command 명령어를 처음 실행할 때 자동 생성됩니다.

php artisan make:command SendEmails

Command Structure

명령어를 생성한 다음에는 클래스의 signature와 description 속성(property)에 적절한 값을 지정해야 합니다. 이 속성들은 list 화면에서 명령어를 표시할 때 활용됩니다. 특히 signature 속성은 your command's input expectations도 함께 정의합니다. 명령어가 실행되면 handle 메서드가 호출되며, 이 메서드 안에 해당 명령어의 동작 로직을 작성하면 됩니다.

예시 명령어를 함께 살펴보겠습니다. 아래 예제에서는 명령어의 handle 메서드를 통해 필요한 의존성을 주입받을 수 있습니다. Laravel의 service container가 이 메서드의 시그니처에 타입힌트된 모든 의존성을 자동으로 주입해줍니다.

<?php

namespace App\Console\Commands;

use App\Models\User;
use App\Support\DripEmailer;
use Illuminate\Console\Command;

class SendEmails extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Send a marketing email to a user';

    /**
     * Execute the console command.
     */
    public function handle(DripEmailer $drip): void
    {
        $drip->send(User::find($this->argument('user')));
    }
}

코드의 재사용성을 높이려면, 콘솔 명령어 자체는 되도록 단순하게 유지하고, 실제 작업은 애플리케이션 서비스에 위임하는 것이 좋은 습관입니다. 위 예제에서도 이메일 전송의 실제 처리는 서비스 클래스에 맡기고 있습니다.

Exit Codes

handle 메서드에서 아무 값도 반환하지 않고 정상적으로 명령어를 실행하면, 종료 코드 0으로 성공을 나타냅니다. 하지만 필요하다면 handle 메서드에서 정수형 값을 반환하여 명령어의 종료 코드를 수동으로 지정할 수도 있습니다.

$this->error('Something went wrong.');

return 1;

명령어 클래스 내부의 어느 메서드에서든 명령어를 "실패" 상태로 종료하고 싶다면 fail 메서드를 사용할 수 있습니다. fail 메서드를 실행하면 즉시 명령어 동작을 중단하고, 종료 코드 1을 반환합니다.

$this->fail('Something went wrong.');

Closure Commands

클로저 기반 명령어는 클래스로 명령어를 정의하는 대신, 클로저로 콘솔 명령어를 정의할 수 있는 대안을 제공합니다. 마치 라우트의 컨트롤러 대신 라우트 클로저를 사용하는 것처럼, 콘솔 명령어를 클래스 대신 클로저로도 만들 수 있습니다.

routes/console.php 파일에서는 HTTP 라우트를 정의하지 않지만, 애플리케이션 진입점 역할을 하는 콘솔 기반 라우트(엔트리)를 정의합니다. 이 파일에서는 Artisan::command 메서드를 통해 클로저 기반 콘솔 명령어를 모두 정의할 수 있습니다. command 메서드는 두 개의 인자(아규먼트)를 받으며, 첫 번째는 command signature, 두 번째는 명령어 인수와 옵션을 받는 클로저입니다.

Artisan::command('mail:send {user}', function (string $user) {
    $this->info("Sending email to: {$user}!");
});

클로저는 내부적으로 해당 명령어 인스턴스에 바인딩되어, 클래스 기반 명령어에서 접근할 수 있던 헬퍼 메서드를 그대로 사용할 수 있습니다.

Type-Hinting Dependencies

명령어 인수와 옵션뿐만 아니라, 클로저로 만든 명령어에서도 추가로 필요한 의존성을 service container로부터 타입힌트로 받아올 수 있습니다.

use App\Models\User;
use App\Support\DripEmailer;

Artisan::command('mail:send {user}', function (DripEmailer $drip, string $user) {
    $drip->send(User::find($user));
});

Closure Command Descriptions

클로저 기반 명령어를 정의할 때, purpose 메서드를 사용하면 해당 명령어에 대한 설명을 추가할 수 있습니다. 이 설명은 php artisan list나 php artisan help 명령어를 실행할 때 표시됩니다.

Artisan::command('mail:send {user}', function (string $user) {
    // ...
})->purpose('Send a marketing email to a user');

Isolatable Commands

이 기능을 사용하려면, 애플리케이션의 기본 캐시 드라이버로 memcached, redis, dynamodb, database, file, 또는 array 드라이버 중 하나를 선택해야 합니다. 또한 모든 서버가 동일한 중앙 캐시 서버와 통신해야 합니다.

동일한 명령어가 한 번에 단 하나만 실행되도록 제한하고 싶을 때가 있습니다. 이럴 때는 명령어 클래스에 Illuminate\Contracts\Console\Isolatable 인터페이스를 구현하면 됩니다.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Contracts\Console\Isolatable;

class SendEmails extends Command implements Isolatable
{
    // ...
}

명령어에 Isolatable이 표시되어 있으면, Laravel은 해당 명령어에 자동으로 --isolated 옵션을 추가합니다. 이 옵션과 함께 명령어를 실행하면, 동일한 명령어가 이미 실행 중인 경우 중복으로 실행되지 않도록 Laravel이 관리합니다. Laravel은 기본 캐시 드라이버를 사용해 원자적 락(atomic lock)을 시도하여 이를 구현합니다. 만약 이미 실행 중인 명령어가 있으면, 실제 명령어 동작은 실행되지 않지만, 종료 상태 코드는 성공으로 반환됩니다.

php artisan mail:send 1 --isolated

명령어가 실행되지 않았을 때 반환할 종료 상태 코드를 직접 지정하려면, isolated 옵션에 원하는 코드를 입력할 수 있습니다.

php artisan mail:send 1 --isolated=12

Lock ID

기본적으로 Laravel은 원자적 락의 문자열 키를 생성할 때 명령어 이름을 사용합니다. 하지만, isolatableId 메서드를 아티즌 명령어 클래스에 정의하면, 필요한 경우 명령어 인수나 옵션을 락 키에 추가하는 등 값을 직접 커스터마이즈할 수 있습니다.

/**
 * Get the isolatable ID for the command.
 */
public function isolatableId(): string
{
    return $this->argument('user');
}

Lock Expiration Time

기본적으로, 격리 락(isolation lock)은 명령어 실행이 끝나면 바로 만료됩니다. 명령어 실행이 중단되어 끝나지 못했다면, 락은 한 시간 후 자동으로 만료됩니다. 만약 이 만료 시간을 직접 조정하고 싶으면, 명령어 클래스에 isolationLockExpiresAt 메서드를 정의할 수 있습니다.

use DateTimeInterface;
use DateInterval;

/**
 * Determine when an isolation lock expires for the command.
 */
public function isolationLockExpiresAt(): DateTimeInterface|DateInterval
{
    return now()->addMinutes(5);
}

Defining Input Expectations

콘솔 명령어를 작성할 때, 사용자로부터 인수 또는 옵션 등의 입력값을 받는 일이 많습니다. Laravel에서는 명령어의 signature 속성을 사용해 입력 기대값을 매우 직관적이고 선언적으로 정의할 수 있습니다. signature 속성에서 명령어의 이름, 인수, 옵션을 하나의 명령어 시그니처(라우트처럼 표현)로 정의합니다.

Arguments

사용자로부터 입력받는 모든 인수와 옵션은 중괄호로 감쌉니다. 아래 예제에서 명령어는 user라는 이름의 필수 인수를 정의합니다.

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user}';

인수를 선택적으로 만들거나, 기본값을 정의할 수도 있습니다.

// Optional argument...
'mail:send {user?}'

// Optional argument with default value...
'mail:send {user=foo}'

Options

옵션 역시 인수와 같이 사용자 입력을 받는 또 다른 방식입니다. 옵션은 커맨드 라인에서 두 개의 하이픈(--)을 붙여 지정합니다. 옵션에는 값이 필요한 경우와 값이 없는 경우(스위치형)이 있습니다. 값이 없는 옵션은 불리언(boolean) 스위치 역할을 합니다. 아래 예시는 불리언 스위치형 옵션입니다.

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue}';

이 예에서는 --queue 스위치를 아티즌 명령어 실행 시 지정할 수 있습니다. --queue 스위치가 전달되면 옵션 값은 true, 전달되지 않으면 false가 됩니다.

php artisan mail:send 1 --queue

Options With Values

이번에는 값이 반드시 필요한 옵션을 살펴보겠습니다. 값을 꼭 지정해야 하는 옵션에는 옵션명 뒤에 =(등호)를 붙여 표현합니다.

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue=}';

이 예제에서, 사용자는 아래와 같이 옵션 값을 넘길 수 있습니다. 만약 옵션 없이 명령어를 실행하면 해당 옵션 값은 null입니다.

php artisan mail:send 1 --queue=default

옵션에도 기본값을 지정할 수 있으며, 값을 넘기지 않은 경우에는 기본값이 사용됩니다.

'mail:send {user} {--queue=default}'

Option Shortcuts

옵션에 단축키를 부여하려면 옵션명 앞에 단축키를 쓰고, |(파이프)로 구분하면 됩니다.

'mail:send {user} {--Q|queue}'

터미널에서 명령어를 실행할 때는 옵션 단축키 앞에 하이픈 하나만 붙이고, 값을 지정할 경우 등호(=) 없이 바로 이어 붙이면 됩니다.

php artisan mail:send 1 -Qdefault

Input Arrays

여러 개의 입력값(인수 또는 옵션)을 받고 싶을 때는 * 문자로 정의하면 됩니다. 먼저 인수 예시를 보겠습니다.

'mail:send {user*}'

이 방식으로 명령어를 실행할 때, user 인수는 명령줄에 순서대로 전달할 수 있습니다. 예를 들어 아래 명령어를 실행하면, user의 값은 1과 2를 원소로 가지는 배열이 됩니다.

php artisan mail:send 1 2

* 문자는 선택적 인수 옵션과 함께 사용해 인수 값을 0개 이상 받을 수도 있습니다.

'mail:send {user?*}'

Option Arrays

옵션도 여러 값이 필요한 경우, 값마다 옵션명을 반복해서 넘기면 됩니다.

'mail:send {--id=*}'

이렇게 정의하면 명령어 실행 시 여러 --id 옵션을 넘길 수 있습니다.

php artisan mail:send --id=1 --id=2

Input Descriptions

명령어 인수와 옵션에 콜론을 사용해 이름과 설명을 구분하여 설명을 추가할 수 있습니다. 명령어 시그니처가 길어질 경우 여러 줄에 걸쳐 정의해도 괜찮습니다.

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send
                        {user : The ID of the user}
                        {--queue : Whether the job should be queued}';

Prompting for Missing Input

명령어에 필수 인수가 있을 때, 사용자가 입력하지 않으면 에러 메시지가 표시됩니다. 대신, 필수 인수가 누락된 경우 사용자에게 입력을 자동으로 요청하도록 설정할 수도 있습니다. 이를 위해 PromptsForMissingInput 인터페이스를 구현하면 됩니다.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Contracts\Console\PromptsForMissingInput;

class SendEmails extends Command implements PromptsForMissingInput
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';

    // ...
}

Laravel이 필수 인수를 입력받아야 하는 상황이라면, 자동으로 인수의 이름이나 설명을 기반으로 적절한 질문을 생성해 사용자에게 입력을 요청합니다. 만약 입력 요청에 사용할 질문을 직접 지정하고 싶으면, promptForMissingArgumentsUsing 메서드를 구현해 각 인수 이름별로 질문 배열을 반환하면 됩니다.

/**
 * Prompt for missing input arguments using the returned questions.
 *
 * @return array<string, string>
 */
protected function promptForMissingArgumentsUsing(): array
{
    return [
        'user' => 'Which user ID should receive the mail?',
    ];
}

질문과 함께 플레이스홀더(placeholder) 텍스트도 튜플 형태로 제공할 수 있습니다.

return [
    'user' => ['Which user ID should receive the mail?', 'E.g. 123'],
];

프롬프트 전체를 커스터마이징하고 싶다면, 사용자 입력을 요청하고 그 답을 반환하는 클로저를 지정할 수도 있습니다.

use App\Models\User;
use function Laravel\Prompts\search;

// ...

return [
    'user' => fn () => search(
        label: 'Search for a user:',
        placeholder: 'E.g. Taylor Otwell',
        options: fn ($value) => strlen($value) > 0
            ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
            : []
    ),
];

자세한 프롬프트 활용법은 Laravel Prompts 공식 문서를 참고하세요.

사용자에게 options을 선택하거나 직접 입력하도록 프롬프트를 띄우고 싶다면, 프롬프트를 명령어의 handle 메서드에서 실행하면 됩니다. 하지만 누락된 인수 프롬프트가 자동으로 띄워진 뒤에만 추가로 질의를 하고 싶다면, afterPromptingForMissingArguments 메서드를 구현해 활용할 수 있습니다.

use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use function Laravel\Prompts\confirm;

// ...

/**
 * Perform actions after the user was prompted for missing arguments.
 */
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output): void
{
    $input->setOption('queue', confirm(
        label: 'Would you like to queue the mail?',
        default: $this->option('queue')
    ));
}

Command I/O

Retrieving Input

명령어가 실행되는 동안, 사용자가 넘긴 인수나 옵션 값을 코드에서 사용할 일이 많습니다. 이럴 때는 argument와 option 메서드를 사용할 수 있습니다. 해당 인수 또는 옵션이 존재하지 않는 경우 null이 반환됩니다.

/**
 * Execute the console command.
 */
public function handle(): void
{
    $userId = $this->argument('user');
}

모든 인수값을 array로 한꺼번에 가져오려면 arguments 메서드를 호출하면 됩니다.

$arguments = $this->arguments();

옵션 역시 option 메서드로 쉽게 값을 가져올 수 있으며, 전체 옵션 값을 배열로 가져오려면 options 메서드를 사용합니다.

// Retrieve a specific option...
$queueName = $this->option('queue');

// Retrieve all options as an array...
$options = $this->options();

Prompting for Input

Laravel Prompts는 커맨드 라인 애플리케이션에 아름답고 사용자 친화적인 폼을 추가할 수 있는 PHP 패키지입니다. 이 패키지는 플레이스홀더 텍스트와 유효성 검증 등 브라우저와 비슷한 기능도 제공합니다.

출력만 하는 것이 아니라, 명령어 실행 중 사용자에게 직접 입력을 요청할 수도 있습니다. ask 메서드를 사용하면 사용자가 입력해야 할 질문을 표시하고, 입력 값을 받아 명령어 내부에서 활용할 수 있습니다.

/**
 * Execute the console command.
 */
public function handle(): void
{
    $name = $this->ask('What is your name?');

    // ...
}

ask 메서드는 두 번째 인수로 기본값도 지정할 수 있습니다. 사용자가 아무 값도 입력하지 않으면 이 값이 반환됩니다.

$name = $this->ask('What is your name?', 'Taylor');

secret 메서드는 ask와 유사하지만, 사용자가 콘솔에 입력하는 내용을 화면에 표시하지 않습니다. 비밀번호 등 민감한 정보를 질문할 때 유용합니다.

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

Asking for Confirmation

사용자에게 단순한 "예/아니오" 확인을 받고 싶을 때는 confirm 메서드를 사용할 수 있습니다. 이 메서드는 기본적으로 false를 반환하지만, 사용자가 y 혹은 yes를 입력하면 true를 반환합니다.

if ($this->confirm('Do you wish to continue?')) {
    // ...
}

필요하다면, confirm 메서드의 두 번째 인수로 true를 전달해 기본값을 true로 설정할 수도 있습니다.

if ($this->confirm('Do you wish to continue?', true)) {
    // ...
}

Auto-Completion

anticipate 메서드는 입력 값에 대한 자동 완성 기능을 제공합니다. 자동 완성 힌트와 관계없이 사용자는 어떤 값을 입력해도 됩니다.

$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);

또는, anticipate 메서드의 두 번째 인수로 클로저를 넘길 수도 있습니다. 이 클로저는 사용자가 문자를 입력할 때마다 호출되며, 입력한 내용을 인수로 받아 자동 완성 옵션의 배열을 반환해야 합니다.

$name = $this->anticipate('What is your address?', function (string $input) {
    // Return auto-completion options...
});

Multiple Choice Questions

사용자에게 미리 정해진 여러 선택지 중 하나를 선택하도록 하려면 choice 메서드를 사용할 수 있습니다. 세 번째 인수로 기본값에 해당하는 배열의 인덱스를 지정할 수도 있습니다. 사용자가 아무것도 선택하지 않으면 이 인덱스의 값이 반환됩니다.

$name = $this->choice(
    'What is your name?',
    ['Taylor', 'Dayle'],
    $defaultIndex
);

또한, choice 메서드는 유효한 값을 선택할 수 있는 최대 시도 횟수와 다중 선택 허용 여부를 결정하는 선택적 네 번째, 다섯 번째 인수를 받습니다.

$name = $this->choice(
    'What is your name?',
    ['Taylor', 'Dayle'],
    $defaultIndex,
    $maxAttempts = null,
    $allowMultipleSelections = false
);

Writing Output

콘솔로 메시지를 출력하려면 line, info, comment, question, warn, error 등의 메서드를 사용할 수 있습니다. 이 메서드들은 각각에 맞는 ANSI 색상을 사용해 텍스트를 표시합니다. 예를 들어, 일반적인 정보를 사용자에게 보여 주고 싶으면 info 메서드를 사용합니다. 이때는 보통 콘솔에 초록색 글자로 출력됩니다.

/**
 * Execute the console command.
 */
public function handle(): void
{
    // ...

    $this->info('The command was successful!');
}

오류 메시지를 출력하려면 error 메서드를 사용합니다. 오류 메시지는 보통 빨간색으로 표시됩니다.

$this->error('Something went wrong!');

색상 없이 일반 텍스트를 출력하고 싶을 때는 line 메서드를 사용합니다.

$this->line('Display this on the screen');

빈 줄을 출력하려면 newLine 메서드를 사용합니다.

// Write a single blank line...
$this->newLine();

// Write three blank lines...
$this->newLine(3);

Tables

table 메서드는 여러 행과 컬럼으로 이루어진 데이터를 보기 좋게 테이블 형식으로 출력할 수 있도록 도와줍니다. 컬럼명과 데이터만 넘겨주면, Laravel이 테이블의 너비와 높이를 자동으로 계산해서 출력해 줍니다.

use App\Models\User;

$this->table(
    ['Name', 'Email'],
    User::all(['name', 'email'])->toArray()
);

Progress Bars

처리 시간이 오래 걸리는 작업을 할 때, 현재 완료된 정도를 사용자에게 보여주면 좋습니다. withProgressBar 메서드를 사용하면, Laravel이 주어진 반복 가능한 값에 대해 순회할 때 자동으로 진행률 바를 표시하고 진행 상황을 갱신합니다.

use App\Models\User;

$users = $this->withProgressBar(User::all(), function (User $user) {
    $this->performTask($user);
});

좀 더 세밀하게 진행률 바의 동작을 제어하려면, 먼저 전체 단계 수를 지정해서 진행률 바를 만들고, 각 항목을 처리할 때마다 직접 진행 상황을 갱신하면 됩니다.

$users = App\Models\User::all();

$bar = $this->output->createProgressBar(count($users));

$bar->start();

foreach ($users as $user) {
    $this->performTask($user);

    $bar->advance();
}

$bar->finish();

더 많은 고급 옵션이 궁금하다면 Symfony Progress Bar component documentation를 참고하십시오.

Registering Commands

기본적으로 Laravel은 app/Console/Commands 디렉토리 안에 있는 모든 명령어를 자동으로 등록합니다. 하지만, 애플리케이션의 bootstrap/app.php 파일에서 withCommands 메서드를 사용해 다른 디렉토리에서 Artisan 명령어를 검색하도록 지시할 수도 있습니다.

->withCommands([
    __DIR__.'/../app/Domain/Orders/Commands',
])

필요하다면, 명령어 클래스 이름을 직접 지정해서 withCommands 메서드로 수동 등록할 수도 있습니다.

use App\Domain\Orders\Commands\SendEmails;

->withCommands([
    SendEmails::class,
])

Artisan이 부팅될 때, 애플리케이션의 모든 명령어는 service container에 의해 resolve(해결)되고 Artisan에 등록됩니다.

Programmatically Executing Commands

CLI가 아닌 곳에서 Artisan 명령어를 실행하고 싶을 때가 있습니다. 예를 들어, 라우트나 컨트롤러 내부에서 Artisan 명령어를 실행하고자 할 수 있습니다. 이럴 때는 Artisan 파사드의 call 메서드를 사용하면 됩니다. call 메서드의 첫 번째 인수에는 명령어 시그니처 이름이나 클래스 이름을 넣고, 두 번째 인수로는 명령어 파라미터의 배열을 넘깁니다. 반환값은 종료 코드(exit code)입니다.

use Illuminate\Support\Facades\Artisan;

Route::post('/user/{user}/mail', function (string $user) {
    $exitCode = Artisan::call('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);

    // ...
});

또는 전체 Artisan 명령어를 문자열로 call 메서드에 전달할 수도 있습니다.

Artisan::call('mail:send 1 --queue=default');

Passing Array Values

명령어에서 배열을 인수로 받도록 옵션을 정의한 경우, 해당 옵션에 값의 배열을 넘길 수 있습니다.

use Illuminate\Support\Facades\Artisan;

Route::post('/mail', function () {
    $exitCode = Artisan::call('mail:send', [
        '--id' => [5, 13]
    ]);
});

Passing Boolean Values

migrate:refresh 명령어의 --force 플래그처럼 문자열이 아닌 값을 받아야 하는 옵션에는 값으로 true나 false를 지정할 수 있습니다.

$exitCode = Artisan::call('migrate:refresh', [
    '--force' => true,
]);

Queueing Artisan Commands

Artisan 파사드의 queue 메서드를 사용하면 Artisan 명령어를 큐에 넣어서, queue workers가 백그라운드에서 처리하도록 할 수 있습니다. 이 기능을 사용하기 전에 큐 설정을 마치고 큐 리스너가 실행 중인지 확인해야 합니다.

use Illuminate\Support\Facades\Artisan;

Route::post('/user/{user}/mail', function (string $user) {
    Artisan::queue('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);

    // ...
});

onConnection과 onQueue 메서드를 사용하면 해당 Artisan 명령어가 전송될 큐 커넥션이나 큐 이름도 직접 지정할 수 있습니다.

Artisan::queue('mail:send', [
    'user' => 1, '--queue' => 'default'
])->onConnection('redis')->onQueue('commands');

Calling Commands From Other Commands

기존 Artisan 명령어 내부에서 또 다른 명령어를 호출해야 할 때가 있습니다. 이럴 때는 call 메서드를 사용할 수 있습니다. 이 call 메서드는 명령어 이름과 인수/옵션 배열을 인수로 받습니다.

/**
 * Execute the console command.
 */
public function handle(): void
{
    $this->call('mail:send', [
        'user' => 1, '--queue' => 'default'
    ]);

    // ...
}

기타 콘솔 명령어를 호출하면서 그 명령어의 모든 출력을 숨기고 싶으면, callSilently 메서드를 사용하면 됩니다. callSilently 메서드는 call 메서드와 동일한 시그니처를 가집니다.

$this->callSilently('mail:send', [
    'user' => 1, '--queue' => 'default'
]);

Signal Handling

운영체제는 프로그램에 신호(signal)를 보낼 수 있습니다. 예를 들어, SIGTERM 신호는 운영체제가 프로그램에 종료를 요청할 때 전송합니다. Artisan 콘솔 명령어에서 이러한 신호를 감지해 신호가 도착했을 때 코드를 실행하고 싶다면, trap 메서드를 사용하면 됩니다.

/**
 * Execute the console command.
 */
public function handle(): void
{
    $this->trap(SIGTERM, fn () => $this->shouldKeepRunning = false);

    while ($this->shouldKeepRunning) {
        // ...
    }
}

여러 개의 신호를 동시에 감지하려면 trap 메서드에 신호들의 배열을 넘길 수 있습니다.

$this->trap([SIGTERM, SIGQUIT], function (int $signal) {
    $this->shouldKeepRunning = false;

    dump($signal); // SIGTERM / SIGQUIT
});

Stub Customization

Artisan 콘솔의 make 명령어는 컨트롤러, 잡, 마이그레이션, 테스트 등 다양한 클래스를 생성합니다. 이 클래스들은 입력 값에 따라 일부 값을 채워넣는 "스텁" 파일을 기반으로 만들어집니다. Artisan이 만들어주는 파일에 소소하게 변경을 가하고 싶다면, stub:publish 명령어로 가장 일반적으로 사용하는 스텁 파일을 애플리케이션에 공개한 뒤, 원하는 대로 수정할 수 있습니다.

php artisan stub:publish

공개된 스텁 파일은 애플리케이션 루트의 stubs 디렉토리에 위치하게 됩니다. 이 파일을 수정하면, Artisan의 make 명령어로 해당 타입의 클래스를 만들 때마다 변경 내용이 반영됩니다.

Events

Artisan은 명령어 실행 시 세 가지 이벤트를 발생시킵니다: Illuminate\Console\Events\ArtisanStarting, Illuminate\Console\Events\CommandStarting, Illuminate\Console\Events\CommandFinished입니다. ArtisanStarting 이벤트는 Artisan이 실행을 시작할 때 바로 발생하며, 그 다음엔서 각 명령어가 실행되기 직전에 CommandStarting 이벤트가 발생합니다. 마지막으로 명령어 실행이 끝나면 CommandFinished 이벤트가 발생합니다.