Search documentation of phoenix_kit

# PhoenixKit.Config (phoenix_kit v1.6.19)

View Source

Configuration management system for PhoenixKit.

This module provides a centralized way to manage PhoenixKit configuration with type-safe getter functions for different data types.

## Usage

    # Get all configuration
    config = PhoenixKit.Config.get_all()

    # Get specific values
    repo = PhoenixKit.Config.get(:repo)
    mailer = PhoenixKit.Config.get(:mailer, PhoenixKit.Mailer)

    # Type-safe getters
    options = PhoenixKit.Config.get_list(:options, [])
    enabled = PhoenixKit.Config.get_boolean(:enabled, false)
    host = PhoenixKit.Config.get_string(:host, "localhost")

## Configuration Keys

- `:repo` - Ecto repository module (required)
- `:mailer` - Mailer module for sending emails
- `:host` - Application hostname
- `:port` - Application port
- `:layout_module` - Custom layout configuration
- `:from_email` - Default sender email address for notifications
- `:from_name` - Default sender name for notifications (default: "PhoenixKit")
- `:users_module` - User schema module (default: PhoenixKit.Users.Auth.User)

## Type-Safe Functions

- `get_list/2` - Gets configuration values with list type validation
- `get_boolean/2` - Gets configuration values with boolean type validation
- `get_string/2` - Gets configuration values with string type validation

These functions provide automatic type validation and fallback to defaults when the configuration value is missing or has the wrong type.

# Summary

## Functions

get(key)

Gets a specific configuration value.

get(key, default)

Gets a specific configuration value with a default.

get_all()

Gets all PhoenixKit configuration.

get_base_url()

Gets configured host with an optional port or default value.

get_boolean(key, default \\ false)

Gets a configuration value as a boolean with type validation.

get_dynamic_base_url()

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

get_list(key, default \\ [])

Gets a configuration value as a list with type validation.

get_mailer()

Gets the configured mailer module.

get_parent_app()

Gets the parent application name that is using PhoenixKit.

get_parent_app_config(key, default \\ nil)

Gets configuration from the parent application.

get_parent_endpoint()

Gets the parent application's Phoenix Endpoint module.

get_parent_endpoint_url()

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

get_repo()

Gets the configured repository module.

get_repo!()

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

get_string(key, default \\ "")

Gets a configuration value as a string with type validation.

get_url_prefix()

Gets configured prefix for urls or default value.

get_users_module()

Gets the configured users module.

mailer_local?()

Checks if the configured mailer adapter is the local adapter.

set(key, value)

Sets a configuration value.

validate_required!(required_keys)

Validates that required configuration is present.

# Functions

# get(key)

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

Gets a specific configuration value.

# get(key, default)

    @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

# get_all()

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

Gets all PhoenixKit configuration.

# get_base_url()

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

Gets configured host with an optional port or default value.

# get_boolean(key, default \\ false)

    @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

# get_dynamic_base_url()

    @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

# get_list(key, default \\ [])

    @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]

# get_mailer()

    @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

# get_parent_app()

    @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.

# get_parent_app_config(key, default \\ nil)

    @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.

# get_parent_endpoint()

    @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.

# get_parent_endpoint_url()

    @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.

# get_repo()

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

Gets the configured repository module.

# get_repo!()

    @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

# get_string(key, default \\ "")

    @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"

# get_url_prefix()

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

Gets configured prefix for urls or default value.

# get_users_module()

    @spec get_users_module() :: module()

Gets the configured users module.

# mailer_local?()

    @spec mailer_local?() :: boolean()

Checks if the configured mailer adapter is the local adapter.

Returns true if the mailer is configured to use Swoosh.Adapters.Local, which is typically used for development and testing environments where emails are stored locally rather than being sent to actual recipients.

## Examples

    iex> PhoenixKit.Config.mailer_local?
    true  # when using Swoosh.Adapters.Local

    iex> PhoenixKit.Config.mailer_local?
    false  # when using a real mailer like SMTP or SendGrid

# set(key, value)

    @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

# validate_required!(required_keys)

Validates that required configuration is present.

Raises an exception if any required keys are missing.

## Examples

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