Defines a Phoenix router.

The router provides a set of macros for generating routes that dispatch to specific controllers and actions. Those macros are named after HTTP verbs. For example:

defmodule MyApp.Web.Router do
  use Phoenix.Router

  get "/pages/:page", PageController, :show
end

The get/3 macro above accepts a request of format "/pages/VALUE" and dispatches it to the show action in the PageController.

Routes can also match glob-like patterns, routing any path with a common base to the same controller. For example:

get "/dynamic*anything", DynamicController, :show

Phoenix’s router is extremely efficient, as it relies on Elixir pattern matching for matching routes and serving requests.

Helpers

Phoenix automatically generates a module Helpers inside your router which contains named helpers to help developers generate and keep their routes up to date.

Helpers are automatically generated based on the controller name. For example, the route:

get "/pages/:page", PageController, :show

will generate the following named helper:

MyApp.Web.Router.Helpers.page_path(conn_or_endpoint, :show, "hello")
"/pages/hello"

MyApp.Web.Router.Helpers.page_path(conn_or_endpoint, :show, "hello", some: "query")
"/pages/hello?some=query"

MyApp.Web.Router.Helpers.page_url(conn_or_endpoint, :show, "hello")
"http://example.com/pages/hello"

MyApp.Web.Router.Helpers.page_url(conn_or_endpoint, :show, "hello", some: "query")
"http://example.com/pages/hello?some=query"

If the route contains glob-like patterns, parameters for those have to be given as list:

MyApp.Web.Router.Helpers.dynamic_path(conn_or_endpoint, :show, ["dynamic", "something"])
"/dynamic/something"

The URL generated in the named URL helpers is based on the configuration for :url, :http and :https. However, if for some reason you need to manually control the URL generation, the url helpers also allow you to pass in a URI struct:

uri = %URI{scheme: "https", host: "other.example.com"}
MyApp.Web.Router.Helpers.page_url(uri, :show, "hello")
"https://other.example.com/pages/hello"

The named helper can also be customized with the :as option. Given the route:

get "/pages/:page", PageController, :show, as: :special_page

the named helper will be:

MyApp.Web.Router.Helpers.special_page_path(conn, :show, "hello")
"/pages/hello"

Scopes and Resources

It is very common in Phoenix applications to namespace all of your routes under the application scope:

scope "/", MyApp do
  get "/pages/:id", PageController, :show
end

The route above will dispatch to MyApp.PageController. This syntax is not only convenient for developers, since we don’t have to repeat the MyApp. prefix on all routes, but it also allows Phoenix to put less pressure in the Elixir compiler. If instead we had written:

get “/pages/:id”, MyApp.PageController, :show

The Elixir compiler would infer that the router depends directly on MyApp.PageController, which is not true. By using scopes, Phoenix can properly hint to the Elixir compiler the controller is not an actual dependency of the router. This provides more efficient compilation times.

Scopes allow us to scope on any path or even on the helper name:

scope "/api/v1", MyApp, as: :api_v1 do
  get "/pages/:id", PageController, :show
end

For example, the route above will match on the path "/api/v1/pages/:id" and the named route will be api_v1_page_path, as expected from the values given to scope/2 option.

Phoenix also provides a resources/4 macro that allows developers to generate “RESTful” routes to a given resource:

defmodule MyApp.Web.Router do
  use Phoenix.Router

  resources "/pages", PageController, only: [:show]
  resources "/users", UserController, except: [:delete]
end

Finally, Phoenix ships with a mix phoenix.routes task that nicely formats all routes in a given router. We can use it to verify all routes included in the router above:

$ mix phoenix.routes
page_path  GET    /pages/:id       PageController.show/2
user_path  GET    /users           UserController.index/2
user_path  GET    /users/:id/edit  UserController.edit/2
user_path  GET    /users/new       UserController.new/2
user_path  GET    /users/:id       UserController.show/2
user_path  POST   /users           UserController.create/2
user_path  PATCH  /users/:id       UserController.update/2
           PUT    /users/:id       UserController.update/2

One can also pass a router explicitly as an argument to the task:

$ mix phoenix.routes MyApp.Web.Router

Check scope/2 and resources/4 for more information.

Pipelines and plugs

Once a request arrives at the Phoenix router, it performs a series of transformations through pipelines until the request is dispatched to a desired end-point.

Such transformations are defined via plugs, as defined in the Plug specification. Once a pipeline is defined, it can be piped through per scope.

For example:

defmodule MyApp.Web.Router do
  use Phoenix.Router

  pipeline :browser do
    plug :fetch_session
    plug :accepts, ["html"]
  end

  scope "/" do
    pipe_through :browser

    # browser related routes and resources
  end
end

Phoenix.Router imports functions from both Plug.Conn and Phoenix.Controller to help define plugs. In the example above, fetch_session/2 comes from Plug.Conn while accepts/2 comes from Phoenix.Controller.

Note that router pipelines are only invoked after a route is found. No plug is invoked in case no matches were found.