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

重要度の高い変更

重要度が中程度の変更

5.7から5.8.0へのアップグレード

アップグレードの見積もり時間：１時間

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

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

composer.jsonファイル中のlaravel/frameworkパッケージのバージョンを5.8.*にアップデートしてください。

次に、アプリケーションで使用している３ｒｄパーティーパッケージを調査し、Laravel5.8をサポートしているバージョンを使用していることを確認してください。

Application契約

environmentメソッド

影響の可能性： とても低い

Illuminate\Contracts\Foundation\Application契約で利用法が規定されているenvironmentメソッドは変更されました。アプリケーションでこの契約を実装している場合は、メソッドの使用法を更新してください。

/**
 * アプリケーション環境の取得もしくは判定
 *
 * @param  string|array  $environments
 * @return string|bool
 */
public function environment(...$environments);

メソッド追加

影響の可能性： とても低い

bootstrapPath、configPath、databasePath、environmentPath、resourcePath、storagePath、resolveProvider、bootstrapWith、configurationIsCached、detectEnvironment、environmentFile、environmentFilePath、getCachedConfigPath、getCachedRoutesPath、getLocale、getNamespace、getProviders、hasBeenBootstrapped、loadDeferredProviders、loadEnvironmentFrom、routesAreCached、setLocale、shouldSkipMiddleware、terminateメソッドがIlluminate\Contracts\Foundation\Application契約に追加されました。

このインターフェイスを実装している可能性はとても低いと思われますが、実装している場合はこれらのメソッドを追加してください。

認証

パスワードリセット通知ルートパラメータ

影響の可能性： 低い

ユーザーがパスワードをリセットするためのリンクを必要とする場合、Laravelはpasswrod.reset名前付きルートに対するURLをrouteヘルパを利用し生成します。Laravel5.7使用時、明確な名前無しにrouteヘルパへトークンを渡してしました。

route('password.reset', $token);

Laravel5.8を使用する場合は、明確なパラメータとしてrouteヘルパへトークンを渡します。

route('password.reset', ['token' => $token]);

そのため、独自のpassword.resetルートを定義している場合、{token}パラメータを確実にURIへ含めてください。

新しいデフォルトパスワード長

影響の可能性： 高い

パスワードの選択とリセット時に要求されるパスワード長が、８文字へ変更されました。この新しい８文字長のデフォルトに合うように、アプリケーション中のバリデーションルールやロジックを変更してください。

以前の６文字長を保持する、もしくは他の長さへ変更する必要がある場合は、Illuminate\Auth\Passwords\PasswordBrokerクラスを拡張し、validatePasswordWithDefaultsメソッドをオーバーライドし、カスタムロジックを組み込んでください。

キャッシュ

持続時間が秒指定に

影響の可能性: とても高い

より細かい時間でアイテムの保存時間を扱えるように、キャッシュの保存時間は分から秒単位になりました。Illuminate\Cache\Repositoryクラスとこれを拡張したクラスのput、putMany、add、remember、setDefaultCacheTimeメソッド、並びに各キャッシュ保存のputメソッドはこの動作変更へ更新されました。詳細は、関係するPRをご覧ください。

前述のメソッドに整数値を渡している場合、キャッシュにアイテムを残したい時間が秒数になったことに留意し、コードを変更してください。言い換えれば、アイテムの期限がいつ切れるかを表すDateTimeインスタンスを渡したほうが良いでしょう。

// Laravel5.7：30分アイテムは保存される
Cache::put('foo', 'bar', 30);

// Laravel5.8：30秒アイテムは保存される
Cache::put('foo', 'bar', 30);

// Laravel5.7と5.8：30秒アイテムは保存される
Cache::put('foo', 'bar', now()->addSeconds(30));

Tip!! この変更により、Laravelキャッシュシステムは、PSR-16キャッシュライブラリ基準に完全に準拠しました。

PSR-16準拠

影響の可能性： 中程度

