Artisan 콘솔

번역일: 2026년 7월 2일

Artisan 콘솔

소개
- Tinker (REPL)
커맨드 작성
입력 정의
커맨드 I/O
커맨드 등록
프로그래밍 방식으로 커맨드 실행
- 다른 커맨드에서 커맨드 호출
시그널 처리
스텁 커스터마이징
이벤트

소개

Artisan은 Laravel에 기본으로 포함된 CLI(명령줄 인터페이스)입니다. 애플리케이션 루트 디렉터리에 artisan 스크립트로 존재하며, 개발 과정에서 반복적으로 필요한 다양한 작업을 명령 하나로 처리할 수 있게 도와줍니다. 사용 가능한 모든 Artisan 커맨드 목록을 보려면 list 커맨드를 실행하세요.

php artisan list

모든 커맨드에는 "도움말" 화면이 내장되어 있어, 해당 커맨드가 받을 수 있는 인수와 옵션을 확인할 수 있습니다. 도움말을 보려면 커맨드 이름 앞에 help를 붙여 실행하세요.

php artisan help migrate

Laravel Sail

로컬 개발 환경으로 Laravel Sail을 사용하고 있다면, Artisan 커맨드는 반드시 sail 명령을 통해 실행해야 합니다. Sail은 애플리케이션의 Docker 컨테이너 안에서 커맨드를 실행합니다.

./vendor/bin/sail artisan list

Tinker (REPL)

Laravel Tinker는 Laravel 애플리케이션을 위한 강력한 대화형 REPL(Read-Eval-Print Loop)로, PsySH 패키지를 기반으로 동작합니다.

설치

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

composer require laravel/tinker

NOTE

Laravel 애플리케이션과 상호작용할 수 있는 그래픽 UI가 필요하다면 Tinkerwell을 참고하세요.

사용법

Tinker를 사용하면 Eloquent 모델, Job, 이벤트 등 Laravel 애플리케이션의 모든 요소를 커맨드라인에서 직접 다룰 수 있습니다. Tinker 환경에 진입하려면 tinker Artisan 커맨드를 실행하세요.

php artisan tinker

vendor:publish 커맨드를 통해 Tinker의 설정 파일을 퍼블리시할 수 있습니다.

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

WARNING

dispatch 헬퍼 함수와 Dispatchable 트레이트의 dispatch 메서드는 가비지 컬렉션에 의존하여 Job을 큐에 넣습니다. 따라서 Tinker 내에서는 Bus::dispatch 또는 Queue::push를 사용해 Job을 디스패치하세요.

허용 커맨드 목록

Tinker는 쉘 내에서 실행할 수 있는 Artisan 커맨드를 "허용 목록(allow list)"으로 관리합니다. 기본적으로 clear-compiled, down, env, inspire, migrate, migrate:install, up, optimize 커맨드를 실행할 수 있습니다. 더 많은 커맨드를 허용하려면 tinker.php 설정 파일의 commands 배열에 추가하세요.

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

자동 별칭에서 제외할 클래스

Tinker는 보통 클래스를 Tinker 환경에서 참조할 때 자동으로 별칭(alias)을 지정합니다. 그러나 일부 클래스는 별칭 지정에서 제외하고 싶을 수 있습니다. 이 경우 tinker.php 설정 파일의 dont_alias 배열에 해당 클래스를 추가하세요.

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

Artisan 콘솔

소개

Artisan은 Laravel에 기본으로 포함된 커맨드라인 인터페이스(CLI)입니다. 프로젝트 루트에 위치한 artisan 스크립트를 통해 실행하며, 애플리케이션 개발 전반에 걸쳐 유용한 다양한 명령어를 제공합니다. 사용 가능한 모든 Artisan 명령어 목록을 확인하려면 list 명령어를 사용하세요:

php artisan list

각 명령어에는 사용 가능한 인수(argument)와 옵션(option)을 설명하는 도움말 화면이 있습니다. 도움말을 확인하려면 명령어 앞에 help를 붙이세요:

php artisan help migrate

Laravel Sail

로컬 개발 환경으로 Laravel Sail을 사용하고 있다면, Artisan 명령어를 실행할 때 sail 명령어를 사용해야 합니다. Sail은 Artisan 명령어를 애플리케이션의 Docker 컨테이너 내부에서 실행합니다:

