From 5aed5da936bbba3b4647e95e2675acab280787ba Mon Sep 17 00:00:00 2001 From: mscherer Date: Wed, 28 Jan 2026 17:56:55 +0100 Subject: [PATCH 1/3] Rename PHPUnit 10 guide to PHPUnit Upgrade and add PHPUnit 11/12 sections Closes #8172 --- docs/en/appendices/5-0-migration-guide.md | 2 +- docs/en/appendices/migration-guides.md | 2 +- docs/en/appendices/phpunit-upgrade.md | 154 ++++++++++++++++++++++ docs/en/appendices/phpunit10.md | 68 ---------- docs/ja/appendices/5-0-migration-guide.md | 2 +- docs/ja/appendices/migration-guides.md | 2 +- docs/ja/appendices/phpunit-upgrade.md | 151 +++++++++++++++++++++ docs/ja/appendices/phpunit10.md | 65 --------- toc_en.json | 2 +- toc_ja.json | 2 +- 10 files changed, 311 insertions(+), 139 deletions(-) create mode 100644 docs/en/appendices/phpunit-upgrade.md delete mode 100644 docs/en/appendices/phpunit10.md create mode 100644 docs/ja/appendices/phpunit-upgrade.md delete mode 100644 docs/ja/appendices/phpunit10.md diff --git a/docs/en/appendices/5-0-migration-guide.md b/docs/en/appendices/5-0-migration-guide.md index 37c64868c4..a7a9f2c236 100644 --- a/docs/en/appendices/5-0-migration-guide.md +++ b/docs/en/appendices/5-0-migration-guide.md @@ -247,7 +247,7 @@ The above will disable creation of entity objects and return rows as arrays inst - `TestSuite` was removed. Users should use environment variables to customize unit test settings instead. - `TestListenerTrait` was removed. PHPUnit dropped support for these listeners. - See [PHPUnit 10 Upgrade](../appendices/phpunit10) + See [PHPUnit Upgrade](../appendices/phpunit-upgrade) - `IntegrationTestTrait::configRequest()` now merges config when called multiple times instead of replacing the currently present config. diff --git a/docs/en/appendices/migration-guides.md b/docs/en/appendices/migration-guides.md index cf2cc6b4f6..74ed56aba4 100644 --- a/docs/en/appendices/migration-guides.md +++ b/docs/en/appendices/migration-guides.md @@ -31,4 +31,4 @@ to ensure the tool can resolve class names correctly. - [5 1 Migration Guide](5-1-migration-guide) - [5 2 Migration Guide](5-2-migration-guide) - [5 3 Migration Guide](5-3-migration-guide) -- [Phpunit10](phpunit10) +- [PHPUnit Upgrade](phpunit-upgrade) diff --git a/docs/en/appendices/phpunit-upgrade.md b/docs/en/appendices/phpunit-upgrade.md new file mode 100644 index 0000000000..d606b2ce35 --- /dev/null +++ b/docs/en/appendices/phpunit-upgrade.md @@ -0,0 +1,154 @@ +# PHPUnit Upgrade + +CakePHP 5 supports PHPUnit 11 and 12. This guide covers migrating from older PHPUnit versions. + +## phpunit.xml Adjustments + +It is recommended to let PHPUnit update its configuration file via the following command: + + vendor/bin/phpunit --migrate-configuration + +> [!NOTE] +> Run `vendor/bin/phpunit --version` to check your current PHPUnit version before executing migration commands. + +With this command out of the way your `phpunit.xml` already has most of the recommended changes present. + +### Extension Configuration + +PHPUnit 10 removed the old hook system and introduced a new [Event system](https://docs.phpunit.de/en/10.5/extending-phpunit.html#extending-the-test-runner) +which requires the following code in your `phpunit.xml` to be adjusted from: + +``` xml + + + +``` + +to: + +``` xml + + + +``` + +## PHPUnit 9 to 10 + +### `->withConsecutive()` Removed + +You can convert the removed `->withConsecutive()` method to a +working interim solution like you can see here: + +``` php +->withConsecutive(['firstCallArg'], ['secondCallArg']) +``` + +should be converted to: + +``` php +->with( + ...self::withConsecutive(['firstCallArg'], ['secondCallArg']) +) +``` + +The static `self::withConsecutive()` method has been added via the `Cake\TestSuite\PHPUnitConsecutiveTrait` +to the base `Cake\TestSuite\TestCase` class so you don't have to manually add that trait to your TestCase classes. + +### Data Providers Must Be Static + +If your test cases leverage the data provider feature of PHPUnit then +you have to adjust your data providers to be static: + +``` php +public function myProvider(): array +``` + +should be converted to: + +``` php +public static function myProvider(): array +``` + +## PHPUnit 10 to 11 + +PHPUnit 11 requires PHP 8.2 or later. + +### Annotations Deprecated + +PHPUnit 11 deprecates annotations in docblocks. You should migrate to PHP 8 attributes: + +``` php +// Before (deprecated) +/** + * @dataProvider myProvider + */ +public function testSomething(): void + +// After +#[DataProvider('myProvider')] +public function testSomething(): void +``` + +Common attribute replacements: + +| Annotation | Attribute | +|------------|-----------| +| `@dataProvider` | `#[DataProvider('methodName')]` | +| `@depends` | `#[Depends('methodName')]` | +| `@group` | `#[Group('name')]` | +| `@covers` | `#[CoversClass(ClassName::class)]` | +| `@test` | `#[Test]` | + +### Test Doubles for Abstract Classes Deprecated + +Methods for creating mock objects for abstract classes and traits are hard-deprecated. Testing traits in isolation from the classes that use them is discouraged. + +### Stub Expectations Deprecated + +Configuring expectations on an object created with `createStub()` triggers a deprecation warning: + +``` php +// Avoid - will warn in PHPUnit 11 +$stub = $this->createStub(SomeClass::class); +$stub->expects($this->once())->method('foo'); + +// Use createMock() instead when you need expectations +$mock = $this->createMock(SomeClass::class); +$mock->expects($this->once())->method('foo'); +``` + +### Test Class Naming + +Test class names must match their file names. A test in `FooTest.php` must have a class named `FooTest`. + +## PHPUnit 11 to 12 + +PHPUnit 12 requires PHP 8.3 or later. + +### Annotations Removed + +Support for docblock annotations has been removed. All tests must use PHP 8 attributes. + +### Test Doubles for Abstract Classes Removed + +Methods for creating mock objects for abstract classes and traits have been removed entirely. + +### Stub Expectations Removed + +Configuring expectations on objects created with `createStub()` no longer works. Use `createMock()` for test doubles that need expectation configuration. + +## Using Rector for Automated Migration + +[Rector](https://getrector.com/) can automate many of these changes: + +``` bash +composer require --dev rector/rector rector/rector-phpunit + +# Create rector.php config +vendor/bin/rector init + +# Run rector +vendor/bin/rector process tests/ +``` + +Configure Rector with PHPUnit rulesets to handle data provider static conversion, annotation to attribute migration, and other changes automatically. diff --git a/docs/en/appendices/phpunit10.md b/docs/en/appendices/phpunit10.md deleted file mode 100644 index a6606f000e..0000000000 --- a/docs/en/appendices/phpunit10.md +++ /dev/null @@ -1,68 +0,0 @@ -# PHPUnit 10 Upgrade - -With CakePHP 5 the minimum PHPUnit version has changed from `^8.5 || ^9.3` to `^10.1`. This introduces a few breaking changes from PHPUnit as well as from CakePHP's side. - -## phpunit.xml adjustments - -It is recommended to let PHPUnit update its configuration file via the following command: - - vendor/bin/phpunit --migrate-configuration - -> [!NOTE] -> Make sure you are already on PHPUnit 10 via `vendor/bin/phpunit --version` before executing this command! - -With this command out of the way your `phpunit.xml` already has most of the recommended changes present. - -### New event system - -PHPUnit 10 removed the old hook system and introduced a new [Event system](https://docs.phpunit.de/en/10.5/extending-phpunit.html#extending-the-test-runner) -which requires the following code in your `phpunit.xml` to be adjusted from: - -``` php - - - -``` - -to: - -``` php - - - -``` - -## `->withConsecutive()` has been removed - -You can convert the removed `->withConsecutive()` method to a -working interim solution like you can see here: - -``` php -->withConsecutive(['firstCallArg'], ['secondCallArg']) -``` - -should be converted to: - -``` php -->with( - ...self::withConsecutive(['firstCallArg'], ['secondCallArg']) -) -``` - -the static `self::withConsecutive()` method has been added via the `Cake\TestSuite\PHPUnitConsecutiveTrait` -to the base `Cake\TestSuite\TestCase` class so you don't have to manually add that trait to your Testcase classes. - -## data providers have to be static - -If your testcases leverage the data provider feature of PHPUnit then -you have to adjust your data providers to be static: - -``` php -public function myProvider(): array -``` - -should be converted to: - -``` text -public static function myProvider(): array -``` diff --git a/docs/ja/appendices/5-0-migration-guide.md b/docs/ja/appendices/5-0-migration-guide.md index eba58cfc44..820a999325 100644 --- a/docs/ja/appendices/5-0-migration-guide.md +++ b/docs/ja/appendices/5-0-migration-guide.md @@ -182,7 +182,7 @@ CakePHP 5.0 には、破壊的な変更が含まれており、4.x リリース ### TestSuite - `TestSuite` は削除されました。単体テストの設定をカスタマイズするには、環境変数を使って下さい。 -- `TestListenerTrait` は削除されました。PHPUnitがこれらの listener のサポートを打ち切ったためです。詳細は [PHPUnit 10 へのアップグレード](../appendices/phpunit10) を参照して下さい。 +- `TestListenerTrait` は削除されました。PHPUnitがこれらの listener のサポートを打ち切ったためです。詳細は [PHPUnit アップグレード](../appendices/phpunit-upgrade) を参照して下さい。 - `IntegrationTestTrait::configRequest()` が複数回呼ばれた際、設定を上書きするのではなく merge するようになりました。 ### Validation diff --git a/docs/ja/appendices/migration-guides.md b/docs/ja/appendices/migration-guides.md index 8fd2b21b3b..cab75cdf02 100644 --- a/docs/ja/appendices/migration-guides.md +++ b/docs/ja/appendices/migration-guides.md @@ -6,4 +6,4 @@ - [5 0 Migration Guide](5-0-migration-guide) - [5 1 Migration Guide](5-1-migration-guide) - [5 2 Migration Guide](5-2-migration-guide) -- [Phpunit10](phpunit10) +- [PHPUnit アップグレード](phpunit-upgrade) diff --git a/docs/ja/appendices/phpunit-upgrade.md b/docs/ja/appendices/phpunit-upgrade.md new file mode 100644 index 0000000000..6e7d89d37e --- /dev/null +++ b/docs/ja/appendices/phpunit-upgrade.md @@ -0,0 +1,151 @@ +# PHPUnit アップグレード + +CakePHP 5 は PHPUnit 11 および 12 をサポートしています。このガイドでは、古いバージョンの PHPUnit からの移行について説明します。 + +## phpunit.xml の調整 + +PHPUnit の設定ファイルを、以下のコマンドで更新することが推奨されます: + + vendor/bin/phpunit --migrate-configuration + +> [!NOTE] +> 上記のコマンドを実行する前に、 `vendor/bin/phpunit --version` を実行して現在の PHPUnit バージョンを確認して下さい。 + +このコマンドを実行することによって、お手元のプロジェクトの `phpunit.xml` ファイルには推奨される変更が適用された状態になります。 + +### エクステンション設定 + +PHPUnit 10 は、古い hook の仕組みを削除した上で、新しい [イベントシステム](https://docs.phpunit.de/en/10.5/extending-phpunit.html#extending-the-test-runner) が導入されました。 +以下に示すような `phpunit.xml` は: + +``` xml + + + +``` + +次のように調整されます: + +``` xml + + + +``` + +## PHPUnit 9 から 10 へ + +### `->withConsecutive()` の削除 + +削除されたメソッド `->withConsecutive()` は、応急措置的に置き換え可能です。例えば以下のコードは: + +``` php +->withConsecutive(['firstCallArg'], ['secondCallArg']) +``` + +次のように置き換えられます: + +``` php +->with( + ...self::withConsecutive(['firstCallArg'], ['secondCallArg']) +) +``` + +`Cake\TestSuite\TestCase` クラスには、 `Cake\TestSuite\PHPUnitConsecutiveTrait` 経由で、静的メソッド `self::withConsecutive()` が追加されました。なので、TestCase のクラスに手動で trait を仕込む必要はありません。 + +### data provider は static に + +お手元のプロジェクトのテストケースにおいて、PHPUnit の data provider 機能を活用している場合、それを static にする必要があります。例えば以下のコードは: + +``` php +public function myProvider(): array +``` + +次のように置き換えて下さい: + +``` php +public static function myProvider(): array +``` + +## PHPUnit 10 から 11 へ + +PHPUnit 11 は PHP 8.2 以降が必要です。 + +### アノテーションの非推奨化 + +PHPUnit 11 では docblock のアノテーションが非推奨になりました。PHP 8 のアトリビュートに移行して下さい: + +``` php +// 以前（非推奨） +/** + * @dataProvider myProvider + */ +public function testSomething(): void + +// 移行後 +#[DataProvider('myProvider')] +public function testSomething(): void +``` + +主なアトリビュートの置き換え: + +| アノテーション | アトリビュート | +|------------|-----------| +| `@dataProvider` | `#[DataProvider('methodName')]` | +| `@depends` | `#[Depends('methodName')]` | +| `@group` | `#[Group('name')]` | +| `@covers` | `#[CoversClass(ClassName::class)]` | +| `@test` | `#[Test]` | + +### 抽象クラスのテストダブルが非推奨に + +抽象クラスおよびトレイトのモックオブジェクトを作成するメソッドが非推奨になりました。トレイトを使用するクラスから分離してテストすることは推奨されません。 + +### スタブのエクスペクテーションが非推奨に + +`createStub()` で作成したオブジェクトにエクスペクテーションを設定すると、非推奨の警告が表示されます: + +``` php +// 非推奨 - PHPUnit 11 で警告が出ます +$stub = $this->createStub(SomeClass::class); +$stub->expects($this->once())->method('foo'); + +// エクスペクテーションが必要な場合は createMock() を使用して下さい +$mock = $this->createMock(SomeClass::class); +$mock->expects($this->once())->method('foo'); +``` + +### テストクラスの命名規則 + +テストクラス名はファイル名と一致する必要があります。`FooTest.php` のテストクラスは `FooTest` という名前でなければなりません。 + +## PHPUnit 11 から 12 へ + +PHPUnit 12 は PHP 8.3 以降が必要です。 + +### アノテーションの削除 + +docblock アノテーションのサポートが削除されました。すべてのテストで PHP 8 のアトリビュートを使用する必要があります。 + +### 抽象クラスのテストダブルの削除 + +抽象クラスおよびトレイトのモックオブジェクトを作成するメソッドが完全に削除されました。 + +### スタブのエクスペクテーションの削除 + +`createStub()` で作成したオブジェクトへのエクスペクテーション設定は機能しなくなりました。エクスペクテーション設定が必要なテストダブルには `createMock()` を使用して下さい。 + +## Rector による自動移行 + +[Rector](https://getrector.com/) を使用すると、多くの変更を自動化できます: + +``` bash +composer require --dev rector/rector rector/rector-phpunit + +# rector.php 設定ファイルの作成 +vendor/bin/rector init + +# rector の実行 +vendor/bin/rector process tests/ +``` + +Rector の PHPUnit ルールセットを設定することで、data provider の static 変換、アノテーションからアトリビュートへの移行などの変更を自動的に処理できます。 diff --git a/docs/ja/appendices/phpunit10.md b/docs/ja/appendices/phpunit10.md deleted file mode 100644 index df453e419a..0000000000 --- a/docs/ja/appendices/phpunit10.md +++ /dev/null @@ -1,65 +0,0 @@ -# PHPUnit 10 へのアップグレード - -CakePHP 5 では、PHPUnit の最低バージョンが `^8.5 || ^9.3` から `^10.1` に変更されました。 この文書は、PHPUnit や CakePHP 由来の、いくつかの破壊的変更を紹介するものです。 - -## phpunit.xml の調整 - -PHPUnitの設定ファイルを、以下のコマンドで更新することが推奨されます: - - vendor/bin/phpunit --migrate-configuration - -> [!NOTE] -> 上記のコマンドを実行する前に、 `vendor/bin/phpunit --version` を実行して PHPUnit 10 が実行されていることを確認して下さい。 - -このコマンド（訳注 : `vendor/bin/phpunit --migrate-configuration` のこと）を実行することによって、お手元のプロジェクトの `phpunit.xml` ファイルには推奨される変更が適用された状態になります。 - -### 新しいイベントシステム - -PHPUnit 10 は、古い hook の仕組みを削除した上で、新しい [イベントシステム](https://docs.phpunit.de/en/10.5/extending-phpunit.html#extending-the-test-runner) が導入されました。 -ここでは、以下に示すような `phpunit.xml` は…: - -``` php - - - -``` - -次のように調整されます: - -``` php - - - -``` - -## `->withConsecutive()` の削除 - -削除されたメソッド `->withConsecutive()` は、応急措置的に置き換え可能です。例えば以下のコードは: - -``` php -->withConsecutive(['firstCallArg'], ['secondCallArg']) -``` - -次のように置き換えられます: - -``` php -->with( - ...self::withConsecutive(['firstCallArg'], ['secondCallArg']) -) -``` - -`Cake\TestSuite\TestCase` クラスには、 `Cake\TestSuite\PHPUnitConsecutiveTrait` 経由で、静的メソッド `self::withConsecutive()` が追加されました。なので、Testcase のクラスに手動で trait を仕込む必要はありません。 - -## data provider は static に - -お手元のプロジェクトのテストケースにおいて、PHPUnitの data provider 機能を活用している場合、それを static にする必要があります。例えば以下のコードは: - -``` php -public function myProvider(): array -``` - -次のように置き換えて下さい: - -``` text -public static function myProvider(): array -``` diff --git a/toc_en.json b/toc_en.json index 6177a7eee4..aff3bc9f13 100644 --- a/toc_en.json +++ b/toc_en.json @@ -413,7 +413,7 @@ "link": "/appendices/cakephp-development-process" }, { "text": "Glossary", "link": "/appendices/glossary" }, - { "text": "PHPUnit 10", "link": "/appendices/phpunit10" } + { "text": "PHPUnit Upgrade", "link": "/appendices/phpunit-upgrade" } ] } ] diff --git a/toc_ja.json b/toc_ja.json index 30690bd08e..39d1c9acc6 100644 --- a/toc_ja.json +++ b/toc_ja.json @@ -500,7 +500,7 @@ "link": "/ja/appendices/cakephp-development-process" }, { "text": "用語集", "link": "/ja/appendices/glossary" }, - { "text": "PHPUnit 10", "link": "/ja/appendices/phpunit10" } + { "text": "PHPUnit アップグレード", "link": "/ja/appendices/phpunit-upgrade" } ] } ] From 1fc139b8888e0bf16e595cc32a8d9ea2a55250e6 Mon Sep 17 00:00:00 2001 From: mscherer Date: Wed, 28 Jan 2026 18:00:36 +0100 Subject: [PATCH 2/3] Add current requirements section, import note, and upgrade checklist --- docs/en/appendices/phpunit-upgrade.md | 25 ++++++++++++++++++++++++- docs/ja/appendices/phpunit-upgrade.md | 25 ++++++++++++++++++++++++- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/docs/en/appendices/phpunit-upgrade.md b/docs/en/appendices/phpunit-upgrade.md index d606b2ce35..e4670e2cde 100644 --- a/docs/en/appendices/phpunit-upgrade.md +++ b/docs/en/appendices/phpunit-upgrade.md @@ -1,6 +1,17 @@ # PHPUnit Upgrade -CakePHP 5 supports PHPUnit 11 and 12. This guide covers migrating from older PHPUnit versions. +This guide covers the PHPUnit version requirements and migration steps for CakePHP 5.x applications. + +## Current Requirements + +CakePHP 5.x requires **PHPUnit ^11.5.3 or ^12.1.3**. This means: + +- PHPUnit 11.5.3+ requires **PHP 8.2** or later +- PHPUnit 12.1.3+ requires **PHP 8.3** or later + +> [!NOTE] +> PHPUnit 10 is no longer supported in CakePHP 5.x. If you are still on PHPUnit 10, +> you must upgrade to PHPUnit 11 or 12. ## phpunit.xml Adjustments @@ -99,6 +110,8 @@ Common attribute replacements: | `@covers` | `#[CoversClass(ClassName::class)]` | | `@test` | `#[Test]` | +Remember to import the attribute classes from `PHPUnit\Framework\Attributes`. + ### Test Doubles for Abstract Classes Deprecated Methods for creating mock objects for abstract classes and traits are hard-deprecated. Testing traits in isolation from the classes that use them is discouraged. @@ -152,3 +165,13 @@ vendor/bin/rector process tests/ ``` Configure Rector with PHPUnit rulesets to handle data provider static conversion, annotation to attribute migration, and other changes automatically. + +## Upgrade Checklist + +Before upgrading PHPUnit versions, ensure: + +1. Your test suite runs without deprecation warnings on your current PHPUnit version +2. All data providers are `public static` methods +3. You are using attributes instead of annotations (required for PHPUnit 12) +4. Mock expectations only use `createMock()`, not `createStub()` +5. Run `vendor/bin/phpunit --migrate-configuration` after upgrading diff --git a/docs/ja/appendices/phpunit-upgrade.md b/docs/ja/appendices/phpunit-upgrade.md index 6e7d89d37e..c7230c8b5a 100644 --- a/docs/ja/appendices/phpunit-upgrade.md +++ b/docs/ja/appendices/phpunit-upgrade.md @@ -1,6 +1,17 @@ # PHPUnit アップグレード -CakePHP 5 は PHPUnit 11 および 12 をサポートしています。このガイドでは、古いバージョンの PHPUnit からの移行について説明します。 +このガイドでは、CakePHP 5.x アプリケーションの PHPUnit バージョン要件と移行手順について説明します。 + +## 現在の要件 + +CakePHP 5.x は **PHPUnit ^11.5.3 または ^12.1.3** が必要です: + +- PHPUnit 11.5.3+ は **PHP 8.2** 以降が必要です +- PHPUnit 12.1.3+ は **PHP 8.3** 以降が必要です + +> [!NOTE] +> CakePHP 5.x では PHPUnit 10 はサポートされなくなりました。まだ PHPUnit 10 を使用している場合は、 +> PHPUnit 11 または 12 にアップグレードする必要があります。 ## phpunit.xml の調整 @@ -96,6 +107,8 @@ public function testSomething(): void | `@covers` | `#[CoversClass(ClassName::class)]` | | `@test` | `#[Test]` | +アトリビュートクラスは `PHPUnit\Framework\Attributes` からインポートして下さい。 + ### 抽象クラスのテストダブルが非推奨に 抽象クラスおよびトレイトのモックオブジェクトを作成するメソッドが非推奨になりました。トレイトを使用するクラスから分離してテストすることは推奨されません。 @@ -149,3 +162,13 @@ vendor/bin/rector process tests/ ``` Rector の PHPUnit ルールセットを設定することで、data provider の static 変換、アノテーションからアトリビュートへの移行などの変更を自動的に処理できます。 + +## アップグレードチェックリスト + +PHPUnit のバージョンをアップグレードする前に、以下を確認して下さい: + +1. 現在の PHPUnit バージョンでテストスイートが非推奨の警告なしに実行できること +2. すべての data provider が `public static` メソッドであること +3. アノテーションではなくアトリビュートを使用していること（PHPUnit 12 で必須） +4. モックのエクスペクテーションが `createStub()` ではなく `createMock()` のみを使用していること +5. アップグレード後に `vendor/bin/phpunit --migrate-configuration` を実行すること From f8ff16e54abc8661287e5ce8c6e6a08fd16f8bbb Mon Sep 17 00:00:00 2001 From: mscherer Date: Wed, 28 Jan 2026 18:20:11 +0100 Subject: [PATCH 3/3] Remove temporary analysis files accidentally committed --- _ANALYSIS_SUMMARY.md | 96 ------------ _quick_reference.md | 102 ------------- _remaining_signatures_analysis.md | 207 -------------------------- _remaining_signatures_by_category.txt | 113 -------------- 4 files changed, 518 deletions(-) delete mode 100644 _ANALYSIS_SUMMARY.md delete mode 100644 _quick_reference.md delete mode 100644 _remaining_signatures_analysis.md delete mode 100644 _remaining_signatures_by_category.txt diff --git a/_ANALYSIS_SUMMARY.md b/_ANALYSIS_SUMMARY.md deleted file mode 100644 index 67f1ddea38..0000000000 --- a/_ANALYSIS_SUMMARY.md +++ /dev/null @@ -1,96 +0,0 @@ -# Analysis Summary: Remaining Method Signatures Without Return Types - -## Overview - -After PR #8173 (scalar return types) and PR #8174 (object return types) merge into the `5.x` branch, **96 method signatures** will still be missing return types in the CakePHP documentation. - -## Baseline Numbers - -- **Total signatures on 5.x branch**: 395 -- **Signatures without return types**: 391 -- **Signatures with return types**: 4 - -## PRs Impact - -- **PR #8173 (scalar types)**: Added return types to 272 signatures - - Includes: `void`, `bool`, `int`, `string`, `array`, `mixed`, `static`, etc. - -- **PR #8174 (object types)**: Added return types to 24 signatures - - Includes: `Response`, `Component`, `SelectQuery`, `EntityInterface`, etc. - -## Remaining: 96 Signatures - -### Breakdown by Category - -| Category | Count | Priority | Description | -|----------|-------|----------|-------------| -| **Has return type in source (easy wins!)** | **40** | **HIGH** | Already have return types in PHP source—just need to add to docs | -| No return type in source | 13 | Medium | Need to investigate and determine appropriate type | -| Fluent methods | 9 | Medium | Return `$this` or `static` but lack type declaration in source | -| Not found / inherited | 33 | Low | May be inherited from third-party libs, deprecated, or in traits | -| Callback classes | 1 | Low | Documentation convention only | - -### Category Highlights - -#### Category 3: Easy Wins (40 signatures) ⭐ - -These are **low-hanging fruit**—they already have return types in the PHP source: - -- **30 Collection methods**: All return `CollectionInterface` - - `append()`, `map()`, `filter()`, `chunk()`, etc. - -- **10 other methods**: - - `Log::log()` → `bool` - - Session methods → `void`, `bool`, `mixed` - - `Debugger::getType()` → `string` - - `Hash::insert()` → `ArrayAccess|array` - -#### Category 1: Fluent Methods (9 signatures) - -Methods that return `$this`/`static` for chaining but lack return type: -- `Controller::addViewClasses()` -- `CorsBuilder` methods (5 methods) -- `Table::addBehavior()` -- `FormHelper::unlockField()` -- `RouteBuilder::setRouteClass()` - -#### Category 2: No Return Type in Source (13 signatures) - -Need to check source to determine return type: -- `Collection::each()` -- `ConsoleOptionParser` methods (7 methods) -- `RouteBuilder` methods (3 methods) -- Others (2 methods) - -#### Category 5: Not Found/Inherited (33 signatures) - -Require investigation: -- **DateTime methods** (7): Likely inherited from Chronos library -- **Helper methods** (5): May be in traits -- **Entity methods** (4): Check for traits -- **Others** (17): Various classes, may be deprecated - -## Recommended Next Steps - -1. **Quick win**: Add the 40 signatures from Category 3 (already have return types) -2. Add return types to 9 fluent methods in PHP source, then update docs -3. Investigate and add return types to 13 methods without declared types -4. Research 33 'not found' methods—determine if inherited/deprecated/in traits - -## Files Generated - -- `/media/mark/data/work/git/docs/_remaining_signatures_analysis.md` - Detailed analysis with code examples -- `/media/mark/data/work/git/docs/_remaining_signatures_by_category.txt` - Simple list by category -- `/media/mark/data/work/git/docs/_ANALYSIS_SUMMARY.md` - This file - -## Verification - -``` -Original without types: 391 -Scalar PR additions: 272 -Object PR additions: 24 - ---- -Remaining: 95-96 ✓ -``` - -The small discrepancy (95 vs 96) is likely due to signature variations or duplicates in the parsing. diff --git a/_quick_reference.md b/_quick_reference.md deleted file mode 100644 index 2787bc635e..0000000000 --- a/_quick_reference.md +++ /dev/null @@ -1,102 +0,0 @@ -# Quick Reference: 96 Remaining Signatures by Priority - -## HIGH PRIORITY: Category 3 - Easy Wins (40 signatures) - -These already have return types in PHP source. Just add to docs! - -### Collection Methods (30) - All return `CollectionInterface` -``` -append, appendItem, buffered, chunk, chunkWithKeys, combine, compile, countBy, -extract, filter, groupBy, indexBy, insert, listNested, map, match, nest, -prepend, prependItem, reject, sample, shuffle, skip, sortBy, stopWhen, take, -through, transpose, unfold, zip -``` - -### Other Methods (10) -| Method | Return Type | -|--------|-------------| -| `Log::log()` | `bool` | -| `Session::check()` | `bool` | -| `Session::delete()` | `void` | -| `Session::destroy()` | `void` | -| `Session::read()` | `mixed` | -| `Session::readOrFail()` | `mixed` | -| `Session::renew()` | `void` | -| `Session::write()` | `void` | -| `Debugger::getType()` | `string` | -| `Hash::insert()` | `ArrayAccess\|array` | - ---- - -## MEDIUM PRIORITY: Categories 1 & 2 (22 signatures) - -### Category 1: Fluent Methods (9) - Need `static`/`self` return type - -``` -Controller::addViewClasses() -CorsBuilder::allowCredentials() -CorsBuilder::allowHeaders() -CorsBuilder::allowMethods() -CorsBuilder::exposeHeaders() -CorsBuilder::maxAge() -Table::addBehavior() -FormHelper::unlockField() -RouteBuilder::setRouteClass() -``` - -### Category 2: No Return Type in Source (13) - Need investigation - -**Collection:** -- `each()` - -**ConsoleOptionParser (7):** -- `addArgument()`, `addArguments()`, `addOption()`, `addOptions()` -- `merge()`, `setDescription()`, `setEpilog()` - -**CorsBuilder:** -- `allowOrigin()` - -**RouteBuilder (3):** -- `fallbacks()`, `plugin()`, `prefix()` - -**View:** -- `set()` - ---- - -## LOW PRIORITY: Categories 4 & 5 (34 signatures) - -### Category 4: Callback Classes (1) -- `Class::responseHeader()` - Documentation convention only - -### Category 5: Not Found/Inherited (33) - -These need research to determine if they're inherited, deprecated, or in traits: - -- **DateTime methods (7)**: Likely from Chronos library -- **Helper methods (5)**: Check traits (FormHelper, HtmlHelper, PaginatorHelper) -- **Entity methods (4)**: Check EntityTrait -- **Controller methods (3)**: Check traits (fetchTable, fetchModel, set) -- **Others (14)**: Various classes - ---- - -## Action Plan - -### Phase 1: Quick Wins (Est. 1-2 hours) -✓ Add 40 signatures that already have return types in source - -### Phase 2: Fluent Methods (Est. 2-3 hours) -✓ Add return types to 9 fluent methods in PHP source -✓ Update documentation - -### Phase 3: Investigation (Est. 3-4 hours) -✓ Investigate 13 methods without return types -✓ Determine and add appropriate types - -### Phase 4: Research (Est. 4-6 hours) -✓ Research 33 'not found' methods -✓ Determine if inherited/deprecated/in traits -✓ Update or remove from documentation - -**Total estimated effort: 10-15 hours** diff --git a/_remaining_signatures_analysis.md b/_remaining_signatures_analysis.md deleted file mode 100644 index 701ae2fdcc..0000000000 --- a/_remaining_signatures_analysis.md +++ /dev/null @@ -1,207 +0,0 @@ -# Remaining Method Signatures Missing Return Types After Both PRs - -After PR #8173 (scalar types, ~272 signatures) and PR #8174 (object types, 24 signatures) merge, **96 method signatures** will still be missing return types in the CakePHP 5.x documentation. - -## Category 1: Fluent/Self-Returning Methods (9 signatures) - -These methods return `$this` or `static` but have no declared return type in the PHP source. -**Recommended action:** Add `: static` or `: self` return type to source, then update docs. - -``` -Cake\Controller\Controller::addViewClasses() -Cake\Http\CorsBuilder::allowCredentials() -Cake\Http\CorsBuilder::allowHeaders(array $headers) -Cake\Http\CorsBuilder::allowMethods(array $methods) -Cake\Http\CorsBuilder::exposeHeaders(array $headers) -Cake\Http\CorsBuilder::maxAge(string|int $age) -Cake\ORM\Table::addBehavior($name, array $options = []) -Cake\View\Helper\FormHelper::unlockField($name) -Cake\Routing\RouteBuilder::setRouteClass($routeClass = null) -``` - -## Category 2: Methods with No Return Type in PHP Source (13 signatures) - -These methods exist in source but have no return type declared. -**Recommended action:** Examine source to determine appropriate return type, add to source, then update docs. - -``` -Cake\Collection\Collection::each($callback) -Cake\Console\ConsoleOptionParser::addArgument($name, $params = []) -Cake\Console\ConsoleOptionParser::addArguments(array $args) -Cake\Console\ConsoleOptionParser::addOption($name, array $options = []) -Cake\Console\ConsoleOptionParser::addOptions(array $options) -Cake\Console\ConsoleOptionParser::merge($spec) -Cake\Console\ConsoleOptionParser::setDescription($text) -Cake\Console\ConsoleOptionParser::setEpilog($text) -Cake\Http\CorsBuilder::allowOrigin(array|string $domains) -Cake\Routing\RouteBuilder::fallbacks($routeClass = null) -Cake\Routing\RouteBuilder::plugin($name, $options = [], $callback) -Cake\Routing\RouteBuilder::prefix($name, $callback) -Cake\View\View::set(string $var, mixed $value) -``` - -## Category 3: Methods with Return Type in Source (40 signatures) ⭐ - -These methods **HAVE return types** in the PHP source but were NOT caught by either PR. -**Recommended action:** These are easy wins! Just add the return types to docs. - -### Collection Methods (30 signatures) -All return `CollectionInterface`: - -``` -Cake\Collection\Collection::append(array|Traversable $items): CollectionInterface -Cake\Collection\Collection::appendItem($value, $key): CollectionInterface -Cake\Collection\Collection::buffered(): CollectionInterface -Cake\Collection\Collection::chunk($chunkSize): CollectionInterface -Cake\Collection\Collection::chunkWithKeys($chunkSize): CollectionInterface -Cake\Collection\Collection::combine($keyPath, $valuePath, $groupPath = null): CollectionInterface -Cake\Collection\Collection::compile($preserveKeys = true): CollectionInterface -Cake\Collection\Collection::countBy($callback): CollectionInterface -Cake\Collection\Collection::extract($path): CollectionInterface -Cake\Collection\Collection::filter($callback): CollectionInterface -Cake\Collection\Collection::groupBy($callback): CollectionInterface -Cake\Collection\Collection::indexBy($callback): CollectionInterface -Cake\Collection\Collection::insert($path, $items): CollectionInterface -Cake\Collection\Collection::listNested($order = 'desc', $nestingKey = 'children'): CollectionInterface -Cake\Collection\Collection::map($callback): CollectionInterface -Cake\Collection\Collection::match($conditions): CollectionInterface -Cake\Collection\Collection::nest($idPath, $parentPath, $nestingKey = 'children'): CollectionInterface -Cake\Collection\Collection::prepend($items): CollectionInterface -Cake\Collection\Collection::prependItem($value, $key): CollectionInterface -Cake\Collection\Collection::reject(callable $c): CollectionInterface -Cake\Collection\Collection::sample($length = 10): CollectionInterface -Cake\Collection\Collection::shuffle(): CollectionInterface -Cake\Collection\Collection::skip($length): CollectionInterface -Cake\Collection\Collection::sortBy($callback, $order = SORT_DESC, $sort = SORT_NUMERIC): CollectionInterface -Cake\Collection\Collection::stopWhen(callable $c): CollectionInterface -Cake\Collection\Collection::take($length, $offset): CollectionInterface -Cake\Collection\Collection::through($callback): CollectionInterface -Cake\Collection\Collection::transpose(): CollectionInterface -Cake\Collection\Collection::unfold(callable $callback): CollectionInterface -Cake\Collection\Collection::zip($items): CollectionInterface -``` - -### Other Methods (10 signatures) - -``` -Cake\Log\Log::log($msg, $level = LOG_ERR): bool -Session::check($key): bool -Session::delete($key): void -Session::destroy(): void -Session::read($key, $default = null): mixed -Session::readOrFail($key): mixed -Session::renew(): void -Session::write($key, $value): void -Debugger::getType($var): string -Hash::insert(array $data, $path, $values = null): ArrayAccess|array -``` - -Note: `Session` is `Cake\Http\Session`, `Debugger` is `Cake\Error\Debugger`, `Hash` is `Cake\Utility\Hash` - -## Category 4: Callback Classes (1 signature) - -Documentation convention for callbacks, not real CakePHP classes. -**Recommended action:** No change needed unless documentation should be updated to clarify. - -``` -Class::responseHeader($header = null, $value = null) -``` - -## Category 5: Not Found / Inherited / Potentially Deprecated (33 signatures) - -These methods were not found in CakePHP 6 source. They may be: -- Inherited from third-party libraries (e.g., Chronos for DateTime) -- Defined in traits (deeper search needed) -- Deprecated or removed in CakePHP 6 -- Documentation errors - -**Recommended action:** Research each method to determine if it's still valid, inherited, or should be removed from docs. - -### DateTime Methods (7 signatures) - Likely from Chronos -``` -Cake\I18n\DateTime::isYesterday() -Cake\I18n\DateTime::isThisWeek() -Cake\I18n\DateTime::isThisMonth() -Cake\I18n\DateTime::isThisYear() -Cake\I18n\DateTime::isWithinNext($interval) -Cake\I18n\DateTime::wasWithinLast($interval) -Cake\Database\DateTimeType::setTimezone(string|\DateTimeZone|null $timezone) -``` - -### CacheEngine Methods (2 signatures) -``` -Cake\Cache\CacheEngine::read($key) -Cake\Cache\CacheEngine::write($key, $value) -``` - -### HTTP Methods (3 signatures) -``` -Cake\Http\Response::withBody($body) -Cake\Http\Response::withHeader($header, $value) -Cake\Http\TestSuite\Response::newClientResponse(int $code = 200, array $headers = [], string $body = '') -``` - -### Mailer Methods (4 signatures) -``` -Cake\Mailer\Mailer::addAttachment(\Psr\Http\Message\UploadedFileInterface|string $path, ?string $name, ?string $mimetype, ?string $contentId, ?bool $contentDisposition) -Cake\Mailer\Mailer::setAttachments($attachments) -Cake\Mailer\Mailer::setEmailPattern($pattern) -Cake\Mailer\Mailer::drop($key) -``` - -### ORM Entity Methods (4 signatures) -``` -Cake\ORM\Entity::dirty($field = null, $dirty = null) -Cake\ORM\Entity::get($field) -Cake\ORM\Entity::patch(array $fields, array $options = []) -Cake\ORM\Entity::set($field, $value = null, array $options = []) -``` - -### Controller Methods (3 signatures) -``` -Cake\Controller\Controller::fetchModel(string|null $modelClass = null, string|null $modelType = null) -Cake\Controller\Controller::fetchTable(string $alias, array $config = []) -Cake\Controller\Controller::set(string $var, mixed $value) -``` - -### View Helper Methods (5 signatures) -``` -Cake\View\Helper\FormHelper::password(string $fieldName, array $options) -Cake\View\Helper\FormHelper::text(string $name, array $options) -Cake\View\Helper\HtmlHelper::setTemplates(array $templates) -Cake\View\Helper\PaginatorHelper::setTemplates($templates) -Cake\View\Helper\PaginatorHelper::sortKey(string $model = null, mixed $options = []) -``` - -### Routing Methods (3 signatures) -``` -Cake\Routing\RouteBuilder::extensions(stringnull $extensions, $merge = true) -Cake\Routing\RouteBuilder::reverse($params, $full = false) -Cake\Routing\RouteBuilder::url($url = null, $full = false) -``` - -### Other Methods (2 signatures) -``` -Cake\Core\Configure::setConfig($name, $engine) -Cake\ORM\TableLocator::get($alias, $config) -``` - ---- - -## Summary - -| Category | Count | Priority | -|----------|-------|----------| -| Fluent methods (need return type in source) | 9 | Medium | -| No return type in source (need investigation) | 13 | Medium | -| **Has return type in source (easy wins!)** | **40** | **HIGH** | -| Callback classes (documentation only) | 1 | Low | -| Not found/inherited (need research) | 33 | Low | -| **TOTAL** | **96** | | - -## Recommended Next Steps - -1. **Quick win:** Add the 40 signatures that already have return types in source (Category 3) -2. Add return types to the 9 fluent methods in PHP source, then update docs (Category 1) -3. Investigate and add return types to the 13 methods without declared types (Category 2) -4. Research the 33 'not found' methods to determine if inherited/deprecated/traits (Category 5) diff --git a/_remaining_signatures_by_category.txt b/_remaining_signatures_by_category.txt deleted file mode 100644 index fa817d533b..0000000000 --- a/_remaining_signatures_by_category.txt +++ /dev/null @@ -1,113 +0,0 @@ -REMAINING 96 METHOD SIGNATURES AFTER BOTH PRS MERGE -==================================================== - -CATEGORY 1: FLUENT METHODS (9) -------------------------------- -Cake\Controller\Controller::addViewClasses() -Cake\Http\CorsBuilder::allowCredentials() -Cake\Http\CorsBuilder::allowHeaders(array $headers) -Cake\Http\CorsBuilder::allowMethods(array $methods) -Cake\Http\CorsBuilder::exposeHeaders(array $headers) -Cake\Http\CorsBuilder::maxAge(string|int $age) -Cake\ORM\Table::addBehavior($name, array $options = []) -Cake\View\Helper\FormHelper::unlockField($name) -Cake\Routing\RouteBuilder::setRouteClass($routeClass = null) - -CATEGORY 2: NO RETURN TYPE IN SOURCE (13) ------------------------------------------- -Cake\Collection\Collection::each($callback) -Cake\Console\ConsoleOptionParser::addArgument($name, $params = []) -Cake\Console\ConsoleOptionParser::addArguments(array $args) -Cake\Console\ConsoleOptionParser::addOption($name, array $options = []) -Cake\Console\ConsoleOptionParser::addOptions(array $options) -Cake\Console\ConsoleOptionParser::merge($spec) -Cake\Console\ConsoleOptionParser::setDescription($text) -Cake\Console\ConsoleOptionParser::setEpilog($text) -Cake\Http\CorsBuilder::allowOrigin(array|string $domains) -Cake\Routing\RouteBuilder::fallbacks($routeClass = null) -Cake\Routing\RouteBuilder::plugin($name, $options = [], $callback) -Cake\Routing\RouteBuilder::prefix($name, $callback) -Cake\View\View::set(string $var, mixed $value) - -CATEGORY 3: HAS RETURN TYPE (EASY WINS!) (40) ----------------------------------------------- -Cake\Collection\Collection::append(array|Traversable $items) -Cake\Collection\Collection::appendItem($value, $key) -Cake\Collection\Collection::buffered() -Cake\Collection\Collection::chunk($chunkSize) -Cake\Collection\Collection::chunkWithKeys($chunkSize) -Cake\Collection\Collection::combine($keyPath, $valuePath, $groupPath = null) -Cake\Collection\Collection::compile($preserveKeys = true) -Cake\Collection\Collection::countBy($callback) -Cake\Collection\Collection::extract($path) -Cake\Collection\Collection::filter($callback) -Cake\Collection\Collection::groupBy($callback) -Cake\Collection\Collection::indexBy($callback) -Cake\Collection\Collection::insert($path, $items) -Cake\Collection\Collection::listNested($order = 'desc', $nestingKey = 'children') -Cake\Collection\Collection::map($callback) -Cake\Collection\Collection::match($conditions) -Cake\Collection\Collection::nest($idPath, $parentPath, $nestingKey = 'children') -Cake\Collection\Collection::prepend($items) -Cake\Collection\Collection::prependItem($value, $key) -Cake\Collection\Collection::reject(callable $c) -Cake\Collection\Collection::sample($length = 10) -Cake\Collection\Collection::shuffle() -Cake\Collection\Collection::skip($length) -Cake\Collection\Collection::sortBy($callback, $order = SORT_DESC, $sort = SORT_NUMERIC) -Cake\Collection\Collection::stopWhen(callable $c) -Cake\Collection\Collection::take($length, $offset) -Cake\Collection\Collection::through($callback) -Cake\Collection\Collection::transpose() -Cake\Collection\Collection::unfold(callable $callback) -Cake\Collection\Collection::zip($items) -Cake\Log\Log::log($msg, $level = LOG_ERR) -Session::check($key) -Session::delete($key) -Session::destroy() -Session::read($key, $default = null) -Session::readOrFail($key) -Session::renew() -Session::write($key, $value) -Debugger::getType($var) -Hash::insert(array $data, $path, $values = null) - -CATEGORY 4: CALLBACK CLASSES (1) ---------------------------------- -Class::responseHeader($header = null, $value = null) - -CATEGORY 5: NOT FOUND / INHERITED (33) ---------------------------------------- -Cake\Cache\CacheEngine::read($key) -Cake\Cache\CacheEngine::write($key, $value) -Cake\Controller\Controller::fetchModel(string|null $modelClass = null, string|null $modelType = null) -Cake\Controller\Controller::fetchTable(string $alias, array $config = []) -Cake\Controller\Controller::set(string $var, mixed $value) -Cake\Core\Configure::setConfig($name, $engine) -Cake\Database\DateTimeType::setTimezone(string|\DateTimeZone|null $timezone) -Cake\Http\Response::withBody($body) -Cake\Http\Response::withHeader($header, $value) -Cake\Http\TestSuite\Response::newClientResponse(int $code = 200, array $headers = [], string $body = '') -Cake\I18n\DateTime::isThisMonth() -Cake\I18n\DateTime::isThisWeek() -Cake\I18n\DateTime::isThisYear() -Cake\I18n\DateTime::isWithinNext($interval) -Cake\I18n\DateTime::isYesterday() -Cake\I18n\DateTime::wasWithinLast($interval) -Cake\Mailer\Mailer::addAttachment(\Psr\Http\Message\UploadedFileInterface|string $path, ?string $name, ?string $mimetype, ?string $contentId, ?bool $contentDisposition) -Cake\Mailer\Mailer::drop($key) -Cake\Mailer\Mailer::setAttachments($attachments) -Cake\Mailer\Mailer::setEmailPattern($pattern) -Cake\ORM\Entity::dirty($field = null, $dirty = null) -Cake\ORM\Entity::get($field) -Cake\ORM\Entity::patch(array $fields, array $options = []) -Cake\ORM\Entity::set($field, $value = null, array $options = []) -Cake\ORM\TableLocator::get($alias, $config) -Cake\Routing\RouteBuilder::extensions(stringnull $extensions, $merge = true) -Cake\Routing\RouteBuilder::reverse($params, $full = false) -Cake\Routing\RouteBuilder::url($url = null, $full = false) -Cake\View\Helper\FormHelper::password(string $fieldName, array $options) -Cake\View\Helper\FormHelper::text(string $name, array $options) -Cake\View\Helper\HtmlHelper::setTemplates(array $templates) -Cake\View\Helper\PaginatorHelper::setTemplates($templates) -Cake\View\Helper\PaginatorHelper::sortKey(string $model = null, mixed $options = [])