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">Sign in</.link>

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

Will be verified against your standard Phoenix.Router definitions:

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

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/2

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.

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

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

Or as a keyword list or map of values:

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

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

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)

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 the 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}"

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

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

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

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