Calling Developers!
We are reenergizing our code contribution process! Learn More

What are the Slack Archives?

It’s a history of our time together in the Slack Community! There’s a ton of knowledge in here, so feel free to search through the archives for a possible answer to your question.

Because this space is not active, you won’t be able to create a new post or comment here. If you have a question or want to start a discussion about something, head over to our categories and pick one to post in! You can always refer back to a post from Slack Archives if needed; just copy the link to use it as a reference..

*Modern PHPDoc Annotations?* I started seen Spryker modules doing this refactoring, from `Type[]` s

Options
Chemaclass
Chemaclass Tech Lead Spryker Solution Partner Posts: 213 🧑🏻‍🚀 - Cadet
edited January 2022 in Knowledge Sharing

Modern PHPDoc Annotations?

I started seen Spryker modules doing this refactoring, from Type[] syntax to array<Type> syntax. And that’s good, but it can be even better.
• You can use list<Type> to express that it’s a numerical-ordered number array
◦ sort of array<int, Type>
• You can use array<KeyType, ValueType> to tell the types of the keys and the values for your key-value array.
◦ For example: ['str-key1' => 1, 'str-key2' => 2]) would be array<string, int>
• Even more, if you have an array where you want to define the keys, because you know them in advance, and they might have different types, you can even specify them individually
◦ For example: ['name' => 'Alice', 'age' => 30] would be array{name:string, age:int}
Psalm and PHPStan support this syntax! You can read with more details these in the Modern PHPDoc Annotation part in this blogpost: https://dev.to/suckup_de/modern-phpdoc-annotations-11d4

Comments

  • Chemaclass
    Chemaclass Tech Lead Spryker Solution Partner Posts: 213 🧑🏻‍🚀 - Cadet
    Options

    But maybe to be able to use this feature you need to exclude some Coding Standard rules such as:

    <rule ref="Spryker.Commenting">
        <exclude name="Spryker.Commenting.DocBlockParam"></exclude>
        <exclude name="Spryker.Commenting.DocBlockParamAllowDefaultValue"></exclude>
    </rule>
    

    Otherwise, it’s possible that list<Type> is not recognised, and also you can’t use array<TypeKey,TypeValue> .
    I’m saying this because this was preventing me to use this modern PHPDoc Annotations, so I disabled these two rules, and now we can use this without any problem.

  • We are currently looking into opening it for all modern ones.
    Especially generics.

    As for the list<> one:
    Do all IDEs yet support and understand it?
    This is a deal breaker otherwise, as most importantly the developers need to be able to work with those, meaning the IDE needs to show them the iterative elements properly.
    Until very recently this was not the case for generics, thats why we waited this long.

    The tools always understand it easily, sure.
    But thats why you are encouraged to not modify the code sniffer ruleset but to use @phpstan-*/psalm-* specific annotations on top here on those custom and non-IDE-supported new types instead.

  • Chemaclass
    Chemaclass Tech Lead Spryker Solution Partner Posts: 213 🧑🏻‍🚀 - Cadet
    Options

    I personally didn’t face any problem in PhpStorm with list<> syntax. Regarding other IDEs I can’t tell.

    And regarding using @phpstan-*/psalm-* I would personally use them only when it’s something specific (e.g: @phpstan-ignore-line) and not for common purpose annotations like @var or @return.

    And yeah, this is especially powerful for generics annotations 👍🏼 !

  • Unknown
    edited January 2022
    Options

    Afaik you can already use any generics now without issues. The sniffer does not complain if you set config to "false"

    /**
     * Use this to keep legacy collection objects as `\FQCN|type[]` instead of
     * `\FQCN<type>` for all non-trivial object types. This helps IDEs to understand this,
     * as long as they do not yet understand new generics here.
     *
     * @var bool
     */
    public $legacyCollectionObjects = true;
    

    The next major should have this part removed.

    I will check into the list topic soon as well for you.

  • If you have time (or anyone else is interested for that matter), there is an open branch you can PR against for further improvements:
    https://github.com/spryker/code-sniffer/pull/315
    We plan to ship this in the next weeks/months, but with collaboration this could be sped up to even only a few weeks.