View Source Phoenix.Param protocol (Phoenix v1.7.12)

A protocol that converts data structures into URL parameters.

This protocol is used by URL helpers and other parts of the Phoenix stack. For example, when you write:

user_path(conn, :edit, @user)

Phoenix knows how to extract the :id from @user thanks to this protocol.

By default, Phoenix implements this protocol for integers, binaries, atoms, and structs. For structs, a key :id is assumed, but you may provide a specific implementation.

Nil values cannot be converted to param.

Custom parameters

In order to customize the parameter for any struct, one can simply implement this protocol.

However, for convenience, this protocol can also be derivable. For example:

defmodule User do
  @derive Phoenix.Param
  defstruct [:id, :username]
end

By default, the derived implementation will also use the :id key. In case the user does not contain an :id key, the key can be specified with an option:

defmodule User do
  @derive {Phoenix.Param, key: :username}
  defstruct [:username]
end

will automatically use :username in URLs.

When using Ecto, you must call @derive before your schema call:

@derive {Phoenix.Param, key: :username}
schema "users" do

Summary

Types

t()

All the types that implement this protocol.

Types

@type t() :: term()

All the types that implement this protocol.

Functions

@spec to_param(term()) :: String.t()