# 機能設計書 40-Artisanコマンド

## 概要

本ドキュメントは、Laravel FrameworkにおけるArtisanコマンド（Artisan Command）機能の設計書である。CLIベースのコマンド実行基盤を提供し、コード生成、マイグレーション実行、キャッシュクリアなど様々なタスクを実行するためのフレームワークである。

### 本機能の処理概要

**業務上の目的・背景**：
Webアプリケーション開発では、コード生成、データベーススキーマ管理、スケジュールタスク実行など、多くのCLI操作が必要となる。Artisanは、Symfony Consoleをベースにした強力なCLIフレームワークを提供し、Laravel固有の機能（依存性注入、シグナルハンドリング、インタラクティブプロンプト等）を追加する。これにより、開発者は一貫したインターフェースでCLIタスクを作成・実行できる。

**機能の利用シーン**：
- コントローラ、モデル、マイグレーション等のコード生成
- データベースマイグレーション実行
- キャッシュのクリア・再構築
- スケジュールタスクの登録・実行
- キューワーカーの起動
- カスタムコマンドの作成・実行

**主要な処理内容**：
1. コマンド定義（`$signature`, `$description`による宣言的定義）
2. 引数・オプション処理（入力パース、バリデーション）
3. 入出力管理（プロンプト、テーブル出力、進捗バー等）
4. コマンド実行（`handle`メソッドによるビジネスロジック）
5. 他コマンド呼び出し（`call`, `callSilent`メソッド）
6. コマンド分離実行（Isolatableインターフェース）
7. シグナルハンドリング（Ctrl+C等の処理）

**関連システム・外部連携**：
- Symfony Console: 基盤ライブラリ
- サービスコンテナ: 依存性注入
- スケジューラ: 定期実行
- キュー: バックグラウンド実行

**権限による制御**：
本機能自体は権限制御を行わない。コマンド内で必要に応じて認可チェックを実装する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLIのため、直接関連する画面はない |

## 機能種別

CLI / コマンド実行基盤

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| arguments | array | No | コマンド引数 | signature定義に従う |
| options | array | No | コマンドオプション（--付き） | signature定義に従う |

### 入力データソース

- CLIからの直接実行
- 他コマンドからの呼び出し
- スケジューラからの実行
- アプリケーションコードからの実行（`Artisan::call`）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| exitCode | int | 終了コード（0: 成功、1以上: 失敗） |
| output | string | コンソール出力 |

### 出力先

- 標準出力（stdout）
- 標準エラー出力（stderr）
- ログファイル（設定時）

## 処理フロー

### 処理シーケンス

```
1. コマンド初期化
   └─ signatureパース
   └─ 引数・オプション定義
   └─ description設定

2. コマンド実行（run呼び出し）
   └─ OutputStyleインスタンス作成
   └─ プロンプト設定
   └─ 親クラスのrun実行

3. execute実行
   └─ コマンド分離チェック（Isolatable）
   └─ handleまたは__invokeメソッド呼び出し
   └─ 依存性注入による引数解決
   └─ ビジネスロジック実行

4. 終了処理
   └─ シグナルハンドラ解除
   └─ 終了コード返却
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド実行] --> B{signature定義?}
    B -->|Yes| C[configureUsingFluentDefinition]
    B -->|No| D[specifyParameters]
    C --> E[Parserでシグネチャパース]
    D --> E
    E --> F[run開始]
    F --> G[OutputStyle作成]
    G --> H[configurePrompts]
    H --> I[親クラスrun実行]
    I --> J[execute呼び出し]
    J --> K{Isolatable?}
    K -->|Yes| L{--isolated?}
    L -->|Yes| M{mutex取得可能?}
    M -->|No| N[既に実行中メッセージ]
    M -->|Yes| O[handle実行]
    L -->|No| O
    K -->|No| O
    O --> P[依存性注入]
    P --> Q[ビジネスロジック実行]
    Q --> R[終了コード返却]
    N --> S[isolatedExitCode返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-40-01 | 終了コード | 0は成功、1以上は失敗を示す | 常時 |
| BR-40-02 | Isolatable | --isolatedオプションで同時実行を防止 | Isolatable実装時 |
| BR-40-03 | 依存性注入 | handleメソッドの引数はコンテナから解決 | 常時 |
| BR-40-04 | シグネチャ構文 | `{name}` は必須引数、`{name?}` はオプション | signature使用時 |
| BR-40-05 | hidden属性 | `$hidden = true` でコマンドリストから除外 | 常時 |

### 計算ロジック

該当なし

## データベース操作仕様

本機能はデータベース操作を行わない。個別コマンド内で実装される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | FAILURE | コマンド失敗 | エラーメッセージを確認 |
| 2 | INVALID | 無効な入力 | 引数・オプションを確認 |
| - | ManuallyFailedException | fail()呼び出し | コマンドロジックを確認 |

### リトライ仕様

Isolatableコマンドは、同時実行を検出した場合に指定の終了コードを返す。

## トランザクション仕様

コマンド内でのデータベーストランザクション管理は、各コマンドの実装に依存する。

## パフォーマンス要件

- コマンド実行はスクリプト起動のオーバーヘッドがある
- 大量データ処理には進捗バー表示を推奨
- 長時間実行コマンドにはシグナルハンドリングを実装

## セキュリティ考慮事項

- コマンド引数からのインジェクション攻撃に注意
- 機密情報はログに出力しない（`#[\SensitiveParameter]`使用）
- 本番環境での危険なコマンドは`--force`オプション要求