./vendor/bin/sail artisan list

Tinker (REPL)

Laravel Tinker는 PsySH 패키지 기반으로 동작하는 강력한 REPL(Read-Eval-Print Loop) 환경입니다. 코드를 직접 실행하면서 애플리케이션 상태를 탐색하고 디버깅할 수 있어, 개발 중에 매우 유용합니다.

설치

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

composer require laravel/tinker

NOTE

핫 리로딩, 여러 줄 코드 편집, 자동완성 기능이 지원되는 더 강력한 인터랙티브 환경을 원한다면 Tinkerwell을 확인해 보세요!

사용법

Tinker를 사용하면 Eloquent 모델, Job, 이벤트 등 Laravel 애플리케이션의 모든 요소를 커맨드라인에서 직접 조작할 수 있습니다. Tinker 환경으로 진입하려면 다음 Artisan 명령어를 실행하세요:

php artisan tinker

Tinker의 설정 파일을 프로젝트에 게시(publish)하려면 vendor:publish 명령어를 사용하세요:

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

WARNING

dispatch 헬퍼 함수나 Dispatchable 클래스의 dispatch 메서드는 가비지 컬렉션에 의존하여 Job을 큐에 등록합니다. 따라서 Tinker 환경에서 Job을 디스패치할 때는 Bus::dispatch 또는 Queue::push를 사용하세요.

명령어 허용 목록

Tinker는 내부적으로 허용 목록(allow list)을 사용하여 셸에서 실행할 수 있는 Artisan 명령어를 제한합니다. 기본적으로 허용된 명령어는 clear-compiled, down, env, inspire, migrate, migrate:install, up, optimize입니다. 추가로 허용할 명령어가 있다면 tinker.php 설정 파일의 commands 배열에 등록하세요:

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

자동 별칭 제외 클래스

Tinker는 사용하는 클래스에 대해 자동으로 별칭(alias)을 생성합니다. 특정 클래스에 대해 이 동작을 비활성화하려면 tinker.php 설정 파일의 dont_alias 배열에 해당 클래스를 추가하세요:

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

커맨드 작성하기

Artisan에 내장된 커맨드 외에도 직접 커스텀 커맨드를 만들 수 있습니다. 커맨드 클래스는 보통 app/Console/Commands 디렉터리에 저장하지만, Composer가 로드할 수 있는 위치라면 어디든 자유롭게 사용해도 됩니다.

커맨드 생성하기

새 커맨드를 만들려면 make:command Artisan 커맨드를 사용합니다. 이 커맨드는 app/Console/Commands 디렉터리에 새 커맨드 클래스 파일을 생성합니다. 해당 디렉터리가 아직 없어도 걱정할 필요 없습니다. make:command를 처음 실행하는 순간 자동으로 생성됩니다.

php artisan make:command SendEmails

커맨드 구조

커맨드 클래스를 생성한 뒤에는 signature와 description 프로퍼티에 적절한 값을 지정해야 합니다. 이 두 프로퍼티는 php artisan list 화면에서 커맨드 목록을 표시할 때 사용됩니다. signature는 커맨드의 입력 정의도 함께 담당합니다. 커맨드를 실행하면 handle 메서드가 호출되며, 실제 커맨드 로직은 이 메서드 안에 작성합니다.

아래 예시를 살펴보겠습니다. handle 메서드의 파라미터에 타입 힌트를 지정하면 Laravel 서비스 컨테이너가 필요한 의존성을 자동으로 주입해 줍니다.

<?php

namespace App\Console\Commands;

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

class SendEmails extends Command
{
    /**
     * 콘솔 커맨드의 이름과 시그니처
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';

    /**
     * 콘솔 커맨드 설명
     *
     * @var string
     */
    protected $description = '지정한 사용자에게 마케팅 이메일을 발송합니다';

    /**
     * 콘솔 커맨드 실행
     */
    public function handle(DripEmailer $drip): void
    {
        $drip->send(User::find($this->argument('user')));
    }
}

NOTE

코드 재사용성을 높이려면 커맨드 클래스는 가볍게 유지하고, 실제 처리 로직은 서비스 클래스에 위임하는 것이 좋습니다. 위 예시에서도 이메일 발송이라는 무거운 작업은 DripEmailer 서비스 클래스에 맡기고 있습니다.

