jetbrains/phpstorm-attributes

PhpStorm specific attributes

phpstorm-attributes's Issues

Parameter Attribute for expected class attributes

Suggestion to add an attribute to ensure an instance has a class attribute.

class ExpectsAttribute
{
    public function __construct(
        #[ExpectedAttribute(CustomAttribute::class)]
        object $instance,
    ) {
        $this->instance = $instance;
    }
}

#[CustomAttribute]
class MyOKClass
{
}

class NotOKClass
{
}

// OK
new ExpectsAttribute(new MyOKClass());

//    Expects parameter 1 to have CustomAttribute
new ExpectsAttribute(new NotOKClass());

Thoughts?

How about #[Internal]?

Similar to the @internal Annotation it would be useful to mark classes and methods for internal use (limited scope) only. The annotation is currently only supported for classes, not methods.

[ArrayShape] doesn't work for structure inside the array

Hello, pseudocode:

    #[ArrayShape(['soldCount' => 'int', 'bookId' => 'int'])]
    public function foo(): array
    {
        $arr = [];

        $arr[] = [
            'soldCount' => 123,
            'bookId' => 453478,
        ];

        $arr[] = [
            'soldCount' => 22,
            'bookId' => 7863,
        ];


        return $arr;
    }

I'm not able to make phpstorm to suggest 'soldCount' and 'bookId' inside foreach. Is there any way how to define ArrayShape for structure inside list of items in array?

foreach ($this->foo() as $item) {
   echo $item['soldCount']; // phpstorm doesn't suggest
}

Using attributes with PHP < 8.0

Hi!

On the anouncement page it says that some of these attributes work on older versions of PHP if used on a single line (so that PHP thinks they are comments).

However if PHPStorm is configured to sync settings with this composer.json:

{
    "require": {
        "php": "^7.4 | ^8.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\": "src"
        }
    }
}

Then the attribute is shown with an error:

And the error:

At the same time the attribute works in other code:

Is that the indented behavior?

[ArrayShape] Cannot prompt using constants

this is normal

But I define it as a constant, he can't code hint

My phpstorm is installed on windows11, the version is PhpStorm 2022.1.4

Provide screenshots/GIFs in readme on each attribute

To demonstrate each attribute effect in PhpStorm and make it more understandable

Can we get a release?

PHPStan is flagging items like this because the only tag in this project does not include all of the changes.

Using `ExpectedValues` attribute with a splat argument

Hi, is it currently possible to define expected values in a function where the argument has a splat operator (...).

For example:

/**
 * @param  string ...$permissions
 * @return bool
 */
public function hasPermissionTo(
    #[ExpectedValues(['view users', 'create users', 'etc'])]
    ...$permissions
): bool
{
    //
}

Currently, I'm seeing code completion only when adding the first argument. After that, nothing.

How do I set the expected value from 0 to infinity?

How can I use the #[ExpectedValues] attribute to indicate that a method or function argument can be 0 or more? And it can only be an integer.

I would like something like this:

#[ExpectedValues([0,1, ...])]
public function test(int $arg) {}

Is there any documentation on ArrayShape?

I can't seem to find any.
The example provided in this repos readme is way too shallow to be useful in the vast majority of real-world usecases.

How do I define that the keys do not matter but the value types do?

// My impression, of how a solution could look like
#[ArrayShape([
    '*' => 'string',
])]

How do I define optional keys?

#[ArrayShape([
   'name' => 'string',
   'occupation?' => 'string',
])]

How do I define multiple valid types?

#[ArrayShape([
   'spouse' => 'string|array',
])]

How do I define numeric arrays?

#[ArrayShape([
 'int', 'int', 'int'
])]

Of arbitrary size?

#[ArrayShape([
 'int+'
])]

In my experience having required, and only required keys is quite the niche usecase. But that's the only usecase shown in the readme. Is there any way to solve the usecases presented above? Otherwise I think my code would be better documented using phpdoc's description feature...

I hope you can point me in the right direction!
Thanks! :3

Add ImPure annotation?

Hey! Since there is a Pure annotation, shouldn't there be an ImPure annotation, or at least a way to set the opposite pure state?

This is supported by PHPStan:

There are two new annotations that can be used above function and method declarations: @phpstan-pure and @phpstan-impure. Additionally, functions and methods that return void are also considered impure.
https://phpstan.org/blog/remembering-and-forgetting-returned-values

Psalm: TooManyArguments when passing a value for $mayDependOnGlobalScope to Pure attribute

