@spec admin_label_presets() :: keyword(String.t())

The preset names the admin area can be called by, as {preset, url_segment}.

"Reads as" is the ENGLISH rendering. Each is a gettext/1 msgid translated in every shipped locale — that is the point of the list being closed, and what a free-typed string cannot do. Rendered by PhoenixKitWeb.Components.Core.AdminLabel.preset_text/1.

mix phoenix_kit.install and mix phoenix_kit.update write this same list into the host's config/config.exs as a comment block (PhoenixKit.Install.AdminLabelConfig), so it is in front of a developer at the moment they go to change it.

iex> PhoenixKit.Config.admin_label_presets() |> Keyword.keys() |> Enum.take(3)
[:admin_panel, :dashboard, :backoffice]

@spec admin_panel_label() :: {:preset, atom()} | {:custom, String.t()}

What the admin area is called — a translated preset, or a host's own string.

Returns {:preset, atom} (rendered through gettext/1, so every visitor reads it in their own language) or {:custom, binary} (shown verbatim to everyone). Never nil: the fallback is {:preset, :admin_panel}.

Resolution order

1. config :phoenix_kit, admin_panel_label: :console — an explicit preset from admin_label_presets/0.

2. config :phoenix_kit, admin_panel_label: "Acme HQ" — free text. The escape hatch for a brand name no preset covers. ⚠️ Not translated: one string, shown to every visitor whatever their language.

3. Unset — derived from :admin_path, so the URL and the wording stay aligned by construction rather than by the host remembering to set two keys:

   config :phoenix_kit, admin_path: "/backoffice"
   #=> {:preset, :backoffice} — URL /backoffice, header "Backoffice"

   - and _ are equivalent in the segment (/control-panel and /control_panel both derive :control_panel).

A segment that matches no preset — /x7q, or any deliberately obscure rename — derives {:preset, :admin_panel} rather than inventing a label from the URL.

Unrecognised values fall back, they do not raise

Unlike get_admin_path/0, a bad value here is cosmetic: a typo must not take the admin area down in production. An unknown atom, a blank string or a non-string, non-atom value falls through to the derivation in step 3.

Examples

iex> PhoenixKit.Config.admin_panel_label()
{:preset, :admin_panel}

# With `config :phoenix_kit, admin_panel_label: :console`:
iex> PhoenixKit.Config.admin_panel_label()
{:preset, :console}

@spec clear_admin_path_cache() :: :ok

Clears the cached admin segment.

Call this if you change the admin_path config at runtime (rare, and it does NOT move the routes — those were compiled into the host router).

@spec clear_url_prefix_cache() :: :ok

Clears the cached URL prefix.

Call this if you change the url_prefix config at runtime (rare).

@spec default_locale() :: String.t()

Returns the default locale for the application.

Parent apps can override via config:

config :phoenix_kit,
  default_locale: "es-ES"

Defaults to "en-US" if not configured.

Examples

iex> PhoenixKit.Config.default_locale()
"en-US"

# With custom config:
iex> PhoenixKit.Config.default_locale()
"es-ES"

@spec get(atom()) :: {:ok, any()} | :not_found

Gets a specific configuration value.

Uses direct Application.get_env lookup for performance (avoids iterating all config keys on every call).

@spec get(atom(), any()) :: any()

Gets a specific configuration value with a default.

Examples

iex> PhoenixKit.Config.get(:mailer, PhoenixKit.Mailer)
MyApp.Mailer

iex> PhoenixKit.Config.get(:nonexistent, :default)
:default

@spec get_admin_path() :: String.t()

The top-level URL segment for the admin area — "/admin" unless configured.

config :phoenix_kit, admin_path: "/backoffice"

This renames the segment inside the mount prefix, so the example above serves the admin area at /phoenix_kit/backoffice/.... It is independent of :url_prefix, which names the mount itself.

/admin stays the canonical name in code

Nothing in core (or in a module package) is written against the configured value. Call sites keep saying Routes.path("/admin/users"); the substitution happens in exactly two places, and they are inverses:

• emitting a URL — PhoenixKit.Utils.Routes.apply_admin_segment/1, reached from Routes.path/2 and Routes.admin_path/2, and from the router's own route table via PhoenixKitWeb.Integration
• reading one back — PhoenixKit.Utils.Routes.canonical_admin_path/1, used wherever a real request path is matched against a canonical one (tab active state, the admin nav, the language switcher)

So a module package needs no changes to honour a renamed admin area, and a grep for "/admin" in core stays meaningful.

Compile-time

Read while the host router is compiled, so it belongs in config.exs — never runtime.exs. phoenix_kit_routes() folds it into __mix_recompile__?/0, so changing it re-expands the host router rather than leaving it serving the old segment.

Validation

Exactly one path segment, lowercase [a-z0-9] plus _ and -, and not one of the segments core already owns. A bad value raises here rather than producing a router that compiles and then 404s.

@spec get_all() :: Keyword.t()

Gets all PhoenixKit configuration.

@spec get_base_url() :: String.t()

Gets configured host with an optional port or default value.

@spec get_boolean(atom(), boolean()) :: boolean()

Gets a configuration value as a boolean with type validation.

Examples

iex> PhoenixKit.Config.get_boolean(:enabled, false)
true

iex> PhoenixKit.Config.get_boolean(:nonexistent, true)
true

@spec get_dynamic_base_url() :: String.t()

Gets the base URL dynamically from the parent Phoenix Endpoint if available, otherwise falls back to the static configuration.

This function automatically detects the correct URL from the running Phoenix application, which is especially useful in development mode where the port might be different from the default configuration.

Examples