종료 코드

handle 메서드에서 아무것도 반환하지 않으면 커맨드는 성공을 의미하는 종료 코드 0으로 종료됩니다. 필요하다면 정수를 직접 반환해 종료 코드를 지정할 수도 있습니다.

$this->error('문제가 발생했습니다.');

return 1;

커맨드 내 어느 메서드에서든 즉시 실패 처리가 필요할 때는 fail 메서드를 사용합니다. fail을 호출하면 커맨드 실행이 즉시 중단되고 종료 코드 1이 반환됩니다.

$this->fail('문제가 발생했습니다.');

클로저 커맨드

커맨드를 클래스로 정의하는 대신 클로저로 간결하게 작성할 수도 있습니다. HTTP 라우트에서 컨트롤러 대신 클로저를 사용하는 것과 같은 개념입니다.

routes/console.php 파일은 HTTP 라우트를 정의하지 않지만, 애플리케이션의 콘솔 진입점(라우트)을 정의합니다. 이 파일에서 Artisan::command 메서드를 사용해 클로저 기반 커맨드를 등록할 수 있습니다. command 메서드는 두 개의 인수를 받습니다. 첫 번째는 커맨드 시그니처, 두 번째는 커맨드의 인수와 옵션을 받는 클로저입니다.

Artisan::command('mail:send {user}', function (string $user) {
    $this->info("이메일 발송 대상: {$user}!");
});

클로저는 내부적으로 커맨드 인스턴스에 바인딩되므로, 커맨드 클래스에서 사용할 수 있는 모든 헬퍼 메서드를 그대로 사용할 수 있습니다.

의존성 타입 힌트

클로저 커맨드에서도 커맨드 인수·옵션 외에 서비스 컨테이너에서 해석할 의존성을 타입 힌트로 주입받을 수 있습니다.

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

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

클로저 커맨드 설명 추가

클로저 커맨드에 설명을 추가하려면 purpose 메서드를 체이닝합니다. 이 설명은 php artisan list나 php artisan help 실행 시 표시됩니다.

Artisan::command('mail:send {user}', function (string $user) {
    // ...
})->purpose('지정한 사용자에게 마케팅 이메일을 발송합니다');

단일 실행 커맨드 (Isolatable Commands)

WARNING

이 기능을 사용하려면 애플리케이션의 기본 캐시 드라이버가 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은 애플리케이션의 기본 캐시 드라이버를 통해 원자적 락(atomic lock)을 획득하려 시도합니다. 이미 같은 커맨드가 실행 중이라면 해당 커맨드는 실행되지 않으며, 성공 종료 코드(0)로 종료됩니다.

php artisan mail:send 1 --isolated

실행에 실패했을 때 반환할 종료 코드를 직접 지정하려면 --isolated 옵션에 원하는 코드를 전달합니다.

php artisan mail:send 1 --isolated=12

락 ID

기본적으로 Laravel은 커맨드 이름을 사용해 캐시의 원자적 락 키를 생성합니다. 커맨드의 인수나 옵션 값을 락 키에 포함시키고 싶다면 커맨드 클래스에 isolatableId 메서드를 정의해 키를 커스터마이징할 수 있습니다.

/**
 * 커맨드의 격리 ID를 반환합니다.
 */
public function isolatableId(): string
{
    return $this->argument('user');
}

락 만료 시간

기본적으로 격리 락은 커맨드가 완료되면 해제됩니다. 커맨드가 중단되어 완료되지 못한 경우에는 1시간 후에 자동으로 만료됩니다. 락 만료 시간을 조정하려면 커맨드에 isolationLockExpiresAt 메서드를 정의합니다.

use DateTimeInterface;
use DateInterval;

/**
 * 커맨드 격리 락의 만료 시점을 반환합니다.
 */
public function isolationLockExpiresAt(): DateTimeInterface|DateInterval
{
    return now()->addMinutes(5);
}

Artisan 콘솔

입력 정의하기

