phoenix-conventions/patterns/deviations.md

Phoenix Deviations from Elixir Core

Where Phoenix deliberately differs from Elixir core patterns and why.

1. Heavy Macro Usage for Performance

Elixir core philosophy: Keep macro usage minimal. From the Router source:

Phoenix does its best to keep the usage of macros low.

Phoenix deviation: The Router uses macros extensively.

Source: lib/phoenix/router.ex:106-128

We use get, post, put, and delete to define your routes. We use macros for two purposes:

• They define the routing engine... Phoenix compiles all of your routes to a single case-statement with pattern matching rules

• For each route you define, we also define metadata to implement Phoenix.VerifiedRoutes

Why the deviation: Performance. Elixir core uses macros sparingly because they add cognitive complexity. Phoenix justifies them because routing is the hottest path in a web app — compile-time optimization yields measurable request/second gains.

---

2. import without Restriction in Router

Elixir core pattern: Always use import Module, only: [...] to be explicit.

Phoenix deviation: The Router imports entire modules:

Source: lib/phoenix/router.ex:303-306

import Phoenix.Router

# TODO v2: No longer automatically import dependencies
import Plug.Conn
import Phoenix.Controller

Why the deviation: The Router is a DSL. Users need get, post, pipe_through, scope, resources, plug, fetch_session, etc. — all available without qualification. Restricting imports would make the DSL unusable.

---

3. Compile-Time State Accumulation

Elixir core pattern: Modules are generally stateless during compilation. Functions are defined and that's it.

Phoenix deviation: Aggressive use of module attribute accumulation.

Source: lib/phoenix/router.ex:297-312

defp prelude(opts) do
  quote do
    Module.register_attribute(__MODULE__, :phoenix_routes, accumulate: true)
    @phoenix_helpers Keyword.get(unquote(opts), :helpers, true)

    import Phoenix.Router
    import Plug.Conn
    import Phoenix.Controller

    # Set up initial scope
    @phoenix_pipeline nil
    Phoenix.Router.Scope.init(__MODULE__)
    @before_compile unquote(__MODULE__)
  end
end

Why the deviation: The Router needs to collect ALL routes, then compile them into a single dispatch function. This requires building up state during module compilation, then consuming it all at @before_compile.

---

4. Channel Restart Strategy: :temporary

Elixir core GenServer default: :permanent (always restart).

Phoenix Channel default: :temporary (never restart).

Source: lib/phoenix/channel.ex:464-472

def child_spec(init_arg) do
  %{
    id: __MODULE__,
    start: {__MODULE__, :start_link, [init_arg]},
    shutdown: @phoenix_shutdown,
    restart: :temporary
  }
end

Why the deviation: A crashed channel should NOT auto-restart — the client needs to explicitly reconnect and rejoin. Auto-restarting would create a channel without a connected client, which is meaningless.

---

5. Auto-Hibernation

Elixir core GenServer: No default hibernation — processes stay in memory.

Phoenix Channel: Defaults to hibernate after 15 seconds of inactivity.

Source: lib/phoenix/channel.ex:459

@phoenix_hibernate_after Keyword.get(opts, :hibernate_after, 15_000)

def start_link(triplet) do
  GenServer.start_link(Phoenix.Channel.Server, triplet,
    hibernate_after: @phoenix_hibernate_after
  )
end

Why the deviation: Web apps have many idle connections. Channels for users who are "connected but not active" are common. Hibernation reclaims memory for the heap without killing the process. A chat app with 10,000 connected users benefits enormously.

---

6. Plug.Builder vs Raw Behaviour

Elixir core: Behaviours define contracts. Implementations are manual.

Phoenix Endpoint: Uses Plug.Builder — a macro that generates the call/2 pipeline by chaining plugs at compile time.

Source: lib/phoenix/endpoint.ex:478-480

defp plug() do
  quote location: :keep do
    use Plug.Builder, init_mode: Phoenix.plug_init_mode()
    ...
  end
end

Why the deviation: The Plug specification (init/1 + call/2) is too low-level for composing dozens of middleware. Plug.Builder provides the plug macro that chains them automatically. It's a higher-level abstraction over the raw behaviour pattern.

---

7. Exception Structs with HTTP Status Codes

Elixir core exceptions: Pure data — message, maybe some context fields.

Phoenix exceptions: Include plug_status for HTTP response mapping.

Source: lib/phoenix/router.ex:2-26

defmodule NoRouteError do
  @moduledoc """
  Exception raised when no route is found.
  """
  defexception plug_status: 404, message: "no route found", conn: nil, router: nil
end

defmodule MalformedURIError do
  @moduledoc """
  Exception raised when the URI is malformed on matching.
  """
  defexception [:message, plug_status: 400]
end

Why the deviation: In a web context, exceptions need to map to HTTP status codes. Plug's error handling middleware reads plug_status to determine the response code. This bridges the gap between Elixir's exception system and HTTP semantics.