Laravelパッケージ開発

パッケージとは

Laravelにおけるパッケージとは、アプリケーションに機能を追加するComposerパッケージです。パッケージには大きく2種類あります。

スタンドアロンパッケージ — Laravelに依存しない汎用PHPライブラリ（例：Carbon、Pest）
Laravelパッケージ — ルート、コントローラー、ビュー、設定など、Laravelと統合された機能を持つパッケージ

このガイドでは後者、Laravel専用パッケージの開発を扱います。パッケージ開発にはサービスプロバイダー、ファサード、設定ファイルの公開など、Laravelの内部構造を深く理解する必要があります。

パッケージのテストを書く場合は、Orchestra Testbench を使います。通常のLaravelアプリケーションと同じようにパッケージのテストを記述できます。

パッケージの自動検出

Laravelはパッケージをインストールした際に、composer.json の extra.laravel セクションを読み取ってサービスプロバイダーとファサードを自動登録します。

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

この設定を加えると、ユーザーは bootstrap/providers.php を手動で編集しなくてもパッケージが自動的に読み込まれます。

この自動検出がどのように実装され、いつキャッシュが再構築されるのかはパッケージ自動検出の内部構造で詳しく解説しています。

自動検出を無効にする

ユーザー側で特定のパッケージの自動検出を無効にしたい場合は、アプリケーションの composer.json に設定します。

"extra": {
    "laravel": {
        "dont-discover": [
            "acme/courier"
        ]
    }
}

サービスプロバイダーの役割

サービスプロバイダーはパッケージのエントリポイントです。ビュー、設定、マイグレーション、ルートなどのリソースをLaravelに登録する処理をここに集約します。サービスプロバイダーは Illuminate\Support\ServiceProvider を継承し、register と boot の2つのメソッドを持ちます。

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * パッケージのサービスを登録する
     */
    public function register(): void
    {
        // サービスコンテナへのバインディングはここで行う
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * パッケージのサービスをブートストラップする
     */
    public function boot(): void
    {
        // リソースの登録はここで行う
        $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
        $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

        $this->publishesMigrations([
            __DIR__.'/../database/migrations' => database_path('migrations'),
        ]);

        $this->publishes([
            __DIR__.'/../config/courier.php' => config_path('courier.php'),
        ], 'courier-config');

        $this->publishes([
            __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
        ], 'courier-views');
    }
}

register メソッド内でイベントリスナー、ルート、ビューなどを登録しないでください。まだ読み込まれていない別のサービスプロバイダーのサービスを誤って使ってしまう可能性があります。バインディング以外の処理は必ず boot メソッドで行います。

サービスを使われるまで生成せずに拡張し、解決済みの場合にも設定を反映する方法は、パッケージのサービス解決後フックを参照してください。callAfterResolving() の実行タイミングと、重複適用に耐える設計を解説しています。 Octaneやキューワーカーでも状態を持ち越さない登録方法は、パッケージサービスのライフサイクル設計を参照してください。scoped() の内部実装と、singletonが保持する依存関係の注意点を解説しています。パッケージのHTTP機能へミドルウェアを追加する方法は、パッケージのミドルウェア登録と適用範囲を参照してください。エイリアスの登録とルートへの適用を分離し、利用アプリケーションの既存グループを上書きしない設計を解説しています。

設定ファイルのPublish

publishes() — ファイルを公開する

boot メソッドで publishes() を呼び出すと、ユーザーが vendor:publish コマンドで設定ファイルを自分のアプリケーションにコピーできるようになります。

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ]);
}

公開後の設定値は通常のconfigアクセスと同じ方法で取得できます。

$value = config('courier.option');

mergeConfigFrom() — デフォルト値とマージする

register メソッドで mergeConfigFrom() を使うと、ユーザーが設定ファイルを公開していない場合にもパッケージのデフォルト値が使われます。

public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

mergeConfigFrom() はネストした配列の深いレベルまではマージしません。多次元配列を持つ設定では、ユーザーが一部だけ定義した場合に残りのオプションがマージされないことがあります。

Laravel 13の再帰的な置換メソッドとの違い、数値キーのリストの扱い、設定キャッシュを利用する場合の更新手順はパッケージ設定のマージとキャッシュで解説しています。

