refactor: add Factories::models() to suppress PHPStan error

[kenjis]

Description
Follow-up: #5186

• add Factories::models() to suppress PHPStan error

Checklist:

• Securely signed commits
• [] Component(s) with PHPDoc blocks, only if necessary or adds value
• [] Unit testing, with >80% coverage
• [] User guide updated
• Conforms to style guide

[MGatner]

I still think this would be better handled by a stub file. I don't see the explicit method causing a problem right now but it will make maintenance harder.

I think this same docblock could be placed in a stub and work fine even though the method doesn't actually exist (not 100% sure on that but I believe so).

[kenjis]

utils/PHPStan/stubs/Factories.stub:

<?php

namespace CodeIgniter\Config;

use CodeIgniter\Database\ConnectionInterface;
use CodeIgniter\Model;
use Config\Services;

class Factories
{
    /**
     * @template T of Model
     *
     * @param class-string<T> $name
     *
     * @return T
     */
    public static function models(string $name, array $options = [], ?ConnectionInterface &$conn = null);
}

--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -61,3 +61,5 @@ parameters:
        - CI_DEBUG
        - ENVIRONMENT
        - SODIUM_LIBRARY_VERSION
+   stubFiles:
+       - utils/PHPStan/stubs/Factories.stub

But errors ocurres. Why invalid return type CodeIgniter\Model?

 ------ --------------------------------------------------------------------------------------------------------------- 
  Line   utils/PHPStan/stubs/Factories.stub                                                                             
 ------ --------------------------------------------------------------------------------------------------------------- 
  18     Method CodeIgniter\Config\Factories::models() has invalid return type CodeIgniter\Model.                       
  18     Method CodeIgniter\Config\Factories::models() has parameter $options with no value type specified in iterable  
         type array.                                                                                                    
  18     PHPDoc tag @template T for method CodeIgniter\Config\Factories::models() has invalid bound type                
         CodeIgniter\Model.                                                                                             
  18     Parameter $conn of method CodeIgniter\Config\Factories::models() has invalid type                              
         CodeIgniter\Database\ConnectionInterface.                                                                      
  18     Parameter $name of method CodeIgniter\Config\Factories::models() has invalid type CodeIgniter\Model.           
 ------ --------------------------------------------------------------------------------------------------------------- 

[MGatner]

I will have to look on desktop.

[sfadschm]

Any progress on this? The PHPStan errors are really annoying for both packages and projects...

[sfadschm]

But errors ocurres. Why invalid return type CodeIgniter\Model?

It seems that if any type is used in a stub file, there needs to be a stub file for this type, too.
Do we maybe need to add a stub for CodeIgniter\Model?

See the bottom notice here:
https://phpstan.org/user-guide/stub-files
Possibly an empty shell will be enough.

[kenjis]

@sfadschm Thank you. But unfortunately it still does not work: #5418

[sfadschm]

Is there anyone a littlle more familiar with PHPStan? (Not me unfortunately...)

I really think this should be handled somehow. In the worst case, my personal opinion would be that improving auto-complete for a single IDE (phpstorm, #5186) does not really justify having to suppress phpstan errors all across projects/packages (as these now occur in projects wherever methods of models derived from the model class are called.

[kenjis]

improving auto-complete for a single IDE (phpstorm, #5186) does not really justify having to suppress phpstan errors all across projects/packages

It is not so. PhpStorm does not need the @phpstan-return Model:
https://github.com/codeigniter4/CodeIgniter4/pull/5186/files#diff-99c83f6a1ccaee1c1ebabad8faa8dac62c69ecee1bab9ec323ea127c6a2263d0R785

But removing it causes PHPStan error.

I recommend to merge this PR. I don't know why everybody loves magic method.

[MGatner]

My ideal would still be to handle this with stub files but it seems like we lack the expertise currently to pull it off. I'm okay with proceeding since this is not a likely candidate for changes in the near future.

[sfadschm]

How about merging for now and then create a new help wanted issue to replace this workaround with stubs or whatever else is the best practice here?
Just to keep track.

[MGatner]

I wonder if adding @internal to this would cause issues with people calling it?

[MGatner]

Actually, can't we just fix this with a @method tag? https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/method.html#method

Nevermind, that is what used to be there 🤦‍♂️ They don't support generics.

[paulbalandan]

I have tried this with stub files before, way before @kenjis tried in his other PR, and it doesn't work. A better solution would be I think is a PHPStan rule for this, but merging this for now is our best compromise.

[kenjis]

A better solution would be I think is a PHPStan rule for this

I don't like to make special rules/stubs for CI4. Essentially it should not be needed.
Basically, I think if we write good OOP code, PHPStan could understand.

Apart from my own preferences, this PR is a small hack and easily can be reverted anytime.
I think merging this for now is our best choice.

[MGatner]

Does anyone have the capacity to see what impact it would have on PHPStan and PHPStorm if we added @internal to this new method?

[sfadschm]

Does anyone have the capacity to see what impact it would have on PHPStan and PHPStorm if we added @internal to this new method?

I don't have phpstorm, but it should not be affected, as the fix for the autocompletion was the other changes that led to the PHPStan errors (that are fixed with this PR). I can try if it affects PHPStan when I'm home.

[sfadschm]

Passes locally with @internal.

[kenjis]

@sfadschm Thank you for confirmation.

@MGatner I also checked. It seems @internal only strikes the models method in PhpStorm:

Do you really want to add @internal?

[MGatner]

I guess not - those strikes will get us questions and issues. Maybe just add a note on the method stating something like "This method is supplied only to assist with static analysis and should not be relied on as a non-magic method."

[sfadschm]

I guess not - those strikes will get us questions and issues. Maybe just add a note on the method stating something like "This method is supplied only to assist with static analysis and should not be relied on as a non-magic method."

And that it is not covered by the BC promise, probably.

[kenjis]

@MGatner I added a commen already.
https://github.com/codeigniter4/CodeIgniter4/pull/5358/files#diff-2642753b4779273c429a26af7d57ca99f2235e5c52748a05dabcbe5cd2970b6aR71

should not be relied on as a non-magic method

What do you mean? I don't understand what users should not do.

[sfadschm]

Basically people should not use this method in their apps/modules/whatever, as it is intended for internal SA use only.

[kenjis]

@sfadschm What's SA ?

It is not real @internal.
Users can use Factories. It is documented:
https://codeigniter4.github.io/CodeIgniter4/concepts/factories.html

[sfadschm]

@sfadschm What's SA ?

It is not real @internal. Users can use Factories. It is documented: https://codeigniter4.github.io/CodeIgniter4/concepts/factories.html

Sorry, SA is static analysis.
Yes, Factories can be used, but with Factories::models being public, people could use it directly or overwrite/extend it in their apps, which they should not, as the method can be deleted anytime. I think this is what MGatner had in mind. But lets wait for him 😄

[MGatner]

Yes, sorry to be unclear! I want this method to be considered "internal", but we can't flag it like that because IDEs will complain even though the "magic version" is acceptable.

Basically, it is fine for people to do this:

Factories::model('Foo');

But I don't want people's code to rely on this being there, so none of this:

if (method_exists(Factories::class, 'model')) {
    echo 'Modeling!';
}

@kenjis i forgot you already had a note on there, I think what you said is fine. Let's merge, unless there are more thoughts?