GeneratorCommand — 自訂 make: 指令的實作

什麼是 GeneratorCommand

Illuminate\Console\GeneratorCommand 是 Laravel 所有程式碼產生指令的基底抽象類別。make:model、make:controller、make:request 等皆繼承此類別。若套件提供自訂的 make:xxx 指令，使用者無需手動建立類別，只要執行 php artisan make:handler OrderHandler 之類的指令，即可產生具備正確命名空間的檔案。

GeneratorCommand 在官方文件中幾乎沒有記載，須直接閱讀框架原始碼才能了解。這是典型的進階主題。

最小實作

繼承 GeneratorCommand 的類別必要實作只有 getStub() 方法。其他屬性為選用，但實務上通常會齊備下列項目。

成員	種類	角色
`$name`	屬性	指令名稱（例：`make:handler`）
`$description`	屬性	指令的說明文字
`$type`	屬性	生成物種類名稱，用於成功訊息（例：`Handler`）
`getStub()`	方法（必要）	回傳 stub 檔案的路徑
`getDefaultNamespace()`	方法	控制產生目的地的預設命名空間

以下為實作 make:handler 指令的範例。

<?php

namespace Vendor\Package\Console\Commands;

use Illuminate\Console\GeneratorCommand;

class HandlerMakeCommand extends GeneratorCommand
{
    protected $name = 'make:handler';

    protected $description = 'Create a new handler class';

    protected $type = 'Handler';

    protected function getStub(): string
    {
        return __DIR__.'/stubs/handler.stub';
    }

    protected function getDefaultNamespace($rootNamespace): string
    {
        return $rootNamespace.'\Handlers';
    }
}

設定 getDefaultNamespace() 後，執行 php artisan make:handler OrderHandler 時，會將 App\Handlers\OrderHandler 類別產生至 app/Handlers/OrderHandler.php。

建立 stub 檔案

於 getStub() 回傳的路徑放置 stub 檔案。stub 是作為範本的 PHP 檔案，其中的預留位置會被替換為命名空間與類別名稱。

src

Console

Commands

HandlerMakeCommand.php

stubs

handler.stub

stub 檔案範例：

handler.stub

<?php

namespace {{ namespace }};

class {{ class }}
{
    public function handle(): void
    {
        //
    }
}

GeneratorCommand 會自動替換 stub 中以下的預留位置。

預留位置	替換後的值	替代表示
`{{ namespace }}`	生成類別的命名空間	`DummyNamespace`
`{{ class }}`	生成類別名稱	`DummyClass`
`{{ rootNamespace }}`	應用程式的根命名空間	`DummyRootNamespace`

{{ namespace }} 與 DummyNamespace 兩種寫法均可獲得相同結果。Laravel 內建的 stub 兩種形式皆有，但新建時建議使用 {{ namespace }} 形式。

讓 stub 可被自訂

若要提供允許使用者覆寫 stub 的機制，可以採用 resolveStubPath() 模式。首先於服務提供者的 boot() 中公開 stub。

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->publishes([
            __DIR__.'/../Console/Commands/stubs' => base_path('stubs'),
        ], 'stubs');
    }
}

接著於 getStub() 優先使用使用者已自訂的 stub。

protected function getStub(): string
{
    return $this->resolveStubPath('/stubs/handler.stub');
}

protected function resolveStubPath(string $stub): string
{
    return file_exists($customPath = $this->laravel->basePath(trim($stub, '/')))
        ? $customPath
        : __DIR__.$stub;
}

執行 php artisan vendor:publish --tag=stubs 的使用者可透過編輯專案根目錄的 stubs/handler.stub 來變更範本。

resolveStubPath() 也是 Laravel 內建 RequestMakeCommand 所使用的模式。若要發布套件，建議採用此模式。

於服務提供者註冊

指令於服務提供者的 boot() 方法中註冊。透過 runningInConsole() 檢查可以避免 Web 請求時多餘的載入。

