Overview

Phoenix controllers are the intermediary modules between the router and views in a Phoenix application. They handle HTTP requests, process parameters, interact with contexts, and determine what response to send back to the client. Controllers are stateless and receive a connection struct (conn) that represents the current HTTP request.

Basic Controller Structure

The simplest Phoenix controller uses the HelloWeb, :controller macro and defines actions as functions that receive the connection and parameters:

defmodule HelloWeb.PageController do
  use HelloWeb, :controller

  def home(conn, _params) do
    render(conn, :home, layout: false)
  end
end

Each controller action receives:

conn - The Plug.Conn struct representing the HTTP request/response
params - A map containing request parameters from the URL, query string, and request body

Controller Actions and Parameter Handling

Extracting Specific Parameters

Use pattern matching to extract specific parameters from the params map:

defmodule HelloWeb.HelloController do
  use HelloWeb, :controller

  def show(conn, %{"messenger" => messenger}) do
    render(conn, :show, messenger: messenger)
  end
end

Accessing Full Parameter Map

To access both a specific parameter and the full params map, use pattern matching with the = operator:

def show(conn, %{"messenger" => messenger} = params) do
  # Access to both messenger and the full params map
  render(conn, :show, messenger: messenger)
end

Ignoring Parameters

When an action doesn't need parameters, prefix the variable with an underscore to avoid compiler warnings:

def index(conn, _params) do
  render(conn, :home)
end

Renaming Actions

Action names can be customized independently of the template name:

defmodule HelloWeb.PageController do
  use HelloWeb, :controller

  def index(conn, _params) do
    # Renders :home template but action is named :index
    render(conn, :home)
  end
end

Update the router accordingly:

get "/", PageController, :index

Rendering Responses

Rendering HTML Templates

Use the render/3 function to render HTML templates via Phoenix Views:

defmodule HelloWeb.HelloController do
  use HelloWeb, :controller

  def show(conn, %{"messenger" => messenger}) do
    render(conn, :show, messenger: messenger)
  end
end

The controller and view must share a root name (e.g., HelloController and HelloHTML).

Rendering Without Layout

Disable the layout for specific actions:

def home(conn, _params) do
  render(conn, :home, layout: false)
end

Assigning Values to Templates

Using assign/3

Pass data to templates using assign/3:

def show(conn, %{"messenger" => messenger}) do
  conn
  |> assign(:messenger, messenger)
  |> render(:show)
end

Chaining Multiple Assigns

Chain multiple assigns for cleaner code:

def show(conn, %{"messenger" => messenger}) do
  conn
  |> assign(:messenger, messenger)
  |> assign(:receiver, "Dweezil")
  |> render(:show)
end

Passing Assigns Directly to render/3

For concise syntax, pass assigns directly to render/3:

def show(conn, %{"messenger" => messenger}) do
  render(conn, :show, messenger: messenger, receiver: "Dweezil")
end

Configuring Controller Formats

Configure supported response formats in your controller configuration:

def controller do
  quote do
    use Phoenix.Controller,
      formats: [:html, :json]
    ...
  end
end

This allows controllers to respond with different formats based on the request.

Flash Messages

Setting Flash Messages

Use put_flash/3 to set temporary messages:

defmodule HelloWeb.PageController do
  use HelloWeb, :controller

  def home(conn, _params) do
    conn
    |> put_flash(:error, "Let's pretend we have an error.")
    |> render(:home, layout: false)
  end
end

Flash message types:

:info - Informational messages
:error - Error messages
:warning - Warning messages (custom)
:success - Success messages (custom)

Clearing Flash Messages

Remove all flash messages from the connection:

clear_flash(conn)

Flash with Redirects

Combine flash messages with redirects to provide context after navigation:

def home(conn, _params) do
  conn
  |> put_flash(:error, "Let's pretend we have an error.")
  |> redirect(to: ~p"/redirect_test")
end

Redirects

Basic Redirect

Redirect to another route using the verified routes syntax:

def create(conn, params) do
  # ... create logic
  redirect(conn, to: ~p"/posts")
end

Redirect with Parameters

Include dynamic parameters in redirects:

def create(conn, params) do
  # ... create post
  redirect(conn, to: ~p"/posts/#{post}")
end

External Redirects

Redirect to external URLs:

def external(conn, _params) do
  redirect(conn, external: "https://example.com")
end

Action Fallback

Action fallback controllers handle error cases elegantly by centralizing error handling logic:

defmodule HelloWeb.MyController do
  use Phoenix.Controller

  action_fallback HelloWeb.MyFallbackController

  def show(conn, %{"id" => id}, current_user) do
    with {:ok, post} <- fetch_post(id),
         :ok <- authorize_user(current_user, :view, post) do
      render(conn, :show, post: post)
    end
  end
end

The fallback controller handles non-ok tuples:

defmodule HelloWeb.MyFallbackController do
  use Phoenix.Controller

  def call(conn, {:error, :not_found}) do
    conn
    |> put_status(:not_found)
    |> put_view(HelloWeb.ErrorHTML)
    |> render(:"404")
  end

  def call(conn, {:error, :unauthorized}) do
    conn
    |> put_status(403)
    |> put_view(HelloWeb.ErrorHTML)
    |> render(:"403")
  end
end

Testing Controllers

HTML Controller Tests

Test controller actions using ConnCase:

defmodule HelloWeb.PostControllerTest do
  use HelloWeb.ConnCase

  import Hello.BlogFixtures

  @create_attrs %{body: "some body", title: "some title"}
  @update_attrs %{body: "some updated body", title: "some updated title"}
  @invalid_attrs %{body: nil, title: nil}

  describe "index" do
    test "lists all posts", %{conn: conn} do
      conn = get(conn, ~p"/posts")
      assert html_response(conn, 200) =~ "Listing Posts"
    end
  end

  describe "show" do
    test "displays a single post", %{conn: conn} do
      post = post_fixture()
      conn = get(conn, ~p"/posts/#{post}")
      assert html_response(conn, 200) =~ post.title
    end
  end
end

Testing Redirects

Assert redirects in tests:

test "redirects after create", %{conn: conn} do
  conn = post(conn, ~p"/posts", post: @create_attrs)
  assert %{id: id} = redirected_params(conn)
  assert redirected_to(conn) == ~p"/posts/#{id}"
end

Testing Flash Messages

Verify flash messages are set correctly:

test "sets flash message on error", %{conn: conn} do
  conn = post(conn, ~p"/posts", post: @invalid_attrs)
  assert get_flash(conn, :error) == "Could not create post"
end

When to Use This Skill

Use this skill when you need to:

Create new controller actions to handle HTTP requests
Process and validate incoming request parameters
Render HTML templates with dynamic data
Implement user feedback with flash messages
Handle redirects after form submissions or actions
Test controller behavior and responses
Implement error handling with action fallbacks
Build RESTful API endpoints
Integrate controller actions with Phoenix contexts
Manage session data and user authentication flows
Handle file uploads and multipart forms
Implement pagination for list views
Create custom response formats (JSON, XML, etc.)
Debug request/response cycles

Best Practices

Keep controllers thin - Move business logic to contexts, keep controllers focused on HTTP concerns
Use pattern matching - Extract only the parameters you need from the params map
Validate early - Validate parameters at the controller level before passing to contexts
Use action fallback - Centralize error handling with action fallback controllers
Leverage pipeline - Use plugs for common operations like authentication and authorization
Be explicit with assigns - Pass only necessary data to templates to avoid exposing sensitive information
Use verified routes - Always use ~p sigil for route paths to catch errors at compile time
Test thoroughly - Write comprehensive tests for all controller actions and edge cases
Handle errors gracefully - Provide meaningful error messages and appropriate HTTP status codes
Use flash messages wisely - Provide clear, actionable feedback to users after actions
Avoid business logic - Controllers should orchestrate, not implement business rules
Return early - Use guard clauses and early returns for cleaner code
Consistent naming - Follow Phoenix conventions for action names (index, show, new, create, edit, update, delete)
Document complex actions - Add comments for non-obvious controller logic
Use structs over maps - Work with structs from contexts rather than raw parameter maps when possible

Common Pitfalls

Putting business logic in controllers - This makes code harder to test and reuse
Not validating parameters - Always validate and sanitize user input
Overusing assigns - Passing entire context modules or large data structures to views
Ignoring error cases - Not handling errors from context functions properly
Hard-coding paths - Using string paths instead of verified routes (~p)
Not using action fallback - Repeating error handling logic across actions
Testing implementation details - Test behavior, not internal implementation
Exposing internal errors - Leaking stack traces or internal errors to users
Not setting status codes - Forgetting to set appropriate HTTP status codes for errors
Mutating params - Attempting to modify the params map instead of using assigns
Skipping CSRF protection - Disabling security features without understanding implications
Large controller files - Creating monolithic controllers instead of splitting concerns
Not using with statements - Missing opportunities to chain operations cleanly
Forgetting content negotiation - Not handling different response formats appropriately
Mixing concerns - Handling both API and HTML responses in the same controller without proper separation

📖 phoenix-controllers