Laravel5.5 LTS 日本語ドキュメント

このリポジトリはPHP Webアプリフレームワークである、LaravelのLTSバージョンである5.5の公式英文ドキュメントを日本語へ翻訳しています。

This project is maintained by okinaka

アップグレードガイド

5.4から5.5.0へのアップグレード

アップデートの見積もり時間：１時間

{note} 私達は、互換性を失う可能性がある変更を全部ドキュメントにしようとしています。しかし、変更点のいくつかは、フレームワークの明確ではない部分で行われているため、一部の変更が実際にアプリケーションに影響を与えてしまう可能性があります。

PHP

Laravel5.5では、PHP7.0.0以上が必要です。

依存パッケージのアップデート

composer.jsonファイル中の、laravel/framework依存指定を5.5.*へ変更してください。さらに、phpunit/phpunitの依存指定を~6.0へ更新してください。次に、composer.jsonファイルのrequire-devセクションに、filp/whoopsパッケージのバージョン~2.0を追加します。最後に、composer.jsonファイルのscriptsセクションで、post-autoload-dumpイベントに対しpackage:discoverコマンドを追加します。

"scripts": {
    ...
    "post-autoload-dump": [
        "Illuminate\Foundation\ComposerScripts::postAutoloadDump",
        "@php artisan package:discover"
    ],
}

もちろん、アプリケーションで使用しているサードパーティ製パッケージを調べ、Laravel5.5に適切なバージョンを使っていることも忘れず確認してください。

Laravelインストーラ

{tip} laravel newを使い、Laravelインストーラによりインストールしている方は、composer global updateコマンドにより、インストーラパッケージを更新してください。

Laravel Dusk

Laravel5.5とヘッドレスChromeでのテストに対し互換性のある、Laravel Dusk 2.0.0がリリースされました。

Pusher

Pusherイベントブロードキャストドライバーは、Pusher SDKのバージョン~3.0が必要となりました。

Swift Mailer

Laravel5.5では、バージョン~6.0のSwift Mailerが必要です。

Artisan

コマンドのオートロード

Laravel5.5では、カーネルへ一々登録しなくても、Artisanはコマンドを自動的に見つけ出します。この新機能を利用するには、App\Console\Kernelクラスへ以下のように、commandsメソッドを追加してください。（訳注：loadメソッドの間違い）

$this->load(__DIR__.'/Commands');

fireメソッド

Artisanコマンド中のfireメソッドは、handleへリネームしてください。

optimizeコマンド

最近のPHPのオペコードキャッシュの向上により、optimize Artisanコマンドは必要なくなりました。将来のリリースでLaravelから削除されるため、デプロイスクリプトからこのコマンドを外してください。

認証

authorizeResourceコントローラメソッド

authorizeResourceメソッドへ複数の単語のモデル名を渡したとき、リソースコントローラの振る舞いと合わせるため、ルートセグメントは「スネーク」ケースになりました。

beforeポリシーメソッド

ポリシークラスにチェックしようとするアビリティの名前と一致する、メソッドが含まれていない場合、beforeメソッドは呼び出されなくなりました。

キャッシュ

データベースドライバ

データベースキャッシュドライバを使用している場合、Laravel5.5へアップグレードしたアプリケーションを最初にデプロイする時に、php artisan cache:clearを実行してください。

Eloquent

belongsToManyメソッド

EloquentモデルのbelongsToManyメソッドをオーバーライドしている場合、新しく追加された引数を反映するように、引数を更新してください。

/**
 * 多対多リレーションの定義
 *
 * @param  string  $related
 * @param  string  $table
 * @param  string  $foreignPivotKey
 * @param  string  $relatedPivotKey
 * @param  string  $parentKey
 * @param  string  $relatedKey
 * @param  string  $relation
 * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany
 */
public function belongsToMany($related, $table = null, $foreignPivotKey = null,
                              $relatedPivotKey = null, $parentKey = null,
                              $relatedKey = null, $relation = null)
{
    //
}

BelongsToMany getQualifiedRelatedKeyName

getQualifiedRelatedKeyNameメソッドは、getQualifiedRelatedPivotKeyNameへリネームされました。

BelongsToMany getQualifiedForeignKeyName

getQualifiedForeignKeyNameメソッドは、getQualifiedForeignPivotKeyNameへリネームされました。

モデルのisメソッド

