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 outgoing 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 :websocket, Phoenix.Transports.WebSocket

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

channel "room:lobby", MyApp.LobbyChannel

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

Socket Behaviour

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

• connect/2 - receives the socket params and authenticates the connection. Must return a Phoenix.Socket struct, often with custom assigns.
• id/1 - receives the socket returned by connect/2 and returns the id of this connection as a string. The id is used to identify socket connections, often to a particular user, allowing us to force disconnections. For sockets requiring no authentication, nil can be returned.

Examples

defmodule MyApp.UserSocket do
  use Phoenix.Socket

  transport :websocket, Phoenix.Transports.WebSocket
  channel "room:*", 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

• id - The string id of the socket
• assigns - The map of socket assigns, default: %{}
• channel - The current channel module
• channel_pid - The channel pid
• endpoint - The endpoint module where this socket originated, for example: MyApp.Endpoint
• handler - The socket module where this socket originated, for example: MyApp.UserSocket
• joined - If the socket has effectively joined the channel
• pubsub_server - The registered name of the socket’s pubsub server
• join_ref - The ref sent by the client when joining
• ref - The latest ref sent by the client
• topic - The string topic, for example "room:123"
• transport - The socket’s transport, for example: Phoenix.Transports.WebSocket
• transport_pid - The pid of the socket’s transport process
• transport_name - The socket’s transport, for example: :websocket
• serializer - The serializer for socket messages, for example: Phoenix.Transports.WebSocketSerializer
• vsn - The protocol version of the client, for example: “2.0.0”

Custom transports

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