Laravel 5.0 パッケージ開発

イントロダクション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 that are Laravel specific.

Laravelのパッケージは、全てPackagistと Composerにより配布されます。ですから、これらの素晴らしいPHPパッケージ配布ツールについて学ぶことは、大切です。All Laravel packages are distributed via Packagist[http://packagist.org] and Composer[http://getcomposer.org], so learning about these wonderful PHP package distribution tools is essential.

ビューViews

パッケージの内部構造は完全に皆さんへ委ねられています。しかし、通常各パッケージは、一つ以上のサービスプロバイダーを含むでしょう。サービスプロバイダーはサービスコンテナ結合を含み、同時にパッケージの設定、ビュー、言語ファイルの設置場所も指定します。Your package's internal structure is entirely up to you; however, typically each package will contain one or more service providers[/docs/{{version}}/providers]. The service provider contains any service container[/docs/{{version}}/container] bindings, as well as instructions as to where package configuration, views, and translation files are located.

ビューファイルViews

パッケージのビューは通常、二重のコロンによる「名前空間」で指定します。Package views are typically referenced using a double-colon "namespace" syntax:

return view('package::view.name');

Laravelに対し、指定された名前空間のビューはどこに存在するのかを伝える必要があります。例えば、パッケージに"courier"という名前がついているなら、サービスパッケージのbootメソッドに、以下のコードを指定します。All you need to do is tell Laravel where the views for a given namespace are located. For example, if your package is named "courier", you might add the following to your service provider's boot method:

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

これで、以下の記法を使用し、パッケージのビューをロードできます。Now you may load your package views using the following syntax:

return view('courier::view.name');

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ディレクトリーで（ユーザーに対し）公開するには、サービスプロバイダーのbootメソッドで、publishesメソッドを使用する必要があります。To publish your package's views to the resources/views/vendor directory, you should use the publishes method from the boot method of your service provider:

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コマンドを実行すると、指定された場所へビューディレクトリーがコピーされます。Now, when users of your package execute Laravel's vendor:publish command, your views directory will be copied to the specified location.

既存のファイルをオーバーライトしたい場合は、--forceスイッチを使用します。If you would like to overwrite existing files, use the --force switch:

php artisan vendor:publish --force

注目： publishesメソッドにより、どんなタイプのファイルでも、好きな場所へ公開できます。Note: You may use the publishes method to publish any type of file to any location you wish.

言語ファイルTranslations

パッケージの言語ファイルは、通常二重コロン記法を使用し指定されます。Package translation files are typically referenced using a double-colon syntax:

return trans('package::file.line');

指定された名前空間の言語ファイルがどこに存在するかをLaravelへ伝える必要があります。例えば、パッケージ名が"courier"ならば、サービスプロバイダーのbootメソッドに以下の行を追加する必要があるでしょう。All you need to do is tell Laravel where the translations for a given namespace are located. For example, if your package is named "courier", you might add the following to your service provider's boot method:

public function boot()
{
	$this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');
}

言語ファイルのフォルダーは、それぞれの言語のサブディレクトリーにわけられている必要があることに注意してください。例えば、en、es、ruなどです。Note that within your translations folder, you would have further directories for each language, such as en, es, ru, etc.

これで、以下の記法を使用し、パッケージの言語ファイルをロードできます。Now you may load your package translations using the following syntax:

return trans('courier::file.line');

設定Configuration

通常、あなたのパッケージの設定ファイルをアプリケーション自身のconfigディレクトリーへ公開する必要があることでしょう。これにより、あなたのデフォルト設定オプションをユーザーに簡単にオーバーライドしてもらえるようになります。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.

設定ファイルを公開するには、サービスプロバイダーのbootメソッドで、publishesメソッドを使用するだけです。To publish a configuration file, just use the publishes method from the boot method of your service provider:

$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');

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

$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 assets, use the publishes method from your service provider's boot method. In this example, we will also add a "public" asset group tag.

$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 files 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

ファイルのグループごとに分割して公開したい場合もあります。例えば、ユーザーにパッケージの設定ファイルとアセットファイルを別々に公開できるようにさせたい場合です。You may want to publish groups of files separately. For instance, you might want your users to be able to publish your package's configuration files and asset files separately. You can do this by 'tagging' them:

// 設定ファイルの公開
$this->publishes([
	__DIR__.'/../config/package.php' => config_path('package.php')
], 'config');

// マイグレーションの公開
$this->publishes([
	__DIR__.'/../database/migrations/' => database_path('/migrations')
], 'migrations');

これでタグを指定してもらえば、分割してファイルを公開できます。You can then publish these files separately by referencing their tag like so:

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

ルートRouting

パッケージのルートファイルをロードするには、サービスプロバイダーのbootメソッドの中で、シンプルにincludeしてください。To load a routes file for your package, simply include it from within your service provider's boot method.

サービスプロバイダー中でルート定義ファイルの読み込みIncluding A Routes File From A Service Provider

public function boot()
{
	include __DIR__.'/../../routes.php';
}

注意： パッケージでコントローラーを使用している場合、ファイルをロードできるように、composer.jsonで確実に設定してください。Note: If your package is using controllers, you will need to make sure they are properly configured in your composer.json file's auto-load section.