前記により返却値が変更されたことに付け加え、Illuminate\Cache\Repositoryクラスのput、putMany、addメソッドのTTL引数もPSR-16基準をより準拠するように変更しました。デフォルトはnullで、TTLを指定しない呼び出しの新しい振る舞いは、キャッシュアイテムを永久に保存することになりました。さらに、TTLが０か負数の場合はキャッシュから削除されます。詳細は、関連するPRをご覧ください。

KeyWrittenイベントもこの変更により、更新されました。

ロックの安全性向上

影響の可能性： 高い

バージョン5.7以前のLaravelでは、いくつかのキャッシュドライバで提供されていた「アトミックロック」機能は予測しない動作を引き起こす可能性がありました。

たとえば、クライアントAが１０秒間有効なfooロックを獲得します。クライアントAがタスクを終了するまで実際には20秒かかるとします。クライアントAの処理中に、１０秒立つとキャッシシステムのロックが自動的に解除されます。クライアントBがfooロックを獲得します。クライアントAがタスクを終了し、fooロックを解除すると、思いがけずクライアントBが獲得しているロックを解除してしまいます。クライアントCは、そのロックを獲得できるようになってしまいます。

このシナリオを避けるに、通常の環境ではロックの所有者のみがリリースできることをフレームワークが確実に行えるようにするために、「スコープトークン」を埋め込んだロックが生成されるようになりました。

ロック操作にCache::lock()->get(Closure)メソッドを使用している場合、変更は必要ありません。

Cache::lock('foo', 10)->get(function () {
    // ロックは自動的に安全な開放を行う
});

しかし、みなさんが自分でCache::lock()->release()を呼び出している場合、ロックのインスタンスを保持するようにコードを変更する必要があります。そのため、タスクを実行し終えた後、同じロックインスタンスのreleaseメソッドを呼び出してください。

if (($lock = Cache::lock('foo', 10))->get()) {
    // タスクの実行…

    $lock->release();
}

ときに、ロックをあるプロセスで獲得し、別のプロセスで開放したい場合があります。たとえば、Webリクエストでロックを獲得し、そのリクエストから起動したキュー済みジョブの最後で、ロックを開放したい場合です。そのようなシナリオでは、ジョブで渡されたトークンを使い、ロックを再インスタンス化できるように、ロックを限定する「所有者(owner)のトークン」をキューするジョブへ渡す必要があります。

// コントローラ側
$podcast = Podcast::find(1);

if (($lock = Cache::lock('foo', 120))->get()) {
    ProcessPodcast::dispatch($podcast, $lock->owner());
}

// ProcessPodcastジョブ側
Cache::restoreLock('foo', $this->owner)->release();

現在の所有者にかかわらず、ロックを開放したい場合は、forceReleaseメソッドを使用します。

Cache::lock('foo')->forceRelease();

RepositoryとStore契約

影響の可能性： とても低い

Illuminate\Contracts\Cache\Repository契約のputとforeverメソッド、およびIlluminate\Contracts\Cache\Store契約のput、putMany、foreverメソッドの返却値をPSR-16へ完全に準拠させるため、voidからboolへ変更されました。

コレクション

addメソッド

影響の可能性： とても低い

addメソッドは、Eloquentのコレクションクラスから、ベースコレクションクラスへ移動しました。Illuminate\Support\Collectionを拡張し、拡張したクラスにaddメソッドがある場合は、メソッドの用法が親クラスと一致するようにしてください。

public function add($item);

firstWhereメソッド

影響の可能性： とても低い

whereメソッドの使用法と合わせるために、firstWhereメソッドの使用法が変更されました。このメソッドをオーバーライドしている場合は、メソッドの使用方法を親クラスと合わせてください。

/**
 * 指定したキー／値ペアの最初のアイテムを取得
 *
 * @param  string  $key
 * @param  mixed  $operator
 * @param  mixed  $value
 * @return mixed
 */
public function firstWhere($key, $operator = null, $value = null);

コンソール

Kernel契約

影響の可能性： とても低い