콘솔 커맨드를 작성할 때는 사용자로부터 인수(argument)나 옵션(option)을 받는 경우가 많습니다. Laravel은 커맨드의 signature 프로퍼티를 통해 이러한 입력을 간결하게 정의할 수 있도록 지원합니다. 라우트 정의와 비슷한 표현식 문법으로 커맨드 이름, 인수, 옵션을 한 번에 선언할 수 있습니다.

인수 (Arguments)

인수와 옵션은 모두 중괄호 {}로 감쌉니다. 아래 예시는 user라는 필수 인수 하나를 정의합니다.

/**
 * 콘솔 커맨드의 이름 및 시그니처
 *
 * @var string
 */
protected $signature = 'mail:send {user}';

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

// 선택적 인수
'mail:send {user?}'

// 기본값이 있는 선택적 인수
'mail:send {user=foo}'

옵션 (Options)

옵션은 인수와 마찬가지로 사용자 입력을 받는 수단이지만, 커맨드 라인에서 --를 앞에 붙여 사용한다는 점이 다릅니다. 옵션에는 두 가지 종류가 있습니다. 값을 받는 옵션과 값 없이 사용하는 스위치형 옵션입니다. 스위치형 옵션은 지정 여부에 따라 true / false로 동작합니다.

/**
 * 콘솔 커맨드의 이름 및 시그니처
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue}';

이 경우 --queue를 전달하면 해당 옵션 값이 true가 되고, 전달하지 않으면 false가 됩니다.

php artisan mail:send 1 --queue

값을 받는 옵션

값을 받는 옵션은 옵션 이름 뒤에 =를 붙여 정의합니다.

/**
 * 콘솔 커맨드의 이름 및 시그니처
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue=}';

값을 전달할 때는 다음과 같이 사용합니다. 옵션을 생략하면 값은 null이 됩니다.

php artisan mail:send 1 --queue=default

기본값을 지정하려면 = 뒤에 바로 값을 적으면 됩니다.

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

옵션 단축키

옵션에 단축키를 지정하려면 전체 옵션 이름 앞에 단축키를 쓰고 |로 구분합니다.

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

터미널에서 단축키를 사용할 때는 -를 하나만 붙이며, 값을 전달할 때 =는 사용하지 않습니다.

php artisan mail:send 1 -Qdefault

배열 입력

인수나 옵션에서 여러 값을 받고 싶다면 * 문자를 사용합니다.

'mail:send {user*}'

이렇게 정의하면 여러 값을 순서대로 전달할 수 있습니다. 아래 예시에서 user는 ['1', '2'] 배열이 됩니다.

php artisan mail:send 1 2

?와 *를 조합하면 0개 이상의 값을 받는 선택적 배열 인수로 만들 수 있습니다.

'mail:send {user?*}'

배열 옵션

옵션에서 여러 값을 받으려면 옵션 이름을 여러 번 반복해서 전달합니다.

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

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

입력 설명 추가

인수나 옵션에 설명을 추가하려면 이름 뒤에 :를 붙이고 설명을 작성합니다. 시그니처가 길어지면 여러 줄에 걸쳐 작성해도 됩니다.

/**
 * 콘솔 커맨드의 이름 및 시그니처
 *
 * @var string
 */
protected $signature = 'mail:send
                        {user : 메일을 받을 사용자 ID}
                        {--queue : 작업을 큐에 넣을지 여부}';

누락된 입력 자동 프롬프트

필수 인수가 누락된 경우 기본적으로는 오류 메시지가 출력됩니다. 하지만 PromptsForMissingInput 인터페이스를 구현하면, 필수 인수가 없을 때 자동으로 사용자에게 입력을 요청하도록 만들 수 있습니다.

<?php

namespace App\Console\Commands;

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

