PhoenixFlags.Flag (PhoenixFlags v0.9.0)

Copy Markdown View Source

Struct defining a flag declaration.

Used in the flags/0 callback to declare which flags should exist:

def flags do
  [
    PhoenixFlags.Flag.new!(
      key: "enable_benefits",
      type: :boolean,
      default: "false",
      category: "integrations",
      label: "Enable Benefits",
      description: "When enabled, the Benefits integration is active."
    )
  ]
end

Fields

  • :key (required) — unique identifier for this flag
  • :type (required) — one of :boolean, :string, :integer, :decimal, :percentage, :select, :secret. Stored as atoms in declarations, converted to strings ("boolean", etc.) for database storage. :secret values are encrypted at rest via the config's :encryptor module and masked in the admin UI and audit log. Declaring a :secret flag without configuring :encryptor raises at boot.
  • :default — default value as a string (defaults to "")
  • :category — grouping key for the admin UI (defaults to "default")
  • :label — display name (defaults to the key)
  • :description — help text for the admin UI
  • :options — for :select type, a list of {label, value} tuples (e.g. [{"Mailjet", "mailjet"}])
  • :variants (required for :variant) — a list of {label, value, weight} tuples whose weights are whole numbers totalling 100 (e.g. [{"Control", "control", 90}, {"New", "new", 10}]). The declared weights become the flag's initial stored value and can then be changed at runtime from the dashboard.
  • :ttl — for :variant, how long an assignment lasts in milliseconds. nil (the default) means an assignment is permanent. A value re-rolls each caller once per window.
  • :seed — for :variant, an explicit hash seed. Without one the split is local to this flag, so concurrent experiments do not correlate. Changing it re-randomises everyone.

See PhoenixFlags.Variant for how assignment works.

Summary

Types

t()

Functions

new!(opts)

Creates a new flag struct, validating all fields.

weights(flag)

Returns the {name, weight} pairs declared for a :variant flag, or [].

Types

t()

@type t() :: %PhoenixFlags.Flag{
  category: String.t(),
  default: String.t(),
  description: String.t() | nil,
  key: String.t(),
  label: String.t() | nil,
  options: [{String.t(), String.t()}] | nil,
  seed: String.t() | nil,
  ttl: pos_integer() | nil,
  type: atom(),
  variants: [{String.t(), String.t(), non_neg_integer()}] | nil
}

Functions

new!(opts)

Creates a new flag struct, validating all fields.

Raises PhoenixFlags.Error on invalid input.

weights(flag)

Returns the {name, weight} pairs declared for a :variant flag, or [].