3.3 移行ガイド

CakePHP 3.3 は、3.2 の API の完全上位互換です。 このページでは、3.3 の変更と改善についてのアウトラインを紹介します。

非推奨

  • Router::mapResources() は非推奨になりました。ルーティングスコープと $routes->resources() を代わりに使用してください。

  • Router::redirect() は非推奨になりました。ルーティングスコープと $routes->redirect() を代わりに使用してください。

  • Router::parseNamedParams() は非推奨になりました。 名前付きパラメーターの後方互換性は 4.0.0 で削除されます。

  • Cake\Http\Client\Response の以下のメソッドは PSR-7 インターフェイスメソッドと 重複しているため非推奨になりました。

    • statusCode() の代わりに getStatusCode() を使用してください。

    • encoding() の代わりに getEncoding() を使用してください。

    • header() の代わりに getHeaderLine() を使用してください。

    • cookie() の代わりに getCookie() を使用してください。

    • version() の代わりに getProtocolVersion() を使用してください。

  • ディスパッチャーフィルターは、非推奨になりました。 代わりに ミドルウェア を使用してください。

  • RequestActionTrait は非推奨になりました。 代わりに ビューセル を使用するようにあなたのコードを修正してください。

  • PHP 7.1 で mcrypt 拡張が非推奨なため、 Cake\\Utility\\Crypto\\Mcrypt エンジンは非推奨になりました。代わりに opensslCake\Utility\Crypto\Openssl を使用してください。

振る舞いの変更

以下の変更は、API 互換性はありますが、あなたのアプリケーションに 影響を及ぼし得る振る舞いのわずかな差異があります。

  • Date と DateTime インスタンスのデフォルトの JSON エンコード形式は、 ISO-8601 です。これは、タイムゾーンの値に : が含まれていることを意味します。 例: 2015-11-06T00:00:00+03:00

  • Controller::referer() は、アプリケーションのローカル URL を生成するときに、 一貫して、アプリケーションのベースパスを省略します。 URL 配列はそうではありませんでしたが、以前の URL 文字列は、 ベースパスを前に付けなければなりませんでした。

  • デフォルトで ErrorController は、 AppController を継承しないため、 AuthSecurity コンポーネントを無効にしなくなりました。 もし、イベントを経由してこれらのコンポーネントを有効にしていたら、 コードを更新する必要があります。

  • Entity::clean は、元の値を削除し、保存時にクリアします。この振る舞いには、 保存の後にエンティティーの元の状態が維持されるべきではなく、代わりに、エンティティーの 新しい状態を反映するべきであるというバグがありました。

PSR-7 ミドルウェアのサポート追加

ディスパッチャーフィルターの非推奨と並行して、PSR-7 ミドルウェアのサポートが 追加されました。ミドルウェアは、CakePHP 3.3.0 のオプトインのコンポーネントである 新しい HTTP スタックの一部です。新しい HTTP スタックを使用することで、 次のような機能を利用することができます。

  • CakePHP の外部プラグイン、およびライブラリーからミドルウェアを使用。

  • Http\Client から取得したレスポンスとあなたのアプリケーションが 生成したレスポンスの両方で同じレスポンスオブジェクトのメソッドを利用。

  • エラー処理やアセットの配信によって送信されたレスポンスオブジェクトを 拡張することができます。

詳細と既存のアプリケーションへの新しい HTTP スタックの追加方法は、 ミドルウェア の章と 既存アプリケーションへの新しい HTTP スタック追加 セクションを ご覧ください。

Http Client は PSR-7 互換

Cake\Network\Http\ClientCake\Http\Client に移動しました。 そのリクエストとレスンポンスオブジェクトは PSR-7 インターフェイス を実装しています。 Cake\Http\Client\Response の幾つかのメソッドは非推奨です。 詳細は、上記をご覧ください。