class SendEmails extends Command implements PromptsForMissingInput
{
    /**
     * 콘솔 커맨드의 이름 및 시그니처
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';

    // ...
}

Laravel은 인수 이름이나 설명을 바탕으로 자연스러운 질문을 자동으로 생성합니다. 질문을 직접 지정하고 싶다면 promptForMissingArgumentsUsing 메서드를 구현하고, 인수 이름을 키로 하는 배열을 반환하면 됩니다.

/**
 * 누락된 인수를 위한 질문 문구를 반환합니다.
 *
 * @return array<string, string>
 */
protected function promptForMissingArgumentsUsing(): array
{
    return [
        'user' => '메일을 받을 사용자 ID를 입력하세요.',
    ];
}

질문과 함께 플레이스홀더 텍스트를 표시하려면 튜플(배열) 형태로 반환합니다.

return [
    'user' => ['메일을 받을 사용자 ID를 입력하세요.', '예: 123'],
];

프롬프트를 완전히 직접 제어하고 싶다면 클로저를 반환할 수 있습니다. 아래 예시는 Laravel Prompts의 search 기능을 활용해 사용자를 이름으로 검색하는 방식입니다.

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

// ...

return [
    'user' => fn () => search(
        label: '사용자를 검색하세요:',
        placeholder: '예: 홍길동',
        options: fn ($value) => strlen($value) > 0
            ? User::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
            : []
    ),
];

NOTE

사용 가능한 프롬프트 종류와 자세한 사용법은 Laravel Prompts 문서를 참고하세요.

옵션에 대한 프롬프트는 커맨드의 handle 메서드 안에서 직접 처리할 수 있습니다. 그러나 누락된 인수에 대한 자동 프롬프트가 완료된 직후에만 추가 프롬프트를 실행하고 싶다면, afterPromptingForMissingArguments 메서드를 구현하세요.

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

// ...

/**
 * 누락된 인수 프롬프트 완료 후 추가 작업을 수행합니다.
 */
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output): void
{
    $input->setOption('queue', confirm(
        label: '메일을 큐에 넣어서 발송할까요?',
        default: $this->option('queue')
    ));
}

커맨드 입출력 (Command I/O)

입력값 가져오기

커맨드가 실행되는 동안, 정의한 인수(argument)와 옵션(option)의 값을 읽어야 할 때가 많습니다. 이때 argument와 option 메서드를 사용하면 됩니다. 해당 인수나 옵션이 존재하지 않으면 null이 반환됩니다.

/**
 * 콘솔 커맨드 실행
 */
public function handle(): void
{
    $userId = $this->argument('user');
}

모든 인수를 배열로 한 번에 가져오려면 arguments 메서드를 사용합니다.

$arguments = $this->arguments();

옵션도 동일한 방식으로 가져올 수 있습니다. 모든 옵션을 배열로 가져오려면 options 메서드를 사용합니다.

// 특정 옵션 가져오기
$queueName = $this->option('queue');

// 모든 옵션을 배열로 가져오기
$options = $this->options();

사용자 입력 받기

NOTE

Laravel Prompts는 커맨드라인 애플리케이션에 플레이스홀더 텍스트, 유효성 검사 등 브라우저와 유사한 UX를 제공하는 PHP 패키지입니다. 보다 세련된 CLI 폼이 필요하다면 참고해 보세요.

출력뿐 아니라, 커맨드 실행 중에 사용자로부터 직접 입력을 받을 수도 있습니다. ask 메서드는 질문을 출력하고 사용자의 입력을 받아 반환합니다.

/**
 * 콘솔 커맨드 실행
 */
public function handle(): void
{
    $name = $this->ask('이름이 무엇인가요?');

    // ...
}

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

$name = $this->ask('이름이 무엇인가요?', '홍길동');

비밀번호처럼 민감한 정보를 입력받을 때는 secret 메서드를 사용하세요. ask와 동일하게 동작하지만, 사용자가 타이핑하는 내용이 콘솔에 표시되지 않습니다.

$password = $this->secret('비밀번호를 입력하세요.');

예/아니오 확인 받기

단순한 예/아니오 확인이 필요할 때는 confirm 메서드를 사용합니다. 기본적으로 false를 반환하며, 사용자가 y 또는 yes를 입력하면 true를 반환합니다.

if ($this->confirm('계속 진행하시겠습니까?')) {
    // ...
}

기본값을 true로 바꾸고 싶다면 두 번째 인수로 true를 전달하세요.

if ($this->confirm('계속 진행하시겠습니까?', true)) {
    // ...
}

자동 완성

anticipate 메서드를 사용하면 입력 후보 목록을 제시할 수 있습니다. 자동 완성 힌트가 표시되더라도 사용자는 목록에 없는 값도 자유롭게 입력할 수 있습니다.

$name = $this->anticipate('이름이 무엇인가요?', ['홍길동', '김철수']);

