Phoenix.Socket

Defines a socket and its state.

Phoenix.Socket is used as a module for establishing and maintaining the socket state via the Phoenix.Socket struct.

Once connected to a socket, incoming and pubsub events are routed to channels. The incoming client data is routed to channels via transports. It is the responsibility of the socket to tie transports and channels together.

By default, Phoenix supports both websockets and longpoll transports. For example:

transport :websockets, Phoenix.Transports.WebSocket

The command above means incoming socket connections can be done via the WebSocket transport. Events are router by topic to channels:

channel "rooms:lobby", MyApp.LobbyChannel

See Phoenix.Channel for more information on channels. Check each transport module to check the options specific to each transport.

Socket Behaviour

Socket handlers are mounted in Endpoints and must define two callbacks:

Examples

defmodule MyApp.UserSocket do
  use Phoenix.Socket

  transport :websockets, Phoenix.Transports.WebSocket
  channel "rooms:*", MyApp.RoomChannel

  def connect(params, socket) do
    {:ok, assign(socket, :user_id, params["user_id"])}
  end

  def id(socket), do: "users_socket:#{socket.assigns.user_id}"
end

# Disconnect all user's socket connections and their multiplexed channels
MyApp.Endpoint.broadcast("users_socket:" <> user.id, "disconnect")

Socket Fields

Custom transports

See the Phoenix.Socket.Transport documentation for more information on writing your own transports.

Source

Summary

assign(socket, key, value)

Adds key/value pair to socket assigns

channel(topic_pattern, module, opts \\ [])

Defines a channel matching the given topic and transports

transport(name, module, config \\ [])

Defines a transport with configuration

Types

t :: %Phoenix.Socket{id: nil, assigns: %{}, channel: atom, channel_pid: pid, endpoint: atom, handler: atom, joined: boolean, pubsub_server: atom, ref: term, topic: String.t, transport: atom, transport_name: atom, serializer: atom, transport_pid: pid}

Functions

assign(socket, key, value)

Adds key/value pair to socket assigns.

Examples

iex> socket.assigns[:token]
nil
iex> socket = assign(socket, :token, "bar")
iex> socket.assigns[:token]
"bar"
Source

Macros

channel(topic_pattern, module, opts \\ [])

Defines a channel matching the given topic and transports.

  • topic_pattern - The string pattern, for example “rooms:“, “users:“, “system”
  • module - The channel module handler, for example MyApp.RoomChannel
  • opts - The optional list of options, see below

Options

  • :via - the transport adapters to accept on this channel. Defaults [:websocket, :longpoll]

Examples

channel "topic1:*", MyChannel
channel "topic2:*", MyChannel, via: [:websocket]
channel "topic",    MyChannel, via: [:longpoll]

Topic Patterns

The channel macro accepts topic patterns in two flavors. A splat argument can be provided as the last character to indicate a “topic:subtopic” match. If a plain string is provied, only that topic will match the channel handler. Most use-cases will use the “topic:*” pattern to allow more versatile topic scoping.

See Phoenix.Channel for more information

Source
transport(name, module, config \\ [])

Defines a transport with configuration.

Examples

# customize default `:websocket` transport options
transport :websocket, Phoenix.Transports.WebSocket,
  timeout: 10_000

# define separate transport, using websocket handler
transport :websocket_slow_clients, Phoenix.Transports.WebSocket,
  timeout: 60_000
Source