Function hint - possible values for parameters

Question

Is it possible to show a user of PhpStorm what the possible function arguments are, not just the type of argument?

For example, I have a function that will show the programmer that two strings are needed, as shown in this graphic:

However, I would like the hint to show the possible values for each variable - tag and tag_type in this example; e.g.,

• The possible values for tag are "full, view, edit, add, or delete".
• The possible values for variable tag_type is a list of about 10 or so activities in the database.

Here is the code I have. Can it be changed to show the user in PhpStorm what the allowed variable values are?

/**
 * @param string $tag
 * @param string $tag_type
 * @return int
 *
 * [tag] = full, view, edit, add, or delete
 * [type] = all, activities, grades, orders, people, schools, users, team_classes,
 *          coaches, team_parents, or organization
 *
 * by default, if leave arguments blank, you are asking if the current user is a full admin,
 */
public function isAdmin(string $tag = '', string $tag_type = ''){

    if ($this->isFullAdmin())
        return true;

    return $this->tagas()
        ->where('tag', '=', 'full')
        ->where('tag_type', '=', $tag_type)
        ->orWhere(function($query) use ($tag, $tag_type) {
            $query->where('tag','=',$tag)
                  ->where('tag_type','=', $tag_type);
        })->count();
}

---

Okay, I came up with this, but it doesn't seem to be working. I checked my php version with phpversion() and it is 8.0.2.

    public function isAdmin(
        #[ExpectedValues(['all', 'activities', 'grades', 'orders', 'people', 'schools', 'users',
            'team_classes','coaches', 'team_parents', 'organization'])] string $tag_type = '',
        #[ExpectedValues(['*', 'full', 'view', 'edit', 'add', 'delete'])] string $tag = '*'
    ){

Yet it has only changed the type hinting slightly.

It shows [ExpectedValues] but doesn't show the actual expected values?

Answer 1

You can use PhpStorm Advanced Metadata. In particular: Arguments Accepted by a Method functionality -- https://www.jetbrains.com/help/phpstorm/ide-advanced-metadata.html#expected-arguments.

Make a separate PHP-alike file named .phpstorm.meta.php and place it in the project root. PhpStorm will parse and use the data from this file in appropriate places. Works with any modern PHP version; it is used by Laravel IDE Helper as well as by Symfony plugin to name a few.

<?php

namespace PHPSTORM_META {
    expectedArguments(\AUser::isAdmin(), 0, 'full', 'view', 'edit', 'add', 'delete');
}

---

For PHP 8 you can use custom #[ExpectedValues] PHP attribute made by JetBrains:

• https://github.com/JetBrains/phpstorm-attributes#expectedvalues
• https://blog.jetbrains.com/phpstorm/2020/12/phpstorm-2020-3-release/#expectedvalues

This way all values are stored together with the method itself and not a separate file.

<?php
declare(strict_types=1);

use JetBrains\PhpStorm\ExpectedValues;

class AUser {
    /**
     * Bla-bla ...
     * 
     * By default, if leave arguments blank, you are asking if the current user is a full admin.
     * 
     * @param string $tag
     * @param string $tag_type
     * @return int
     * 
     */
    public function isAdmin(
        string $tag = '',
        #[ExpectedValues(['all', 'activities', 'grades', 'orders', 'people', 'schools', 'users', 'team_classes', 'coaches', 'team_parents', 'organization'])]
        string $tag_type = ''
    )
    {
        if ($this->isFullAdmin()) {
            return true;
        }

        return $this->tagas()
            ->where('tag', '=', 'full')
            ->where('tag_type', '=', $tag_type)
            ->orWhere(function($query) use ($tag, $tag_type) {
                $query->where('tag','=',$tag)
                      ->where('tag_type','=', $tag_type);
            })->count();
    }
}

$user = new AUser();
$user->isAdmin('full', '');

The IDE can also hint you that an unexpected value is used:

NOTE: it's a Weak Warning severity so it's not super visible (you may adjust that in the inspection settings):