Add proper generic type annotations (fixes missingType.generics) by dereuromark · Pull Request #19200 · cakephp/cakephp

dereuromark · 2026-01-17T05:03:38Z

Summary

This PR adds proper generic type annotations to fix PHPStan missingType.generics errors instead of ignoring them globally.

Progress

Metric	Before	After
missingType.generics errors	405	0
Total errors	405+	69

The 69 remaining errors are different types (return.type, argument.type, generics.interfaceConflict) not related to the original missingType.generics ignore rule.

Files Modified

40 files across these subsystems:

View: Helper, HelperRegistry, Cell, ViewBuilder, ViewVarsTrait, Widget classes
Cache: CacheEngine, CacheRegistry, Cache.php
ORM: Table, Association, EagerLoader, Marshaller, Behavior classes
Database: Query, QueryFactory
Datasource: FactoryLocator, Paginator classes
Event: EventManager, EventDispatcherTrait
Console: BaseCommand, HelpCommand
Http: BaseApplication, BodyParserMiddleware
Utility: Hash
Core: BasePlugin, PluginInterface
Controller: Controller, Component

Approach

For each generic class/interface:

Add @template annotation to define type parameters
Use ClassName<TemplateType> in PHPDoc @param, @return, @var
Add @extends/@implements annotations to subclasses
Add @phpstan-ignore missingType.generics only for truly self-referential cases

Status

Ready for review. All missingType.generics errors are fixed, allowing removal of the global ignore rule from phpstan.neon.dist.

…enerics This is a work-in-progress to properly specify generic types instead of ignoring the missingType.generics errors in PHPStan. Changes include: - Add @template annotations to Helper, View subclasses, Cache classes - Add proper generic type parameters to method signatures - Fix Collection, ORM, Event system generic types Progress: ~210 of 405 errors fixed (52%) Remaining work needed for complete fix.

Complete the fix for generic type annotations by: - Add generic types to Association.php methods (attachTo, find, etc.) - Add @phpstan-ignore for self-referential generics in EventDispatcherTrait - Fixes all remaining missingType.generics errors Remaining 69 errors are different types (return.type, argument.type, generics.interfaceConflict) not related to the original missingType.generics issue.

LordSimal · 2026-01-17T17:03:52Z

src/Event/EventDispatcherTrait.php

+     * @phpstan-ignore missingType.generics
     */
-    public function dispatchEvent(string $name, array $data = [], ?object $subject = null): EventInterface
+    public function dispatchEvent(string $name, array $data = [], ?object $subject = null): EventInterface // @phpstan-ignore missingType.generics


I'd rather add these kind of ignore statements via the basline file instead of doing them inline

I wanted to make them visible first, maybe we can fix some of them up.
Then we can still move them to baseline.

- Add @phpstan-ignore comments for Collection return type mismatches - Add path-specific ignores for generics.interfaceConflict in TreeIterator/TreePrinter - Add path-specific ignores for argument.type covariance issues in Cache/ORM - Use consistent SelectQuery generic types in Association.php

- Cache.php: inline ignore for NullEngine fallback - TableRegistry.php: inline ignore for TableLocator - bootstrap.php: inline ignore for TableLocator generics.interfaceConflict must remain in config (PHPStan limitation for class-level interface conflicts)

dereuromark · 2026-01-18T04:38:16Z

@rochamarcelo what do you think?

src/Core/BasePlugin.php

rochamarcelo · 2026-01-18T10:20:13Z

src/Console/Command/HelpCommand.php

 /**
 * Print out command list
+ *
+ * @extends \Cake\Console\BaseCommand<\Cake\Console\Command\HelpCommand>


This is a bit strange, but if it works , it works.

src/Collection/CollectionTrait.php

rochamarcelo · 2026-01-18T10:44:20Z

It looks good.

Autocomplete works for collections on PHPStorm when using the result of $collection->filter() in foreach loop.

I got this with SelectQuery: ' variable $query contains generic class Cake\ORM\Query\SelectQuery but does not specify its types: TSubject'

@inheritdoc

- Remove unused import EntityInterface from EagerLoader - Remove @inheritdoc when combined with @param/@return (coding standard violation) - Add proper type hints and @param annotations

dereuromark · 2026-01-18T12:42:08Z

Fixed! Using {@inheritDoc} (with curly braces) instead of removing it entirely. This preserves the inherited documentation while satisfying phpcs. Thanks for catching this @ADmad!

rochamarcelo · 2026-01-18T13:17:17Z

Okay, I didn't expected the trait requires to override @return from CollectionInterface.

Looks good.

dereuromark · 2026-01-18T16:30:32Z

@rochamarcelo To fix the PHPStan error about SelectQuery not specifying its types, you need to add the generic type annotation:

/** @var \Cake\ORM\Query\SelectQuery<\App\Model\Entity\YourEntity> $query */
$query = $this->YourTable->find();

