View Source Bonfire.Common.Settings (Bonfire v0.9.10-classic-beta.156)

Helpers to get app/extension settings, or to override a config key.

This module provides functionality for fetching and updating application and extension settings. The process for fetching settings follows a bottom-up system of overrides:

  1. User-specific settings: If opts contains current_user, settings are fetched from the user's settings.

  2. Account-specific settings: If no settings are found for the user and opts contains current_account, settings are fetched from the account's settings.

  3. Instance-specific settings: NOTE: Changes to instance settings are stored both in the database and the OTP app config/application environment, and are loaded from the DB into OTP config at app startup by Bonfire.Common.Settings.LoadInstanceConfig.

  4. Default OTP config: If no settings are found at the user or account level, instance settings are loaded from OTP application configuration via Bonfire.Common.Config.

  5. Default value: If no settings are found in the previous steps, the provided default value is returned.

Summary

Functions

Retrieves the setting value for a given config key or nested key path.

Retrieves the setting value for a given config key like in get/3, but raises an exception if the key is not found, ensuring that the setting must be present.

Sets a value for a specific key or list of nested keys.

Resets all settings.

Resets settings for the instance scope.

Sets multiple settings at once.

Functions

Link to this function

do_get_in(result, keys_tree)

View Source
Link to this function

get(key, default \\ nil, opts \\ [])

View Source

Retrieves the setting value for a given config key or nested key path.

As explained above, this function checks settings in the following order:

  1. User settings (if opts contains current_user).
  2. Account settings (if opts contains current_account and no user settings are found).
  3. Instance settings.
  4. OTP application config (includes compile time and runtime config).
  5. Default value (if no settings are found).

Examples

iex> get(:test_key)
"test_value"

iex> get([:non_existing_extension, :sub_key])
nil

iex> get(:non_existing_key, "default")
"default"

iex> get(:otp_app)
:bonfire

iex> get([:bonfire_common, :otp_app])
:bonfire

iex> get([:bonfire_common, :otp_app])
:bonfire

iex> get([Bonfire.Common.Localise.Cldr, :gettext])
Bonfire.Common.Localise.Gettext

iex> get([:bonfire_common, Bonfire.Common.Localise.Cldr, :gettext])
Bonfire.Common.Localise.Gettext

Options

  • :otp_app - Optionally specifies the OTP application for which to fetch settings. If none is specified, it will look at the (first) key and check if it references a known OTP application (i.e. an extension) or a module, in which case it will fetch settings from that application. Otherwise it will look in the configured top-level OTP app (see Config.top_level_otp_app/0).
  • :scope - Optionally defines the scope for settings retrieval (e.g., :user, :account, or :instance).

Retrieves the setting value for a given config key like in get/3, but raises an exception if the key is not found, ensuring that the setting must be present.

Examples

iex> get!(:test_key)
"test_value"

iex> get!(:non_existing_key)
** (RuntimeError) Missing setting or configuration value: :non_existing_key
Link to this function

load_instance_settings()

View Source
Link to this function

put(keys, value, opts \\ [])

View Source

Sets a value for a specific key or list of nested keys.

This function updates the configuration with the provided value. You can specify a single key or a list of nested keys.

Examples

# when no scope or current_user are passed in opts:
> put(:some_key, "new_value")
{:error, "You need to be authenticated to change settings."}

# when the scope is :instance but an admin isn't passed as current_user in opts:
> put(:some_key, "new_value", scope: :instance)
** (Bonfire.Fail) You do not have permission to change instance settings. Please contact an admin.

> {:ok, %Bonfire.Data.Identity.Settings{}} = put(:some_key, "new_value", skip_boundary_check: true, scope: :instance)

> {:ok, %Bonfire.Data.Identity.Settings{}} = put([:top_key, :sub_key], "new_value", skip_boundary_check: true, scope: "instance")

Options

  • :otp_app - Specifies the OTP application for which to set settings. If not specified, it decides where to put it using the same logic as get/3.
  • :scope - Defines the scope for settings (e.g., :user, :account, or :instance).

Resets all settings.

This function deletes all settings from the database, including instance-specific settings and user-specific settings for all users. Please be careful!

Examples

> reset_all()
{:ok, %{}}

Resets settings for the instance scope.

This function deletes the settings associated with the whole instance and returns the result.

Examples

> reset_instance()
{:ok, %Bonfire.Data.Identity.Settings{id: "some_id"}}

Sets multiple settings at once.

This function accepts a map or keyword list of settings to be updated. It determines the appropriate scope and updates the settings accordingly.

Examples

> {:ok, %Bonfire.Data.Identity.Settings{}} = set(%{some_key: "value", another_key: "another_value"}, skip_boundary_check: true, scope: :instance)

> {:ok, %Bonfire.Data.Identity.Settings{}} = set([some_key: "value", another_key: "another_value"], skip_boundary_check: true, scope: "instance")

Options

  • :otp_app - Specifies the OTP application for which to set settings.
  • :scope - Defines the scope for settings (e.g., :user, :account, or :instance).