Artisan 콘솔 - Knowledge of Laravel

Artisan이란

Artisan은 Laravel에 동봉된 커맨드 라인 인터페이스(CLI) 도구입니다. 프로젝트 루트의 artisan 스크립트로 존재하며, 개발·운영을 효율화하는 다수의 명령을 제공합니다. 사용 가능한 명령 목록을 확인하려면 list 명령을 사용합니다.

php artisan list

명령 사용법을 확인하려면 help를 앞에 붙입니다.

php artisan help migrate

Laravel Sail을 사용하는 경우, php artisan 대신 sail artisan을 사용하세요. 명령은 Docker 컨테이너 내에서 실행됩니다.

./vendor/bin/sail artisan list

Tinker

Laravel Tinker는 Eloquent 모델이나 잡, 이벤트 등 애플리케이션 전체를 커맨드 라인상에서 대화형으로 조작할 수 있는 REPL 환경입니다.

php artisan tinker

시작 후에는 PHP 코드를 그대로 실행할 수 있습니다.

// 사용자 조회 및 확인
>>> App\Models\User::find(1)
// 팩토리로 레코드 생성
>>> App\Models\User::factory()->create()
// 서비스 클래스를 직접 호출
>>> app(App\Services\OrderService::class)->process(1)

Tinker는 데이터를 실제로 변경합니다. 프로덕션 환경에서의 실행에는 충분히 주의하세요. 로컬이나 스테이징 환경에서의 동작 확인·디버깅 용도에 적합합니다.

커스텀 명령 만들기

명령 생성하기

make:command로 명령 클래스의 스켈레톤을 생성합니다.

php artisan make:command ImportProducts

app/Console/Commands/ImportProducts.php가 생성됩니다.

명령의 기본 구조

생성된 명령 클래스에는 $signature, $description, handle()이라는 3가지 주요 요소가 있습니다.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ImportProducts extends Command
{
    /**
     * 명령 이름과 인수·옵션 정의
     */
    protected $signature = 'import:products';

    /**
     * 명령 설명 (php artisan list에 표시됨)
     */
    protected $description = '상품 데이터를 CSV에서 임포트한다';

    /**
     * 명령 실행 처리
     */
    public function handle(): void
    {
        $this->info('임포트를 시작합니다...');
        // 처리를 작성한다
        $this->info('완료되었습니다.');
    }
}

Laravel 13에서는 PHP 어트리뷰트를 사용한 작성 방식도 사용할 수 있습니다.

use Illuminate\Console\Attributes\Description;
use Illuminate\Console\Attributes\Signature;

#[Signature('import:products')]
#[Description('상품 데이터를 CSV에서 임포트한다')]
class ImportProducts extends Command
{
    public function handle(): void
    {
        // ...
    }
}

인수와 옵션 정의

$signature에 명령 이름·인수·옵션을 함께 정의합니다.

protected $signature = 'import:products
                        {file : 임포트할 CSV 파일 경로}
                        {--limit= : 임포트할 최대 건수}
                        {--dry-run : 실제로는 DB에 저장하지 않음(확인용)}';

표기법	종류	설명
`{file}`	필수 인수	생략하면 오류 발생
`{file?}`	생략 가능한 인수	생략한 경우 `null`
`{file=products.csv}`	기본값 있는 인수	생략한 경우 기본값 사용
`{--queue}`	플래그 옵션	지정 시 `true`, 생략 시 `false`
`{--limit=}`	값 있는 옵션	`--limit=100` 형식으로 값 전달
`{--limit=50}`	기본값 있는 옵션	생략 시 `50`
`{--Q\|queue}`	단축키 있음	`-Q`로도 지정 가능

인수와 옵션 취득

handle() 메서드 내에서 argument()와 option()을 사용하여 값을 취득합니다.

public function handle(): void
{
    $file    = $this->argument('file');       // 인수 취득
    $limit   = $this->option('limit');        // 옵션 취득
    $dryRun  = $this->option('dry-run');      // 플래그 옵션(bool)

    $this->info("파일: {$file}");

    if ($dryRun) {
        $this->warn('드라이런 모드: DB에 저장을 건너뜁니다');
    }
}

`input()` — 타입 액세서

input() 메서드를 사용하면 HTTP 요청과 동일한 타입 액세서로 명령의 인수나 옵션을 취득할 수 있습니다.