## 備考

- Macroableトレイトにより、カスタムメソッドを追加可能
- `InteractsWithIO`トレイトで入出力ヘルパーを提供
- `CallsCommands`トレイトで他コマンド呼び出しを提供
- `InteractsWithSignals`トレイトでシグナルハンドリングを提供

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: 基底Commandクラスを理解する

コマンドの中核クラスを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Command.php | `src/Illuminate/Console/Command.php` | コマンド基底クラス |

**主要処理フロー**:
- **29行目**: `$laravel` - Laravelアプリケーションインスタンス
- **36行目**: `$signature` - コマンドシグネチャ
- **43行目**: `$name` - コマンド名
- **50行目**: `$description` - コマンド説明
- **64行目**: `$hidden` - 非表示フラグ
- **71行目**: `$isolated` - 分離実行フラグ
- **90-125行目**: コンストラクタ - 初期化処理
- **132-143行目**: `configureUsingFluentDefinition()` - シグネチャパース
- **168-186行目**: `run()` - 実行エントリーポイント
- **194-221行目**: `execute()` - メイン実行ロジック
- **208行目**: handleまたは__invoke呼び出し
- **270-281行目**: `fail()` - 手動失敗

**読解のコツ**: CommandクラスはSymfony\Console\Commandを継承し、Laravelの機能を追加している。トレイトで機能を分割しているため、各トレイトも確認する。

#### Step 2: Concernsトレイトを理解する

コマンド機能を構成するトレイトを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | InteractsWithIO.php | `src/Illuminate/Console/Concerns/InteractsWithIO.php` | 入出力操作 |
| 2-2 | CallsCommands.php | `src/Illuminate/Console/Concerns/CallsCommands.php` | 他コマンド呼び出し |
| 2-3 | HasParameters.php | `src/Illuminate/Console/Concerns/HasParameters.php` | 引数・オプション |
| 2-4 | InteractsWithSignals.php | `src/Illuminate/Console/Concerns/InteractsWithSignals.php` | シグナル処理 |

#### Step 3: Parserを理解する

シグネチャのパース処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Parser.php | `src/Illuminate/Console/Parser.php` | シグネチャパーサー |

### プログラム呼び出し階層図

```
php artisan make:controller UserController
    │
    └─ Artisan::handle()
           │
           └─ Application::run()
                  │
                  └─ Command::run($input, $output)
                         │
                         ├─ OutputStyle作成
                         │
                         ├─ configurePrompts()
                         │
                         └─ parent::run()
                                │
                                └─ Command::execute()
                                       │
                                       ├─ Isolatable チェック
                                       │      └─ commandIsolationMutex()
                                       │
                                       └─ $laravel->call([$this, 'handle'])
                                              │
                                              ├─ 依存性解決
                                              │
                                              └─ MakeController::handle()
                                                     │
                                                     └─ ファイル生成処理
```

### データフロー図

```
[入力]                    [処理]                           [出力]

CLI引数/オプション ────────▶ Parser::parse()
                               │
                         引数・オプション定義
                               │
                         InputDefinition
                               │
                         Command::run()
                               │
                         OutputStyle作成
                               │
                         execute()
                               │
                         handle()呼び出し
                               │
                         ビジネスロジック
                               │
                    終了コード + 出力 ◀────────▶ stdout/stderr
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Command.php | `src/Illuminate/Console/Command.php` | ソース | コマンド基底クラス |
| Parser.php | `src/Illuminate/Console/Parser.php` | ソース | シグネチャパーサー |
| Application.php | `src/Illuminate/Console/Application.php` | ソース | Artisanアプリケーション |
| Kernel.php | `src/Illuminate/Foundation/Console/Kernel.php` | ソース | コンソールカーネル |
| InteractsWithIO.php | `src/Illuminate/Console/Concerns/InteractsWithIO.php` | ソース | 入出力トレイト |
| CallsCommands.php | `src/Illuminate/Console/Concerns/CallsCommands.php` | ソース | コマンド呼び出しトレイト |
| HasParameters.php | `src/Illuminate/Console/Concerns/HasParameters.php` | ソース | パラメータトレイト |
| InteractsWithSignals.php | `src/Illuminate/Console/Concerns/InteractsWithSignals.php` | ソース | シグナルトレイト |
| ConfiguresPrompts.php | `src/Illuminate/Console/Concerns/ConfiguresPrompts.php` | ソース | プロンプト設定トレイト |
| PromptsForMissingInput.php | `src/Illuminate/Console/Concerns/PromptsForMissingInput.php` | ソース | 欠落入力プロンプト |
| OutputStyle.php | `src/Illuminate/Console/OutputStyle.php` | ソース | 出力スタイル |
| Isolatable.php | `src/Illuminate/Contracts/Console/Isolatable.php` | インターフェース | 分離実行契約 |