Or for array results (when using ->disableHydration()):

/** @var \Cake\ORM\Query\SelectQuery<array> $query */

The TSubject template parameter expects either an entity class or array.

dereuromark · 2026-01-22T16:41:21Z

So, how do we move forward with the inline ignores?
Are some of them solvable?
Should we move them to baseline? Or keep them visible on the specific lines?

rochamarcelo · 2026-01-22T21:46:33Z

I prefer a baseline file but no hard opnion on this.

Btw, about dispatchEvent not sure if is relevant but in any class we can use any type as subject not only the main class, for example in a command I could have dispatchEvent('someEvent', [], $apiClient), since $apiClient is not a Command it will raise a phpstan error

rochamarcelo · 2026-01-22T22:33:18Z

@dereuromark please check https://github.com/dereuromark/cakephp/pull/1/changes#diff-ed974706180ffd2397606c808669a47463376072112de17e319abb71cedbc94d

…view Suggestions for generic usage on view

dereuromark · 2026-02-01T06:26:10Z

@rochamarcelo Thx, merged in.
Anything else missing from your side?

rochamarcelo · 2026-02-01T11:21:30Z

@dereuromark I forgot to update command dereuromark#2

* use static instead of self used generic template * use static instead of self used generic template

dereuromark · 2026-02-08T23:34:17Z

@ADmad How shall we proceed here?

LordSimal · 2026-02-14T17:07:59Z

I'd say if we get the CI green this is fine to merge since its a major step into better static analysis

ADmad · 2026-02-17T04:38:51Z

@ADmad How shall we proceed here?

We can merge once CI is green.

- Resolve merge conflict in CollectionTrait.php by keeping both generic templates and @require-implements annotation - Fix Association::find() return type to SelectQuery<EntityInterface|array> to be compatible with BelongsToMany::find() override

dereuromark added 2 commits January 17, 2026 06:03

Additional fixes from parallel agents

966e149

dereuromark added this to the 5.3.2 milestone Jan 17, 2026

dereuromark changed the title ~~WIP: Add proper generic type annotations (fixes missingType.generics)~~ Add proper generic type annotations (fixes missingType.generics) Jan 17, 2026

LordSimal reviewed Jan 17, 2026

View reviewed changes

dereuromark added 3 commits January 17, 2026 18:13

Improve inline ignore comments wording

ddf81af

ADmad reviewed Jan 18, 2026

View reviewed changes

src/Core/BasePlugin.php Show resolved Hide resolved

rochamarcelo reviewed Jan 18, 2026

View reviewed changes

src/Collection/CollectionTrait.php Show resolved Hide resolved

Fix phpcs violations

6650705

- Remove unused import EntityInterface from EagerLoader - Remove @inheritdoc when combined with @param/@return (coding standard violation) - Add proper type hints and @param annotations

dereuromark force-pushed the fix/phpstan-view-generic-types branch from f195061 to 6650705 Compare January 18, 2026 12:41

dereuromark marked this pull request as ready for review January 22, 2026 16:40

dereuromark added the documentation label Jan 28, 2026

Merge pull request #1 from rochamarcelo/suggestions-generic-usage-on-…

a5470a6

…view Suggestions for generic usage on view

Cleanup.

a9822fa

rochamarcelo and others added 2 commits February 1, 2026 19:39

use static instead of self used generic template on command (#2)

683bbc7

* use static instead of self used generic template * use static instead of self used generic template

Merge branch '5.x' into fix/phpstan-view-generic-types

5776304

dereuromark requested a review from markstory February 5, 2026 08:16

Resolve merge conflict with 5.x

65f5e12

Comments

Conversation

dereuromark commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Progress

Files Modified

Approach

Status

Uh oh!

LordSimal Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

dereuromark Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

dereuromark commented Jan 18, 2026

Uh oh!

Uh oh!

rochamarcelo Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rochamarcelo commented Jan 18, 2026

Uh oh!

dereuromark commented Jan 18, 2026

Uh oh!

rochamarcelo commented Jan 18, 2026

Uh oh!

dereuromark commented Jan 18, 2026

Uh oh!

dereuromark commented Jan 22, 2026

Uh oh!

rochamarcelo commented Jan 22, 2026

Uh oh!

rochamarcelo commented Jan 22, 2026

Uh oh!

dereuromark commented Feb 1, 2026

Uh oh!

rochamarcelo commented Feb 1, 2026

Uh oh!

dereuromark commented Feb 8, 2026

Uh oh!

LordSimal commented Feb 14, 2026

Uh oh!

ADmad commented Feb 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dereuromark commented Jan 17, 2026 •

edited

Loading