Update getBehavior annotation to allow better code analyse on applica… #18323

rochamarcelo · 2025-04-12T20:14:58Z

Related to CakeDC/cakephp-phpstan#44 and #18318

Add annotation to improve static analyse.

Application models will be able to use a phpdoc to set possible return types for Table::getBehavior

/**
 * Usuarios Model
 *
 * @extends \Cake\ORM\Table<array{Register: \CakeDC\Users\Model\Behavior\RegisterBehavior, Filterable: \PlumSearch\Model\Behavior\FilterableBehavior, MyC: \App\Model\Behavior\PasswordBehavior, Tree: \App\Model\Behavior\TreeBehavior}>
 */
class UsersTable extends Table
{
    use DefaultOrderTrait;

    /**
     * Initialize method
     *
     * @param array $config The configuration for the Table.
     * @return void
     */
    public function initialize(array $config): void
    {
        parent::initialize($config);

        $this->addBehavior('CakeDC/Users.Register');
        $this->addBehavior('MyC', ['className' => 'Password']);
        $this->addBehavior('Tree');
    }

    public function register()
    {
          //This will not result in phpstan error
          debug($this->getBehavior('Filterable')->filters());
    }
}

…tion.

src/ORM/Table.php

rochamarcelo · 2025-04-13T00:24:32Z

At model I've used @phpstan-extends instead of @extends, since we have that in Cake\ORM\Table class

rochamarcelo · 2025-04-13T00:32:54Z

Using @phpstan-return still doens't work perfect with PHPStorm. Psalm also complains about return type.

dereuromark · 2025-04-13T01:04:22Z

For PHPStorm the IdeHelper and meta file helps.
Does it work for PHPStan so far? I would say we can then ignore the psalm one, that tool should be decommissioned anyway.

ADmad · 2025-04-13T06:13:44Z

Using @phpstan-return still doens't work perfect with PHPStorm. Psalm also complains about return type.

Pretty much all popular stan tools and IDEs understand annotation template vars. So using un-prefixed annotations is fine. Also for consistency TBehaviors<TName> instead TBehaviors[TName].

ADmad · 2025-04-13T06:15:09Z

We already have multiple use of @template in our codebase.

dereuromark · 2025-04-13T09:18:45Z

Using @phpstan-return still doens't work perfect with PHPStorm. Psalm also complains about return type.

Pretty much all popular stan tools and IDEs understand annotation template vars. So using un-prefixed annotations is fine. Also for consistency TBehaviors<TName> instead TBehaviors[TName].

This is the first indirect case (trick for getBehavior).
And in general it would still be nice if we knew the direct types.

rochamarcelo · 2025-04-13T11:24:08Z

Using @phpstan-return still doens't work perfect with PHPStorm. Psalm also complains about return type.

Pretty much all popular stan tools and IDEs understand annotation template vars. So using un-prefixed annotations is fine. Also for consistency TBehaviors<TName> instead TBehaviors[TName].

TBehaviors[TName] is used to match defined behaviors, can't be replaced with TBehaviors<TName>

src/ORM/Table.php

rochamarcelo · 2025-04-13T15:29:29Z

Please let me know if we should use phpstan- prefix

dereuromark · 2025-04-13T15:31:04Z

Not for template, and for the others also not if it doesnt work any other way.
If it works already keeping the old param/return and adding phpstan-param/phpstan-return on top, that would be perfect and increases compatibility in general.

rochamarcelo · 2025-04-13T15:37:36Z

At PHP Storm both ways have the same behavior. It can't autcomplete methods from concrete behavior class only from \Cake\ORM\Behavior.

dereuromark · 2025-04-13T15:46:17Z

PHPStorm can itself also autocomplete, through the meta file, thats a PHPStorm internal separate topic. at least that works for sure, if we keep the old param/return.

So right now "working" I mean the new PHPStan introspection, that ideally works with prefixed param/return then.
And psalm doesnt work either way, so we can ignore that one (see first commit).

rochamarcelo · 2025-04-13T15:52:02Z

Updated. Tested at localhost with phpstan and tag generated with cakephp-ide-helper.

dereuromark · 2025-04-13T15:56:56Z

OK, I needed to run phpstan with --debug to clear the cache
Then it works with

 * @param string $name The behavior alias to get from the registry.
 * @return \Cake\ORM\Behavior
 * @template TName of key-of<TBehaviors>
 * @phpstan-param TName $name The behavior alias to get from the registry.
 * @phpstan-return TBehaviors[TName]