Message: ERROR: TooManyArguments - foo.php:3:2 - Class JetBrains\PhpStorm\Pure has no __construct, but arguments were passed (see https://psalm.dev/026)

<?php

#[Pure(true)]
function bar($a) {
    return $a;
}

ArrayShape does not support `list()`.

<?php

#[\JetBrains\PhpStorm\ArrayShape(['int', \Throwable::class])]
function foo()
{
    return [];
}

$ret = foo();
$ret[1]->getMessage(); // Ok

[$id, $driver] = foo();
$driver->getMessage(); // Not work

[ArrayShape] Document how to set the type to nullable or even join / intersection type

There is nothing in the README that states how to set the type nullable or use a join / intersection type.
I assume it is the same as for phpdoc so '?' . DateTime::class for example.

Because I also have a problem with #13 I cannot test it.

Please use semver

Semver is the standard for PHP: https://semver.org/

ExpectedValues do not support enum class

ExpectedValues do not support enum class, sample code below

use JetBrains\PhpStorm\ExpectedValues;

enum Color:string
{
    case RED='red';
    case BLUE='blue';
}


function test(#[ExpectedValues(valuesFromClass: Color::class)] string $color):string
{
    return $color;
}


test();//autocomplete not working yet

PhpStorm complains about multiple definitions when installing this package

Today I installed PhpStorm 2020.3 and noticed this package - awesome! Works as expected and I like how the IDE proposes to add the correct attributes when it believes it's required, like for Pure and Immutable.

However, to ensure my code base is also compatible with non-PhpStorm environments, I've also installed this package with composer require --dev jetbrains/phpstorm-attributes and now PhpStorm complains how there are multiple definitions for the attribute classes I use: "Multiple definitions exist for class 'Immutable'". It detects both the class loaded via PhpStorm and the class loaded via Composer in the vendor directory.

Is there any way to convince PhpStorm to use either?

Specify two ArrayShapes for a function.

Hi, its posible specify two ArrayShapes for a function.

public function text(array $attributes = [], array $config = []): self

I would like to specify the attributes for each array try:

#[ArrayShape(['attributes' => ['dirname' => 'string'], 'config' => ['key' => int]])]
public function text(array $attributes = [], array $config = []): self

But it didn't work thanks for the help.

[ArrayShape] Not working on properties

<?php

declare(strict_types=1);

namespace App;

use DateTimeInterface;
use IteratorAggregate;
use JetBrains\PhpStorm\ArrayShape;

final class MyList implements IteratorAggregate
{
    #[
        ArrayShape([
            'name' => 'string',
            'from' => DateTimeInterface::class,
            'to'   => '?' . DateTimeInterface::class,
        ])
    ]
    private array $rawList;

    public function __construct(
        iterable $rawList
    ) {
        $this->rawList = $rawList;
    }

    public function getIterator()
    {
        foreach ($this->rawList as $rawItem) {
            $rawItem[''] // expecting autocomplete but nothing shows.
        }
    }
}

With the above example the autocomplete is not working... Did I do something wrong ?

Is there any plan to support Property,Method etc. as alternatives to phpdoc?

In the past, we took advantage of magic methods to simplicify our development, and as metadata, we parse the @properties and @methods from phpdoc into php code. Without syntax support, these are fragile. I am exploring to replace these to Attibutes, but which are inconvenient after losing IDE support.
So, I was wondering if it's possible that you can implement this feature.

Again with Attributes

Hello guys first and foremost sorry for my bad English, but not is my primary language.

PHP Attributes are supported by PHPStorm and the downloadable package in this github allows users to provide attributes even to those who use IDEs different from PHPStorm.

The question at this point is only one.

If I want to define custom Attributes how can I tell PHPStorm not to use its built-in?

In the Settings->Inspection section I saw that it is possible to disable the inspection, but in doing so the help that PHPStorm gives to programmers during the inspection phase is lost by signaling when it would be useful/necessary to use an Attribute.

Wouldn't it be possible to make the inspection go further in the case of a Custom Attribute by merely indicating that that method or property needs an attribute?

I believe that allowing developers to harness the power of PHPStorm inspection by allowing them to customize attributes would be a very useful feature.

At the moment if I assign a custom attribute to a method or property PHPStorm keeps saying that it wants to use its built-in.

I hope I have explained myself in an understandable way.

I wish you a good job, keep it up.

Adriano

Impossible to read properties from `#[ExpectedValues]`

Our codebase is annotated with #[ExpectedValues] and for a custom analyzer I want to read some of these but that's not possible.

phpstorm-attributes/src/ExpectedValues.php

Line 40 in 411f40e

public function __construct(array $values = [], array $flags = [], string $valuesFromClass = null, string $flagsFromClass = null)

Please change the attributes so that the variables are public readonly or add getters so that the values can be retrieved.

[ArrayShape] for maps/associative arrays as dynamic array indexes

Right now if I have following attribute

class Shema {
   #[ArrayShape(['string' => Property::class])]
    public array $properties;
}

$schema->properties['prop1'] = new Property();
$shcema->properties['prop2'] = new Property();

PHPStorm (PhpStorm 2023.3.4) will report on key Value should be one of: 'string' (why value?).

Is there any way to show possible index values? Like "string" / "int" / "SomeEnum->getValues()"