[Routing] Clarify route aliases examples with explicit route names

[welcoMattic]

Refers to #20638 (comment)

Actual examples for route aliasing are not crystal clear.

Now, examples in YAML, XML and PHP provide

• An original route, declared with an explicit name
• An alias to this route, with an explicit name

This change will allow to provide another clear example for route aliasing using Attribute in #20638

cc @stof @damienfern

[welcoMattic]

@javiereguiluz this one could be merged to unlock #20638

[javiereguiluz]

I'm not sure about these changes. I think the previous description (old route + new route) was more clear.

The new names (some route + alias to some route) could be less clear, especially the new route name. Including "alias" as part of the route alias is unnecessarily long in my opinion and could make some readers think that the route alias must contain that alias prefix.

Let me ask @xabbuh and @OskarStark about this. Thanks!

[welcoMattic]

I'm not sure about these changes. I think the previous description (old route + new route) was more clear.

The new names (some route + alias to some route) could be less clear, especially the new route name. Including "alias" as part of the route alias is unnecessarily long in my opinion and could make some readers think that the route alias must contain that alias prefix.

Let me ask @xabbuh and @OskarStark about this. Thanks!

I can replace "alias" with "new", but it implies underlying use case: replacing the some_route usage with the alias. In my mind aliases are not necessarily here to replace existing routes, but to co-exists.
Imagine 2 websites sharing the same codebase except templates, 1 for BrandA and another for BrandB. Route aliases can be used to name route according to the Brand name in dedicated templates.

We can add a site note to mention the alias name is not mandatory to contain "alias" word.

These changes are on purpose to clarify the behavior using the Attribute way to alias route.

[stof]

If you want to replace, you will generaly define the route with the new name and add a BC alias for the old name (especially when you want to deprecate it). That was the main confusion with the existing example. new_route_name is the deprecated name.

[welcoMattic]

I think we do not have to presume what users will do with route aliasing feature (e.g creating new route and create an alias with the old route name). Just showing how to generally use route aliasing with generic terms, and then users will adapt to their needs/preferences. WDYT?

EDIT: I've update the PR by adding a small paragaph to explain clearly how route aliasing can be used to provide BC for renamed routes.

cc @javiereguiluz

[javiereguiluz]

Maybe it's me, but this looks very confusing:

You create an alias ... and immediately deprecate it. The alias, being a new thing that you add, feels like the new route name, not the legacy route name.

---

I still think we should use names like "new_route_name" and "original_route_name" or "legacy_route_name". It's true that this alias feature can be used in different ways, but I think we should focus on its main usage and use terms that are impossible to misunderstand.

[damienfern]

I understand @javiereguiluz POV because I had the same feeling about aliases. Isn't this a sign that aliases on routes are plugged in a wrong way ?

IMHO, here is how it should be (a first draft, I don't know if it's doable):

some_route_name:
    path: /some-path
    controller: App\Controller\SomeController::index
    alias: 
          alias_to_some_route_name:
              # this outputs the following generic deprecation message:
              # Since acme/package 1.2: The "alias_to_some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
              deprecated:
                  package: 'acme/package'
                  version: '1.2'

[Jean-Beru]

IMO, the blog post explains clearly the concept of deprecating a route. We could update the documentation in that way. eg:

My current route.

some_route_name:
    path: /some-path
    controller: App\Controller\SomeController::index

I want to deprecate it in favor of new_route_name.

some_route_name:
    alias: new_route_name
    # this outputs the following generic deprecation message:
    # Since acme/package 1.2: The "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
    deprecated:
        package: 'acme/package'
        version: '1.2'

new_route_name:
    path: /some-path
    controller: App\Controller\SomeController::index

[welcoMattic]

I've addressed comments, now examples are more explicit and I hope clearer:

First code block with initial route definition

# config/routes.yaml
some_route_name:
    path: /some-path
    controller: App\Controller\SomeController::index

Second code block with an alias to the initial route

# config/routes.yaml
some_route_name:
    path: /some-path
    controller: App\Controller\SomeController::index

new_route_name:
    # "alias" option refers to the name of the route declared above
    alias: some_route_name

Third code block where we "invert" the alias to be able to deprecate the initial route

# Move the concrete route definition under ``new_route_name``
new_route_name:
    path: /some-path
    controller: App\Controller\SomeController::index

# Define the alias and the deprecation under the ``some_route_name`` definition
some_route_name:
    alias: new_route_name

    # this outputs the following generic deprecation message:
    # Since acme/package 1.2: The "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
    deprecated:
        package: 'acme/package'
        version: '1.2'

    # or

    # you can also define a custom deprecation message (%alias_id% placeholder is available)
    deprecated:
        package: 'acme/package'
        version: '1.2'
        message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'

I've also rephrased text paragraphs before and after each code block to explicitly explain what is the goal in each code block.

@javiereguiluz @Jean-Beru @damienfern @stof let me know if this version is good to you 🙏

[Jean-Beru]

Suggested change

	In the previous example, the alias was ``new_route_name`` was pointing to
	In the previous example, the alias ``new_route_name`` was pointing to