use App\Enums\ReportType;

public function handle(): void
{
    // 인수·옵션을 CommandInput 인스턴스로 취득
    $from = $this->input()->date('from');
    $type = $this->input()->enum('type', ReportType::class);
    $limit = $this->input()->integer('limit');
}

특정 이름만 취득하고 싶다면 이름을 직접 전달합니다(인수와 옵션 양쪽에서 검색됩니다).

$queue = $this->input('queue', 'default');

argument()나 option()이 문자열을 반환하는 데 비해, input()의 타입 액세서는 적절한 타입으로 변환합니다. 날짜·수치·Enum 등 타입 안전하게 다루고 싶은 경우에 편리합니다.

사용자와의 상호작용

메시지 출력

콘솔에 색상이 있는 메시지를 출력하는 메서드가 준비되어 있습니다.

$this->info('처리가 정상적으로 완료되었습니다');    // 녹색
$this->warn('이 작업은 되돌릴 수 없습니다');        // 노랑
$this->error('오류가 발생했습니다');               // 빨강
$this->line('일반 텍스트');                       // 색상 없음
$this->comment('부가 정보');                     // 옅은 회색

사용자에게 질의

대화적으로 사용자로부터 입력을 받을 수 있습니다.

// 텍스트 입력
$name = $this->ask('담당자 이름을 입력하세요');

// 기본값 포함
$env = $this->ask('실행 환경 선택', 'production');

// 비밀번호 등 비밀 정보(입력이 화면에 표시되지 않음)
$password = $this->secret('API 키를 입력하세요');

// Yes/No 확인
if (! $this->confirm('프로덕션 DB에 임포트하시겠습니까?')) {
    $this->info('취소했습니다.');
    return;
}

// 선택지에서 선택
$format = $this->choice('출력 형식을 선택하세요', ['csv', 'json', 'xml'], 0);

진행률 바

대량 데이터 처리 중 진행 상황을 알기 쉽게 표시할 수 있습니다.

use App\Models\Product;

// 컬렉션을 전달하는 것만으로 자동으로 진행률 바 표시
$this->withProgressBar(Product::cursor(), function (Product $product) {
    $this->processProduct($product);
});

수동으로 세밀하게 제어하고 싶다면 다음 방법을 사용합니다.

$total = Product::count();
$bar = $this->output->createProgressBar($total);
$bar->start();

Product::cursor()->each(function (Product $product) use ($bar) {
    $this->processProduct($product);
    $bar->advance();
});

$bar->finish();
$this->newLine();

실용적인 유즈케이스

데이터 임포트 명령

CSV 파일에서 상품 데이터를 임포트하는 실전적인 명령의 예입니다.

명령 생성하기

php artisan make:command ImportProducts

명령 구현하기

<?php

namespace App\Console\Commands;

use App\Models\Product;
use Illuminate\Console\Command;

class ImportProducts extends Command
{
    protected $signature = 'import:products
                            {file : CSV 파일 경로}
                            {--limit= : 임포트할 최대 건수}
                            {--dry-run : 확인만(DB에 저장하지 않음)}';

    protected $description = '상품 데이터를 CSV 파일에서 임포트한다';

    public function handle(): void
    {
        $filePath = $this->argument('file');
        $limit    = $this->option('limit') ? (int) $this->option('limit') : null;
        $dryRun   = $this->option('dry-run');

        if (! file_exists($filePath)) {
            $this->error("파일을 찾을 수 없습니다: {$filePath}");
            return;
        }

        // PHP 내장 함수로 CSV 읽기
        $handle = fopen($filePath, 'r');
        $headers = fgetcsv($handle); // 첫 번째 행을 헤더로 취득
        $rows = [];
        while (($row = fgetcsv($handle)) !== false) {
            $rows[] = array_combine($headers, $row);
            if ($limit !== null && count($rows) >= $limit) {
                break;
            }
        }
        fclose($handle);

        $count = 0;

        $this->withProgressBar($rows, function (array $row) use ($dryRun, &$count) {
            if (! $dryRun) {
                Product::updateOrCreate(
                    ['sku' => $row['sku']],
                    [
                        'name'  => $row['name'],
                        'price' => $row['price'],
                    ]
                );
            }
            $count++;
        });

        $this->newLine();

        if ($dryRun) {
            $this->warn("{$count}건이 대상입니다(드라이런: 저장을 건너뛰었습니다)");
        } else {
            $this->info("{$count}건의 임포트가 완료되었습니다.");
        }
    }
}

