Laravel 5.6 アップグレードガイド

5.6から5.6.30へのアップグレード(セキュリティーリリース)

Laravel5.6.30はセキュリティーリリースのため、すべてのユーザーに対して即時にアップグレードすることを推奨します。また、Laravel5.6.30はクッキーの暗号化とシリアライズに関するロジックに、互換性がない変更を含んでいるため、アプリケーションのアップグレード時に以降の注釈を注意深く読んでください。

この脆弱性はアプリケーションの暗号化キー(APP_KEY環境変数)が悪意のあるユーザーからアクセスされる場合にのみ悪用されます。 通常、アプリケーションのユーザーが、この値にアクセスできる可能性はありません。しかしながら、以前雇用していた人が暗号化キーにアクセスできていた場合、アプリケーションへ攻撃するためにこのキーを利用することができます。悪意のある人々の手に、暗号化キーが渡ったと信じるいかなる理由がある場合はいつでも、キーの値を変更すべきです。

クッキーのシリアライズ化

Laravel5.6.30では、クッキー値のシリアライズ化/非シリアライズ化を無効にしました。その理由は、Laravelのすべてのクッキーは、暗号化し、署名してあり、クライアントによる改ざんに対し、通常安全であると考えられます。しかしながら、アプリケーションの暗号化キーが悪意のある人々の手に入れば、彼らは暗号化キーを使用しクッキー値を生成できます。アプリケーションの中の任意のクラスメソッドを呼び出すことなど、PHPオブジェクトのシリアライズ化/非シリアライズ化に本来の脆弱性を悪用できてしまいます。**

すべてのクッキー値に対するシリアライズ化を無効にすることで、アプリケーションのセッションはすべて無効になり、ユーザーはアプリケーションに再ログインする必要が起きます。更に、アプリケーションで使用している他の暗号化クッキーの設定値が、無効になります。このため、カスタムクッキー値がリストと一致する事を確認するロジックをアプリケーションに追加する必要があるかも知れません。そうしない場合、全てを破棄することになります。

クッキーのシリアライズ化の設定

アプリケーションの暗号化キーにアクセスできない場合、この脆弱性は悪用できないため、今回の変更に対してもアプリケーションの互換性を維持できるように、暗号化クッキーのシリアライズ化を最有効にする手段を提供します。クッキーのシリアライズ化を有効/無効にするには、App\Http\Middleware\EncryptCookies ミドルウェアserializeスタティックプロパティを変更してください。

/**
 * クッキーをシリアライズするかの指定
 *
 * @var bool
 */
protected static $serialize = true;

注意 暗号化されたクッキーのシリアライズ化を有効にし、暗号化キーが悪意のある他者からアクセスできる場合、攻撃される可能性のある脆弱性がアプリケーションに起きます。キーが悪意のある人々の手に入ったと確信できる場合は、暗号化されたクッキーのシリアライズを有効にする前に、キーを新しい値に変更すべきです。

Dusk4.0.0

Dusk4.0.0がリリースされ、クッキーをシリアライズしなくなりました。クッキーのシリアライズを有効にする場合は、Dusk3.0.0を使用し続けてください。そうでなければ、Dusk4.0.0へアップグレードしてください。

Passport6.0.7

Passport6.0.7が、新しいLaravel\Passport\Passport::withoutCookieSerialization()メソッドと共にリリースされました。クッキーのシリアライズを無効にした場合は、アプリケーションのAppServiceProviderの中で、このメソッドを呼び出す必要があります。

5.5から5.6.0へのアップグレード

見積もり時間:10〜30分

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

PHP

Laravel5.6の動作には、PHPバージョン7.1.3以上が必要です。

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

composer.jsonファイルのlaravel/framework依存指定を5.6.*に、fideloper/proxy依存指定を^4.0へアップデートしてください。

さらに、以下のファーストパーティLaravelパッケージを使用している場合は、最新のリリースへアップグレードしてください。

  • Dusk (^3.0へアップグレード)
  • Passport (^6.0へアップグレード)
  • Scout (^4.0へアップグレード)

もちろん、アプリケーションで使用しているサードパーティパッケージについても調査し、Laravel5.6をサポートしているバージョンを使用していることを確認してください。

Symfony4

