4.3 移行ガイド
CakePHP 4.3 は 4.0 からのAPI互換アップグレードです。 このページでは、4.3で追加された非推奨事項と機能の概要を説明します。
4.3.0へのアップグレード
CakePHP 4.3.0にアップグレードするには、次の Composer コマンドを実行してください。:
php composer.phar require --update-with-dependencies "cakephp/cakephp:^4.3"
非推奨
4.3では、いくつかの非推奨機能が導入されています。 これらの機能はすべて 4.x の間は継続されますが、5.0 で削除されます。 非推奨機能の更新を自動化するには、 upgrade tool を使用します。:
text
bin/cake upgrade rector --rules cakephp43 <path/to/app/src>NOTE
これはCakePHP 4.3の変更点のみを更新します。CakePHP 4.2の変更を最初に適用していることを確認してください。
新しい設定オプションが追加され、パスごとに非推奨を無効にすることができるようになりました。 詳細は Deprecation Warnings を参照してください。
Connection
Connection::supportsDynamicConstraints()は非推奨となりました。 フィクスチャが動的に制約を削除したり作成したりしないようになったためです。
Controller
Controller.shutdownコンポーネントのイベントコールバックの名前がshutdownからafterFilterに変更されました。これにより、コールバックの一貫性が高まりました。
Database
- 可変のdatetimeクラスを
DateTimeTypeやその他の時間関連の型クラスで使用することは、非推奨となります。 そのため、他の型クラスのメソッドであるDateTimeType::useMutable(),DateTimeType::useImmutable()や 同様のメソッドは非推奨となります。 DriverInterfaceで定義された機能定数を受け付けるDriverInterface::supports()を採用しているDriverInterface::supportsQuoting()およびDriverInterface::supportSavepoints()は現在、非推奨となっています。DriverInterface::supportsDynamicConstraints()は、フィクスチャが動的な制約の削除、作成を試みないため、非推奨となりました。
I18n
- datetime クラスの
TimeとDateは非推奨です。 代わりに、不変的な代替クラスであるFrozenTimeとFrozenDateを使用してください。
Log
FileLogは、dateFormat設定オプションをDefaultFormatterに移動しました。ConsoleLogは、dateFormat設定オプションをDefaultFormatterに移動しました。SyslogLogでは、format設定オプションをLegacySyslogFormatterに移動しました。 現在のデフォルトはDefaultFormatterです。
Middleware
- "ダブルパス"のミドルウェア、つまり、
__invoke($request, $response, $next)メソッドを持つクラスは非推奨です。 代わりに、function($request, $handler)というシグネチャを持つClosureや、PsrhttpHttpServer\MiddlewareInterfaceを実装したクラスを使用してください。
Network
Socket::$connectedは非推奨です。代わりにisConnected()を使用してください。Socket::$descriptionは非推奨です。Socket::$encryptedは非推奨です。代わりにisEncrypted()を使用してください。Socket::$lastErrorは非推奨です。代わりにlastError()を使用してください。
ORM
ModelAwareTrait::loadModel()は非推奨です。 代わりに、新しいLocatorAwareTrait::fetchTable()を使用してください。 例えば、コントローラではデフォルトのテーブルインスタンスを取得するために$this->fetchTable()を実行することもできますし、 デフォルト以外のテーブルを取得するには$this->fetchTable('Foos')を使用することもできます。- クエリをプロキシするすべての
ResultSetInterfaceメソッド（`CollectionInterfaceを含む） （これらは強制的に結果を取得し、その結果に対してプロキシされたメソッドを呼び出します）は非推奨になりました。 非推奨な使い方の例として、 $query->combine('id', 'title'); があります。 これを $query->all()->combine('id', 'title');` に変更する必要があります。 - バリデータオブジェクトを
Table::save()のvalidateオプションに渡すことは、非推奨です。 バリデーターはテーブルクラス内で定義するか、代わりにsetValidator()を使用してください。 Association::setName()は非推奨です。 アソシエーション名は、アソシエーションが存在するときに定義されるべきです。QueryExpression::addCase()は非推奨です。代わりにcase()を使用してください。 また、['value' => 'literal']および['column' => 'identifier']の構文は、新しい流暢なケースビルダーではサポートされていません。
Routing
:controllerのようなコロンの付いたルートプレースホルダーは非推奨です。 代わりに{controller}のような波括弧付きのプレースホルダーを使用してください。
TestSuite
TestFixture::$fieldsとTestFixture::$importは非推奨です。 アプリケーションを new fixture system に変換する必要があります。TestCase::$dropTablesは非推奨です。 テスト実行中にテーブルを削除することは 新しいマイグレーションやスキーマダンプベースのフィクスチャとは互換性がなく、5.0では削除されます。
View
- FormHelperメソッドの非関連性オプション（例：
['disabled']）は非推奨となりました。 ViewBuilder::setHelpers()の第2引数$mergeは非推奨となり、 専用のViewBuilder::addHelpers()メソッドを使うことで、マージと上書きの操作が明確に分離できるようになりました。
Behaviorの変更
以下の変更はどのメソッドのシグネチャも変更しませんが、メソッドのセマンティクスや動作を変更します。
Collection
- 同一の実装で、
$preserveKeysパラメータを$keepKeysに名称変更しました。
Command
cake i18n extractには--relative-pathsオプションがなくなりました。 このオプションはデフォルトでオンになっています。
Core
Configure::load()は、無効な設定エンジンが使用されている場合、例外を発生させるようになりました。
Database
ComparisonExpressionは、生成されたIdentifierExpressionのsqlを()でラップしなくなりました。 これはQuery::where()や、その他のComparisonExpressionが生成される場所に影響します。
Datasource
ConnectionManager::alias()の$aliasと$sourceのパラメータ名を、それぞれの内容に合わせて変更しました。 これはドキュメントと名前付きパラメータにのみ影響します。
Http
Http\Clientは、ini_get('user_agent')で 'CakePHP' を ユーザーエージェントのフォールバックとして使用するようになりました。
ORM
Entity::isEmpty()とEntity::hasValue()を、'0'を空でない値として扱うように調整しました。 これにより、ドキュメントや本来の意図に沿った動作となります。TranslateBehaviorのエンティティ検証エラーは、{lang}ではなく_translations.{lang}のパスに設定されるようになりました。 これにより、エンティティエラーのパスが、リクエストデータに使用されるフィールドと同じになります。 一度に複数の翻訳を変更するフォームがある場合は、検証エラーの表示方法を更新する必要があるかもしれません。- カラムを選択する際に、カラムに設定されているデフォルトの型よりも関数式で指定された型が優先されるようになりました。 例えば、
$query->select(['id' => $query->func()->min('id')])を使うと、 取得したエンティティの id の値は、`integer` ではなく float になります。
Routing
Router::connect(),Router::prefix(),Router::plugin(),Router::scope()は非推奨です。 代わりに、対応する非静的なRouteBuilderメソッドを使用してください。RouteBuilder::resources()は、'braced' プレースホルダーを使用するルートを生成するようになりました。
TestSuite
TestCase::deprecated()は、コールバックによって 少なくとも1つのdeprecation warningが発生したことをアサートするようになりました。
Validation
Validator::setProvider()は、オブジェクトでも文字列でもないプロバイダ名が使用された場合、 例外を発生させるようになりました。 これまでは、エラーは発生しませんでしたが、そのプロバイダも動作しませんでした。
View
ViewBuilder::build()の$varsパラメータは非推奨です。 代わりにsetVar()を使用してください。HtmlHelper::script()とHtmlHelper::css()は、スキームを含む絶対URLをエスケープするようになりました。
破壊的変更
API の背後に、対応が必要ないくつかの破壊的変更があります。 これらの変更は通常、テストにのみ影響します。
Log
BaseLog::_getFormattedDate()とdateFormatの設定が削除されました。 メッセージのフォーマットロジックがログフォーマッタに移されたためです。
View
TimeHelper::fromString()は、TimeではなくFrozenTimeのインスタンスを返すようになりました。
新機能
Controller
Controller::middleware()が追加され、単一のコントローラに対してのみミドルウェアを定義することができるようになりました。 詳しくは Controller Middleware をご覧ください。- コントローラでは、アクションパラメータに
float,int,bool,arrayのいずれかの型宣言をサポートするようになりました。 ブール型で渡されるパラメータは、0か1のどちらかでなければなりません。
Core
deprecationWarning()は、重複した通知を出さなくなりました。代わりに 最初に表示されるようになりました。 これにより、テスト出力の読みやすさ これにより、テスト出力の可読性が向上し、HTMLの文脈での視覚的ノイズも改善されます。app_local.phpで、Error.allowDuplicateDeprecationsをtrueに設定することで、 重複した通知出力を復元することができます。- CakePHP の
league/containerへの依存度が^4.1.1に変更されました。 DIコンテナは実験的とされていますが、このアップグレードにより、 サービスプロバイダーの定義のアップグレードが必要になる可能性があります。
Database
- データベースマッピングタイプは、カラムのSQL生成とカラムスキーマの反映を指定するために、
Cake\Database\SchemaAwareInterfaceを実装できるようになりました。 これにより、カスタムタイプで非標準のカラムを扱うことができます。 - ログに記録されるクエリは、postgres、sqlite、mysql の各ドライバで
TRUEとFALSEを使用するようになりました。 これにより、クエリをコピーして対話型プロンプトで実行することが容易になりました。 DateTimeTypeでは、リクエストデータをユーザーのタイムゾーンから アプリケーションのタイムゾーンに変換できるようになりました。 詳しくは Converting Request Data From User Timezone をご覧ください。JsonType::setEncodingOptions()が追加されました。 このメソッドでは、データを永続化する際にORMがJSONをシリアライズする際のjson_encode()オプションを定義することができます。- すべての機能チェックをひとつの関数にまとめた
DriverInterface::sets()を追加しました。 ドライバーは、カスタム機能名、または 機能 constants: の定数のいずれかをサポートします。FEATURE_CTEFEATURE_JSONFEATURE_QUOTEFEATURE_SAVEPOINTFEATURE_WINDOW
PDO::inTranaction()が返すステータスを反映するDriverInterface::inTransaction()を追加しました。CASE, WHEN, THEN文のための流暢なビルダーが追加されました。
Form
Form::execute()に$optionsパラメータが追加されました。 このパラメータは、どのバリデータを適用するかを選択したり、バリデーションを無効にするために使用できます。Form::validate()に$validatorパラメータが追加され、適用するバリデーションセットを選択できるようになりました。 このパラメータは、適用されるバリデーションセットを選択します。
Http
CspMiddlewareは、cspScriptNonceとcspStyleNonceのリクエスト属性を設定するようになり、 厳格なコンテンツセキュリティポリシーの採用を効率化しました。Client::addMockResponse()とclearMockResponses()が追加されました。
Log
- ログエンジンは、書き込む前にメッセージ文字列をフォーマットするためにフォーマッタを使用するようになりました。 これは
formatter設定オプションで設定できます。 詳細は Logging Formatters のセクションを参照してください。 JsonFormatterが追加され、任意のログエンジンのformatterオプションとして設定できるようになりました。
ORM
- HasManyおよびBelongsToManyのアソシエーションを
contain()するクエリは、 結果キャストのステータスを伝搬するようになりました。 これにより、すべてのアソシエーションからの結果は、タイプマッピングオブジェクトでキャストされるか、 まったくキャストされないかのいずれかになります。 Tableでは、displayFieldのデフォルトの候補となるフィールドのリストにlabelが含まれるようになりました。- nullを許容するカラムに対して、
Query::whereNotInListOrNull()とQueryExpression::notInOrNull()を追加しました。 なぜなら、null != valueは常にfalseであり、カラムがnullの場合、NOT INのテストは常に失敗するからです。 LocatorAwareTrait::fetchTable()が追加されました。 これにより、$this->fetchTable()を使って、コントローラ、コマンド、メーラー、セルなどの traitを使ったクラスのテーブルインスタンスを取得することができます。LocatorAwareTrait::$defaultTableプロパティを設定することで、デフォルトのテーブルエイリアスを指定することができます。
TestSuite
IntegrationTestTrait::enableCsrfToken()において、 カスタムのCSRFクッキー/セッションキー名を使用できるようになりました。- HTTPモックを簡単に書けるように
HttpClientTraitを追加しました。 詳細は Httpclient Testing を参照してください。 - 新しいフィクスチャシステムが導入されました。 このフィクスチャシステムはスキーマとデータを分離し、既存のマイグレーションを再利用してテストスキーマを定義することができます。 アップグレードの方法は Fixture Upgrade ガイドで説明しています。
View
HtmlHelper::script()とHtmlHelper::css()は、cspScriptNonceとcspStyleNonceのリクエスト属性が存在する場合、 生成されたタグにnonce属性を追加するようになりました。FormHelper::control()はバリデータのメタデータに基づいてaria-invalid,aria-required,aria-describedby属性を生成するようになりました。 自動ラベル要素を無効にしてプレースホルダーを提供した場合には、aria-label属性が設定されます。ViewBuilder::addHelpers()が追加され、マージと上書きの操作が明確に分離されました。