terminateメソッドがIlluminate\Contracts\Console\Kernel契約へ追加されました。このインターフェイスを実装している場合は、このメソッドを追加してください。

コンテナ

ジェネレータとタグ付けサービス

影響の可能性： 中程度

コンテナのtaggedメソッドは、指定したタグのサービスに対し、PHPジェネレータの遅延インスタンス化を活用するようになりました。これにより、タグつけしたサービスを全部使用しない場合に、パフォーマンスの改善を達成しました。

この変更により、taggedメソッドは配列（array）の代わりに、iterableを返すようになりました。このメソッドの返却値をタイプヒントしている場合は、iterableへ確実に変更してください。

付け加えると、$container->tagged('foo')[0]のように、配列のオフセット値により直接タグ付けサービスへアクセスすることは、もうできなくなりました。

resolveメソッド

影響の可能性： とても低い

resolveメソッドは新しい論理値引数を受け取るようになりました。これはオブジェクトのインスタンス化の間に、（コールバックを解決する）イベントが発生させられるか／実行されるかを指示します。このメソッドをオーバーライドしている場合、親クラスのものと一致するようにメソッドの使用法を変更してください。

addContextualBindingメソッド

影響の可能性： とても低い

addContextualBindingメソッドが、Illuminate\Contracts\Container\Container契約に追加されました。このインターフェイスを実装している場合は、このメソッドを追加してください。

taggedメソッド

影響の可能性： 低い

taggedメソッドの使用法が変更されました。そして、配列の代わりにiterableを返すようになりました。皆さんコードの引数として、このメソッドの返却値を配列としてタイプヒントしている場合は、iterableへ変更してください。

flushメソッド

影響の可能性： とても低い

flushメソッドがIlluminate\Contracts\Container\Container契約へ追加されました。このインターフェイスを実装している場合は、このメソッドを追加してください。

データベース

クオートしないMySQL JSON値

影響の可能性： 低い

MySQLとMariaDBを使用している場合、クエリビルダはクオートしないJSON値を返すようになりました。この振る舞いは、サポートしている他のデータベースと一貫性を持たせるためです。

$value = DB::table('users')->value('options->language');

dump($value);

// Laravel5.7
'"en"'

// Laravel5.8
'en'

その結果として、->>操作子は必要なくなり、サポートされなくなりました。

SQLite

影響の可能性： 中程度

Laravel5.8がサポートする一番古いSQLiteバージョンはSQLite3.7.11です。より古いSQLiteバージョンを使用している場合は、アップデートしてください。SQLite3.8.8以上を推奨します。

マイグレーションとbigIncrements

影響の可能性： なし

Laravel5.8では、マイグレーションスタブのデフォルトとして、IDカラムにbigIncrementsを使います。以前のバージョンでは、IDカラムはincrementsメソッドを使用し、生成されていました。

これは既存のプロジェクトのコードへ、影響を与えません。しかしながら、外部キーを同じタイプにするように気を付けてください。incrementsメソッドを使用して生成されたカラムは、bigIncrementsメソッドを使って生成したカラムを参照できないためです。

Eloquent

不規則変化する複数形のモデル名

影響の可能性： 中程度

Laravel5.8では、複数後のモデル名で不規則変化する単語で終わる場合も、正しい複数形になるようになりました。

// Laravel5.7
App\Feedback.php -> feedback (正しい複数形)
App\UserFeedback.php -> user_feedbacks (間違った複数形)

// Laravel5.8
App\Feedback.php -> feedback (正しい複数形)
App\UserFeedback.php -> user_feedback (正しい複数形)

間違った複数形のモデルがある場合は、モデルの$tableプロパティを定義することにより、古いテーブル名を続けて使用できます。

/**
 * モデルと関連するテーブル
 *
 * @var string
 */
protected $table = 'user_feedbacks';

IDが増加するカスタムピボットモデル

カスタムピボットモデルを使用する多対多リレーションを定義しており、そのピボットモデルが自動増分の主キーを持つ場合、カスタムピボットモデルクラスで確実にincrementingプロパティを定義し、trueをセットしてください。