Laravelを動作させるために使用している、すべてのSymfonyコンポーネントは、Symfony ^4.0シリーズへアップグレードされました。アプリケーションで直接Symfonyコンポーネントを取り扱っている場合は、Symfonyの変更ログをレビューすべきでしょう。

PHPUnit

アプリケーションのphpunit/phpunit依存指定は、^7.0にアップグレードしてください。

配列

Arr::wrapメソッド

Arr::wrapメソッドへnullを渡すと、空の配列が返ってくるようになりました。

Artisan

optimizeコマンド

以前から非推奨になっていた、optimize Artisanコマンドは削除されました。PHP自身がOPcacheを含んだ、最近の向上により、optimizeコマンドは妥当なパフォーマンスの向上を提供できなくなりました。そのため、composer.jsonファイルのscripts項目から、php artisan optimizeを取り除いてください。

Blade

HTMLエンティティエンコーディング

以前のバージョンのLaravelでは、Blade(およびeヘルパ)は、HTMLエンティティをダブルエンコードしませんでした。これは、裏で使用しているhtmlspecialchars関数のデフォルト動作とは異なり、コンテンツのレンダリングやインラインJSONコンテンツをJavaScriptフレームワークへ渡す際に、予想外の動作を引き起こしました。

Laravel5.6では、Bladeとeヘルパはデフォルトとして、特別な文字をダブルエンコードします。これにより、裏で動作しているPHPのhtmlspecialchars関数のデフォルトと、この機能は動作が統一されました。ダブルエンコーディングを行わない、以前の振る舞いを継続したい場合は、Blade::withoutDoubleEncodingメソッドを使用します。

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * アプリケーションの全サービスの初期処理
     *
     * @return void
     */
    public function boot()
    {
        Blade::withoutDoubleEncoding();
    }
}

キャッシュ

レートリミッターのtooManyAttemptsメソッド

このメソッドの引数から、使用されていなかった$decayMinutes引数が削除されました。このメソッドを自分の実装でオーバーライドしている場合、メソッドからこの引数を削除してください。

データベース

morphsカラムのインデックス順

morphsマイグレーションメソッドにより作られるカラムのインデックスが、効率を改善するために改善されました。マイグレーションでmorphsメソッドを使用している場合は、マイグレーションのdownメッソッドを実行しようと試みると、エラーが発生します。アプリケーションが開発段階の場合は、migrate:freshコマンドを使い、初めからデータベースを構築し直してください。アプリケーションが実働している場合は、明確にmorphsメソッドにインデックス名を渡す必要があります。

MigrationRepositoryInterfaceメソッド追加

MigrationRepositoryInterfaceへ、新しくgetMigrationsBatchesメソッドが追加されました。このクラスを自分で実装するというのは、まずあり得ませんが、実装している場合は実装にこのメソッドを追加してください。フレームワークのデフォルト実装を例として参照してください。

Eloquent

getDateFormatメソッド

getDateFormatメソッドが、protectedの代わりにpublicになりました。

ハッシュ

新しい設定ファイル

ハッシュの全設定は、config/hashing.php設定ファイルへ保存されるようになりました。デフォルトの設定ファイルをアプリケーションへコピーしてください。ほとんどの場合、デフォルトドライバーとしてbcryptを継続する必要があります。しかしながら、argonもサポートされました。

ヘルパ

eヘルパ

以前のバージョンのLaravelでは、Blade(およびeヘルパ)は、HTMLエンティティをダブルエンコードしませんでした。これは、裏で使用しているhtmlspecialchars関数のデフォルト動作とは異なり、コンテンツのレンダリングやインラインJSONコンテンツをJavaScriptフレームワークへ渡す際に、予想外の動作を引き起こしました。

Laravel5.6では、Bladeとeヘルパはデフォルトとして、特別な文字をダブルエンコードします。これにより、裏で動作しているPHPのhtmlspecialchars関数のデフォルトと、この機能は動作が統一されました。ダブルエンコーディングを行わない、以前の振る舞いを継続したい場合は、eヘルパの第2引数に、falseを渡してください。

<?php echo e($string, false); ?>

ログ

新しい設定ファイル

新しいログ設定は、config/logging.php設定ファイルで全て保存されるようになりました。デフォルト設定ファイルをアプリケーションへコピーし、必要に応じて設定を調整してください。

