Hologram.Server (hologram v0.6.5)

@type t() :: %Hologram.Server{
  __meta__: Hologram.Server.Metadata.t(),
  cookies: %{required(String.t()) => any()},
  next_action: Hologram.Component.Action.t() | nil,
  session: %{required(atom()) => any()}
}

Functions

delete_cookie(server, key)

@spec delete_cookie(t(), String.t()) :: t()

Removes a cookie from the server struct and marks it for deletion in the client's browser.

If the cookie exists, it is removed from the server struct's cookies data and a delete operation is recorded in the metadata. If the cookie does not exist, this function is a no-op and returns the server struct unchanged.

Parameters

server - The server struct
key - The cookie name to delete (must be a string)

Examples

iex> server = %Hologram.Server{cookies: %{"user_id" => "123", "theme" => "dark"}}
iex> delete_cookie(server, "user_id")
%Hologram.Server{cookies: %{"theme" => "dark"}}

iex> # Deleting a nonexistent cookie is a no-op
iex> server = %Hologram.Server{cookies: %{"theme" => "dark"}}
iex> delete_cookie(server, "nonexistent")
%Hologram.Server{cookies: %{"theme" => "dark"}}

iex> server = %Hologram.Server{}
iex> delete_cookie(server, "any_key")
%Hologram.Server{cookies: %{}}

delete_session(server, key)

@spec delete_session(t(), atom() | String.t()) :: t()

Removes a session entry from the server struct and marks it for deletion in the client's browser.

If the session entry exists, it is removed from the server struct's session data and a delete operation is recorded in the metadata. If the session entry does not exist, this function is a no-op and returns the server struct unchanged.

Atom keys are automatically converted to string.

Parameters

server - The server struct
key - The session entry name to delete (atom or string)

from(conn)

@spec from(Plug.Conn.t()) :: t()

Creates a new Hologram.Server struct from a Plug.Conn struct.

Excludes "hologram_session" cookie.

get_cookie(server, key, default \\ nil)

@spec get_cookie(t(), String.t(), any()) :: any()

Retrieves a cookie value by key from the server struct.

Returns the value associated with the given key or the default value if the key does not exist in the cookies.

Parameters

server - The server struct
key - The cookie name (string)
default - The value to return if the key is not found (default: nil)

Examples

iex> server = %Hologram.Server{cookies: %{"user_id" => "abc123"}}
iex> get_cookie(server, "user_id")
"abc123"

iex> server = %Hologram.Server{cookies: %{"user_id" => "abc123"}}
iex> get_cookie(server, "nonexistent")
nil

iex> server = %Hologram.Server{cookies: %{"user_id" => "abc123"}}
iex> get_cookie(server, "nonexistent", "default_value")
"default_value"

get_cookie_ops(server)

@spec get_cookie_ops(t()) :: %{required(String.t()) => Hologram.Runtime.Cookie.op()}

Retrieves the cookie operations recorded in the server struct's metadata.

get_session(server, key, default \\ nil)

@spec get_session(t(), atom() | String.t(), any()) :: any()

Retrieves a session value by key from the server struct.

Returns the value associated with the given key or the default value if the key does not exist in the cookies.

Atom keys are automatically converted to string.

Parameters

server - The server struct
key - The session entry name (atom or string)
default - The value to return if the key is not found (default: nil)

get_session_ops(server)

@spec get_session_ops(t()) :: %{required(String.t()) => Hologram.Runtime.Session.op()}

Retrieves the session operations recorded in the server struct's metadata.

has_cookie_ops?(server)

@spec has_cookie_ops?(t()) :: boolean()

Checks if the server struct has any recorded cookie operations.

Returns true if there are any cookie operations (put or delete) in the server structs's metadata, false otherwise.

Parameters

server - The server struct

Examples

iex> server = %Hologram.Server{}
iex> has_cookie_ops?(server)
false

iex> server = %Hologram.Server{cookies: %{"user_id" => "123"}}
iex> server = put_cookie(server, "theme", "dark")
iex> has_cookie_ops?(server)
true

put_cookie(server, key, value, opts \\ [])

@spec put_cookie(t(), String.t(), any(), keyword()) :: t()

Adds a cookie to be set in the client's browser.

Parameters

server - The server struct
key - The cookie name (must be a string)
value - The cookie value
opts - Optional cookie attributes (keyword list)

Options

:domain - The domain for the cookie (default: nil)
:http_only - Whether the cookie should be accessible only through HTTP(S) requests (default: true)
:max_age - Maximum age in seconds (default: nil)
:path - The path for the cookie (default: nil)
:same_site - SameSite attribute (default: :lax)
:secure - Whether the cookie should only be sent over HTTPS (default: true)

Examples

iex> server = %Hologram.Server{}
iex> put_cookie(server, "user_id", 123)
%Hologram.Server{cookies: %{"user_id" => 123}}

iex> server = %Hologram.Server{}
iex> put_cookie(server, "theme", "dark", secure: false, path: "/admin")
%Hologram.Server{cookies: %{"theme" => "dark"}}

put_session(server, key, value)

@spec put_session(t(), atom() | String.t(), any()) :: t()

Adds a session entry.

Atom keys are automatically converted to string.

Parameters

server - The server struct
key - The session entry name (atom or string)
value - The session entry value