0
# Phoenix Web Framework
1

2
Phoenix is a comprehensive web framework for Elixir that provides a complete foundation for building scalable, maintainable web applications and APIs. It offers productive development through live code reloading, comprehensive generators, real-time features via channels and LiveView, robust authentication systems, and built-in security measures leveraging the fault-tolerant Erlang VM.
3

4
## Package Information
5

6
- **Package Name**: phoenix
7
- **Package Type**: hex
8
- **Language**: Elixir
9
- **Installation**: `{:phoenix, "~> 1.8"}` in `mix.exs`
10

11
## Core Imports
12

13
```elixir
14
# In your application
15
defmodule MyAppWeb.Endpoint do
16
  use Phoenix.Endpoint, otp_app: :my_app
17
end
18

19
# In controllers
20
defmodule MyAppWeb.PageController do
21
  use Phoenix.Controller, formats: [:html, :json]
22
end
23

24
# In channels
25
defmodule MyAppWeb.UserChannel do
26
  use Phoenix.Channel
27
end
28

29
# Common imports for utilities
30
import Phoenix.Controller
31
import Phoenix.Token
32
import Phoenix.VerifiedRoutes
33
```
34

35
## Basic Usage
36

37
```elixir
38
# Define an endpoint
39
defmodule MyAppWeb.Endpoint do
40
  use Phoenix.Endpoint, otp_app: :my_app
41

42
  plug Plug.RequestId
43
  plug Plug.Telemetry, event_prefix: [:phoenix, :endpoint]
44
  plug MyAppWeb.Router
45
end
46

47
# Define routes
48
defmodule MyAppWeb.Router do
49
  use Phoenix.Router
50

51
  pipeline :browser do
52
    plug :accepts, ["html"]
53
    plug :fetch_session
54
    plug :protect_from_forgery
55
  end
56

57
  scope "/", MyAppWeb do
58
    pipe_through :browser
59
    get "/", PageController, :index
60
    resources "/users", UserController
61
  end
62
end
63

64
# Handle requests
65
defmodule MyAppWeb.PageController do
66
  use Phoenix.Controller, formats: [:html]
67

68
  def index(conn, _params) do
69
    render(conn, "index.html", title: "Welcome")
70
  end
71
end
72
```
73

74
## Architecture
75

76
Phoenix follows the Model-View-Controller pattern with additional layers:
77

78
- **Endpoint**: Entry point that handles all requests and provides configuration
79
- **Router**: Matches URLs to controller actions using pipelines for shared functionality
80
- **Controller**: Handles requests, processes data, and renders responses
81
- **View**: Transforms data for presentation (optional with Phoenix 1.7+)
82
- **Channel**: Enables bidirectional real-time communication over WebSockets
83
- **Context**: Business logic layer that encapsulates related functionality
84
- **PubSub**: Message broadcasting system for real-time features
85
- **Presence**: Distributed user presence tracking across nodes
86

87
## Capabilities
88

89
### Core Phoenix Module
90

91
Application-level configuration and JSON library management.
92

93
```elixir { .api }
94
defmodule Phoenix do
95
  def json_library() :: module
96
  def plug_init_mode() :: :compile | :runtime
97
end
98
```
99

100
### Web Foundation and Request Handling
101

102
Core web server functionality, request routing, and response handling.
103

104
```elixir { .api }
105
defmodule Phoenix.Endpoint do
106
  @callback start_link(keyword) :: Supervisor.on_start()
107
  @callback config(atom, term) :: term
108
  @callback url() :: String.t()
109
  @callback struct_url() :: URI.t()
110
  @callback static_path(String.t()) :: String.t()
111
  @callback host() :: String.t()
112
  @callback server_info(Plug.Conn.scheme()) :: {:ok, {String.t(), pos_integer}} | :error
113
  @callback subscribe(binary, keyword) :: :ok | {:error, term}
114
  @callback unsubscribe(binary) :: :ok | {:error, term}
115
  @callback broadcast(binary, binary, term) :: :ok | {:error, term}
116
  @callback broadcast!(binary, binary, term) :: :ok
117
end
118

119
defmodule Phoenix.Router do
120
  defmacro get(path, plug, plug_opts \\ [], options \\ [])
121
  defmacro post(path, plug, plug_opts \\ [], options \\ [])
122
  defmacro put(path, plug, plug_opts \\ [], options \\ [])
123
  defmacro patch(path, plug, plug_opts \\ [], options \\ [])
124
  defmacro delete(path, plug, plug_opts \\ [], options \\ [])
125
  defmacro resources(path, controller, opts \\ [])
126
  defmacro scope(options \\ [], do: context)
127
  defmacro pipeline(name, do: block)
128
  defmacro plug(plug, opts \\ [])
129
  defmacro pipe_through(pipes)
130
end
131

132
defmodule Phoenix.Controller do
133
  def action_name(conn) :: atom
134
  def controller_module(conn) :: atom
135
  def render(conn, template_or_assigns \\ [])
136
  def json(conn, data)
137
  def text(conn, data)
138
  def html(conn, data)
139
  def redirect(conn, opts)
140
  def put_view(conn, formats)
141
  def put_layout(conn, layout)
142
end
143
```
144