명령 실행하기

# 일반 임포트
php artisan import:products storage/products.csv

# 건수 제한
php artisan import:products storage/products.csv --limit=100

# 드라이런으로 확인
php artisan import:products storage/products.csv --dry-run

정기 유지보수 명령

오래된 데이터 삭제 등, 정기적으로 실행하는 유지보수 명령의 예입니다.

<?php

namespace App\Console\Commands;

use App\Models\Order;
use Illuminate\Console\Command;

class PruneOldOrders extends Command
{
    protected $signature = 'orders:prune {--days=90 : 며칠 이전 데이터를 삭제할지}';

    protected $description = '지정 일수보다 오래된 완료 주문을 삭제한다';

    public function handle(): void
    {
        $days = (int) $this->option('days');

        if (! $this->confirm("{$days}일 이상 이전의 완료 주문을 삭제하시겠습니까?")) {
            $this->info('취소했습니다.');
            return;
        }

        $deleted = Order::where('status', 'completed')
            ->where('created_at', '<', now()->subDays($days))
            ->delete();

        $this->info("{$deleted}건의 주문 데이터를 삭제했습니다.");
    }
}

스케줄 실행과 조합

작성한 명령은 routes/console.php에서 스케줄 실행할 수 있습니다. 자세한 내용은 작업 스케줄링을 참조하세요.

use Illuminate\Support\Facades\Schedule;

// 매일 심야 2시에 실행
Schedule::command('orders:prune --days=90')->dailyAt('2:00');

// 매주 월요일 9시에 실행
Schedule::command('import:products storage/weekly.csv')->weeklyOn(1, '9:00');

명령 테스트

Laravel의 테스트 기능을 사용하여 Artisan 명령의 동작을 검증할 수 있습니다.

<?php

namespace Tests\Feature\Commands;

use App\Models\Order;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class PruneOldOrdersTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_deletes_old_completed_orders(): void
    {
        // 90일 이상 이전의 완료 주문 생성
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(100),
        ]);

        // 최근 완료 주문(삭제되지 않아야 함)
        Order::factory()->create([
            'status'     => 'completed',
            'created_at' => now()->subDays(10),
        ]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('90일 이상 이전의 완료 주문을 삭제하시겠습니까?', 'yes')
            ->expectsOutput('1건의 주문 데이터를 삭제했습니다.')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }

    public function test_it_cancels_when_user_declines(): void
    {
        Order::factory()->create(['status' => 'completed', 'created_at' => now()->subDays(100)]);

        $this->artisan('orders:prune', ['--days' => 90])
            ->expectsConfirmation('90일 이상 이전의 완료 주문을 삭제하시겠습니까?', 'no')
            ->expectsOutput('취소했습니다.')
            ->assertExitCode(0);

        $this->assertDatabaseCount('orders', 1);
    }
}

artisan() 메서드에서 사용 가능한 어서션 메서드의 예:

메서드	설명
`expectsOutput('...')`	지정한 텍스트가 출력되는지 검증
`expectsQuestion('?', '답변')`	`ask()`의 입력을 시뮬레이션
`expectsConfirmation('?', 'yes')`	`confirm()`의 응답을 시뮬레이션
`expectsChoice('?', '선택지')`	`choice()`의 선택을 시뮬레이션
`assertExitCode(0)`	종료 코드 검증(0 = 성공)
`assertFailed()`	종료 코드가 0 이외임을 검증

`dev` 명령

dev Artisan 명령은, 로컬 개발에 필요한 여러 프로세스를 하나의 터미널 창에서 함께 시작합니다. 기본적으로 PHP 개발 서버·큐 워커·Pail에 의한 로그 모니터링·Vite의 에셋 컴파일이 병렬로 실행됩니다.

php artisan dev

내부적으로는 concurrently라는 npm 패키지를 사용하여 프로세스를 관리합니다. 각 프로세스는 라벨링되고 색상으로 구분되므로, 터미널 출력에서 어떤 프로세스인지 쉽게 구별할 수 있습니다. 어느 프로세스가 실패하면 다른 모든 프로세스도 자동으로 정지됩니다. 기본으로 실행되는 프로세스는 다음과 같습니다.