두 번째 인수로 클로저를 전달할 수도 있습니다. 사용자가 문자를 입력할 때마다 클로저가 호출되며, 현재까지 입력된 문자열을 받아 자동 완성 후보 배열을 반환하면 됩니다.

$name = $this->anticipate('주소를 입력하세요.', function (string $input) {
    // 자동 완성 후보 목록 반환
});

선택형 질문

미리 정해진 항목 중에서 선택하게 하고 싶을 때는 choice 메서드를 사용합니다. 세 번째 인수로 기본 선택 항목의 배열 인덱스를 지정할 수 있으며, 아무것도 선택하지 않으면 해당 값이 반환됩니다.

$name = $this->choice(
    '이름을 선택하세요.',
    ['홍길동', '김철수'],
    $defaultIndex
);

네 번째와 다섯 번째 인수로 최대 재시도 횟수와 복수 선택 허용 여부를 설정할 수 있습니다.

$name = $this->choice(
    '이름을 선택하세요.',
    ['홍길동', '김철수'],
    $defaultIndex,
    $maxAttempts = null,
    $allowMultipleSelections = false
);

출력 작성하기

콘솔에 내용을 출력할 때는 line, info, comment, question, warn, error 메서드를 사용할 수 있습니다. 각 메서드는 용도에 맞는 ANSI 색상을 자동으로 적용합니다. 예를 들어 info 메서드는 일반적으로 녹색 텍스트로 출력됩니다.

/**
 * 콘솔 커맨드 실행
 */
public function handle(): void
{
    // ...

    $this->info('커맨드가 성공적으로 실행되었습니다!');
}

오류 메시지는 error 메서드로 출력합니다. 빨간색 텍스트로 표시됩니다.

$this->error('문제가 발생했습니다!');

색상 없이 일반 텍스트를 출력하려면 line 메서드를 사용합니다.

$this->line('화면에 이 텍스트를 출력합니다.');

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

// 빈 줄 한 줄 출력
$this->newLine();

// 빈 줄 세 줄 출력
$this->newLine(3);

테이블 출력

여러 행과 열로 구성된 데이터를 보기 좋게 출력할 때는 table 메서드를 사용합니다. 컬럼 이름과 데이터만 전달하면 Laravel이 자동으로 적절한 너비와 높이를 계산해 줍니다.

use App\Models\User;

$this->table(
    ['이름', '이메일'],
    User::all(['name', 'email'])->toArray()
);

진행 표시줄 (Progress Bar)

오래 걸리는 작업에는 진행 상황을 시각적으로 보여주는 진행 표시줄이 유용합니다. withProgressBar 메서드를 사용하면, 반복 가능한 값을 순회하면서 자동으로 진행 표시줄을 업데이트해 줍니다.

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();

NOTE

진행 표시줄의 고급 옵션은 Symfony Progress Bar 컴포넌트 문서를 참고하세요.

커맨드 등록

기본적으로 Laravel은 app/Console/Commands 디렉터리 안의 모든 커맨드를 자동으로 등록합니다. 그 외 다른 디렉터리에 커맨드를 작성했다면, bootstrap/app.php 파일의 withCommands 메서드를 통해 해당 디렉터리를 추가로 스캔하도록 지정할 수 있습니다.

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

필요하다면 디렉터리 경로 대신 커맨드 클래스명을 직접 지정해 개별 등록하는 것도 가능합니다.

use App\Domain\Orders\Commands\SendEmails;

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

Artisan이 부팅될 때 애플리케이션의 모든 커맨드는 서비스 컨테이너를 통해 resolve되어 Artisan에 등록됩니다.

Artisan 콘솔

프로그래밍 방식으로 커맨드 실행하기

CLI 환경이 아닌 곳에서 Artisan 커맨드를 실행해야 할 때가 있습니다. 예를 들어, 라우트나 컨트롤러 내부에서 Artisan 커맨드를 호출하고 싶을 수 있습니다. 이럴 때는 Artisan 파사드의 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('mail:send 1 --queue=default');

배열 값 전달하기

커맨드 옵션이 배열 값을 받는 경우, 해당 옵션에 값의 배열을 그대로 전달할 수 있습니다.

use Illuminate\Support\Facades\Artisan;

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

불리언 값 전달하기