タグで公開グループを分ける

publishes() の第2引数にタグを指定すると、ユーザーが必要なリソースだけを選んで公開できます。

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ], 'courier-config');

    $this->publishesMigrations([
        __DIR__.'/../database/migrations/' => database_path('migrations'),
    ], 'courier-migrations');
}

# 設定ファイルだけを公開する
php artisan vendor:publish --tag=courier-config

# プロバイダーが提供するすべてのファイルを公開する
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

ルートの登録

loadRoutesFrom() を使ってルートファイルを読み込みます。アプリケーションのルートキャッシュが有効な場合は自動的にスキップされます。

public function boot(): void
{
    $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
}

ルートファイルではパッケージのコントローラーを指定します。

// routes/web.php
use Acme\Courier\Http\Controllers\TrackingController;
use Illuminate\Support\Facades\Route;

Route::prefix('courier')->group(function () {
    Route::get('/track/{id}', [TrackingController::class, 'show'])
        ->name('courier.track');
});

ミドルウェアの明示、URIとルート名の衝突回避、設定変更をキャッシュへ反映する手順はパッケージのルート登録とキャッシュで解説しています。

マイグレーションのPublish

publishesMigrations() を使うと、マイグレーションファイルを公開対象に登録できます。Laravel 13の標準構成では、database.migrations.update_date_on_publish が有効なため、公開時にファイル名のタイムスタンプが更新されます。設定が無効または存在しない場合は、この更新は行われません。

public function boot(): void
{
    $this->publishesMigrations([
        __DIR__.'/../database/migrations' => database_path('migrations'),
    ]);
}

公開と直接読み込みの使い分け、タイムスタンプ変更の条件、再公開のリスク、既存利用者へのスキーマ変更はパッケージのマイグレーション公開と更新で解説しています。

ビューのPublish

loadViewsFrom() — ビューを登録する

loadViewsFrom() でビューディレクトリを登録します。第2引数の名前空間を使って package::view の形式でビューを参照します。

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
}

登録後、ビューはパッケージ名前空間で参照します。

Route::get('/dashboard', function () {
    return view('courier::dashboard');
});

Laravelはビューを2か所から探します。まずアプリケーションの resources/views/vendor/courier ディレクトリを確認し、なければパッケージのビューディレクトリを使います。これによりユーザーがビューをカスタマイズできます。実装上の検索順序とファイル単位のフォールバック、公開済みテンプレートへの変更の届け方、Bladeキャッシュとの違いはパッケージビューの上書きと更新で解説しています。

ビューを公開する

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');

    $this->publishes([
        __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
    ], 'courier-views');
}

Bladeコンポーネントを登録する

コンポーネントをパッケージに含める場合は、boot メソッドで登録します。

use Illuminate\Support\Facades\Blade;
use Acme\Courier\View\Components\AlertComponent;

public function boot(): void
{
    Blade::component('courier-alert', AlertComponent::class);
}

コンポーネント名前空間を使って一括登録することもできます。

use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::componentNamespace('Acme\\Courier\\View\\Components', 'courier');
}

{{-- 個別登録の場合 --}}
<x-courier-alert />

{{-- 名前空間登録の場合 --}}
<x-courier::alert />

公開アセットの配布

パッケージのJavaScript・CSS・画像を配布するには、publishes() で public_path('vendor/courier') などへのコピーを登録します。パッケージを更新しても公開済みファイルは自動では変わりません。タグとプロバイダーによる対象の絞り込み、--force と --existing の違い、削除済みファイルの扱い、laravel-assets による更新はパッケージの公開アセットと更新で解説しています。

翻訳ファイルのPublish

loadTranslationsFrom() で翻訳ファイルを登録します。翻訳は package::file.key の形式で参照します。

public function boot(): void
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

    $this->publishes([
        __DIR__.'/../lang' => $this->app->langPath('vendor/courier'),
    ]);
}

// 翻訳の使用
echo trans('courier::messages.welcome');

JSONの翻訳ファイルを使う場合は loadJsonTranslationsFrom() を使います。

public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}

PHP翻訳の部分上書き、JSON翻訳の読み込み順序と上書き先、翻訳キーの互換性と公開済みファイルの更新はパッケージ翻訳の上書きと更新で解説しています。

コマンドの登録

パッケージのArtisanコマンドは commands() メソッドで登録します。コンソール環境でのみ登録するのが一般的です。

use Acme\Courier\Console\Commands\InstallCommand;
use Acme\Courier\Console\Commands\SyncCommand;

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            SyncCommand::class,
        ]);
    }
}

optimize コマンドへの統合

パッケージが独自のキャッシュを持つ場合、optimizes() メソッドで php artisan optimize と php artisan optimize:clear に統合できます。

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->optimizes(
            optimize: 'courier:cache',
            clear: 'courier:clear-cache',
        );
    }
}

コマンドクラスの登録と最適化タスクの登録は別の処理です。登録キーの衝突、--except による除外、標準タスクとの実行順序、失敗時の終了コードはパッケージのキャッシュとoptimizeへの統合で解説しています。

`about` コマンドへの情報追加

php artisan about の出力にパッケージ情報を追加するには AboutCommand::add() を使います。

use Illuminate\Foundation\Console\AboutCommand;

public function boot(): void
{
    AboutCommand::add('Courier Package', fn () => ['Version' => '1.0.0']);
}

データを評価するタイミング、--only とJSON出力、秘密情報を含めない設計、テストでの登録状態はパッケージの診断情報をaboutに追加するで解説しています。

ファサードの作成

ファサードを使うと、サービスコンテナのバインディングを静的メソッドのように呼び出せます。

サービスクラスを作成する

<?php

namespace Acme\Courier;

class CourierManager
{
    public function __construct(
        protected array $config,
    ) {}

    public function send(string $to, string $message): bool
    {
        // メッセージ送信処理
        return true;
    }

    public function track(string $id): array
    {
        // 追跡情報取得処理
        return ['status' => 'delivered'];
    }
}

ファサードクラスを作成する

Illuminate\Support\Facades\Facade を継承し、getFacadeAccessor() でサービスコンテナのバインディングキーを返します。

<?php

namespace Acme\Courier\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @method static bool send(string $to, string $message)
 * @method static array track(string $id)
 *
 * @see \Acme\Courier\CourierManager
 */
class Courier extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return \Acme\Courier\CourierManager::class;
    }
}

サービスプロバイダーでバインドする

public function register(): void
{
    $this->app->singleton(\Acme\Courier\CourierManager::class, function ($app) {
        return new \Acme\Courier\CourierManager($app['config']['courier']);
    });
}

composer.json に登録する

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

ファサードのメソッドにはPHPDocの @method アノテーションを付けることで、IDEの補完が有効になります。

// ファサード経由でサービスを呼び出す
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', 'パッケージが届きました');
$status = Courier::track('ABC-123');

DeferrableProvider — 遅延読み込みの実装

サービスコンテナへのバインディングのみを行うプロバイダーは、DeferrableProvider インターフェースを実装することで遅延読み込みを実現できます。サービスが実際に必要になるまでプロバイダーが読み込まれないため、アプリケーションのパフォーマンスが向上します。

<?php

namespace Acme\Courier;

use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * このプロバイダーが提供するサービスの一覧を返す
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravelは遅延プロバイダーが提供するサービスのリストをコンパイルして保存します。provides() に列挙したサービスが解決されるときだけプロバイダーが読み込まれます。

リソースの登録（ビュー、ルート、イベントリスナーなど）が必要なプロバイダーには DeferrableProvider を使わないでください。遅延読み込みされると、それらのリソースが登録されないままになります。

パッケージのテスト

パッケージ単体でテストする場合は Orchestra Testbench を使います。通常のLaravelアプリケーション内にいるかのようにパッケージのテストを記述できます。

composer require --dev orchestra/testbench

テストケースで getPackageProviders() をオーバーライドしてパッケージのサービスプロバイダーを登録します。

<?php

namespace Acme\Courier\Tests;

use Acme\Courier\CourierServiceProvider;
use Orchestra\Testbench\TestCase as BaseTestCase;

class TestCase extends BaseTestCase
{
    /**
     * パッケージのサービスプロバイダーを登録する
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * パッケージのファサードエイリアスを登録する
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * テスト用の環境設定
     */
    protected function defineEnvironment($app): void
    {
        $app['config']->set('courier.api_key', 'test-key');
    }
}

<?php

namespace Acme\Courier\Tests\Feature;

use Acme\Courier\Facades\Courier;
use Acme\Courier\Tests\TestCase;

class CourierTest extends TestCase
{
    public function test_can_send_message(): void
    {
        $result = Courier::send('[email protected]', 'テストメッセージ');

        $this->assertTrue($result);
    }
}

Composerへの公開

パッケージを Packagist に公開するためのベストプラクティスです。 composer.json の基本設定

{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^11.0||^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ],
            "aliases": {
                "Courier": "Acme\\Courier\\Facades\\Courier"
            }
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

illuminate/support に依存することで、illuminate/framework 全体ではなくLaravelの必要なコンポーネントだけを依存に含められます。パッケージの依存ツリーを小さく保ちましょう。

ディレクトリ構造の例

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── ja/
│       └── messages.php
├── resources/
│   └── views/
│       └── dashboard.blade.php
├── routes/
│   └── web.php
├── src/
│   ├── Console/
│   │   └── Commands/
│   │       └── InstallCommand.php
│   ├── Facades/
│   │   └── Courier.php
│   ├── Http/
│   │   └── Controllers/
│   │       └── TrackingController.php
│   ├── CourierManager.php
│   └── CourierServiceProvider.php
├── tests/
│   ├── Feature/
│   └── TestCase.php
├── composer.json
└── README.md

サービスプロバイダー

サービスプロバイダーの register と boot メソッド、遅延プロバイダーの詳細を確認します。

バージョン互換性管理

LaravelとPHPのメジャーバージョンアップへの対応戦略とGitHub Actionsのテストマトリクス設定を解説します。

AI開発

デザインパターン

パッケージ開発

アプリケーション構造

Laravel 13 新機能

Eloquent 深掘り

バリデーション拡張

認証の拡張

セキュリティ

キュー

テスト

リアルタイム通信

パッケージとは

パッケージの自動検出

自動検出を無効にする

サービスプロバイダーの役割

設定ファイルのPublish

publishes() — ファイルを公開する

mergeConfigFrom() — デフォルト値とマージする

タグで公開グループを分ける

ルートの登録

マイグレーションのPublish

ビューのPublish

loadViewsFrom() — ビューを登録する

ビューを公開する

Bladeコンポーネントを登録する

公開アセットの配布

翻訳ファイルのPublish

コマンドの登録

optimize コマンドへの統合

`about` コマンドへの情報追加

ファサードの作成

DeferrableProvider — 遅延読み込みの実装

パッケージのテスト

Composerへの公開

関連ページ

サービスプロバイダー

バージョン互換性管理

​パッケージとは

​パッケージの自動検出

​自動検出を無効にする

​サービスプロバイダーの役割

​設定ファイルのPublish

​publishes() — ファイルを公開する

​mergeConfigFrom() — デフォルト値とマージする

​タグで公開グループを分ける

​ルートの登録

​マイグレーションのPublish

​ビューのPublish

​loadViewsFrom() — ビューを登録する

​ビューを公開する

​Bladeコンポーネントを登録する

​公開アセットの配布

​翻訳ファイルのPublish

​コマンドの登録

​optimize コマンドへの統合

​about コマンドへの情報追加

​ファサードの作成

​DeferrableProvider — 遅延読み込みの実装

​パッケージのテスト

​Composerへの公開

​関連ページ

サービスプロバイダー

バージョン互換性管理

パッケージとは

パッケージの自動検出

自動検出を無効にする

サービスプロバイダーの役割

設定ファイルのPublish

publishes() — ファイルを公開する

mergeConfigFrom() — デフォルト値とマージする

タグで公開グループを分ける

ルートの登録

マイグレーションのPublish

ビューのPublish

loadViewsFrom() — ビューを登録する

ビューを公開する

Bladeコンポーネントを登録する

公開アセットの配布

翻訳ファイルのPublish

コマンドの登録

optimize コマンドへの統合

`about` コマンドへの情報追加

ファサードの作成

DeferrableProvider — 遅延読み込みの実装

パッケージのテスト

Composerへの公開

関連ページ