Eloquentモデルのisメソッドをオーバーライドしている場合、メソッドからModelのタイプヒントを削除してください。これにより、isメソッドがnullを引数に取れるようになります。

/**
 * ２つのモデルが同じIDで、同じテーブルに属しているか判定
 *
 * @param  \Illuminate\Database\Eloquent\Model|null  $model
 * @return bool
 */
public function is($model)
{
    //
}

モデルの$eventsプロパティ

モデルの$eventsプロパティを$dispatchesEventsへリネームしてください。多くのユーザーがeventsリレーションを定義する必要がありましたが、古いプロパティ名と競合していたため、変更されました。

Pivotの$parentプロパティ

Illuminate\Database\Eloquent\Relations\Pivotクラスの$parent protectedプロパティを$pivotParentへ変更してください。

リレーションのcreateメソッド

BelongsToManyとHasOneOrMany、MorphOneOrManyクラスのcreateメソッドは、$attributes引数にデフォルト値を取るように変更されました。このメソッドをオーバーライドしている場合は、新しい定義に合わせて、引数を変更してください。

public function create(array $attributes = [])
{
    //
}

モデルのソフトデリート

モデルの「ソフトデリート」時に、モデルのexistsプロパティはtrueのままになりました。

withCountカラム形式

エイリアス使用時、withCountメソッドは、結果のカラム名に自動的に_countを付けなくなりました。たとえば、Laravel5.4ではクエリにbar_countカラムが結果に追加されていました。

$users = User::withCount('foo as bar')->get();

しかし、Laravel5.5では、エイリアスは指定された通りに使用されます。結果のカラムに、_countを付けたい場合は、エイリアスを定義する時に、明確にサフィックスを指定します。

$users = User::withCount('foo as bar_count')->get();

モデルのメソッドと属性名

配列アクセスを使う場合に、モデルのプライベートプロパティがアクセスされることを防ぐため、属性やプロパティと同じ名前のモデルメソッドを使えなくなりました。配列アクセス($user['name'])やdata_getヘルパ関数により、モデルの属性へアクセスすることで、これが起きると例外が発生します。

例外フォーマット

Laravel5.5では、バリデーション例外を含むすべての例外は、例外ハンドラによりHTTPレスポンスへ変換されています。更に、JSONバリデーションエラーのデフォルトフォーマットが変更されました。新しいフォーマットは、以下の規約にしたがっています。

{
    "message": "The given data was invalid.",
    "errors": {
        "field-1": [
            "Error 1",
            "Error 2"
        ],
        "field-2": [
            "Error 1",
            "Error 2"
        ],
    }
}

Laraverl5.4のJSONエラーフォーマットをそのまま使用したい場合は、App\Exceptions\Handlerクラスへ以下のメソッドを追加してください。

use Illuminate\Validation\ValidationException;

/**
 * バリデーション例外をJSONレスポンスへ変換
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Illuminate\Validation\ValidationException  $exception
 * @return \Illuminate\Http\JsonResponse
 */
protected function invalidJson($request, ValidationException $exception)
{
    return response()->json($exception->errors(), $exception->status);
}

JSON認証試行

この変更は、JSONで試みる認証のバリデーションエラーフォーマットにも影響を与えます。Laravel5.5では、上記で説明した新しいフォーマット規約に従い、JSON認証に失敗したエラーメッセージも送り返されます。

フォームRequestsの注意

個別のフォームリクエストの、レスポンスフォーマットをカスタマイズしている場合、failedValidationメソッドをオーバーライドし、カスタムレスポンスを含めたHttpResponseException例外インスタンスを投げてください。

use Illuminate\Http\Exceptions\HttpResponseException;

/**
 * バリデーション試行の失敗の処理
 *
 * @param  \Illuminate\Contracts\Validation\Validator  $validator
 * @return void
 *
 * @throws \Illuminate\Validation\ValidationException
 */
protected function failedValidation(Validator $validator)
{
    throw new HttpResponseException(response()->json(..., 422));
}

ファイルシステム

filesメソッド

Illuminate\Filesystem\Filesystemクラスのfilesメソッドは、$hidden引数が追加され、allFilesメソッドのようにSplFileInfoオブジェクトの配列を返すようになりました。以前は、パス名の配列を返していました。新しい引数は以下の通りです。

public function files($directory, $hidden = false)

メール

未使用のパラメータ

Illuminate\Contracts\Mail\MailQueue契約のqueueとlaterメソッドから、未使用の$dataと$callback引数が削除されました。

