View Source Plug.Builder (Plug v1.14.2)

Conveniences for building plugs.

You can use this module to build a plug pipeline:

defmodule MyApp do
  use Plug.Builder

  plug Plug.Logger
  plug :hello, upper: true

  # A function from another module can be plugged too, provided it's
  # imported into the current module first.
  import AnotherModule, only: [interesting_plug: 2]
  plug :interesting_plug

  def hello(conn, opts) do
    body = if opts[:upper], do: "WORLD", else: "world"
    send_resp(conn, 200, body)

Multiple plugs can be defined with the plug/2 macro, forming a pipeline. The plugs in the pipeline will be executed in the order they've been added through the plug/2 macro. In the example above, Plug.Logger will be called first and then the :hello function plug will be called on the resulting connection.

Plug.Builder also imports the Plug.Conn module, making functions like send_resp/3 available.



When used, the following options are accepted by Plug.Builder:

  • :init_mode - the environment to initialize the plug's options, one of :compile or :runtime. Defaults :compile.

  • :log_on_halt - accepts the level to log whenever the request is halted

  • :copy_opts_to_assign - an atom representing an assign. When supplied, it will copy the options given to the Plug initialization to the given connection assign


Plug behaviour

Internally, Plug.Builder implements the Plug behaviour, which means both the init/1 and call/2 functions are defined.

By implementing the Plug API, Plug.Builder guarantees this module is a plug and can be handed to a web server or used as part of another pipeline.


Overriding the default Plug API functions

Both the init/1 and call/2 functions defined by Plug.Builder can be manually overridden. For example, the init/1 function provided by Plug.Builder returns the options that it receives as an argument, but its behaviour can be customized:

defmodule PlugWithCustomOptions do
  use Plug.Builder
  plug Plug.Logger

  def init(opts) do

The call/2 function that Plug.Builder provides is used internally to execute all the plugs listed using the plug macro, so overriding the call/2 function generally implies using super in order to still call the plug chain:

defmodule PlugWithCustomCall do
  use Plug.Builder
  plug Plug.Logger
  plug Plug.Head

  def call(conn, opts) do
    |> super(opts) # calls Plug.Logger and Plug.Head
    |> assign(:called_all_plugs, true)


Halting a plug pipeline

A plug pipeline can be halted with Plug.Conn.halt/1. The builder will prevent further plugs downstream from being invoked and return the current connection. In the following example, the Plug.Logger plug never gets called:

defmodule PlugUsingHalt do
  use Plug.Builder

  plug :stopper
  plug Plug.Logger

  def stopper(conn, _opts) do

Link to this section Summary


builder_opts() deprecated

Using builder_opts/0 is deprecated.

Compiles a plug pipeline.

A macro that stores a new plug. opts will be passed unchanged to the new plug.

Link to this section Types

@type plug() :: module() | atom()

Link to this section Functions

Link to this macro


View Source (macro)
This macro is deprecated. Pass :copy_opts_to_assign on "use Plug.Builder".

Using builder_opts/0 is deprecated.

Instead use :copy_opts_to_assign on use Plug.Builder.

Link to this function

compile(env, pipeline, builder_opts)

View Source
@spec compile(Macro.Env.t(), [{plug(), Plug.opts(), Macro.t()}], Keyword.t()) ::
  {Macro.t(), Macro.t()}

Compiles a plug pipeline.

Each element of the plug pipeline (according to the type signature of this function) has the form:

{plug_name, options, guards}

Note that this function expects a reversed pipeline (with the last plug that has to be called coming first in the pipeline).

The function returns a tuple with the first element being a quoted reference to the connection and the second element being the compiled quoted pipeline.



Plug.Builder.compile(env, [
  {Plug.Logger, [], true}, # no guards, as added by the Plug.Builder.plug/2 macro
  {Plug.Head, [], quote(do: a when is_binary(a))}
], [])
Link to this macro

plug(plug, opts \\ [])

View Source (macro)

A macro that stores a new plug. opts will be passed unchanged to the new plug.

This macro doesn't add any guards when adding the new plug to the pipeline; for more information about adding plugs with guards see compile/3.



plug Plug.Logger               # plug module
plug :foo, some_options: true  # plug function