Scoped Routes section of the Phoenix guides refers to a problem without explaining what it is ("but there is a problem")

brecabral

Documentation

While reading the Scoped Routes section, I noticed that the documentation currently refers to a problem without explaining what the problem is.

I looked at the history of this section and found that an older version of the documentation contained an explanation immediately after this part. It said:

“We can fix this problem by adding an as: :admin option to our admin scope:”

followed by:

scope "/admin", HelloWeb.Admin, as: :admin do
  pipe_through :browser

  resources "/reviews", ReviewController
end

From the older documentation, it appears that the problem being referred to was the generated path helpers having the same name, such as review_path.

My question is whether this problem still exists in the current Phoenix version.

If it has been resolved at some point, should the current documentation still mention “but there is a problem”, or should that statement be removed/updated?

4 comments

/phoenix

1 1033 4

2026-09-14 19:21:20 UTC

Marked As Solved

Show Best Posts
Show All (oldest first)
Show All (newest first)

rhcarvalho

Hi Breno, welcome to the Elixir community and the Forum!

Indeed, in Phoenix 1.7+, route helpers were replaced with Verified Routes (e.g. ~p"/reviews"), making helper name collisions irrelevant. That transition sentence ("This looks good, but there is a problem here...") was accidentally left behind without the original context explaining helper name collisions.

I’m sure a docs PR would be very welcome.

If you haven’t figured it out yet, the documentation has links that take you directly to the source code:

The particular sentence is still there in main:

github.com/phoenixframework/phoenix

guides/routing.md?plain=1

3087baacf


      
          GET     /admin/reviews/:id/edit  HelloWeb.Admin.ReviewController :edit
          GET     /admin/reviews/new       HelloWeb.Admin.ReviewController :new
          GET     /admin/reviews/:id       HelloWeb.Admin.ReviewController :show
          POST    /admin/reviews           HelloWeb.Admin.ReviewController :create
          PATCH   /admin/reviews/:id       HelloWeb.Admin.ReviewController :update
          PUT     /admin/reviews/:id       HelloWeb.Admin.ReviewController :update
          DELETE  /admin/reviews/:id       HelloWeb.Admin.ReviewController :delete
          ...
          ```
          
          This looks good, but there is a problem here. Remember that we wanted both user-facing review routes `/reviews` and the admin ones `/admin/reviews`. If we now include the user-facing reviews in our router under the root scope like this:
          
          ```elixir
          scope "/", HelloWeb do
            pipe_through :browser
          
            ...
            resources "/reviews", ReviewController
          end
          
          scope "/admin", HelloWeb.Admin do

Post #3

Also Liked

josevalim

Creator of Elixir

It has been resolved since path helpers are deprecated. It seems it is already no longer there on more recent versions of the documentation!

Post #1

brecabral

Thanks for the explanation! I opened a PR to remove the outdated statement: PR link

Hope it helps with the project!

Post #4

brecabral

Wow, first of all, I didn’t expect to get a response from José Valim himself. Thanks!

Second, I just started learning Elixir/Phoenix, so I’m going through the documentation. When I read “but there is a problem”, I started looking for an explanation and a solution to that problem.

The guide at /main/guides/routing.md on line 321, still has the same text.

Maybe I’m just misunderstanding what you mean — English isn’t my native language — but is the problem you were referring to something else? For example, is it about having both the admin routes and the regular user-facing routes?

Because that is actually the behavior I would expect, and I don’t see it as a problem. Or there is a even more recent versions of the documentation?

Post #2