What is the "Add #[Pure] attribute" inspection in PhpStorm checking for?

Question

I've got a very simple FormRequest class in a Laravel project. Two methods, both of which return a simple array that's partially populated by a method, but the IDE treats them differently.

<?php

namespace App\Http\Requests;

class VerifyPhoneNumber extends FormRequest {
    use Support\ValidatesPhoneNumbers;

    public function authorize(): bool {
        return true;
    }

    public function rules(): array {
        return [
            "phone_number" => $this->getPhoneNumberRules(),
            "verify_code" => ["required", "numeric", "max:999999"],
        ];
    }

    public function messages(): array {
        return [
            "phone_number.regex" => $this->getPhoneNumberMessage(),
        ];
    }
}

And the very basic trait methods:

<?php

namespace App\Http\Requests\Support;

trait ValidatesPhoneNumbers {
    protected function getPhoneNumberMessage(): string {
        return __("Some localized error message");
    }

    protected function getPhoneNumberRules(): array {
        return ["regex:/^\+?1?[2-9][0-9]{5,14}$/", "max:16"];
    }
}

The thing I'm puzzled about is that the IDE inspection complains that I should add the JetBrains\PhpStorm\Pure attribute to the rules() method, but not the messages() method.

The comments in the class definition say:

The attribute marks the function that has no impact on the program state or passed parameters used after the function execution. This means that a function call that resolves to such a function can be safely removed if the execution result is not used in code afterwards.

That doesn't really give me any clues why it treats these two methods differently. If I'm understanding the second sentence correctly, when the result of a "pure" method is unused the IDE will flag usage of the method as unused and recommend its removal.

What is the logic used to determine when this attribute is needed?

Answer 1

The rules() method has fixed (better say "side effects free") result -- it uses fixed values only. Sure, it calls getPhoneNumberRules() from a trait but it also returns fixed array (always the same). It does not make changes anywhere else (internal state or external storage).

The messages() method calls a method from a trait that calls __() to get translated message... that can come from a different source (a DB, a file) and therefore potentially can throw exceptions if a storage (file/DB) is not readable. The IDE does not know for sure if __() makes changes to a file/DB -- it's not annotated as pure and PhpStorm cannot make such decision from the methods that it uses.

---

P.S. If this inspection annoys you (which I can understand) then I suggest you just ignore such inspection and lower its severity in PhpStorm Settings to "No highlighting, only fix" (Settings (Preferences on macOS) | Editor | Inspections | PHP | Attributes | '#[Pure]' attribute can be added)

Answer 2

If a function only depends on other pure functions, then it is also pure. Since getPhoneNumberRules() just returns a fixed array, it's pure, so rules() is also pure.

But messages() calls getPhoneNumberMessage(), which calls the __() function that can return a different localized message if the location state changes, so it's not pure.

Answer 3

Use this attribute for functions that do not produce any side effects. All such PHP internal functions are already marked in PhpStorm.

#[Pure]
function compare(Foo $a, Foo $b): int
{
    return $a->a <=> $b->b;
}

Source: https://github.com/JetBrains/phpstorm-attributes#pure

As this function only does something within its own it can be called a #[Pure] function and so you know that via PhpStorm.

Answer 4

Forget about side effects for a second.

A pure function is one that is guaranteed to always give the same result if called with the same parameters.

If your application calls $verifyPhoneNumberRequest->rules() it will get a certain result. Then some other code could change the application locale and the next time you call $verifyPhoneNumberRequest->rules() in exactly the same way (i.e. without parameters), it may return a different result because the __() or trans() function checks some global state (the locale) to decide which string to return.

Pure functions only rely on their direct input parameters, and not some outside state that may or may not have been modified elsewhere.

Another criterium for pure functions is that they do not modify non-local state. It's totally possible to drop your entire database within a getUsername() method (or cause less devastating yet painful to debug modifications). However if the method is marked and approved as pure you are guaranteed that this will not happen.