ORM の改善

  • 複雑なデータ型をマッピングするために追加サポートが 追加されています。これは、SQL クエリー内の文字列で 表すことができない地理空間の型およびデータでの動作を 簡単にします。詳細は、 独自データ型から SQL 表現への変換 セクションをご覧ください。

  • 新しく JsonType が追加されました。この新しい型は、 MySQL と Postgres の中で使用可能なネイティブの JSON 型を 使用することができます。他のデータベースプロバイダでは、 json 型は TEXT のカラムにマップされます。

  • Association::unique() が追加されました。このメソッドは、 対象のテーブルの unique() メソッドを中継しますが、 アソシエーション条件が適用されることを保証します。

  • isUnique ルールはアソシエーション条件を適用します。

  • エンティティーが JSON に変換された場合、関連オブジェクトは、 もはや最初の toArray() を使用して配列に変換されません。 代わりに、 jsonSerialize() メソッドは、すべての関連する エンティティー上で呼び出されます。これは、エンティティーの JSON 表現で どのプロパティーが公開されているか、より多くの柔軟性と制御を提供します。

  • Table::newEntity()Table::patchEntity() は、 'associated' キーの中で未知のアソシエーションがあるとき例外が発生します。

  • RulesChecker::validCount() が追加されました。この新しいメソッドは、 エンティティーが持つ関連するレコードの数にルールを適用することができます。

  • existsIn ルールに allowNullableNulls オプションが追加されました。 このオプションは、いくつかのカラムが null である場合にルールを 通過することができます。

  • 翻訳されたレコードの保存がシンプルになりました。詳しくは、 複数の翻訳を保存 をご覧ください。

マルチページネーションのサポート追加

単一のコントローラーのアクション/ビューテンプレートに 複数のクエリーで paginate することができます。 詳細は、 複数クエリーのページネーション セクションをご覧ください。

キャッシュシェルの追加

CLI 環境でキャッシュデータをよりよく管理するために、 シェルコマンドで、キャッシュデータを消去するための方法が 追加されました。

// 一つの設定のキャッシュをクリア
bin/cake cache clear <configname>

// すべての設定のキャッシュをクリア
bin/cake cache clear_all

FormHelper

  • FormHelper は自動的にデータベースのカラムで定義された デフォルト値をフィールドのデフォルト値を設定します。 schemaDefault オプションを false に設定することで、 この動作を無効にすることができます。

Validation

  • Validator::requirePresence(), Validator::allowEmpty() そして Validator::notEmpty() フィールドのリストを受け入れます。 これで、より簡潔に必要なフィールドを定義することができます。

StringTemplate

StringTemplate::format() は 、リクエストされたテンプレートが 見つからない場合、 null を返す代わりに例外をスローします。

その他の機能強化

  • Collection::transpose() が追加されました。このメソッドは、 行と列が同じ長さの行列の行と列を入れ替えることができます。

  • デフォルトで ErrorController は、エラーページで コンテンツタイプのネゴシエーションに必要な Accept ヘッダーを 有効にするために RequestHandlerComponent をロードします。

ルーティング

  • Router::parse(), RouteCollection::parse() そして Route::parse() は、 $method 引数が追加されました。 デフォルトは、'GET' です。この新しいパラメーターは、 グローバルな状態への依存と、 PSR-7 に必要な動作の統合を削減します。

  • リソースルートを構築する場合、プレフィックスを定義することができます。 ネストされたリソースの特別なコントローラーを作成するために、 ネストされたリソースを定義するときに便利です。

  • ディスパッチャーフィルターは、非推奨になりました。 代わりに ミドルウェア を使用してください。

コンソール

  • CLI から直接起動されるシェルタスクは、もはや _welcome メソッドは呼び出されません。 それらは、 requested パラメーターセットを持つことになります。

  • Shell::err() は、テキストに「error」スタイルを適用します。 デフォルトのスタイルは、赤色のテキストです。

リクエスト

  • Request::is()Request::addDetector() は検出器における 追加の引数をサポートしています。これは、検出器の callable で、 追加のパラメーターを操作することができます。

デバッグ関数

  • pr(), debug(), そして pj() 関数は、ダンプされた値を返します。 これは、戻り値に使用することがより簡単になります。

  • dd() は、実行を完全に停止するために追加されました。