iex> PhoenixKit.Config.get_dynamic_base_url()
"http://localhost:4001"  # from Phoenix Endpoint

iex> PhoenixKit.Config.get_dynamic_base_url()
"http://localhost:4000"  # fallback to static config

@spec get_list(atom(), list()) :: list()

Gets a configuration value as a list with type validation.

Examples

iex> PhoenixKit.Config.get_list(:options, [])
[]

iex> PhoenixKit.Config.get_list(:nonexistent, [:default])
[:default]

@spec get_mailer() :: module()

Gets the configured mailer module.

Returns the configured mailer or falls back to PhoenixKit.Mailer.

Examples

iex> PhoenixKit.Config.get_mailer()
MyApp.Mailer

@spec get_parent_app() :: atom() | nil

Gets the parent application name that is using PhoenixKit.

This function attempts to detect the main application that has included PhoenixKit as a dependency.

@spec get_parent_app_config(atom(), any()) :: any()

Gets configuration from the parent application.

This is useful for accessing parent app mailer, endpoint, or other configurations that PhoenixKit needs to integrate with.

@spec get_parent_endpoint() :: {:ok, module()} | :error

Gets the parent application's Phoenix Endpoint module.

This function attempts to detect the main application's endpoint that is using PhoenixKit as a dependency.

Returns {:ok, endpoint_module} if found, :error otherwise.

@spec get_parent_endpoint_url() :: {:ok, String.t()} | :error

Gets the parent Phoenix Endpoint URL if the endpoint is available and running.

Returns {:ok, url} if successful, :error if the endpoint cannot be found or accessed.

@spec get_repo() :: module() | nil

Gets the configured repository module.

@spec get_repo!() :: module()

Gets the configured repository module, raising an error if not found.

Examples

iex> PhoenixKit.Config.get_repo!()
MyApp.Repo

iex> PhoenixKit.Config.get_repo!()
** (ArgumentError) PhoenixKit repository not configured. Please set config :phoenix_kit, repo: YourApp.Repo

@spec get_string(atom(), String.t()) :: String.t()

Gets a configuration value as a string with type validation.

Examples

iex> PhoenixKit.Config.get_string(:host, "localhost")
"example.com"

iex> PhoenixKit.Config.get_string(:nonexistent, "default")
"default"

@spec get_url_prefix() :: String.t()

Gets configured prefix for urls or default value.

This value is cached using :persistent_term for performance since it's called on every tab path match during dashboard renders.

@spec get_users_module() :: module()

Gets the configured users module.

@spec mailer_local?() :: boolean()

Checks whether outgoing mail will actually land in the local dev mailbox.

True iff the send path deliver_email/2 would take resolves to Swoosh.Adapters.Local. Resolution order (via PhoenixKit.Mailer.resolved_send_path/0): the operator's default send integration, then the delegated host mailer (config :phoenix_kit, :mailer, adapter read from the parent app's env), then the built-in mailer's own config. A raw read of config :phoenix_kit, PhoenixKit.Mailer answered for a mailer that may not be the one sending — false negative under delegation, false positive when the installer-written Local block coexists with a real delegated mailer (issue #687).

This renders on public pages, so a dead database (the integration lookup reads Settings) means false, never a raise or exit.

Examples

iex> PhoenixKit.Config.mailer_local?
true  # when the resolved send path uses Swoosh.Adapters.Local

iex> PhoenixKit.Config.mailer_local?
false  # when a send integration or a real adapter (SMTP, SES, ...) sends

@spec pubsub_server() :: atom() | nil

Gets the configured PubSub server for broadcasting messages.

Returns the internal PhoenixKit PubSub server or configured custom server.

Examples

iex> PhoenixKit.Config.pubsub_server()
:phoenix_kit_internal_pubsub

@spec set(atom(), any()) :: :ok

Sets a configuration value.

Examples

iex> PhoenixKit.Config.set(:repo, MyApp.Repo)
:ok

iex> PhoenixKit.Config.set(:custom_option, "custom_value")
:ok

@spec user_dashboard_configured?() :: boolean()

Whether the host has said anything at all about :user_dashboard_enabled.

Distinguishes "took the new default" from "explicitly chose false", which user_dashboard_enabled?/0 cannot: both answer false. mix phoenix_kit.update uses it to tell an upgrading host that the default flipped under them — a host that already wrote the key made a choice and needs no notice.

@spec user_dashboard_enabled?() :: boolean()

Whether the deprecated user dashboard (/dashboard) is routed.

Defaults to false. The user dashboard is deprecated — its job has moved into the unified admin panel at /admin, which shows each visitor the sections their permissions allow (and greets a permission-less visitor rather than bouncing them, see PhoenixKitWeb.Users.Auth.landing_view?/1). Core therefore stopped routing it by default; nothing in core links to it any more.

It is not deleted. A host that still wants it turns it back on:

config :phoenix_kit, user_dashboard_enabled: true

and gets /dashboard, /dashboard/settings and the confirm-email compat redirects back, exactly as before.

Read at macro-expansion time by the route macros in PhoenixKitWeb.Integration, so it is compile-time config — config.exs, never runtime.exs. phoenix_kit_routes/0 folds it into __mix_recompile__?/0, so flipping it re-expands the host router instead of leaving it serving the old route table.

Examples

iex> PhoenixKit.Config.user_dashboard_enabled?()
false

# With `config :phoenix_kit, user_dashboard_enabled: true`:
iex> PhoenixKit.Config.user_dashboard_enabled?()
true

Validates that required configuration is present.

Raises an exception if any required keys are missing.

Examples

PhoenixKit.Config.validate_required!([:repo, :secret_key_base])