# `PhoenixKit.Install.IgniterConfig`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L1)

Helper functions for working with Igniter to read and modify parent project configuration.

This module provides utilities to read, update, and merge configuration values in the
parent Phoenix application's config files using Igniter's configuration system.

All functions are designed to work with Igniter's project modification capabilities
and provide safe operations that handle missing configs and merge strategies.

## Examples

    iex> igniter = Igniter.new()
    iex> {igniter, value} = PhoenixKit.Install.IgniterConfig.read_config(igniter, :my_app, [:key])
    {igniter, nil}

    iex> igniter = PhoenixKit.Install.IgniterConfig.update_config(igniter, :my_app, [:key], :value)
    # Returns updated igniter with the new config

# `add_to_admin_category`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L282)

```elixir
@spec add_to_admin_category(Igniter.t(), String.t(), map(), keyword()) :: Igniter.t()
```

Adds an item to an admin dashboard category in PhoenixKit configuration.

Shortcut for `add_to_category/7` with PhoenixKit-specific defaults.

## Parameters

- `igniter` - The Igniter project struct
- `category_title` - The title of the category to add to
- `item` - The item to add to the category's subsections
- `category_opts` - Options for creating a new category if needed

## Returns

The updated `igniter` struct

## Examples

    iex> igniter = Igniter.new()
    iex> new_page = %{title: "Reports", url: "/admin/reports", icon: "hero-chart-bar"}
    iex> igniter = PhoenixKit.Install.IgniterConfig.add_to_admin_category(
    ...>   igniter, "Analytics", new_page
    ...> )

# `add_to_category`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L449)

```elixir
@spec add_to_category(
  Igniter.t(),
  atom(),
  [atom()],
  String.t(),
  map(),
  keyword(),
  String.t()
) :: Igniter.t()
```

Adds an item to a category within a list configuration, creating the category if needed.

This function is designed for configurations that contain a list of categories,
each with a `:title` key and `:subsections` list. It will find an existing category
by title and add the new item to its subsections, or create a new category if it doesn't exist.

## Parameters

- `igniter` - The Igniter project struct
- `app_name` - The application name (atom)
- `key_path` - List of atoms representing the configuration key path
- `category_title` - The title of the category to add to
- `item` - The item to add to the category's subsections
- `category_opts` - Options for creating a new category if needed:
  - `:icon` - Icon for the new category (default: "hero-folder")
- `config_file` - Config file name (default: "config.exs")

## Returns

The updated `igniter` struct

## Examples

    iex> igniter = Igniter.new()
    iex> new_page = %{title: "Reports", url: "/admin/reports"}
    iex> igniter = PhoenixKit.Install.IgniterConfig.add_to_category(
    ...>   igniter, :my_app, [:admin_categories], "Analytics", new_page
    ...> )

# `add_to_category_with_tabs`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L342)

```elixir
@spec add_to_category_with_tabs(
  Igniter.t(),
  atom(),
  [atom()],
  String.t(),
  map(),
  keyword(),
  String.t()
) :: Igniter.t()
```

Adds a tab to a category within a list configuration (using :tabs key).

Similar to `add_to_category/7` but uses `:tabs` instead of `:subsections`.
Designed for user dashboard categories.

# `add_to_user_dashboard_category`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L316)

```elixir
@spec add_to_user_dashboard_category(Igniter.t(), String.t(), map(), keyword()) ::
  Igniter.t()
```

Adds a tab to a user dashboard category, creating the category if it doesn't exist.

This function is similar to `add_to_admin_category/4` but for user dashboard tabs.
It uses `:tabs` instead of `:subsections` to match the user dashboard category format.

## Parameters

- `igniter` - The Igniter project struct
- `category_title` - The title of the category (e.g., "Farm Management")
- `tab` - A map with tab properties: `:title`, `:url`, `:icon`, `:description`
- `category_opts` - Options for creating a new category:
  - `:icon` - Icon for the new category (default: "hero-folder")

## Examples

    iex> igniter = Igniter.new()
    iex> new_tab = %{title: "History", url: "/dashboard/history", icon: "hero-chart-bar"}
    iex> igniter = PhoenixKit.Install.IgniterConfig.add_to_user_dashboard_category(
    ...>   igniter, "Farm Management", new_tab, icon: "hero-cube"
    ...> )

# `config_exists?`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L533)

```elixir
@spec config_exists?(Igniter.t(), atom(), [atom()], String.t()) ::
  {Igniter.t(), boolean()}
```