Just fine for me

I also verified that PHPStorm still can autocomplete through meta file, also works

override(
		\Cake\ORM\Table::getBehavior(),
		map([
			...
		]),
);

Takes care of that

dereuromark

We should probably silence the psalm issue.
Or add a psalm-* tag on top that specifically sets it for psalm to the expected behavior.

rochamarcelo · 2025-04-13T16:16:43Z

psalm tests passed with @psalm-return \Cake\ORM\Behavior

dereuromark · 2025-04-13T16:25:28Z

dereuromark/cakephp-ide-helper#374
is also done.

It would by default add the annotations only for 5.2.2+ (since before it would throw errors)
you can silence the old mixins or display both, ... full options if needed.

othercorey · 2025-04-13T17:05:42Z

src/ORM/Table.php

+     * @template TName of key-of<TBehaviors>
+     * @phpstan-param TName $name The behavior alias to get from the registry.
+     * @phpstan-return TBehaviors[TName]
+     * @psalm-return \Cake\ORM\Behavior


psalm-return looks the same as return.

Yes, but see the commits above. If not added on top, psalm goes all ballistic on us.

This is needed because psalm reads @phpstan- prefixed annotations too (and vice versa) and it doesn't understand TBehaviors[TName], hence @psalm-return is also required to override the @phpstan-return.

Update getBehavior annotation to allow better code analyse on applica…

41d6abe

…tion.

rochamarcelo mentioned this pull request Apr 12, 2025

getBehavior() support CakeDC/cakephp-phpstan#44

Closed

dereuromark mentioned this pull request Apr 12, 2025

Add new getBehavior() introspection annotation. dereuromark/cakephp-ide-helper#374

Merged

dereuromark reviewed Apr 12, 2025

View reviewed changes

src/ORM/Table.php Outdated Show resolved Hide resolved

Update annotation to use phpstan prefixed phpdoc

321847b

markstory added this to the 5.2.2 milestone Apr 13, 2025

dereuromark reviewed Apr 13, 2025

View reviewed changes

src/ORM/Table.php Outdated Show resolved Hide resolved

Don't use prefix phpstan for template phpdoc

e8230b2

dereuromark approved these changes Apr 13, 2025

View reviewed changes

dereuromark added the enhancement label Apr 13, 2025

use base return type for psalm

4032460

othercorey reviewed Apr 13, 2025

View reviewed changes

markstory merged commit 417b769 into cakephp:5.x Apr 13, 2025
13 checks passed

rochamarcelo deleted the feature/get-behavior-annotation branch April 14, 2025 10:56

dereuromark mentioned this pull request Apr 16, 2025

5.x: Remove PHPStan silencing for getBehavior() proxy calls. #18344

Merged

dereuromark mentioned this pull request Apr 18, 2025

Fix up template annotation. #18351

Merged

LordSimal mentioned this pull request May 3, 2025

Missing Table generic definitions CakeDC/users#1131

Open

Update getBehavior annotation to allow better code analyse on applica… #18323

Update getBehavior annotation to allow better code analyse on applica… #18323

Uh oh!

Conversation

rochamarcelo commented Apr 12, 2025

Uh oh!

Uh oh!

rochamarcelo commented Apr 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rochamarcelo commented Apr 13, 2025

Uh oh!

dereuromark commented Apr 13, 2025

Uh oh!

ADmad commented Apr 13, 2025

Uh oh!

ADmad commented Apr 13, 2025

Uh oh!

dereuromark commented Apr 13, 2025

Uh oh!

rochamarcelo commented Apr 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

rochamarcelo commented Apr 13, 2025

Uh oh!

dereuromark commented Apr 13, 2025

Uh oh!

rochamarcelo commented Apr 13, 2025

Uh oh!

dereuromark commented Apr 13, 2025

Uh oh!

rochamarcelo commented Apr 13, 2025

Uh oh!

dereuromark commented Apr 13, 2025

Uh oh!

dereuromark left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rochamarcelo commented Apr 13, 2025

Uh oh!

dereuromark commented Apr 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

othercorey Apr 13, 2025

Choose a reason for hiding this comment

Uh oh!

dereuromark Apr 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ADmad Apr 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rochamarcelo commented Apr 13, 2025 •

edited

Loading

rochamarcelo commented Apr 13, 2025 •

edited

Loading

dereuromark left a comment •

edited

Loading

dereuromark commented Apr 13, 2025 •

edited

Loading

dereuromark Apr 13, 2025 •

edited

Loading