/**
 * IDが自動増分する
 *
 * @var bool
 */
public $incrementing = true;

loadCountメソッド

影響の可能性： 低い

loadCountメソッドが、ベースのIlluminate\Database\Eloquent\Modelクラスへ追加されました。皆さんのアプリケーションでもloadCountメソッドを定義している場合、Eloquentの定義と名前が衝突してしまいます。

originalIsEquivalentメソッド

影響の可能性： とても低い

Illuminate\Database\Eloquent\Concerns\HasAttributesトレイトのoriginalIsEquivalentメソッドが、protectedからpublicへ変更されました。

ソフト削除のdeleted_atプロパティの自動キャスト

影響の可能性： 低い

Illuminate\Database\Eloquent\SoftDeletesトレイトを使用しているEloquentモデルを使用している場合、deleted_atプロパティはCarbonインスタンスへ、自動的にキャストされるようになりました。この振る舞いはプロパティのカスタムアクセサを書くか、casts属性へ追加することによりオーバーライドできます。

protected $casts = ['deleted_at' => 'string'];

BelongsToのgetForeignKeyとgetOwnerKeyメソッド

影響の可能性： 低い

Laravelにより提供されている他のリレーションのメソッド名と統一するために、BelongsToのgetForeignKey、getQualifiedForeignKey、getOwnerKeyメソッドは、getForeignKeyName、getQualifiedForeignKeyName、getOwnerKeyNameへ名前が変わりました。

環境変数のパース

影響の可能性： 高い

.envファイルのパースに利用している、phpdotenvパッケージが新しいメジャーバージョンをリリースしました。そのため、envヘルパ画の戻り値に影響が起きます。クオートされていない#文字は、値の一部ではなくコメントとして扱われるようになりました。

以前の振る舞い：

ENV_VALUE=foo#bar

env('ENV_VALUE'); // foo#bar

新しい振る舞い：

ENV_VALUE=foo#bar
env('ENV_VALUE'); // foo

もとの振る舞いにするには、環境変数をクオートしてください。

ENV_VALUE="foo#bar"

env('ENV_VALUE'); // foo#bar

より詳細な情報は、phpdotenvアップグレードガイドを参照してください。

イベント

fireメソッド

影響の可能性： 低い

Laravel5.4で非推奨になっていた、Illuminate\Events\Dispatcherクラスのfireメソッドが、削除されました。 代わりに、dispatchメソッドを使用してください。

例外処理

ExceptionHandler契約

影響の可能性： 低い

shouldReportメソッドがIlluminate\Contracts\Debug\ExceptionHandler契約へ追加されました。このインターフェイスを実装している場合は、メソッドを追加してください。

renderHttpExceptionメソッド

影響の可能性： 低い

Illuminate\Foundation\Exceptions\HandlerクラスのrenderHttpExceptionメソッドの使用法が変更されました。例外ハンドラのこのメソッドをオーバーライドしている場合は、親クラスとメソッドの使い方を合わせるように変更してください。

/**
 * 渡されたHttpExceptionをレンダーする
 *
 * @param  \Symfony\Component\HttpKernel\Exception\HttpExceptionInterface  $e
 * @return \Symfony\Component\HttpFoundation\Response
 */
protected function renderHttpException(HttpExceptionInterface $e);

メール

Markdownファイルのディレクトリ変更

影響の可能性： 高い

LaravelのMarkdownメールコンポーネントをvendor:publishコマンドでリソース公開している場合は、/resources/views/vendor/mail/markdownディレクトリを/resources/views/vendor/mail/textへリネームしてください

さらに、markdownComponentPathsメソッドはtextComponentPathsへリネームされました。このメソッドをオーバーライドしている場合は、親のクラスへ合わせるようにメソッド名を変更してください。

PendingMailクラスのメソッド使用法変更

影響の可能性： とても低い