config/app.php設定ファイルから、loglog_level設定オプションは削除されました。

configureMonologUsingメソッド

アプリケーションのために、configureMonologUsingメソッドを使用し、Monologインスタンスをカスタマイズしている場合は、customログチャンネルを作成する必要があります。カスタムチャンネル作成の詳細は、ログのドキュメントで確認してください。

ログWriterクラス

Illuminate\Log\Writerクラスは、Illuminate\Log\Loggerに名前が変更されました。アプリケーションのクラスで、このクラスをタイプヒントで明確に指定している場合は、新しい名前を参照するように変更してください。もしくは代わりに、標準化されたPsr\Log\LoggerInterfaceインターフェイスをタイプヒントで使うように、よく考慮してください。

Illuminate\Contracts\Logging\Logインターフェイス

Psr\Log\LoggerInterfaceインターフェイスと完全にダブってしまうため、このインターフェイスは削除されました。代わりに、Psr\Log\LoggerInterfaceをタイプヒントに使用してください。

メール

withSwiftMessageコールバック

Laravelの以前のリリースでは、withSwiftMessageを使用し登録した、Swiftメッセージのカスタマイズコールバックは、コンテンツが既にエンコードされ、メッセージに追加されたに呼び出されていました。これらのコールバックが、コンテンツが追加されるに呼び出されるようになり、必要に応じてエンコードや他のメッセージオプションをカスタマイズできるようになりました。

ペジネーション

Bootstrap4

ペジネータにより生成されるペジネーションリンクが、デフォルトでBootstrap4向けになりました。Bootstrap3向けに生成するように、ペジネータへ指示するには、AppServiceProviderbootメソッドから、Paginator::useBootstrapThreeメソッドを呼び出してください。

<?php

namespace App\Providers;

use Illuminate\Pagination\Paginator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * アプリケーションの全サービスの起動処理
     *
     * @return void
     */
    public function boot()
    {
        Paginator::useBootstrapThree();
    }
}

リソース

originalプロパティ

リソースレスポンスoriginalプロパティへ、JSON文字列/配列の代わりにオリジナルのモデルがセットされるようになりました。これにより、テスト時にレスポンスのモデルの検査が簡単になりました。

ルート

新しく生成されたモデルの返却

ルートから直接、新たに生成されたEloquentモデルをリターンする場合、レスポンス状態は200の代わりに、201が自動的にセットされます。アプリケーションのテストで明確に、200レスポンスを期待している場合は、201を期待するように変更する必要があります。

信頼するプロキシ

Laravelが使用しているSymfony HttpFoundationの、信頼するプロキシの機能変更により、アプリケーションのApp\Http\Middleware\TrustProxiesミドルウェアに、僅かな変更がおきました。

$headersプロパティは以前配列でしたが、様々な異なった値を受け付けるようになりました。たとえば、フォワーディングヘッダを全て信頼するには、$headersプロパティを次のように変更してください。

use Illuminate\Http\Request;

/**
 * プロキシを検出するために使用するヘッダ
 *
 * @var int
 */
protected $headers = Request::HEADER_X_FORWARDED_ALL;

$headersに指定可能な値についての詳細は、trusting proxiesのドキュメントで確認してください。

バリデーション

ValidatesWhenResolvedインターフェイス

ValidatesWhenResolvedインターフェイス/トレイトのvalidateメソッドは、$request->validate()によるコンフリクトを避けるために、validateResolvedに変更されました。

その他

laravel/laravel GitHubリポジトリで、変更を確認することも推奨します。変更の多くが必要なくても、それらのファイルを皆さんのアプリケーションで、最新版に合わせておきたいでしょう。変更のいくつかは、このアップグレードガイドで取り扱われていますが、設定ファイルやコメントの変更は取り扱っていません。変更は、GitHub比較ツールで簡単に確認できるので、どの変更が自分にとって重要か選んでください。

ドキュメント章別ページ

公式パッケージ

ヘッダー項目移動

注目:アイコン:ページ内リンク設置(リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

PDC

ページ(章)移動の左オフキャンバスオープン

HA

ヘッダー移動モーダルオープン

MS

移動/設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

NJ

次ヘッダー(H2〜H4)へ移動

BK

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる