Laravel 5.1 パッケージ開発

イントロダクションIntroduction

パッケージはLaravelに機能を追加する一番重要な方法です。パッケージとして何でも動作させることができます。たとえば日付ライブラリーであるCarbonや、振る舞い駆動開発(BDD)テストフレームワークのBehatなどです。Packages are the primary way of adding functionality to Laravel. Packages might be anything from a great way to work with dates like Carbon[https://github.com/briannesbitt/Carbon], or an entire BDD testing framework like Behat[https://github.com/Behat/Behat].

もちろんパッケージには色々な種類が存在しています。スタンドアローンで動作するパッケージがあります。動作させるのにLaravelに限らず、どんなフレームワークも必要としません。CarbonもBehatもスタンドアローンパッケージの例です。Laravelと一緒に使用するにはcomposer.jsonファイルでただ使用を指定するだけです。Of course, there are different types of packages. Some packages are stand-alone, meaning they work with any framework, not just Laravel. Both Carbon and Behat are examples of stand-alone packages. Any of these packages may be used with Laravel by simply requesting them in your composer.json file.

逆にLaravelと一緒に使用することを意図したパッケージもあります。こうしたパッケージはLaravelアプリケーションを高めることを特に意図したルート、コントローラー、ビュー、設定を持つことでしょう。このガイドはLaravelに特化したパッケージの開発を主に説明します。On the other hand, other packages are specifically intended for use with Laravel. These packages may have routes, controllers, views, and configuration specifically intended to enhance a Laravel application. This guide primarily covers the development of those packages that are Laravel specific.

サービスプロバイダーService Providers

サービスプロバイダーはパッケージとLaravelを結びつけるところです。サービスプロバイダーは何かをLaravelのサービスコンテナと結合し、ビューや設定、言語ファイルのようなリソースをどこからロードするかをLaravelに知らせる責務を持っています。Service providers[/docs/{{version}}/providers] are the connection points between your package and Laravel. A service provider is responsible for binding things into Laravel's service container[/docs/{{version}}/container] and informing Laravel where to load package resources such as views, configuration, and localization files.

サービスプロバイダーはIlluminate\Support\ServiceProviderクラスを拡張し、registerとbootの２メソッドを含んでいます。ベースのServiceProviderクラスは、illuminate/support Composerパッケージにあります。A service provider extends the Illuminate\Support\ServiceProvider class and contains two methods: register and boot. The base ServiceProvider class is located in the illuminate/support Composer package, which you should add to your own package's dependencies.

サービスプロバイダーの構造と目的について詳細を知りたければ、ドキュメントを調べてください。To learn more about the structure and purpose of service providers, check out their documentation[/docs/{{version}}/providers].

ルーティングRouting

パッケージのルートを定義するには、パッケージのサービスプロバイダーのbootメソッドからルートファイルをrequireするだけです。ルートファイルの中は典型的なLaravelアプリケーションと同様にRouteファサードを使いルートを登録します。To define routes for your package, simply require the routes file from within your package service provider's boot method. From within your routes file, you may use the Route facade to register routes[/docs/{{version}}/routing] just as you would within a typical Laravel application:

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

リソースResources

ビューViews

パッケージのビューをLaravelへ登録するには、ビューがどこにあるのかLaravelに知らせる必要があります。そのためにはサービスプロバイダーのloadViewsFromメソッドを使用してください。loadViewsFromメソッドは２つの引数を取ります。ビューテンプレートへのパスと、パッケージの名前です。たとえばパッケージ名が"courier"であれば、以下の行をサービスプロバイダーのbootメソッドに追加してください。To register your package's views[/docs/{{version}}/views] with Laravel, you need to tell Laravel where the views are located. You may do this using the service provider's loadViewsFrom method. The loadViewsFrom method accepts two arguments: the path to your view templates and your package's name. For example, if your package name is "courier", add the following to your service provider's boot method:

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

パッケージのビューはダブルコロンを使うpackage::view記法を使い参照します。ですからcourierパッケージのadminビューをロードするには、次のように書きます。Package views are referenced using a double-colon package::view syntax. So, you may load the admin view from the courier package like so:

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

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

loadViewsFromメソッドを使用する場合、Laravelはビューの２つの場所を実際には登録します。一つはアプリケーションのresources/views/vendorディレクトリーで、もう一つは皆さんが指定したディレクトリーです。ではcourierの例を使って確認しましょう。パッケージのビューがリクエストされると、Laravelは最初にresources/views/vendor/courierの中にカスタムバージョンのビューが開発者により用意されていないかチェックします。カスタムビューが用意されていなければ、次にloadViewsFromの呼び出しで指定したパッケージビューディレクトリーを探します。この仕組みのおかげで、パッケージのビューがエンドユーザーにより簡単にカスタマイズ／オーバーライドできるようになっています。When you use the loadViewsFrom method, Laravel actually registers two locations for your views: one in the application's resources/views/vendor directory and one in the directory you specify. So, using our courier example: when requesting a package view, Laravel will first check if a custom version of the view has been provided by the developer in resources/views/vendor/courier. Then, if the view has not been customized, Laravel will search the package view directory you specified in your call to loadViewsFrom. This makes it easy for end-users to customize / override your package's views.

ビューの公開Publishing Views

パッケージのビューをresources/views/vendorディレクトリーで公開したい場合は、サービスプロバイダーのpublishesメソッドを使ってください。publishesメソッドはパッケージのビューパスと対応する公開場所の配列を引数に取ります。If you would like to make your views available for publishing to the application's resources/views/vendor directory, you may use the service provider's publishes method. The publishes method accepts an array of package view paths and their corresponding publish locations.

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

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

これであなたのパッケージのユーザーがLaravelのvendor::publish Artisanコマンドを実行すると、パッケージのビューは指定された場所へコピーされます。Now, when users of your package execute Laravel's vendor:publish Artisan command, your package's views will be copied to the specified location.

言語ファイルTranslations

パッケージに言語ファイルを含んでいる場合は、loadTranslationsFromメソッドでLaravelへどのようにロードするのかを知らせてください。たとえばパッケージ名がcourierであれば、以下の行をサービスプロバイダーのbootメソッドに追加します。If your package contains translation files[/docs/{{version}}/localization], you may use the loadTranslationsFrom method to inform Laravel how to load them. For example, if your package is named "courier", you should add the following to your service provider's boot method:

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

パッケージの言語行はダブルコロンを使うpackage::file.line記法を使い参照します。ですからcourierパッケージのmessages.phpファイルからwelcome行をロードする場合、次のようになります。Package translations are referenced using a double-colon package::file.line syntax. So, you may load the courier package's welcome line from the messages file like so:

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

翻訳の公開Publishing Translations

パッケージの翻訳をアプリケーションのresources/lang/vendorディレクトリーへ公開したい場合は、サービスプロバイダーのpublishesメソッドを使ってください。publishesメソッドはパッケージパスと対応する公開位置の配列を受け取ります。たとえば例のcourierパッケージの翻訳ファイルを公開してみましょう。If you would like to publish your package's translations to the application's resources/lang/vendor directory, you may use the service provider's publishes method. The publishes method accepts an array of package paths and their corresponding publish locations. For example, to the publish the translation files for our example courier package:

/**
 * サービスの起動登録後に実行
 *
 * @return void
 */
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');

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

これでパッケージのユーザーが、Laravelのvendor:publish Artisanコマンドを実行すると、パッケージの翻訳が指定した場所へ公開されます。Now, when users of your package execute Laravel's vendor:publish Artisan command, your package's translations will be published to the specified location.

設定Configuration

通常、あなたのパッケージの設定ファイルをアプリケーション自身のconfigディレクトリーへ公開したいことでしょう。これにより、あなたのデフォルト設定オプションをユーザーに簡単にオーバーライドしてもらえるようになります。設定ファイルを公開するには、サービスプロバイダーのbootメソッドで、publishesメソッドを使用するだけです。Typically, you will want to publish your package's configuration file to the application's own config directory. This will allow users of your package to easily override your default configuration options. To publish a configuration file, just use the publishes method from the boot method of your service provider:

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

これであなたのパッケージのユーザーがLaravelのvendor:publishコマンドを実行すると、ファイルが指定された場所へコピーされます。もちろん設定ファイルが一度公開されると、他の設定ファイル同様に設定内容へアクセスできるようになります。Now, when users of your package execute Laravel's vendor:publish command, your file will be copied to the specified location. Of course, once your configuration has been published, it can be accessed like any other configuration file:

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

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

もしくはあなたのパッケージ設定ファイルをアプリケーションのファイルへマージすることを選ぶこともできます。これにより設定の公開済ファイルの中で、実際にオーバーライドしたいオプションだけを含めてもらう指定方法をユーザーに取ってもらえます。設定ファイルをマージする場合はサービスプロバイダーのregisterメソッドで、mergeConfigFromメソッドを使います。You may also choose to merge your own package configuration file with the application's copy. This allows your users to include only the options they actually want to override in the published copy of the configuration. To merge the configurations, use the mergeConfigFrom method within your service provider's register method:

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

公開アセットPublic Assets

パッケージにはJavaScriptやCSS、画像などのアセットを含むと思います。アセットを公開するには、サービスプロバイダーのbootメソッドでpublishesメソッドを使用してください。次の例では、関連するアセットをまとめて公開するためにpublicアセットグループタグも追加指定しています。Your packages may have assets such as JavaScript, CSS, and images. To publish these assets to the application's public directory, use the service provider's publishes method. In this example, we will also add a public asset group tag, which may be used to publish groups of related assets:

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

これにより、皆さんのパッケージのユーザーは、vendor:publishコマンドを実行できるようになりました。実行すれば皆さんのファイルは指定された場所へコピーされます。通常、パッケージがアップデートされる度に、アセットを上書きする必要があります。--forceフラッグが使用できますNow, when your package's users execute the vendor:publish command, your assets will be copied to the specified location. Since you typically will need to overwrite the assets every time the package is updated, you may use the --force flag:

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

公開アセットをいつも確実にアップデートしたい場合は、このコマンドをcomposer.jsonファイルのpost-update-cmdリストへ追加します。If you would like to make sure your public assets are always up-to-date, you can add this command to the post-update-cmd list in your composer.json file.

ファイルグループの公開Publishing File Groups

アセットとリソースのパッケージグループを別々に公開したいこともあるでしょう。たとえばパッケージのアセットの公開を強要せずに設定ファイルを公開したい場合です。publishesメソッドの呼び出し時の「タグ指定」で行えます。例としてパッケージのサービスプロバイダーのbootメソッドで２つの公開グループを定義してみましょう。You may want to publish groups of package assets and resources separately. For instance, you might want your users to be able to publish your package's configuration files without being forced to publish your package's assets at the same time. You may do this by "tagging" them when calling the publishes method. For example, let's define two publish groups in the boot method of a package service provider:

/**
 * サービス初期処理登録後の処理
 *
 * @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コマンドを使用するときにタグ名を指定することでグループを別々に公開できます。Now your users may publish these groups separately by referencing their tag name when using the vendor:publish Artisan command:

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