/**
 * 送信する新しいメールメッセージをキュー
 *
 * @param  string|array|MailableContract  $view
 * @param  string  $queue
 * @return mixed
 */
public function queue($view, $queue = null);

/**
 * （ｎ）秒後に送信する新しいメールメッセージをキュー
 *
 * @param  \DateTimeInterface|\DateInterval|int  $delay
 * @param  string|array|MailableContract  $view
 * @param  string  $queue
 * @return mixed
 */
public function later($delay, $view, $queue = null);

キュー

dispatchヘルパ

即時に実行するジョブをディスパッチし、handleメソッドから値を返す場合は、ジョブのディスパッチにdispatch_nowか、Bus::dispatchNowメソッドを使用してください。

use Illuminate\Support\Facades\Bus;

$value = dispatch_now(new Job);

$value = Bus::dispatchNow(new Job);

リクエスト

allメソッド

Illuminate\Http\Requestのallメソッドをオーバーライドしてる場合は、新しい$keys引数の使用方法を反映してください。

/**
 * リクエストの入力とファイルをすべて取得
 *
 * @param  array|mixed  $keys
 * @return array
 */
public function all($keys = null)
{
    //
}

hasメソッド

$request->hasメソッドは、入力が空文字列やnullであってもtrueを返すようになりました。以前のhasの振る舞いを提供するため、新しい$request->filledメソッドが追加されました。

intersectメソッド

intersectメソッドは削除されました。この動作を模倣するため、$request->onlyの引数で、array_filterを使用してください。

return array_filter($request->only('foo'));

onlyメソッド

onlyメソッドはリクエストペイロードに実際に存在する属性のみの返すようになりました。onlyメソッドの古い振る舞いを使いたい場合は、allメソッドを代わりに使用してください。

return $request->all('foo');

request()ヘルパ

requestヘルパはネストしたキーを受け取らなくなりました。この振る舞いが必要であれば、リクエストのinputメソッドを使用してください。

return request()->input('filters.date');

テスト

認証のアサート

いくつかの認証アサートは、フレームワークの他とより一貫性を持たせるため、名前を変更しました。

  • seeIsAuthenticatedは、assertAuthenticatedへ変更
  • dontSeeIsAuthenticatedは、assertGuestへ変更
  • seeIsAuthenticatedAsは、assertAuthenticatedAsへ変更
  • seeCredentialsは、assertCredentialsへ変更
  • dontSeeCredentialsは、assertInvalidCredentialsへ変更

Mail Fake

Mail fakeをリクエスト中にMailableがキューされたことを判定するために使用しているなら、Mail::assertSentの代わりにMail::assertQueuedを使用してください。この区別により、メールがバックグランド送信のためにキューされたが、リクエスト間では送られないことをアサートで指定できるようになりました。

Tinker

Laravel Tinkerはアプリケーションクラスを参照する際の、省略した名前空間をサポートするようになりました。この機能にはComposerクラスマップの最適化が必要であるため、composer.jsonファイルのconfigセクションへ、optimize-autoloaderディレクティブを追加する必要があります。

"config": {
    ...
    "optimize-autoloader": true
}

翻訳

LoaderInterface

Illuminate\Translation\LoaderInterfaceインターフェイスは、Illuminate\Contracts\Translation\Loaderへ変更になりました。

バリデーション

バリデータメソッド

バリデータの全バリデーションメソッドは、protectedからpublicへ変更になりました。

ビュー

動的”with”変数名

ビューと変数を共有するため、動的__callメソッドが許されています。こうした変数は「キャメル」ケースとして自動的に使えるようになります。

return view('pool')->withMaximumVotes(100);

maximumVotes変数へ、テンプレートから次のようにアクセスできます。

@php Bladeディレクティブ

@php Bladeディレクティブは、インラインタグを引数に取らなくなりました。代わりにディレクティブを完全に記述してください。

@php
    $teamMember = true;
@endphp

その他

私達は皆さんへ、laravel/laravel GitHubリポジトリで変更を確認することを勧めます。多くの変更は必須ではありませんが、皆さんのアプリケーションでは同期を取りたい変更もあることでしょう。そうした変更のいくつかは、このアップグレードガイドで取り扱っていますが、設定ファイルやコメントなどは載っていません。GitHub差分比較ツールで変更を簡単に確認できますので、自分にとってどの変更が重要であるかを洗い出せます。