[PSR-19] Proposal for adding route tag

[dbuhonov]

This proposal introduces the @route tag for PSR-19.
The tag documents HTTP endpoints handled by a class, method, or action, making it easier to connect code with its corresponding routes.

This improves code readability, IDE navigation, and API documentation generation especially in frameworks where routes are implicitly defined.

Example:

/**
 * Creates a new resource.
 *
 * @route POST /resource/create
 */
class ResourceCreateAction
{
    // ...
}

Use cases:

• Enhancing discoverability of endpoints in large codebases.
• Assisting automated tools (API docs, static analyzers, IDEs).
• Providing developers with a quick reference to the route served by each action.

[Crell]

Most frameworks that define routes this way have moved to attributes already. This doesn't belong in docblocks anymore.

[dbuhonov]

Most frameworks that define routes this way have moved to attributes already. This doesn't belong in docblocks anymore.

Thanks for the feedback!

You absolutely right that most modern frameworks have moved to PHP 8 attributes for routing.
However, this proposal is not meant to replace attributes or define routing behavior it about documentation and discoverability.

The @route tag serves a different purpose:

• It provides a standardized way to describe routes across projects regardless of framework conventions.
• It helps IDE navigation, static analysis, and API documentation tools identify routes even when attributes are not present or accessible.
• It remains useful for legacy codebases or mixed PHP versions, where attributes cannot be used.

In short, the goal of @route is the same as other PSR-19 tags like @deprecated or @internal purely informational and documentation-oriented, not behavioral.

[jaapio]

As many frameworks are moving away from docblocks, tools are adjusting as well.
Today phpDocumentor for example does not only display docblocks any more. We started this years ago when people were omitting the docblocks about their functions and classes. And replaced type tags with php native type hints.

The same applies to attributes. As more meta information is moving to attributes, we started to use that as well.

When you are in your ide you can easily read the attribute. When in tools, those will have to process the attributes. By using the same information at runtime as writing time, it is always correct.

The only thing I can think of is that we try to standardize the route attribute. But that's not in scope of this PSR.

Thanks for your suggestion. But I agree with the other comments. This is not a tag that needs to be added.

[Jean85]

The only thing I can think of is that we try to standardize the route attribute. But that's not in scope of this PSR.

For reference, this could be of interest for https://github.com/php-fig/per-attributes, cc @heiglandreas

[heiglandreas]

This is definitely something that could be part of the Attributes PER. The tough challenge though might be to unify the different frameworks that are already using it to use one attribute that they can't easily modify themselves should something need to be changed.

Feel free to check out the Attributes PER process (That we are right now trying to figure out) and create a PR towards it.