Laravel 5.dev パッケージ開発

イントロダクション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

パッケージの内部構造は完全にみなさん次第です。しかし、通常各パッケージは、一つ以上のサービスプロバイダーを含むでしょう。サービスプロバイダーはIoC結合を含み、同時にパッケージの設定、ビュー、言語ファイルの設置場所も指定します。Your package's internal structure is entirely up to you; however, typically each package will contain one or more service providers[/docs/master/providers]. The service provider contains any IoC[/docs/master/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

パッケージのビューをresource/views/vendorディレクトリーへ発行するには、サービスプロバイダーのbootメソッドで、publishesメソッドを使用する必要があります。To publish your package's views to the resource/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'
);

ファイルグループの発行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/' => base_path('/database/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.