Narrow Model API

[jordisala1991]

Subject

I am targeting this branch, because this is a BC break.

Changelog

### Changed
- Narrow the API for classes declared under the `Sonata\AdminBundle\Model\` namespace.

I have applied PHPStan level 8 when doing it and all of the errors related to the typehints are done.

[jordisala1991]

I had to change a little more things:

I reduced the number of method on the test Datagrid.php (it had old methods that are already removed)
Removing them caused a bug on template where we didn't follow correctly this message (probably my bad):
https://github.com/sonata-project/SonataAdminBundle/blob/3.x/src/Model/ModelManagerInterface.php#L266-L267

So I changed that too.

[jordisala1991]

ping @sonata-project/contributors

[VincentLanglet]

class-string and array-key are not handled by Phpstorm.

I don't know if it's not better to write

@param string
@phpstan-param class-string

[jordisala1991]

How are you dealing with this on dbal @greg0ire , vscode does not recognise it but does not complain either, and it becomes harder to spot those mistakes

[jordisala1991]

Also when adding psalm do I have to write param, psalm-param and phpstan-param?

[greg0ire]

We are using prefixes (psalm- in dbal, phpstan- in annotations, which does not have Psalm yet). I think one of psalm-param or phpstan-param would be enough. Anyway, it's an issue with VSCode and PHPStorm, and I use none of those, so I don't know the details well enough.

[jordisala1991]

The idea is to use it for array-key and for class-string? Also for using generics like: array<string, string> we should do like:

@param string[] $var
@phpstan-param array<string, string> $var

I guess phpstorm does not work for @template tag or does it work? Doing something like:

@template T of object

@param T $foo
@return T

Not sure if I should revert to basic phpdoc, or figure this out on this PR, to move on with the same idea on next PRs

[VincentLanglet]

The idea is to use it for array-key and for class-string? Also for using generics like: array<string, string> we should do like:

@param string[] $var
@phpstan-param array<string, string> $var

Phpstorm understand array when you write array<string, string>. I think that's enough.
So on my projects I don't annoy myself and write.

@param array<string, string> $var

But for array-key and class-string, I prefer to use

@param string       $bar
@param string|int $foo

@phpstan-param class-string $bar
@phpstan-param array-key     $foo

In order to work with phpstorm.

I guess phpstorm does not work for @template tag or does it work? Doing something like:

@template T of object

@param T $foo
@return T

Indeed

@template T of object
 
@param object $foo
@phpstan-param T $foo

@return object
@phpstan-return T

seems better to me.

[jordisala1991]

This method on 3.x was deprecated, (will be removed once we merge 3.x with master, and we removed deprecated code again) but I wanted to show how this would have been (the relevant lines are the phpdoc, not this one). cc/ @VincentLanglet @phansys

[VincentLanglet]

I like this way.

[jordisala1991]

We should be ready to go now. Please review @sonata-project/contributors

[jordisala1991]

Lets have this one for now, Thank you for your reviews :)