145
[Web Foundation and Request Handling](./web-foundation.md)
146

147
### Real-time Communication
148

149
WebSocket channels, broadcasting, and bidirectional communication.
150

151
```elixir { .api }
152
defmodule Phoenix.Channel do
153
  @callback join(binary, map, Phoenix.Socket.t()) ::
154
    {:ok, Phoenix.Socket.t()} | {:error, term}
155
  @callback handle_in(binary, map, Phoenix.Socket.t()) ::
156
    {:noreply, Phoenix.Socket.t()} | {:reply, map, Phoenix.Socket.t()}
157

158
  def broadcast(socket, event, message)
159
  def push(socket, event, message)
160
end
161

162
defmodule Phoenix.Socket do
163
  @callback connect(map, Phoenix.Socket.t(), map) ::
164
    {:ok, Phoenix.Socket.t()} | :error
165
end
166
```
167

168
[Real-time Communication](./real-time.md)
169

170
### Security and Authentication
171

172
Token generation, CSRF protection, and secure headers.
173

174
```elixir { .api }
175
defmodule Phoenix.Token do
176
  def sign(context, salt, data, opts \\ [])
177
  def verify(context, salt, token, opts \\ [])
178
end
179

180
defmodule Phoenix.Controller do
181
  def protect_from_forgery(conn, opts \\ [])
182
  def put_secure_browser_headers(conn, headers \\ %{})
183
end
184
```
185

186
[Security and Authentication](./security.md)
187

188
### Code Generation and Development Tools
189

190
Mix tasks for generating boilerplate code and development utilities.
191

192
```elixir { .api }
193
# Mix tasks (command line)
194
mix phx.gen.html Accounts User users name:string email:string
195
mix phx.gen.json Accounts User users name:string email:string
196
mix phx.gen.live Accounts User users name:string email:string
197
mix phx.gen.auth Accounts User users
198
mix phx.gen.channel RoomChannel
199
```
200

201
[Code Generation and Development Tools](./code-generation.md)
202

203
### Testing Support
204

205
Test helpers for controllers, channels, and integration testing.
206

207
```elixir { .api }
208
defmodule Phoenix.ConnTest do
209
  def build_conn(method \\ :get, path \\ "/", params_or_body \\ nil)
210
  def get(conn, path, params \\ nil)
211
  def post(conn, path, params \\ nil)
212
  def json_response(conn, status)
213
end
214

215
defmodule Phoenix.ChannelTest do
216
  def connect(handler, params, connect_info \\ %{})
217
  def subscribe_and_join(socket, channel, topic, payload \\ %{})
218
  def push(socket, event, payload \\ %{})
219
end
220
```
221

222
[Testing Support](./testing.md)
223

224
### Distributed Presence Tracking
225

226
Track user presence across distributed nodes with real-time updates.
227

228
```elixir { .api }
229
defmodule Phoenix.Presence do
230
  @callback track(Phoenix.Socket.t(), binary, map) :: {:ok, binary}
231
  @callback list(Phoenix.Socket.t() | binary) :: map
232

233
  def track(socket, key, meta)
234
  def untrack(socket, key)
235
  def update(socket, key, meta_or_fun)
236
end
237
```
238

239
[Distributed Presence Tracking](./presence.md)
240

241
## Types
242

243
```elixir { .api }
244
# Core socket type for real-time communication
245
defmodule Phoenix.Socket do
246
  defstruct [
247
    :id, :assigns, :channel, :channel_pid, :endpoint,
248
    :handler, :joined, :join_ref, :ref, :pubsub_server,
249
    :topic, :transport, :transport_pid, :serializer
250
  ]
251

252
  @type t :: %__MODULE__{}
253
end
254

255
# Connection type for HTTP requests
256
@type Plug.Conn.t :: %Plug.Conn{}
257

258
# Token options
259
@type token_opts :: [
260
  max_age: pos_integer,
261
  key_iterations: pos_integer,
262
  key_length: pos_integer,
263
  key_digest: atom
264
]
265
```