NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #2702 most downloaded on Packagist
CakePHP IdeHelper Plugin to improve auto-completion
Latest stable
2.23.1
Last release 1 months ago
11 Oct 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
10 years old
207 releases · first in 2017
Drag across the ruler to compare, or tap a release to open it.
The model-aware class annotator now runs for classes that use LocatorAwareTrait or have a fetchTable() method, and annotates properties assigned via $
LocatorAwareTrait or have a fetchTable() method, and annotates properties assigned via $this->Foo = $this->fetchTable('Foo'). Legacy fetchModel() calls are still picked up. #484readonly properties and properties typed as Cake\ORM\Table. #485Console/Helper on CakePHP versions that ship them there, while still reading Command/Helper. #485bin/cake annotate all -i no longer fails on an uninitialized interactive property. #484mixed when IdeHelper.autoCollect is not a plain type string. #485bin/cake generate code_completion. #484bin/cake annotate all after updating. Classes that assign tables through fetchTable() get new property annotations, so a CI dry-run check will report changes until they are committed.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.23.0...2.23.1
Your coding agent can read these notes before it upgrades. Set up the MCP server →
EntityField illuminator task can now generate typed class constants (public const string FIELD_X = 'x';, PHP 8.3+). Opt-in via 'IdeHelper' => ['illumi
public const string FIELD_X = 'x';, PHP 8.3+). Opt-in via 'IdeHelper' => ['illuminatorTypedConstants' => true] or the task config 'typed' => true. When enabled, existing untyped field constants with a string literal value are upgraded too. By @jorisvaesen in https://github.com/dereuromark/cakephp-ide-helper/pull/482Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.7...2.23.0
Detect typed FIELD_* constants in EntityFieldTask by @jorisvaesen in https://github.com/dereuromark/cakephp-ide-helper/pull/479
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.6...2.22.7
Support keyed collection template annotations by @josbeir in https://github.com/dereuromark/cakephp-ide-helper/pull/477
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.5...2.22.6
Prevent PHP-Parser token compatibility crashes when PHP_CodeSniffer 4 is loaded first on PHP < 8.5 - https://github.com/dereuromark/cakephp-ide-helper
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.4...2.22.5
Do not register the synthetic _joinData association on the junction table - https://github.com/dereuromark/cakephp-ide-helper/pull/473
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.3...2.22.4
Fixed MissingTableClassException when annotating entities of tables with a belongsToMany association (#471).
Fixed MissingTableClassException when annotating entities of tables with a belongsToMany association (#471).
bin/cake annotate models aborted with Table class for alias TagsJoin could not be found. on any app that runs allowFallbackClass(false), which the CakePHP application skeleton does by default. The synthetic association carrying the _joinData type info now gets its target table and foreign key passed explicitly, so the table locator is no longer consulted for the generated alias.
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.2...2.22.3
Fix paginate() controller annotation to use \Cake\Datasource\Paging\PaginatedInterface instead of \Cake\Datasource\ResultSetInterface. Controller::pag
paginate() controller annotation to use \Cake\Datasource\Paging\PaginatedInterface instead of \Cake\Datasource\ResultSetInterface. Controller::paginate() never returned a result set, so PHPStan reported the whole paging API (currentPage(), pageCount(), totalCount(), items(), ...) as undefined methods. Existing annotations refresh with one bin/cake annotate controllers run.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.1...2.22.2
Fix duplicate annotations on CRLF (Windows) source files. Repeated annotate runs no longer stack duplicate doc-blocks or tags - emitted doc-block line
annotate runs no longer stack duplicate doc-blocks or tags - emitted doc-block lines now follow the source file's own line endings, so runs stay idempotent.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.22.0...2.22.1
Add support for sebastian/diff 9.x
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.21.0...2.22.0
Added configurable property type annotations through IdeHelper.propertyTypeMap. This allows apps to add more specific PHPDoc types for declared proper
IdeHelper.propertyTypeMap. This allows apps to add more specific PHPDoc types for declared properties such as $helpers, $components, $actsAs or $paginate without narrowing the native property type and breaking BC. Generated annotations use regular multiline property PHPDoc blocks and preserve existing indentation, including tabs.Recommended config for CakePHP 5.4+:
'IdeHelper' => [
'propertyTypeMap' => [
'actsAs' => 'array<string, mixed>',
'helpers' => 'array<int|string, string|array<string, mixed>>',
'components' => 'array<int|string, string|array<string, mixed>>',
'paginate' => 'array<string, mixed>',
],
],
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.20.0...2.21.0
Entities: pure virtual fields now get a @property-read tag instead of @property. A field counts as read-only when it has a _get...() accessor but no b
@property-read tag instead of @property. A field counts as read-only when it has a _get...() accessor but no backing DB column / association and no matching _set...() mutator. Writable fields (real columns, associations, or a _get/_set pair) keep the plain @property tag.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.19.3...2.20.0
Helper annotations now emit a generic extends tag so PHPStan stops reporting missingType.generics on app and plugin helpers. It is gated by a reflecti
extends tag so PHPStan stops reporting missingType.generics on app and plugin helpers. It is gated by a reflection check on the base View Helper, so it self-disables on cores where the base helper is not generic and never emits an over-specified generic on a non-generic parent.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.19.2...2.19.3
Corrected ResultSetInterface arity in generated table @method annotations. It now emits ResultSetInterface (two type params) for saveMany/saveManyOrFa
ResultSetInterface arity in generated table @method annotations. It now emits ResultSetInterface<int, TEntity> (two type params) for saveMany/saveManyOrFail/deleteMany/deleteManyOrFail returns, fixing missingType.generics under strict PHPStan. Applies in all modes, including the default. (#455)IdeHelper.genericsInParam set to true) no longer leaves params as a bare array. The get() $finder, findOrCreate() $search, and loadInto() $contain params now carry a generic type, so PHPStorm gets generic info without the detailed shapes it cannot handle. (#454)findOrCreate() $search emits SelectQuery<TEntity>, associative option/condition arrays use array<string, mixed>, and $contain keeps the loose array<mixed> for the list form. The false and 'detailed' modes are unchanged apart from the arity fix above. (#455)Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.19.1...2.19.2
Skip extends-annotation generation when the parent class isn't generic
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.19.0...2.19.1
Generated method-override annotations no longer drop the parent's throws info for newEmptyEntity(), get(), save() and saveOrFail() on CakePHP 5.3.4+ w
newEmptyEntity(), get(), save() and saveOrFail() on CakePHP 5.3.4+ when the entity-type template is in effect, which previously caused PHPStan to report the matching catch blocks as catch.neverThrown. (#445)find(), findOrCreate() and loadInto() overrides are suppressed (the parent Table propagates the entity type itself). Marshalling-family overrides (newEntity()/newEntities()/patchEntity()/patchEntities()) are likewise suppressed on 5.3.4+. Narrowing variants are still emitted in detailed (genericsInParam) / strict (concreteEntitiesInParam) modes. (#445, #446)--remove now also prunes a parent-superseded override when the class self-calls that method (the in-use guard previously kept it, retaining the false catch.neverThrown). (#447)annotate run now reports outdated/removable annotations instead of silently ignoring them: N annotations outdated (run with -r to remove) (verbose lists each). No file is changed. (#448)--ci) now fails with code 2 on outdated annotations as well — without requiring the destructive -r. (#449)Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.18.0...2.19.0
bin/cake annotate all -r no longer silently strips manual @property-read lines for virtual accessors inherited from a trait, parent class, or abstract
bin/cake annotate all -r no longer silently strips manual @property-read lines for virtual accessors inherited from a trait, parent class, or abstract base. The tokenizer-based scan in EntityAnnotator::buildVirtualPropertyHintTypeMap() only saw _get* methods declared in the entity's own file body, so inherited accessors looked unaccounted-for and the --remove pass dropped them. A complementary reflection-based scan now fills the inheritance gap: methods whose source file differs from the entity's own file are picked up via reflection, with the type resolved from the docblock @return (preferred — keeps generics, unions, FQCNs), then the PHP return type hint, then mixed. The existing tokenizer path stays the source of truth for in-class methods. No public API change.New 'strict' tier for concreteEntitiesInParam, mirroring the genericsInParam tri-state pattern (false | true | 'strict'). On top of true, strict mode adds explicit method doc-blocks for delete(), deleteOrFail(), deleteMany(), deleteManyOrFail(), and loadInto() typed with the concrete entity class, and narrows iterable params on patchEntities / saveMany / saveManyOrFail / deleteMany / deleteManyOrFail to iterable<TEntity> even when genericsInParam is left at the default false. This gives PHPStan enough signal to reject Table::delete($order) against an InvoicesTable at static-analysis time, mirroring the runtime guard discussed in cakephp/cakephp#19428. Both DocBlockHelper (bake template) and ModelAnnotator share the new branch so freshly-baked and re-annotated output stay aligned. Method order follows the existing builder convention (delete / deleteOrFail before deleteMany / deleteManyOrFail, loadInto last). Fully opt-in — existing true users see no change; association methods (link, unlink, replaceLinks, …) are intentionally out of scope.
Generated table doc-blocks now emit @extends first, aligning with the class-level tag order proposed in php-collective/code-sniffer#59 (template, extends, implements, property, property-read, property-write, method, mixin). Applies to fresh annotations via the addNewDocBlock path; the append-to-existing path is unchanged — full reordering of legacy doc-blocks is left to the sniff fixer to avoid duplicating its work.
TestClassAnnotatorTask is now a PathAwareClassAnnotatorTaskInterface consumer (declares tests/TestCase via scanPaths()), and the dedicated tests/TestCase/ walk inside ClassesCommand::execute() is removed. The last remaining "special" path is folded into the unified path-aware mechanism introduced in 2.17.0; per-task shouldRun() gating is preserved so the same files are visited and the same tasks fire. Third-party tasks that declare overlapping roots now collapse via the shared dedup map instead of double-walking. Behavior is unchanged for users who keep the default task list.
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.17.0...2.18.0
Throw on file_put_contents / mkdir failures in the code-gen path so a silently swallowed write (full disk, EACCES on a read-only checkout, ENOSPC, NFS
file_put_contents / mkdir failures in the code-gen path so a silently swallowed write (full disk, EACCES on a read-only checkout, ENOSPC, NFS hiccup) no longer lets the command exit 0 while a source file is left zero-byte truncated. Affects AbstractAnnotator::storeFile(), Illuminator\TaskCollection::storeFile(), CodeCompletion\CodeCompletionGenerator, and GeneratePhpStormMetaCommand. Behavior on a healthy filesystem is unchanged.PathAwareClassAnnotatorTaskInterface: a class annotator task can now declare extra directories that bin/cake annotate classes should walk on top of the default src/ and tests/TestCase/ scans. Tasks expose a static scanPaths(): array<string> returning project-root-relative (or plugin-root-relative under -p) paths. Fully back-compatible — the interface is opt-in and existing tasks behave exactly as before. Enables consumers like cakephp-fixture-factories to drop their bespoke annotate_factories command and reach tests/Factory/ (and similar trees) through the unified annotate classes entry point.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.8...2.17.0
Support new Cake\ORM\Table TEntity template param on CakePHP 5.4+ — the @extends annotation now emits the entity FQCN as a second template argument so
Cake\ORM\Table TEntity template param on CakePHP 5.4+ — the @extends annotation now emits the entity FQCN as a second template argument so Psalm v7 stops reporting MissingTemplateParam on every table class. Output on CakePHP < 5.4 is unchanged.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.7...2.16.8
Fix trailing whitespace in paginate annotation for generics mode.
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.6...2.16.7
Fix annotation duplication when a @method / @property type contained spaces inside generic brackets (e.g. ResultSetInterface ). The type was previousl
@method / @property type contained spaces inside generic brackets (e.g. ResultSetInterface<int, \Foo\Entity>). The type was previously truncated at the first space, leaving the rest glued onto the method name, which made matches() silently fail and caused lines like saveMany / deleteMany to be re-appended instead of replaced on subsequent runs — most visible when enabling IdeHelper.genericsInParam => 'detailed' on existing annotations (#430)Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.5...2.16.6
Added new 'detailed' value for the IdeHelper.genericsInParam config option. In addition to false (bare) and true (basic generics), projects can now op
'detailed' value for the IdeHelper.genericsInParam config option. In addition to false (bare) and true (basic generics), projects can now opt into fully detailed param types throughout the Table @method annotations: array<string, mixed>, array<array<string, mixed>>, ResultSetInterface<int, TEntity>, SelectQuery<TEntity> inside findOrCreate, and array<string, mixed>|string for get()'s finder param. Fully BC — existing true / false users see no change. See #428.<img width="1759" height="558" alt="generics" src="https://github.com/user-attachments/assets/5b4e578b-551e-4f81-8d37-6a595bbb40f2" />
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.4...2.16.5
Added SelectQuery code completion stubs for entity-aware query chains. To also annotate table find() calls with the entity-aware return type, enable w
SelectQuery code completion stubs for entity-aware query chains. To also annotate table find() calls with the entity-aware return type, enable with 'tableEntityQuery' => true in your app config - https://github.com/dereuromark/cakephp-ide-helper/pull/426Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.3...2.16.4
Fix annotation generation for virtual fields with nested generics - https://github.com/dereuromark/cakephp-ide-helper/pull/425
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.2...2.16.3
Fix preg_match() compilation error when using Form classes in nested namespaces (e.g. App\Form\Admin\ContactForm)
App\Form\Admin\ContactForm) (#423)Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.1...2.16.2
Only remove annotations whose tag type matches generated annotations - https://github.com/dereuromark/cakephp-ide-helper/pull/419
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.16.0...2.16.1
Switched fully to @link instead of @uses as the latter is PHPUnit specific and can cause issues with the respective attributes added. There is a confi
@link instead of @uses as the latter is PHPUnit specific and can cause issues with the respective attributes added. There is a config to retain the old behavior, but it is not advised.Note: Now PHP 8.2+
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.15.1...2.16.0
Fix nullable in template to not get lost.
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.15.1...2.15.2
Skip @property annotations for typed Table properties in controllers - https://github.com/dereuromark/cakephp-ide-helper/pull/413
@property annotations for typed Table properties in controllers - https://github.com/dereuromark/cakephp-ide-helper/pull/413Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.15.0...2.15.1
Add support for compact() in template variable extraction - https://github.com/dereuromark/cakephp-ide-helper/pull/409
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.14.0...2.15.0
Added TableValidationLinkTask to link table validation methods for Illuminator
bin/cake illuminate codeFull Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.13.4...2.14.0
Fix up annotations for templates around $this usage.
$this usage.Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.13.3...2.13.4
Updated finder return type from Query to SelectQuery
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.13.2...2.13.3
Also added auto-complete for other table() method usage in Migrations or Seeds.
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.13.1...2.13.2
Fixed type hinting in beforeRedirect() code completion file
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.13.0...2.13.1
Allow adding $defaultTable for non existing models in controllers.
$defaultTable for non existing models in controllers.bin/cake illuminate src/Controller --task ControllerDefaultTable
Fixed phpcs v4 handling of doc blocks after open tag.
Fix callable (anonymous function) variables to be excluded from template annotations
Added missing afterMarshal callback annotating.
afterMarshal callback annotating.Adjust to skip URLs in link annotations. by @dereuromark in https://github.com/dereuromark/cakephp-ide-helper/pull/392
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.11.1...2.11.2
Fixed CI status code for accumulated result
IdeHelper can now run in CI pipelines using --ci flag, e.g. add this after phpunit, phpstan, and cs: ```
IdeHelper can now run in CI pipelines using --ci flag, e.g. add this after phpunit, phpstan, and cs:
- vendor/bin/phpunit
- vendor/bin/phpstan
- vendor/bin/phpcs
- bin/cake annotate all -d --ci
This requires the test DB connection to be up and migrations run (up to date tables).
This helps to make sure PRs are fully up to date on the annotations, as those are often needed for PHPStan to fully understand the code and be able to give proper feedback.
For larger projects you might need to raise also memory limit:
- php -d memory_limit=1G bin/cake.php annotate all -d --ci
Note how it requires the -d/--dry-run flag here to not modify any code, only report it.
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.10.2...2.11.0
Allow using @link instead of @uses for tests to avoid PHPUnit clash (which wants to make it attributes).
@link instead of @uses for tests to avoid PHPUnit clash (which wants to make it attributes).Note: There is no auto-migration. Find and replace all occurances of @uses \... in your tests folder with the link replacement and only then switch on the feature toggle IdeHelper.preferLinkOverUsesInTests for it.
Allow class doc block finding also with attributes attached to them
Add --file support for tooling based run
--file support for tooling based runThis enables watchers to be able to run for specific files created/modified.
node vendor/dereuromark/cakephp-ide-helper/annotate-watcher.cjs
Now when you bake, or modify your code, it will automatically run it in the background over the touched files.
Fixed up callbacks to non-deprecated signature
Added request attribute auto complete - https://github.com/dereuromark/cakephp-ide-helper/pull/383
Added request attribute auto complete - https://github.com/dereuromark/cakephp-ide-helper/pull/383
Check out the PR and video demo for how it works.
Full Changelog: https://github.com/dereuromark/cakephp-ide-helper/compare/2.8.4...2.9.0
Improved variable parsing in templates
It now also finds variables inside double quoted strings like
echo "<strong>'{$url}'</strong>: $title ...";
Fixed up @extends annotation for comments or ! overwrite protector.
@extends annotation for comments or ! overwrite protector.Fixed new @extends to respect actual parent class
@extends to respect actual parent classNote: The auto enable for it has been moved to CakePHP 5.2.3+. if you want to use it beforehand, set the config to true or 'extends' here.
Fixed up also other migration meta to new Base classes.
Added support for Table::getBehavior() autocomplete and behavior object discover. This becomes now more important as behavior methods will need to be
Added support for Table::getBehavior() autocomplete and behavior object discover.
This becomes now more important as behavior methods will need to be called directly on the behavior in the future.
The new @extends annotations also make it possible now for PHPStan to introspect your getBehavior() calls and see if those behaviors - and their methods - actually exist or throw an error otherwise.
It is enabled by default for CakePHP 5.2.2+. You can also use the configuration to adjust this and also fade out @mixin ones if you don't need them anymore. IdeHelper.tableBehaviors can be set to true/false/extends/mixin or null to autodetect.
In this context also hasBehavior() support has been added.
The new (Phinx removed) Migrations Base classes are now supported for autocomplete.
Dropped phpstan/phpdoc-parser v1 support
phpstan/phpdoc-parser v1 supportCompatibility with PHPStan parser v2
Improve MailerClassAnnotatorTask: Chainable usage now preferred: `php $this->getMailer('User')->send('forgotPassword', [$user]); will be annotated as
$this->getMailer('User')->send('forgotPassword', [$user]);
will be annotated as /** @uses \App\Mailer\UserMailer::forgotPassword() */
$this->getMailer('User')->send('forgotPassword', [$user]);
To be able to follow it through a click in the IDE and also for the method to be checkable for usage (IDE => jump to the usage).Added 'ignoreDatabaseTables' config for DatabaseTableTask
'ignoreDatabaseTables' config for DatabaseTableTaskFix up FQCN for property annotations in entity.
Allow wildcard for partial match on plugin option: MyNamespace/* would run over all such matching app plugins
MyNamespace/* would run over all such matching app plugins-p all to run over all app plugins### Fixes - Fix disabling of class tasks
Fixed up findOrCreate() annotation.
One column per quarter.