migrate:refresh 커맨드의 --force 플래그처럼 문자열 값을 받지 않는 옵션을 지정해야 할 때는, 옵션 값으로 true 또는 false를 전달합니다.

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

Artisan 커맨드 큐에 등록하기

Artisan 파사드의 queue 메서드를 사용하면 Artisan 커맨드를 큐에 등록하여 큐 워커가 백그라운드에서 처리하도록 할 수 있습니다. 이 메서드를 사용하기 전에 큐 설정을 완료하고 큐 리스너가 실행 중인지 확인하세요.

use Illuminate\Support\Facades\Artisan;

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

    // ...
});

onConnection과 onQueue 메서드를 체이닝하면 커맨드를 디스패치할 커넥션이나 큐를 직접 지정할 수 있습니다.

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

커맨드에서 다른 커맨드 호출하기

기존 Artisan 커맨드 내부에서 다른 커맨드를 호출해야 할 때는 call 메서드를 사용합니다. 커맨드 이름과 인자/옵션 배열을 전달하면 됩니다.

/**
 * 커맨드를 실행합니다.
 */
public function handle(): void
{
    $this->call('mail:send', [
        'user' => 1, '--queue' => 'default'
    ]);

    // ...
}

다른 커맨드를 호출하되 그 출력을 모두 숨기고 싶다면 callSilently 메서드를 사용하세요. callSilently는 call과 동일한 시그니처를 가집니다.

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

시그널 처리

운영체제는 실행 중인 프로세스에 시그널을 보낼 수 있습니다. 예를 들어 SIGTERM은 프로그램에 종료를 요청하는 표준 시그널입니다. Artisan 커맨드 실행 중에 이러한 시그널을 감지하고 그에 맞는 처리를 하고 싶다면 trap 메서드를 사용하세요.

/**
 * 콘솔 커맨드 실행
 */
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
});

스텁 커스터마이징

Artisan의 make 계열 명령어는 컨트롤러, Job, 마이그레이션, 테스트 등 다양한 클래스 파일을 생성할 때 사용됩니다. 이 파일들은 내부적으로 "스텁(stub)"이라 불리는 템플릿을 기반으로 생성되며, 입력한 값에 따라 내용이 채워집니다.

기본 스텁 내용을 프로젝트에 맞게 수정하고 싶다면, stub:publish 명령어로 스텁 파일들을 애플리케이션에 퍼블리시할 수 있습니다:

php artisan stub:publish

퍼블리시된 스텁 파일들은 애플리케이션 루트의 stubs 디렉터리에 위치합니다. 이 파일들을 수정하면, 이후 Artisan의 make 명령어로 클래스를 생성할 때 변경된 스텁이 자동으로 반영됩니다.

NOTE

예를 들어 모든 컨트롤러에 공통으로 들어가는 use 구문이나 주석을 추가하고 싶다면, stubs/controller.stub 파일을 수정해두면 됩니다. 이후 php artisan make:controller로 생성되는 모든 컨트롤러에 해당 내용이 포함됩니다.

이벤트

Artisan은 명령어 실행 중에 세 가지 이벤트를 디스패치합니다: Illuminate\Console\Events\ArtisanStarting, Illuminate\Console\Events\CommandStarting, Illuminate\Console\Events\CommandFinished. ArtisanStarting 이벤트는 Artisan이 실행을 시작할 때 즉시 디스패치됩니다. 이어서 CommandStarting 이벤트가 명령어 실행 직전에 디스패치되고, 마지막으로 CommandFinished 이벤트가 명령어 실행이 완료된 후 디스패치됩니다.

이벤트

Artisan은 명령어 실행 과정에서 세 가지 이벤트를 발생시킵니다.

이벤트	발생 시점
`Illuminate\Console\Events\ArtisanStarting`	Artisan이 시작되는 즉시
`Illuminate\Console\Events\CommandStarting`	명령어가 실행되기 직전
`Illuminate\Console\Events\CommandFinished`	명령어 실행이 완료된 직후

이 이벤트들을 활용하면 명령어 실행 전후에 로깅, 모니터링, 알림 발송 등의 부가 작업을 처리할 수 있습니다. 이벤트 리스너 등록 방법은 이벤트 문서를 참고하세요.