Provides route generation with compile-time verification.

Use of the sigil_p macro allows paths and URLs throughout your application to be compile-time verified against your Phoenix router(s). For example, the following path and URL usages:

<.link href={~p"/sessions/new"} method="post">Log in</.link>

redirect(to: url(~p"/posts/#{post}"))copy

Will be verified against your standard Phoenix.Router definitions:

get "/posts/:post_id", PostController, :show
post "/sessions/new", SessionController, :createcopy

Unmatched routes will issue compiler warnings:

warning: no route path for AppWeb.Router matches "/postz/#{post}"
  lib/app_web/controllers/post_controller.ex:100: AppWeb.PostController.show/2copy

Additionally, interpolated ~p values are encoded via the Phoenix.Param protocol. For example, a %Post{} struct in your application may derive the Phoenix.Param protocol to generate slug-based paths rather than ID based ones. This allows you to use ~p"/posts/#{post}" rather than ~p"/posts/#{post.slug}" throughout your application. See the Phoenix.Param documentation for more details.

Finally, query strings are also supported in verified routes, either in traditional form:

~p"/posts?page=#{page}"copy

Or as a keyword list or map of values:

params = %{page: 1, direction: "asc"}
~p"/posts?#{params}"copy

Like path segments, query strings params are proper URL encoded and may be interpolated directly into the ~p string.

What about named routes?

Many web frameworks, and early versions of Phoenix, provided a feature called "named routes". The idea is that, when you define routes in your web applications, you could give them names too. In Phoenix that was done as follows:

get "/login", SessionController, :create, as: :logincopy

And now you could generate the route usnig the login_path function.

Named routes exist to avoid hardcoding routes in your templates, if you wrote <a href="/login"> and then changed your router, the link would point to a page that no longer exist. By using login_path, we make sure it always points to a valid URL in our router. However, named routes come with the downsides of indirection: when you look at the code, it is not immediately clear which URL will be generated. Furthermore, if you have an existing URL and you want to add it to a template, you need to do a reverse lookup and find its name in the router. At the end of the day, named routes are arbitrary names that need to be memorized by developers, adding cognitive overhead.

Verified routes tackle this problem by allowing the routes to be written as we would read them in a browser, but using the ~p sigil to guarantee they actually exist at compilation time. They remove the indirection of named routes while keeping their guarantees.

In any case, if part of your application requires features similar to named routes, then remember you can still leverage Elixir features to achieve the same result. For example, you can define several functions as named routes to be reused across modules:

def login_path, do: ~p"/login"
def user_home_path(user), do: ~p"/users/#{user.username}"copy

Options

To verify routes in your application modules, such as controller, templates, and views, use Phoenix.VerifiedRoutes, which supports the following options:

• :router - The required router to verify ~p paths against
• :endpoint - The optional endpoint for ~p script_name and URL generation
• :statics - The optional list of static directories to treat as verified paths

For example:

use Phoenix.VerifiedRoutes,
  router: AppWeb.Router,
  endpoint: AppWeb.Endpoint,
  statics: ~w(images)copy

Usage

The majority of path and URL generation needs your application will be met with ~p and url/1, where all information necessary to construct the path or URL is provided by the compile-time information stored in the Endpoint and Router passed to use Phoenix.VerifiedRoutes.

That said, there are some circumstances where path/2, path/3, url/2, and url/3 are required:

• When the runtime values of the %Plug.Conn{}, %Phoenix.LiveSocket{}, or a %URI{} dictate the formation of the path or URL, which happens under the following scenarios:

  • Phoenix.Controller.put_router_url/2 is used to override the endpoint's URL
  • Phoenix.Controller.put_static_url/2 is used to override the endpoint's static URL

• When the Router module differs from the one passed to use Phoenix.VerifiedRoutes, such as library code, or application code that relies on multiple routers. In such cases, the router module can be provided explicitly to path/3 and url/3.

Tracking Warnings

All static path segments must start with forward slash, and you must have a static segment between dynamic interpolations in order for a route to be verified without warnings. For example, the following path generates proper warnings

~p"/media/posts/#{post}"copy

While this one will not allow the compiler to see the full path:

type = "posts"
~p"/media/#{type}/#{post}"copy

In such cases, it's better to write a function such as media_path/1 which branches on different ~p's to handle each type.

Like any other compilation warning, the Elixir compiler will warn any time the file that a ~p resides in changes, or if the router is changed. To view previously issued warnings for files that lack new changes, the --all-warnings flag may be passed to the mix compile task. For the following will show all warnings the compiler has previously encountered when compiling the current application code:

$ mix compile --all-warnings
copy

*Note: Elixir >= 1.14.0 is required for comprehensive warnings. Older versions will compile properly, but no warnings will be issued.