From afff13177309b5dc041fc4c8442f26f0e2c2a0e6 Mon Sep 17 00:00:00 2001 From: tamurayk Date: Sat, 28 Jun 2025 19:42:23 +0900 Subject: [PATCH] update ja docs about appendices --- ja/appendices/5-0-migration-guide.rst | 9 +- ja/appendices/5-1-migration-guide.rst | 162 ++++++++++++++++++++++++++ ja/appendices/5-2-migration-guide.rst | 110 +++++++++++++++++ ja/appendices/migration-guides.rst | 4 +- 4 files changed, 282 insertions(+), 3 deletions(-) create mode 100644 ja/appendices/5-1-migration-guide.rst create mode 100644 ja/appendices/5-2-migration-guide.rst diff --git a/ja/appendices/5-0-migration-guide.rst b/ja/appendices/5-0-migration-guide.rst index 532a3ebd3b..f64ab5b1d5 100644 --- a/ja/appendices/5-0-migration-guide.rst +++ b/ja/appendices/5-0-migration-guide.rst @@ -43,8 +43,8 @@ CakePHP 5.0 には、破壊的な変更が含まれており、4.x リリース Auth ---- -- `Auth` は削除されました。代わりにプラグイン `cakephp/authentication `__ および - `cakephp/authorization `__ をお使い下さい。 +- `Auth` は削除されました。代わりに `cakephp/authentication `__ および + `cakephp/authorization `__ プラグインを使用してください。 Cache ----- @@ -63,6 +63,9 @@ Console - ``BaseCommand::__construct()`` は削除されました。 - ``ConsoleIntegrationTestTrait::useCommandRunner()`` は、もはや必要無いため削除されました。 - ``Shell`` は削除されました。代わりに `Command `__ をお使い下さい。 +- ``ConsoleOptionParser::addSubcommand()`` は ``Shell`` の削除とともに削除されました。 + サブコマンドは ``Command`` クラスで置き換えてください。 + 必要なコマンド名は ``Command::defaultName()`` を実装することで定義できます。 - ``BaseCommand`` は ``execute()`` メソッドがフレームワークから呼び出される前後に ``Command.beforeExecute`` および ``Command.afterExecute`` のイベントを発行するようになりました。 @@ -145,6 +148,8 @@ I18n - ``FrozenDate`` は `Date` に名称変更され、また ``FrozenTime`` も `DateTime` に名称変更されました。 - ``Time`` は ``Cake\Chronos\ChronosTime`` を継承するようになりました。その結果として変更不可能(immutable)になりました。 +- ``Date`` オブジェクトは ``DateTimeInterface`` を継承しなくなりました。そのため、 ``DateTime`` オブジェクトと比較することはできません。 + 詳細は `cakephp/chronos のリリースドキュメント `__ を参照してください。 - ``Date::parseDateTime()`` は削除されました。 - ``Date::parseTime()`` は削除されました。 - ``Date::setToStringFormat()`` および ``Date::setJsonEncodeFormat()`` は、配列を受け付けないようになりました。 diff --git a/ja/appendices/5-1-migration-guide.rst b/ja/appendices/5-1-migration-guide.rst new file mode 100644 index 0000000000..3fe70b060a --- /dev/null +++ b/ja/appendices/5-1-migration-guide.rst @@ -0,0 +1,162 @@ +5.1 移行ガイド +################### + +5.1.0 リリースは 5.0 と後方互換性があります。 +新機能が追加され、新たな非推奨機能が導入されます。 +5.x で非推奨とされた機能は 6.0.0 で削除されます。 + +動作の変更 +================ + +- Connectionは、設定に ``read`` または ``write`` キーが存在する場合、その値に関係なく一意の読み取りおよび書き込みドライバーを作成するようになりました。 +- FormHelper は、 ``required`` 属性が設定されている入力要素に対して ``aria-required`` 属性を生成しなくなりました。 + これらの要素では ``aria-required`` 属性は冗長であり、HTML のバリデーション警告を引き起こします。 + スタイリングやスクリプトで ``aria-required`` 属性を使用している場合は、アプリケーションを更新する必要があります。 +- 重複した名前でアソシエーションを追加しようとすると例外が発生するようになりました。 + 必要に応じて ``$table->associations()->has()`` を使って条件付きでアソシエーションを定義できます。 +- テキストユーティリティおよび TextHelper の省略や最大長に関するメソッドは、 + ``...`` の代わりに UTF-8 文字の ``ellipsis`` を使用するようになりました。 +- ``TableSchema::setColumnType()`` は、指定したカラムが存在しない場合に例外をスローするようになりました。 +- ``PluginCollection::addPlugin()`` は、同じ名前のプラグインがすでに追加されている場合に例外をスローするようになりました。 +- ``TestCase::loadPlugins()`` は、以前にロードされたプラグインをすべてクリアするようになりました。 + そのため、以降のテストで必要なすべてのプラグインを指定する必要があります。 +- ``groups`` を使用する ``Cache`` 設定用のハッシュアルゴリズムが変更されました。 + すべてのキーに対して新しいグループプレフィックスのハッシュが生成されるため、キャッシュミスが発生します。 + 完全にコールドキャッシュとなるのを避けるため、段階的なデプロイを検討してください。 +- ``FormHelper::getFormProtector()`` は、従来の型に加えて ``null`` を返すようになりました。 + これにより動的なビューコードがエラーになりにくくなりますが、ほとんどのアプリケーションには影響しません。 +- ``Table::findList()`` の ``valueSeparator`` のデフォルト値が ``;`` から半角スペースに変更されました。 +- ``ErrorLogger`` は ``Psr\Log\LogTrait`` を使用するようになりました。 +- ``Database\QueryCompiler::$_orderedUnion`` は削除されました。 + +非推奨 +============ + +I18n +---- + +- ``_cake_core_`` キャッシュ設定キーは ``_cake_translations_`` に変更されました。 + +Mailer +------ + +- ``Mailer::setMessage()`` は非推奨となりました。このメソッドは直感的でない動作をし、利用頻度も非常に低いためです。 + + +新機能 +============ + +Cache +----- + +- ``RedisEngine`` で Redis への TLS 接続を有効にする ``tls`` オプションがサポートされるようになりました。。 + ``ssl_ca``、``ssl_cert``、``ssl_key`` オプションを使用して Redis 用の TLS コンテキストを定義できます。 + +Command +------- + +- ``bin/cake plugin list`` が追加され、利用可能なすべてのプラグイン、そのロード設定、およびバージョンを一覧表示できるようになりました。 +- オプションの ``Command`` 引数に ``default`` 値を指定できるようになりました。 +- ``BannerHelper`` が追加されました。このコマンドヘルパーは、テキストをカラフルな背景と余白付きのバナーとして整形できます。 +- ``ConsoleOutput`` に ``info.bg``、``warning.bg``、``error.bg``、``success.bg`` のデフォルトスタイルが追加されました。 + +Console +------- + +- ``Arguments::getBooleanOption()`` および ``Arguments::getMultipleOption()`` が追加されました。 +- ``Arguments::getArgument()`` は、未知の引数名が指定された場合に例外をスローするようになりました。 + これにより、オプション名と引数名の混同を防ぐことができます。 + + +Controller +---------- + +- コンポーネントでも、コントローラやコマンドと同様に、DIコンテナを使用して依存関係を解決し、コンストラクタの引数として受け取れるようになりました。 + +Core +---- + +- ``PluginConfig`` が追加されました。このクラスを使用すると、利用可能なすべてのプラグイン、そのロード設定、およびバージョンを取得できます。 +- ``toString``、 ``toInt``、 ``toBool`` 関数が追加されました。これらの関数は、リクエストデータや他の入力値を型安全にキャストし、変換に失敗した場合は ``null`` を返します。 +- ``pathCombine()`` が追加され、重複や末尾のスラッシュを気にせずパスを組み立てられるようになりました。 +- ``BaseApplication`` および ``BasePlugin`` クラスに新しい ``events`` フックが追加されました。 + このフックは、アプリケーションのグルーバルイベントリスナーを登録する推奨方法です。詳しくは :ref:`Registering Listeners ` を参照してください。 + +Database +-------- + +- ``point``、 ``linestring``、 ``polygon``、 ``geometry`` 型のサポートが追加されました。 + これらの型は地理空間やデカルト座標を扱う際に便利です。SQLite のサポートは内部的にテキストカラムを使用しており、 + データを地理空間値として操作するための関数はありません。 +- ``SelectQuery::__debugInfo()`` に、クエリがどのコネクションロール用のものかが含まれるようになりました。 +- ``SelectQuery::intersect()`` および ``SelectQuery::intersectAll()`` が追加されました。 + これらのメソッドにより、 ``INTERSECT`` および ``INTERSECT ALL`` 結合を使用したクエリを記述できるようになりました。 +- ``intersect``、 ``intersect-all``、および ``set-operations-order-by`` 機能がサポートされるようになりました。 +- 4.x に存在したバッファリングなしでレコードを取得する機能が復活しました。 + ``SelectQuery::enableBufferedResults()``、` `SelectQuery::disableBufferedResults()``、 + ``SelectQuery::isBufferedResultsEnabled()`` メソッドが再追加されました。 + +Datasource +---------- + +- ``RulesChecker::remove()``、 ``removeCreate()``、 ``removeUpdate()``、および + ``removeDelete()`` メソッドが追加されました。これらのメソッドにより、ルールを名前で削除できるようになりました。 + + +Http +---- + +- ``SecurityHeadersMiddleware::setPermissionsPolicy()`` が追加されました。このメソッドにより、``permissions-policy`` ヘッダー値を定義できるようになりました。 +- ``Client`` はリクエスト送信時に ``HttpClient.beforeSend`` および ``HttpClient.afterSend`` イベントを発火するようになりました。 + これらのイベントを利用して、ログ記録、キャッシュ、テレメトリ収集などを行うことができます。 +- ``Http\Server::terminate()`` が追加されました。 + このメソッドは ``Server.terminate`` イベントを発火し、fastcgi 環境ではレスポンス送信後にロジックを実行できます。 + その他の環境では ``Server.terminate`` イベントはレスポンス送信 *前* に実行されます。 + +I18n +---- + +- ``Number::formatter()`` および ``currency()`` は、丸め方法を上書きする ``roundingMode`` オプションを受け付けるようになりました。 +- ``toDate`` および ``toDateTime`` 関数が追加されました。これらの関数は、リクエストデータや他の入力値を型安全にキャストし、変換に失敗した場合は ``null`` を返します。 + +ORM +--- + +- アソシエーションのファインダークエリで ``preserveKeys`` オプションを設定できるようになりました。 + これにより、 ``formatResults()`` と組み合わせて、アソシエーションのファインダー結果を連想配列として返すことができます。 +- 名前に ``json`` を含む SQLite カラムを ``JsonType`` にマッピングできるようになりました。 + この機能は現時点ではオプトインであり、アプリで ``ORM.mapJsonTypeForSqlite`` 設定値を ``true`` にすることで有効になります。 + +TestSuite +--------- + +- CakePHP およびアプリのテンプレートは PHPUnit ``^10.5.5 || ^11.1.3"`` を使用するように更新されました。 +- ``ConnectionHelper`` のメソッドがすべて static になりました。このクラスは状態を持たず、メソッドが static に更新されました。 +- ``LogTestTrait`` が追加されました。この新しいトレイトにより、テスト内でログを簡単にキャプチャし、ログメッセージの有無をアサートできるようになりました。 +- ``IntegrationTestTrait::replaceRequest()`` が追加されました。 + +Utility +------- + +- ``Hash::insert()`` および ``Hash::remove()`` は、 ``array`` データに加えて ``ArrayAccess`` オブジェクトも受け付けるようになりました。 + +Validation +---------- + +- ``Validation::enum()`` および ``Validator::enum()`` が追加されました。これらのバリデーションメソッドにより、Backed Enum 値の検証が簡単になりました。 +- ``Validation::enumOnly()`` および ``Validation::enumExcept()`` が追加されました。これらのメソッドにより、特定のケースの検証や、Backed Enum 値のバリデーションをさらに簡単に行うことができます。 + +View +---- + +- View cells は、アクションの前後で ``Cell.beforeAction`` および ``Cell.afterAction`` イベントを発火するようになりました。 +- ``NumberHelper::format()`` は、丸め方法を上書きする ``roundingMode`` オプションを受け付けるようになりました。 + +Helpers +------- + +- ``TextHelper::autoLinkUrls()`` に、リンクラベルの表示を改善するためのオプションが追加されました: + * ``stripProtocol``: リンク先の先頭から ``http://`` や ``https://`` を取り除きます。デフォルトは無効です。 + * ``maxLength``: リンクラベルの最大長を指定します。デフォルトは無効です。 + * ``ellipsis``: リンクラベルの末尾に付加する文字列です。デフォルトはUTF8バージョンです。 +- ``HtmlHelper::meta()`` で ``meta('csrfToken')`` を使うことで、現在の CSRF トークンを含む meta タグを生成できるようになりました。 diff --git a/ja/appendices/5-2-migration-guide.rst b/ja/appendices/5-2-migration-guide.rst new file mode 100644 index 0000000000..51a85cda8b --- /dev/null +++ b/ja/appendices/5-2-migration-guide.rst @@ -0,0 +1,110 @@ +5.2 移行ガイド +################### + +5.2.0 リリースは 5.0 と後方互換性があります。 +新機能が追加され、新たな非推奨機能が導入されます。 +5.x で非推奨とされた機能は 6.0.0 で削除されます。 + +動作の変更 +================ + +- ``ValidationSet::add()`` は、すでに定義されている名前でルールが追加された場合にエラーを発生させるようになりました。 + この変更は、ルールが誤って上書きされるのを防ぐことを目的としています。 +- ``Http\Session`` は、無効なセッション・プリセットが使用された場合に例外を発生させるようになりました。 +- ``FormProtectionComponent`` は、 ``Cake\Controller\Exception\FormProtectionException`` を発生させるようになりました。 + このクラスは ``BadRequestException`` のサブクラスであり、ログからフィルタリングできる利点があります。 +- ``NumericPaginator::paginate()`` は、 ``SelectQuery`` インスタンスが渡された場合でも ``finder`` オプションを使用するようになりました。 + +非推奨 +============ + +Console +------- + +- ``Arguments::getMultipleOption()`` は非推奨になりました。代わりに ``getArrayOption()`` を使用してください。 + +Datasource +---------- + +- ``EntityInterface`` インスタンスを文字列にキャストする機能は非推奨となりました。 + 代わりにエンティティを ``json_encode()`` してください。 + +- ``EntityInterface::set()`` を使って複数のエンティティフィールドを一括代入することは非推奨となりました。 + 代わりに ``EntityInterface::patch()`` を使用してください。例えば、 + ``$entity->set(['field1' => 'value1', 'field2' => 'value2'])`` のような使い方は + ``$entity->patch(['field1' => 'value1', 'field2' => 'value2'])`` に変更してください。 + +Event +----- + +- イベントリスナーやコールバックから値を返すことは非推奨となりました。代わりに ``$event->setResult()`` を使用してください。 + また、イベントの伝播を停止したい場合は ``$event->stopPropogation()`` を使用してください。 + +View +---- + +- ``FormHelper`` の ``errorClass`` オプションは非推奨となり、テンプレート文字列の使用が推奨されます。 + アップグレードするには、 ``errorClass`` の定義をテンプレートセットに移動してください。 + 詳細は :ref:`customizing-templates` を参照してください。 + + +新機能 +============ + +Console +------- + +- ``cake counter_cache`` コマンドが追加されました。このコマンドは ``CounterCacheBehavior`` を使用しているモデルのカウンターを再生成するために使用できます。 +- ``ConsoleIntegrationTestTrait::debugOutput()`` により、コンソールコマンドの統合テストのデバッグが容易になりました。 +- ``ConsoleInputArgument`` は ``separator`` オプションをサポートするようになりました。 + このオプションにより、位置引数を ``,`` などの文字列で区切ることができ、 + CakePHP は引数を配列として分割して処理します。 +- ``Arguments::getArrayArgumentAt()`` および ``Arguments::getArrayArgument()`` が追加されました。 + これらのメソッドにより、区切り文字 ``separator`` で区切られた位置引数を配列として取得できます。 +- ``ConsoleInputOption`` は ``separator`` オプションをサポートするようになりました。 + このオプションにより、オプション値を ``,`` などの文字列で区切ることができ、 + CakePHP は引数を配列として分割して処理します。 +- ``Arguments::getArrayArgumentAt()``、 ``Arguments::getArrayArgument()``、および + ``Arguments::getArrayOption()`` が追加されました。これらのメソッドにより、 + 区切り文字 ``separator`` で区切られた位置引数やオプションを配列として取得できます。 + +Database +-------- + +- ``nativeuuid`` 型が追加されました。この型により、MariaDB を使用した Mysql 接続で ``uuid`` カラムを利用できるようになりました。他のすべてのドライバーでは、 ``nativeuuid`` は ``uuid`` のエイリアスです。 +- ``Cake\Database\Type\JsonType::setDecodingOptions()`` が追加されました。このメソッドにより、 ``json_decode()`` の ``$flags`` 引数の値を設定できます。 +- ``CounterCacheBehavior::updateCounterCache()`` が追加されました。このメソッドにより、設定された関連付けのすべてのレコードのカウンターキャッシュ値を更新できます。 + 同様の処理をコンソールから実行する ``CounterCacheCommand`` も追加されました。 +- ``Cake\Database\Driver::quote()`` が追加されました。このメソッドは、プリペアドステートメントが使用できない場合に、SQL クエリで使用する値をクォートする方法を提供します。 + +Datasource +---------- + +- アプリケーションルールで ``Closure`` を使用してバリデーションメッセージを定義できるようになりました。 + これにより、エンティティの状態やバリデーションルールのオプションに基づいて動的なバリデーションメッセージを作成できます。 + +Error +----- + +- カスタム例外に対して、 ``ErrorController`` で特定のエラーハンドリングロジックを定義できるようになりました。 + +ORM +--- + +- ``CounterCacheBehavior::updateCounterCache()`` が追加されました。このメソッドにより、設定された関連付けのすべてのレコードのカウンターキャッシュ値を更新できます。 +- ``BelongsToMany::setJunctionProperty()`` および ``getJunctionProperty()`` が追加されました。 + これらのメソッドにより、中間テーブルのレコードをハイドレートする際に使用される ``_joinData`` プロパティをカスタマイズできます。 +- ``Table::findOrCreate()`` は、第2引数に配列を直接渡してデータを指定できるようになりました。 + +TestSuite +--------- + +- ``TestFixture::$strictFields`` プロパティが追加されました。このプロパティを有効にすると、フィクスチャーのレコードリストにスキーマに存在しないフィールドが含まれている場合にエラーが発生します。 + +View +---- + +- ``FormHelper::deleteLink()`` が追加されました。これは、テンプレート内で ``DELETE`` メソッドを使用した削除リンクを簡単に作成できるラッパーです。 +- ``HtmlHelper::importmap()`` が追加されました。このメソッドにより、JavaScript ファイルのインポートマップを定義できます。 +- ``FormHelper`` は、フォームコントロールの div にクラスを適用するために ``containerClass`` テンプレートを使用するようになりました。デフォルト値は ``input`` です。 + diff --git a/ja/appendices/migration-guides.rst b/ja/appendices/migration-guides.rst index 73d3fdba32..901651b08a 100644 --- a/ja/appendices/migration-guides.rst +++ b/ja/appendices/migration-guides.rst @@ -1,11 +1,13 @@ 移行ガイド ################ -移行ガイドは、各バージョンで導入された新機能に関する情報と、4.x から 5.x への移行手順を解説します。 +移行ガイドは、各バージョンで導入された新機能に関する情報と、5.x のマイナーリリース間の移行手順を解説します。 .. toctree:: :maxdepth: 1 ./5-0-upgrade-guide ./5-0-migration-guide + ./5-1-migration-guide + ./5-2-migration-guide ./phpunit10