Illuminate\Mail\Mailableの代わりにIlluminate\Contracts\Mail\Mailableを受け付けるため、Illuminate\Mail\PendingMailクラスのsend、sendNow、queue、later、fillメソッドは変更されました。これらのメソッドをオーバーライドしている場合は、親クラスと使用法を合わせるように更新してください。

キュー

Pheanstalk4.0

影響の可能性： 中程度

Laravel5.8は、Pheanstalkキューライブラリの~4.0をサポートしました。皆さんのアプリケーションでPheanstalkライブラリを使用している場合は、Composerを使用し~4.0リリースへライブラリをアップグレードしてください。

Job契約

影響の可能性： とても低い

isReleased、hasFailed、markAsFailedメソッドが、Illuminate\Contracts\Queue\Job契約へ追加されました。このインターフェイスを実装してる場合は、これらのメソッドを追加してください。

Job::failedとFailingJobクラス

影響の可能性： とても低い

Laravel5.7ではキューされたジョブが失敗したときに、キューワーカはFailingJob::handleメソッドを実行していました。Laravel5.8では、FailingJobクラスに含まれていたロジックは、ジョブクラス自身のfailメソッドへそのまま移動されました。このため、Illuminate\Contracts\Queue\Job契約へfailメソッドが追加されました。

ベースのIlluminate\Queue\Jobs\Jobクラスがfailの実装を含んでも、通常のアプリケーションコードではコードの変更は必要ありません。しかし、Laravelにより提供されているベースのジョブクラスを拡張しないで、ジョブクラスを活用するカスタムキュードライバを構築している場合は、カスタムジョブクラスへfailメソッドを自分で実装する必要があります。実装の例として、Laravelのベースジョブクラスを参照してください。

この変更により、ジョブの削除過程をカスタムキュードライバがよりコントロールできるようになりました。

Redis Blocking Pop

影響の可能性： とても低い

Redisキュードライバの"blocking pop"機能の使用が安全になりました。以前は、ジョブ再取得と同時にRedisサーバかワーカがクラッシュすると、キューされたジョブを失う機会が多少ありました。Blocking popが安全になったため、各Laravelキューに対し新しいRedisは、:notifyサフィックス付けてリストします。

リクエスト

TransformsRequestミドルウェア

影響の可能性： 低い

Illuminate\Foundation\Http\Middleware\TransformsRequestミドルウェアのtransformメソッドは、入力が配列のときに「完全な」リクエスト入力キーを受け入れるようになりました。

'employee' => [
    'name' => 'Taylor Otwell',
],

/**
 * 渡された値を変形する
 *
 * @param  string  $key
 * @param  mixed  $value
 * @return mixed
 */
protected function transform($key, $value)
{
    dump($key); // 'employee.name' (Laravel5.8)
    dump($key); // 'name' (Laravel5.7)
}

ルート

UrlGenerator契約

影響の可能性： とても低い

previousメソッドが、Illuminate\Contracts\Routing\UrlGenerator契約へ追加されました。このインターフェイスを実装している場合は、メソッドを追加してください。

Illuminate\Routing\UrlGeneratorのcachedSchemaプロパティ

影響の可能性： とても低い

Laravel5.7で非推奨になっていた、Illuminate\Routing\UrlGeneratorの$cachedSchemaプロパティ名が、$cachedSchemeへ変更されました。

セッション

StartSessionミドルウェア

影響の可能性： とても低い

セッションの維持ロジックをterminate()メソッドからhandle()メソッドへ移動しました。これらのメソッドをオーバーライドしている場合は、この変更を反映するように更新してください。

サポート

ヘルパから文字列と配列クラスへ

影響の可能性： 中程度

すべてのarray_*とstr_*グローバルヘルパが、非推奨となりました。Illuminate\Support\ArrとIlluminate\Support\Strのメソッドを直接使用してください。

全ての配列と文字列のグローバル関数の後方互換性層を提供する、新しいlaravel/helpersパッケージへヘルパは移動されたため、この変更はmediumと記載しました。

