Laravel 5.2 パッケージ開発

イントロダクション

パッケージはLaravelに機能を追加する一番重要な方法です。パッケージとして何でも動作させることができます。たとえば日付ライブラリーであるCarbonや、振る舞い駆動開発(BDD)テストフレームワークのBehatなどです。

もちろんパッケージには色々な種類が存在しています。スタンドアローンで動作するパッケージがあります。動作させるのにLaravelに限らず、どんなフレームワークも必要としません。CarbonもBehatもスタンドアローンパッケージの例です。Laravelと一緒に使用するにはcomposer.jsonファイルでただ使用を指定するだけです。

逆にLaravelと一緒に使用することを意図したパッケージもあります。こうしたパッケージはLaravelアプリケーションを高めることを特に意図したルート、コントローラー、ビュー、設定を持つことでしょう。このガイドはLaravelに特化したパッケージの開発を主に説明します。

サービスプロバイダ

サービスプロバイダはパッケージとLaravelを結びつけるところです。サービスプロバイダは何かをLaravelのサービスコンテナと結合し、ビューや設定、言語ファイルのようなリソースをどこからロードするかをLaravelに知らせる責務を持っています。

サービスプロバイダはIlluminate\Support\ServiceProviderクラスを拡張し、registerとbootの２メソッドを含んでいます。ベースのServiceProviderクラスは、illuminate/support Composerパッケージにあります。

サービスプロバイダの構造と目的について詳細を知りたければ、ドキュメントを調べてください。

ルーティング

パッケージのルートを定義するには、パッケージのサービスプロバイダのbootメソッドからルートファイルをrequireするだけです。ルートファイルの中は典型的なLaravelアプリケーションと同様にRouteファサードを使いルートを登録します。

/**
 * サービス初期処理登録後の処理
 *
 * @return void
 */
public function boot()
{
    if (! $this->app->routesAreCached()) {
        require __DIR__.'/../../routes.php';
    }
}

リソース

ビュー

パッケージのビューをLaravelへ登録するには、ビューがどこにあるのかLaravelに知らせる必要があります。そのためにはサービスプロバイダのloadViewsFromメソッドを使用してください。loadViewsFromメソッドは２つの引数を取ります。ビューテンプレートへのパスと、パッケージの名前です。たとえばパッケージ名が"courier"であれば、以下の行をサービスプロバイダのbootメソッドに追加してください。

/**
 * サービス初期処理登録後の処理
 *
 * @return void
 */
public function boot()
{
    $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');
}

パッケージのビューはダブルコロンを使うpackage::view記法を使い参照します。ですからcourierパッケージのadminビューをロードするには、次のように書きます。

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

パッケージビューのオーバーライド

loadViewsFromメソッドを使用する場合、Laravelはビューの２つの場所を実際には登録します。一つはアプリケーションのresources/views/vendorディレクトリで、もう一つは皆さんが指定したディレクトリです。ではcourierの例を使って確認しましょう。パッケージのビューがリクエストされると、Laravelは最初にresources/views/vendor/courierの中にカスタムバージョンのビューが開発者により用意されていないかチェックします。カスタムビューが用意されていなければ、次にloadViewsFromの呼び出しで指定したパッケージビューディレクトリを探します。この仕組みのおかげで、パッケージのビューがエンドユーザにより簡単にカスタマイズ／オーバーライドできるようになっています。

ビューの公開

パッケージのビューをresources/views/vendorディレクトリで公開したい場合は、サービスプロバイダのpublishesメソッドを使ってください。publishesメソッドはパッケージのビューパスと対応する公開場所の配列を引数に取ります。

/**
 * サービス初期処理登録後の処理
 *
 * @return void
 */
public function boot()
{
    $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');

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

これであなたのパッケージのユーザがLaravelのvendor::publish Artisanコマンドを実行すると、パッケージのビューは指定された場所へコピーされます。

言語ファイル

パッケージに言語ファイルを含んでいる場合は、loadTranslationsFromメソッドでLaravelへどのようにロードするのかを知らせてください。たとえばパッケージ名がcourierであれば、以下の行をサービスプロバイダのbootメソッドに追加します。

/**
 * サービス初期処理登録後の処理
 *
 * @return void
 */
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');
}

パッケージの言語行はダブルコロンを使うpackage::file.line記法を使い参照します。ですからcourierパッケージのmessages.phpファイルからwelcome行をロードする場合、次のようになります。

echo trans('courier::messages.welcome');

翻訳の公開

パッケージの翻訳をアプリケーションのresources/lang/vendorディレクトリーへ公開したい場合は、サービスプロバイダのpublishesメソッドを使ってください。publishesメソッドは、パッケージパスと対応する公開位置の配列を受け取ります。たとえば、前記例のcourierパッケージ翻訳ファイルを公開してみましょう。

/**
 * サービス初期処理登録後の処理
 *
 * @return void
 */
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');

    $this->publishes([
        __DIR__.'/path/to/translations' => resource_path('lang/vendor/courier'),
    ]);
}

これでパッケージのユーザが、Laravelのvendor:publish Artisanコマンドを実行すると、パッケージの翻訳が指定した場所へ公開されます。

設定

通常、あなたのパッケージの設定ファイルをアプリケーション自身のconfigディレクトリへ公開したいことでしょう。これにより、あなたのデフォルト設定オプションをユーザに簡単にオーバーライドしてもらえるようになります。設定ファイルを公開するには、サービスプロバイダのbootメソッドで、publishesメソッドを使用するだけです。

/**
 * サービス初期処理登録後の処理
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/path/to/config/courier.php' => config_path('courier.php'),
    ]);
}

これであなたのパッケージのユーザがLaravelのvendor:publishコマンドを実行すると、ファイルが指定された場所へコピーされます。もちろん設定ファイルが一度公開されると、他の設定ファイル同様に設定内容へアクセスできるようになります。

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

デフォルトパッケージ設定

もしくはあなたのパッケージ設定ファイルをアプリケーションのファイルへマージすることを選ぶこともできます。これにより設定の公開済ファイルの中で、実際にオーバーライドしたいオプションだけを含めてもらう指定方法をユーザに取ってもらえます。設定ファイルをマージする場合はサービスプロバイダのregisterメソッドで、mergeConfigFromメソッドを使います。

/**
 * コンテナ結合の登録
 *
 * @return void
 */
public function register()
{
    $this->mergeConfigFrom(
        __DIR__.'/path/to/config/courier.php', 'courier'
    );
}

公開アセット

パッケージにはJavaScriptやCSS、画像などのアセットを含むと思います。アセットを公開するには、サービスプロバイダのbootメソッドでpublishesメソッドを使用してください。次の例では、関連するアセットをまとめて公開するためにpublicアセットグループタグも追加指定しています。

/**
 * サービス初期処理登録後の処理
 *
 * @return void
 */
public function boot()
{
    $this->publishes([
        __DIR__.'/path/to/assets' => public_path('vendor/courier'),
    ], 'public');
}

これにより、皆さんのパッケージのユーザは、vendor:publishコマンドを実行できるようになりました。実行すれば皆さんのファイルは指定された場所へコピーされます。通常、パッケージがアップデートされる度に、アセットを上書きする必要があります。--forceフラッグが使用できます

php artisan vendor:publish --tag=public --force

公開アセットをいつも確実にアップデートしたい場合は、このコマンドをcomposer.jsonファイルのpost-update-cmdリストへ追加します。

ファイルグループの公開

アセットとリソースのパッケージグループを別々に公開したいこともあるでしょう。たとえばパッケージのアセットの公開を強要せずに設定ファイルを公開したい場合です。publishesメソッドの呼び出し時の「タグ指定」で行えます。例としてパッケージのサービスプロバイダのbootメソッドで２つの公開グループを定義してみましょう。

/**
 * サービス初期処理登録後の処理

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

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

これでユーザは、vendor::publish Artisanコマンドを使用するときにタグ名を指定することで、グループを別々に公開できます。

php artisan vendor:publish --provider="Vendor\Providers\PackageServiceProvider" --tag="config"