Checks if a configuration value exists.

## Parameters

- `igniter` - The Igniter project struct
- `app_name` - The application name (atom)
- `key_path` - List of atoms representing the configuration key path
- `config_file` - Config file name (default: "config.exs")

## Returns

`{igniter, true}` if the config exists
`{igniter, false}` if the config doesn't exist

# `merge_into_list_config`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L168)

```elixir
@spec merge_into_list_config(
  Igniter.t(),
  atom(),
  [atom()],
  list(),
  String.t(),
  keyword()
) :: Igniter.t()
```

Merges a new value into an existing list configuration.

If the config doesn't exist or is not a list, it will be created with the new value.

## Parameters

- `igniter` - The Igniter project struct
- `app_name` - The application name (atom)
- `key_path` - List of atoms representing the configuration key path
- `items` - List of items to add to the existing configuration
- `config_file` - Config file name (default: "config.exs")
- `opts` - Options:
  - `:merge_strategy` - How to merge when items are maps with `:title` keys:
    - `:prepend` - Add new items at the beginning (default)
    - `:append` - Add new items at the end
    - `:replace` - Replace existing items with matching titles

## Returns

The updated `igniter` struct

## Examples

    iex> igniter = Igniter.new()
    iex> items = [%{title: "New Item", value: 1}]
    iex> igniter = PhoenixKit.Install.IgniterConfig.merge_into_list_config(
    ...>   igniter, :my_app, [:my_list], items
    ...> )

# `read_config`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L48)

```elixir
@spec read_config(Igniter.t(), atom(), [atom()], String.t()) ::
  {Igniter.t(), {:ok, any()} | {:error, String.t()}}
```

Reads a configuration value from the parent project's config files.

## Parameters

- `igniter` - The Igniter project struct
- `app_name` - The application name (atom)
- `key_path` - List of atoms representing the configuration key path
- `config_file` - Config file name (default: "config.exs")

## Returns

`{igniter, {:ok, value}}` if the config exists
`{igniter, {:error, reason}}` if the config doesn't exist or can't be read

## Examples

    iex> igniter = Igniter.new()
    iex> {igniter, result} = PhoenixKit.Install.IgniterConfig.read_config(igniter, :my_app, [:my_key])
    {igniter, {:ok, :my_value}}

# `read_phoenix_kit_config`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L230)

```elixir
@spec read_phoenix_kit_config(Igniter.t(), [atom()], String.t()) ::
  {Igniter.t(), {:ok, any()} | {:error, String.t()}}
```

Reads a PhoenixKit-specific configuration value.

Shortcut for reading config values from the :phoenix_kit application.

## Parameters

- `igniter` - The Igniter project struct
- `key_path` - List of atoms representing the configuration key path
- `config_file` - Config file name (default: "config.exs")

## Returns

`{igniter, {:ok, value}}` if the config exists
`{igniter, {:error, reason}}` if the config doesn't exist or can't be read

# `update_config`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L104)

```elixir
@spec update_config(Igniter.t(), atom(), [atom()], any(), String.t(), keyword()) ::
  Igniter.t()
```

Updates or creates a configuration value in the parent project's config files.

## Parameters

- `igniter` - The Igniter project struct
- `app_name` - The application name (atom)
- `key_path` - List of atoms representing the configuration key path
- `value` - The new value to set
- `config_file` - Config file name (default: "config.exs")
- `opts` - Options:
  - `:merge_lists` - If true and both existing and new values are lists, merges them (default: false)

## Returns

The updated `igniter` struct

## Examples

    iex> igniter = Igniter.new()
    iex> igniter = PhoenixKit.Install.IgniterConfig.update_config(igniter, :my_app, [:my_key], :new_value)
    # Returns igniter with the updated config

# `update_phoenix_kit_config`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.63/lib/phoenix_kit/install/igniter_config.ex#L253)

```elixir
@spec update_phoenix_kit_config(Igniter.t(), [atom()], any(), String.t(), keyword()) ::
  Igniter.t()
```

Updates a PhoenixKit-specific configuration value.

Shortcut for updating config values in the :phoenix_kit application.

## Parameters

- `igniter` - The Igniter project struct
- `key_path` - List of atoms representing the configuration key path
- `value` - The new value to set
- `config_file` - Config file name (default: "config.exs")
- `opts` - Options passed through to `update_config/5`

## Returns

The updated `igniter` struct

---

*Consult [api-reference.md](api-reference.md) for complete listing*