이름	명령
`server`	`php artisan serve --host=localhost`
`queue`	`php artisan queue:listen --tries=1 --timeout=0`
`logs`	`php artisan pail --timeout=0`
`vite`	`npm run dev`

vite 프로세스는 사용 중인 Node 패키지 매니저(npm, pnpm, Yarn, Bun)를 자동 감지하여 적절한 실행 명령을 사용합니다.

`dev` 프로세스 커스터마이징

dev 명령이 실행하는 프로세스는 DevCommands 클래스를 사용하여 커스터마이즈할 수 있습니다. 보통 애플리케이션의 AppServiceProvider의 boot 메서드 내에서 등록합니다. register 메서드는 명령 문자열과 임의의 프로세스명을 받습니다.

use Illuminate\Foundation\DevCommands;

/**
 * 애플리케이션 서비스의 초기 시작 처리
 */
public function boot(): void
{
    DevCommands::register('some-command --flag', 'my-process');
}

Artisan 명령을 등록할 때는 자동으로 php artisan을 앞에 붙여주는 artisan 메서드를 사용할 수 있습니다.

DevCommands::artisan('horizon', 'horizon');

마찬가지로 node 메서드는 감지된 패키지 매니저의 실행 명령(예: npm run)을, nodeExec 메서드는 패키지 매니저의 exec 명령(예: npx)을 앞에 붙입니다.

DevCommands::node('storybook', 'storybook');

DevCommands::nodeExec('tailwindcss -i resources/css/app.css -o public/css/app.css --watch', 'tailwind');

기본 프로세스와 같은 이름으로 프로세스를 등록하면 해당 기본 프로세스를 치환합니다. 예를 들어 서버 프로세스를 다른 포트로 사용하도록 커스터마이즈할 수 있습니다.

DevCommands::artisan('serve --host=localhost --port=9000', 'server');

터미널에서의 프로세스 라벨 색상도 커스터마이즈할 수 있습니다. 이용 가능한 색상 메서드는 blue, purple, pink, orange, green, yellow입니다. color 메서드에 커스텀 hex 컬러를 전달할 수도 있습니다.

DevCommands::register('my-command', 'my-process')->green();

DevCommands::register('my-command', 'my-process')->color('#ff6347');

등록된 dev 프로세스를 실제로 시작하지 않고 목록만 표시하고 싶다면 dev:list 명령을 사용합니다.

php artisan dev:list

`dev` 프로세스 필터링

only 메서드를 사용하면 dev 명령 실행 시 특정 프로세스만 시작하도록 지정할 수 있습니다. 마찬가지로 except 메서드로 특정 프로세스를 제외할 수도 있습니다.

// server와 vite 프로세스만 시작...
DevCommands::only('server', 'vite');

// 큐 워커 이외의 모든 프로세스 시작...
DevCommands::except('queue');

로컬 개발에서 Horizon이나 Reverb 등을 함께 사용하는 경우, DevCommands::artisan()으로 등록해 두면 php artisan dev 하나로 모두 시작할 수 있어 편리합니다.

자주 사용하는 명령 정리

# 명령 신규 작성
php artisan make:command CommandName

# 이용 가능한 명령 목록
php artisan list

# 명령 사용법 확인
php artisan help command:name

# Tinker 시작
php artisan tinker

​Artisan이란

​Tinker

​커스텀 명령 만들기

​명령 생성하기

​명령의 기본 구조

​인수와 옵션 정의

​인수와 옵션 취득

​input() — 타입 액세서

​사용자와의 상호작용

​메시지 출력

​사용자에게 질의

​진행률 바

​실용적인 유즈케이스

​데이터 임포트 명령

​정기 유지보수 명령

​스케줄 실행과 조합

​명령 테스트

​dev 명령

​dev 프로세스 커스터마이징

​dev 프로세스 필터링

​자주 사용하는 명령 정리

Artisan이란

Tinker

커스텀 명령 만들기

명령 생성하기

명령의 기본 구조

인수와 옵션 정의

인수와 옵션 취득

`input()` — 타입 액세서

사용자와의 상호작용

메시지 출력

사용자에게 질의

진행률 바

실용적인 유즈케이스

데이터 임포트 명령

정기 유지보수 명령

스케줄 실행과 조합

명령 테스트

`dev` 명령

`dev` 프로세스 커스터마이징

`dev` 프로세스 필터링

자주 사용하는 명령 정리