Tech Starlog

Laravel Artisan Commandの作成方法

投稿日：2026/01/18

Laravelでは、CLIから実行できる処理をArtisan Commandとして作成できます。
本記事では、Artisan Commandの作成方法を解説します。

Artisan Commandとは？

Artisan Commandとは、Laravelアプリケーション内で実行できるCLIコマンドです。

  • CLI = Command Line Interface（コマンドラインインターフェース）
  • ターミナル（黒い画面）からコマンドを実行して、Laravelアプリケーションの処理を直接起動できます。
  • ブラウザを経由せずに、サーバー上で処理を実行できます。

主な用途は次のとおりです。

  • 定期バッチ処理（cron実行）
  • データの一括更新・削除
  • 集計処理
  • 外部API連携
  • キャッシュクリア・メンテナンス

Web画面から実行する処理と分離することで、

  • タイムアウト制限を受けない
  • 実行ログを残しやすい
  • 障害時の切り分けがしやすい

というメリットがあります。

コマンドを作成する

artisanコマンドで作成

以下のコマンドで、新しいコマンドを作成します。

php artisan make:command PublishSamplesCommand

作成されるファイルはこちらです。

app/Console/Commands/PublishSamplesCommand.php

このファイルに、コマンド名・引数定義・実行処理を実装していきます。
実際にコマンド処理のロジックを書くのは、このクラスになります。

コマンドの基本構成

class PublishSamplesCommand extends Command
{
    protected $signature = 'samples:publish';
    protected $description = '未公開のサンプルデータを公開状態にする';

    public function handle(): int
    {
        // 実行される処理
        return Command::SUCCESS;
    }
}

コマンドのクラスには、次の要素があります。

各要素の役割

項目 役割 備考
signature コマンド名・引数・オプションを定義する コマンド名だけでなく、引数やオプションの定義もまとめて記述します。
description コマンドの説明
handle() 実際の処理

コマンド処理を実装する

サンプル：未公開サンプルデータを公開する

use App\Models\Sample;

public function handle(): int
{
    $count = Sample::where('is_published', false)
        ->update([
            'is_published' => true,
            'published_at' => now(),
        ]);

    $this->info("{$count} 件のサンプルデータを公開しました。");

    return Command::SUCCESS;
}

補足：

  • update() の戻り値には、更新されたレコード件数が返ります。
  • そのため、何件のデータが更新されたかをログに表示できます。

コマンドを実行する

実行コマンド

php artisan samples:publish

正常に実行されると、ターミナルにメッセージが表示されます。

登録済みコマンド一覧を見る

php artisan list

引数・オプションを受け取る

signatureに定義する

protected $signature = 'samples:publish {limit=10} {--dry-run}';

補足：

  • 引数は「必須または位置で指定する値」
  • オプションは「任意で指定するフラグや設定値」

例：

  • limit → 処理件数を指定する引数
  • --dry-run → 実際には更新せず確認だけ行うオプション、本番環境で安全に動作確認したい場合によく使用されます。

handle()で取得する

$limit = (int) $this->argument('limit');
$dryRun = $this->option('dry-run');

使用例

php artisan samples:publish 5 --dry-run

定期実行（cron）に登録する

Laravelでは、Schedulerを使ってコマンドを定期実行できます。

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('samples:publish')->daily();
}

サーバー側のcronには以下を登録します。

* * * * * php /path/to/artisan schedule:run

補足：

  • この設定は「毎分 schedule:run を実行する」という意味です。
  • LaravelのSchedulerは、内部で実行タイミングを判定するため、cron自体は1分ごとに起動しておけば問題ありません。

実運用時の注意点

  • 本番環境で実行するコマンドは必ずdry-runや確認ログを用意する
  • 途中失敗しても再実行できる設計にする
  • 大量データ処理ではメモリ使用量・実行時間に注意する
  • 処理ロジックはServiceクラスに切り出すとテストしやすい

まとめ

  • Artisan Commandでバッチ処理を実装できる
  • signatureで引数・オプションを定義できる
  • Schedulerと組み合わせることで定期実行が可能
⬅️ 記事一覧へ戻る