<?php

namespace Vendor\Package;

use Illuminate\Support\ServiceProvider;
use Vendor\Package\Console\Commands\HandlerMakeCommand;

class PackageServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->runningInConsole()) {
            $this->commands([
                HandlerMakeCommand::class,
            ]);

            $this->publishes([
                __DIR__.'/../Console/Commands/stubs' => base_path('stubs'),
            ], 'stubs');
        }
    }
}

若在套件的 composer.json 設定 extra.laravel，使用者就無需手動註冊服務提供者。

"extra": {
    "laravel": {
        "providers": [
            "Vendor\\Package\\PackageServiceProvider"
        ]
    }
}

活用範例

以下列舉 GeneratorCommand 大顯身手的幾種情境。

擴充 Form Request

產生繼承包含驗證檢查或自訂驗證邏輯之獨自基底類別的 Request 指令。以 getDefaultNamespace() 回傳 App\Http\Requests。

DTO Generator

產生 Data Transfer Object 樣板的指令。準備包含 readonly 屬性與 from() factory 方法的 stub。

Action 類別

產生單一職責 Action 類別的指令。在 App\Actions 命名空間下產生具有 execute() 方法的類別。

Livewire 使用相同的機制

make:livewire 指令由繼承 GeneratorCommand 的 MakeCommand 類別實作。為了同時產生元件類別與 Blade view 兩個檔案，覆寫了 handle()。

測試

使用 Orchestra Testbench，測試指令是否正確產生檔案。

<?php

namespace Tests\Feature\Console;

use Illuminate\Support\Facades\File;
use Orchestra\Testbench\TestCase;
use Vendor\Package\PackageServiceProvider;

class HandlerMakeCommandTest extends TestCase
{
    protected function getPackageProviders($app): array
    {
        return [PackageServiceProvider::class];
    }

    protected function tearDown(): void
    {
        File::deleteDirectory(app_path('Handlers'));

        parent::tearDown();
    }

    public function test_make_handler_creates_file(): void
    {
        $path = app_path('Handlers/OrderHandler.php');

        $this->artisan('make:handler', ['name' => 'OrderHandler'])
            ->assertSuccessful();

        $this->assertFileExists($path);
        $this->assertStringContainsString('namespace App\Handlers;', File::get($path));
        $this->assertStringContainsString('class OrderHandler', File::get($path));
    }

    public function test_make_handler_does_not_overwrite_existing_file(): void
    {
        $path = app_path('Handlers/OrderHandler.php');
        File::ensureDirectoryExists(dirname($path));
        File::put($path, '<?php // existing');

        $this->artisan('make:handler', ['name' => 'OrderHandler'])
            ->assertFailed();
    }
}

Generator 指令會對實際的檔案系統寫入。務必於 tearDown() 進行清理。即使測試中途失敗也能確實執行。

Laravel 套件開發

確認使用服務提供者進行套件開發的基礎。

以 Orchestra Testbench 測試 Laravel 套件

確認套件測試基礎的建立方式。

Source: Illuminate\Console\GeneratorCommand, Illuminate\Foundation\Console\RequestMakeCommand

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

GeneratorCommand — 自訂 make: 指令的實作

什麼是 GeneratorCommand

最小實作

建立 stub 檔案

讓 stub 可被自訂

於服務提供者註冊

活用範例

測試

相關頁面

Laravel 套件開發

以 Orchestra Testbench 測試 Laravel 套件

​什麼是 GeneratorCommand

​最小實作

​建立 stub 檔案

​讓 stub 可被自訂

​於服務提供者註冊

​活用範例

​測試

​相關頁面

Laravel 套件開發

以 Orchestra Testbench 測試 Laravel 套件

什麼是 GeneratorCommand

最小實作

建立 stub 檔案

讓 stub 可被自訂

於服務提供者註冊

活用範例

測試

相關頁面