Laravel master パッケージ開発

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

もちろんパッケージには、色々な種類が存在しています。スタンドアローンで動作するパッケージがあります。つまり、どんなPHPフレームワークでも動作します。CarbonもBehatもスタンドアローンパッケージの例です。Laravelと一緒に使用するにはcomposer.jsonファイルでただ使用を指定するだけです。Of course, there are different types of packages. Some packages are stand-alone, meaning they work with any PHP framework. 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.

ファサード使用の注意A Note On Facades

Laravelアプリケーションをプログラムする場合は、契約とファサードのどちらを使用しても、一般的には問題ありません。両方共に基本的に同じレベルのテスタビリティがあるからです。しかし、パッケージを書く場合は、ファサードの代わりに、契約を使用してください。パッケージでは、Laravelのテストヘルパの全てへアクセスができないためです。ファサードをモックするよりは、契約をモックしたり、スタブするほうが簡単です。When writing a Laravel application, it generally does not matter if you use contracts or facades since both provide essentially equal levels of testability. However, when writing packages, it is best to use contracts[/docs/{{version}}/contracts] instead of facades[/docs/{{version}}/facades]. Since your package will not have access to all of Laravel's testing helpers, it will be easier to mock or stub a contract than to mock a facade.

サービスプロバイダ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アプリケーションと同様に、Illuminate\Support\Facades\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 Illuminate\Support\Facades\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

設定Configuration

通常、パッケージの設定ファイルをアプリケーション自身のconfigディレクトリへ公開する必要が起きます。これにより、ユーザが皆さんのパッケージのデフォルト設定オプションを簡単にオーバーライドできるようになります。設定ファイルを公開するには、サービスプロバイダのbootメソッドで、publishesメソッドを呼び出してください。Typically, you will need 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 allow your configuration files to be published, call 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 publish location. Of course, once your configuration has been published, its values may be accessed like any other configuration file:

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

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

もしくは、アプリケーションへ公開したコピーと、自身のパッケージの設定ファイルをマージすることもできます。これにより、ユーザは公開された設定のコピーの中で、実際にオーバーライドしたいオプションのみを定義すればよくなります。設定をマージする場合は、サービスプロバイダのregisterメソッドの中で、mergeConfigFromメソッドを使用します。（訳注：registerではなく、bootメソッドの間違いかもしれません）You may also merge your own package configuration file with the application's published copy. This will allow your users to define 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'
    );
}

マイグレーションMigrations

もしパッケージがデータベースマイグレーションを含んでいる場合、loadMigrationsFromメソッドを使用し、Laravelへどのようにロードするのかを知らせます。loadMigrationsFromメソッドは引数を一つ取り、パッケージのマイグレーションのパスです。If your package contains database migrations[/docs/{{version}}/migrations], you may use the loadMigrationsFrom method to inform Laravel how to load them. The loadMigrationsFrom method accepts the path to your package's migrations as its only argument:

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

パッケージのマイグレーションが登録されると、php artisan migrateコマンド実行時に、自動的にパッケージのマイグレーションも行われます。アプリケーションのdatabase/migrationsディレクトリへ公開する必要はありません。Once your package's migrations have been registered, they will automatically be run when the php artisan migrate command is executed. You do not need to export them to the application's main database/migrations directory.

言語ファイル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ファイル中の、welcome行をロードするには、次のようになります。Package translations are referenced using the package::file.line syntax convention. 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 desired publish locations. For example, to publish the translation files for the courier package, you may do the following:

/**
 * サービス初期処理登録後の処理
 *
 * @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コマンドを実行すると、パッケージの翻訳は指定された公開場所で公開されます。Now, when users of your package execute Laravel's vendor:publish Artisan command, your package's translations will be published to the specified publish location.

ビュー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's name is courier, you would 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 the package::view syntax convention. So, once your view path is registered in a service provider, 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: the application's resources/views/vendor directory and the directory you specify. So, using the courier example, 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 package 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 desired publish locations:

/**
 * サービス初期処理登録後の処理
 *
 * @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コマンドを実行すると、パッケージのビューは指定された公開場所へコピーされます。Now, when users of your package execute Laravel's vendor:publish Artisan command, your package's views will be copied to the specified publish location.

コマンドCommands

パッケージのArtisanコマンドをLaravelへ登録するには、commandsメソッドを使います。このメソッドは、コマンドクラス名の配列を引数に取ります。コマンドを登録したら、Artisan CLIを使い、実行できます。To register your package's Artisan commands with Laravel, you may use the commands method. This method expects an array of command class names. Once the commands have been registered, you may execute them using the Artisan CLI[/docs/{{version}}/artisan]:

/**
 * アプリケーションサービスの初期処理
 *
 * @return void
 */
public function boot()
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            FooCommand::class,
            BarCommand::class,
        ]);
    }
}

公開アセットPublic Assets

パッケージにはJavaScriptやCSS、画像などのアセットを含むと思います。こうしたアセットをpublicディレクトリへ公開するには、サービスプロバイダのpublishesメソッドを使用してください。次の例では、関連するアセットをまとめて公開するためにpublicアセットグループタグも追加指定しています。Your package 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 publish location. Since you will typically need to overwrite the assets every time the package is updated, you may use the --force flag:

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

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

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

php artisan vendor:publish --tag=config