遅延サービスプロバイダ

影響の可能性： 中程度

プロバイダを遅延させるかどうかを示すための、サービスプロバイダのdefer論理プロパティは、非推奨となりました。そのサービスプロバイダを遅延させるように指示するには、Illuminate\Contracts\Support\DeferrableProvider契約を実装してください。

リードオンリーenvヘルパ

影響の可能性： 低い

以前のenvヘルパは、実行時に変更された環境変数から値を取得していました。Laravel5.8から、環境変数値が変わらないように取り扱います。実行時に環境変数を変更したい場合は、configヘルパを使い取得できる設定値の使用を考慮してください。

以前の振る舞い：

dump(env('APP_ENV')); // local

putenv('APP_ENV=staging');

dump(env('APP_ENV')); // staging

新しい振る舞い：

dump(env('APP_ENV')); // local

putenv('APP_ENV=staging');

dump(env('APP_ENV')); // local

テスト

setUpとtearDownメソッド

setUpとtearDownメソッドは、voidを返却タイプとして要求するようになりました。

protected function setUp(): void
protected function tearDown(): void

PHPUnit 8

影響の可能性： 状況による

Laravel5.8ではPHPUnit7をデフォルトで使用します。しかしながら、PHP7.2以上が必要なPHPUnit8へアップグレードする選択肢もあります。詳細は、PHPUnit8のリリースアナウンスメントの変更一覧へ一通り目を通してください。

バリデーション

Validator契約

影響の可能性： とても低い

validatedメソッドが、Illuminate\Contracts\Validation\Validator契約へ追加されました。

/**
 * バリデートされた属性と値の取得
 *
 * @return array
 */
public function validated();

このインターフェイスを実装してる場合は、メソッドを追加してください。

ValidatesAttributesトレイト

影響の可能性： とても低い

Illuminate\Validation\Concerns\ValidatesAttributesトレイトのparseTable、getQueryColumn、requireParameterCountメソッドをprotectedからpublicに変更しました。

DatabasePresenceVerifierクラス

影響の可能性： とても低い

Illuminate\Validation\DatabasePresenceVerifierクラスのtableメソッドをprotectedからpublicに変更しました。

Validatorクラス

影響の可能性： とても低い

Illuminate\Validation\ValidatorクラスのgetPresenceVerifierForメソッドをprotectedからpublicに変更しました。

メールバリデーション

影響の可能性： とても低い

メールのバリデーションルールをメールがRFC6530準拠するかをチェックするようになりました。SwiftMailerが使用しているバリデーションロジックと統一しました。Laravel5.7では、emailルールはメールがRFC822を準拠しているかのみを検証していました。

これにより、Laravel5.8を使用すると以前は誤って有効でないと判断したメールを有効と判断するようになりました。（例：hej@bär.se）一般的にはバグフィックスとして考えるべきでしょう。しかしながら、これは注意の必要な互換性のない変更としてリストされています。この変更により、問題が起きたらお知らせください。

ビュー

getDataメソッド

影響の可能性： とても低い

getDataメソッドが、Illuminate\Contracts\View\View契約へ追加されました。このインターフェイスを実装している場合は、メソッドを追加してください。

通知

Nexmo／Slack通知チャンネル

影響の可能性： 高い

NexmoとSlackの通知チャンネルをファーストパーティパッケージとして独立させました。これらのチャンネルをアプリケーションで使用する場合は、以下のパッケージをインストールしてください。

composer require laravel/nexmo-notification-channel
composer require laravel/slack-notification-channel

その他

laravel/laravelのGitHubリポジトリで、変更を確認することをおすすめします。これらの変更は必須ではありませんが、皆さんのアプリケーションではファイルの同期を保つほうが良いでしょう。変更のいくつかは、このアップグレードガイドで取り扱っていますが、設定ファイルやコメントなどの変更は取り扱っていません。変更は簡単にGitHubの比較ツールで閲覧でき、みなさんにとって重要な変更を選択できます。