Configuration Manager API

This document provides a comprehensive API reference for the ConfigManager class, which is the core configuration management system in ai-commit. It documents all public methods, their signatures, parameters, return types, and usage patterns. For end-user configuration guide and file format documentation, see Configuration Reference. For configuration usage in commands, see Core Commands API.

Overview

The ConfigManager class is located at app/ConfigManager.php39 and extends Laravel's Repository class to provide hierarchical configuration management with JSON serialization capabilities. It manages three configuration sources: PHP defaults, global JSON files, and local JSON files, merging them using a recursive replacement strategy.

Sources: app/ConfigManager.php1-270

Class Definition and Inheritance

Sources: app/ConfigManager.php39-46

Constants

Constant	Value	Description
BASE_NAME	".ai-commit.json"	Default configuration file name
BASE_DIRNAME	".ai-commit"	Global configuration directory name
JSON_OPTIONS	JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR	Default JSON encoding options

Sources: app/ConfigManager.php47-49

Factory Methods

load()

Creates a ConfigManager instance from default configuration sources and registers it in the Laravel configuration container as 'ai-commit'.

Returns: ConfigManager instance

Throws: \Illuminate\Contracts\Filesystem\FileNotFoundException

Behavior:

• Calls make() to create the instance
• Registers the instance via Config::set('ai-commit', $instance)

Sources: app/ConfigManager.php62-65

---

make()

Factory method that creates a ConfigManager instance. If $items is provided, creates an instance with those items. Otherwise, loads and merges configuration from existing files.

Parameters:

• $items (array|null): Optional configuration array. If provided, creates instance with this data instead of loading from files.

Returns: ConfigManager instance

Throws: \Illuminate\Contracts\Filesystem\FileNotFoundException

Merge Order:

1. config/ai-commit.php (PHP defaults)
2. ~/.ai-commit/.ai-commit.json (global configuration)
3. ./.ai-commit.json (local configuration)

Sources: app/ConfigManager.php70-80

---

makeFrom()

Creates a ConfigManager instance by loading and merging configuration from specified files.

Parameters:

• ...$files (string): Variable number of file paths to load and merge

Returns: ConfigManager instance

Throws:

• \Illuminate\Contracts\Filesystem\FileNotFoundException
• UnsupportedConfigFileTypeException if file extension is not .php or .json

Sources: app/ConfigManager.php85-88 app/ConfigManager.php252-269

Path Resolution Methods

globalPath()

Returns the absolute path to the global configuration file.

Returns: String path to global configuration file

Platform-specific behavior:

• Windows: C:\Users\{username}\.ai-commit\.ai-commit.json
• Unix/Linux/macOS: ~/.ai-commit/.ai-commit.json

Sources: app/ConfigManager.php90-95

---

localPath()

Returns the absolute path to the local configuration file in the current working directory.

Parameters:

• $path (string): Optional custom filename. Defaults to ".ai-commit.json"

Returns: String path to local configuration file (e.g., /path/to/project/.ai-commit.json)

Sources: app/ConfigManager.php97-106

File I/O Methods

Sources: app/ConfigManager.php111-162 app/ConfigManager.php168-171 app/ConfigManager.php252-269

putGlobal()

Writes the current configuration to the global configuration file.

Parameters:

• $options (int): JSON encoding options. Defaults to JSON_OPTIONS

Returns: Number of bytes written or false on failure

Throws: \JsonException

Sources: app/ConfigManager.php111-114

---

putLocal()

Writes the current configuration to the local configuration file in the current working directory.

Parameters:

• $options (int): JSON encoding options. Defaults to JSON_OPTIONS

Returns: Number of bytes written or false on failure

Throws: \JsonException

Sources: app/ConfigManager.php119-122

---

putFile()

Writes the current configuration to a specified file. This method filters out non-serializable objects before writing.

Parameters:

• $file (string): Target file path
• $options (int): JSON encoding options. Defaults to JSON_OPTIONS

Returns: Number of bytes written or false on failure

Throws: \JsonException

Behavior:

1. Filters out objects that are not JsonSerializable, Arrayable, or Jsonable
2. Keeps specific generator parameters (messages, prompt, user)
3. Ensures parent directory exists
4. Writes JSON-encoded configuration

Sources: app/ConfigManager.php127-163

---

replaceFrom()

Loads configuration from a file and recursively merges it into the current configuration.

Parameters:

• $file (string): Path to configuration file (.php or .json)

Returns: ConfigManager instance (fluent interface)

Throws:

• \Illuminate\Contracts\Filesystem\FileNotFoundException
• UnsupportedConfigFileTypeException

Sources: app/ConfigManager.php168-171

Data Manipulation Methods

replace()

Recursively merges the provided array into the current configuration. Existing keys are replaced, nested arrays are merged recursively.

Parameters:

• $items (array): Configuration array to merge

Returns: ConfigManager instance (fluent interface)

Algorithm: Uses array_replace_recursive() to merge $items into $this->items

Sources: app/ConfigManager.php176-181

---

forget()

Removes one or more keys from the configuration using dot notation.

Parameters:

• $keys (array-key|list): Single key or array of keys in dot notation (e.g., "generators.openai_chat.api_key")

Returns: ConfigManager instance (fluent interface)

Sources: app/ConfigManager.php188-193

Serialization Methods

Configuration Loading and Merging Flow

Sources: app/ConfigManager.php70-80 app/ConfigManager.php252-269

jsonSerialize()

Converts the configuration to a JSON-serializable array. Handles nested objects implementing JsonSerializable, Jsonable, or Arrayable.

Returns: Array suitable for JSON encoding

Throws: \JsonException

Sources: app/ConfigManager.php202-222

---

toDotArray()

Converts the configuration to a flattened array using dot notation for nested keys.

Returns: Flat array with dot-notated keys

For example, the nested key generators.openai.api_key becomes the flat dot-notation key generators.openai.api_key. This format is used by ConfigCommand to display all keys in the list action.

Sources: app/ConfigManager.php224-227 app/Commands/ConfigCommand.php95-98

---

toArray()

Converts the configuration to a plain array, converting Arrayable objects to arrays.

Returns: Plain nested array

Sources: app/ConfigManager.php232-235

---

toJson()

Converts the configuration to a JSON string.

Parameters:

• $options (mixed): JSON encoding options. Defaults to JSON_OPTIONS

Returns: JSON-encoded string

Throws: \JsonException

Sources: app/ConfigManager.php244-247

---

__toString()

Magic method to convert the ConfigManager instance to a JSON string when cast to string.

Returns: JSON-encoded string

Throws: \JsonException

Sources: app/ConfigManager.php54-57

Integration with ConfigCommand

The ConfigCommand class uses ConfigManager to implement CRUD operations for configuration management.

Sources: app/Commands/ConfigCommand.php55-114 app/Commands/ConfigCommand.php177-188

ConfigCommand Usage Examples

Action	Command	ConfigManager Methods Used
Set value	config set generators.openai_chat.api_key "sk-..."	set(), putFile()
Get value	config get generators.openai_chat.api_key	get()
Get all	config get	toJson()
Unset value	config unset generators.openai_chat.api_key	forget(), putFile()
Reset to defaults	config reset	replace(), putFile()
Reset specific key	config reset generators.openai_chat	set(), putFile()
List all	config list	toDotArray()
Edit with editor	config edit	File path only (Process)
Global scope	config set key value --global	globalPath(), putFile()

Sources: app/Commands/ConfigCommand.php72-109

Usage Patterns

Creating and Initializing

ConfigManager::load() is called during application bootstrap (see page 4.1) to create the singleton instance and register it in the Laravel config container as 'ai-commit'. It delegates to make() which discovers and merges configuration from the three standard file sources. makeFrom() allows callers to specify an explicit set of file paths to merge. Passing an array directly to make() bypasses file loading entirely.

The test suite uses this pattern: ConfigManager::makeFrom($this->app->configPath('ai-commit.php')) to isolate test configuration from user-level global files.

Sources: app/ConfigManager.php62-88 tests/TestCase.php53-57

---

Reading Configuration

Reading uses methods inherited from Illuminate\Config\Repository: get(key, default), has(key), and all(). The ConfigManager adds toDotArray() for flat key enumeration and toJson() for JSON output. All read methods support dot-notation for nested key access.

Sources: app/ConfigManager.php224-247

---

Writing Configuration

set(key, value) is inherited from Repository. Mutations are in-memory until persisted via putGlobal(), putLocal(), or putFile(). The replace() method performs a deep recursive merge rather than a shallow overwrite, making it suitable for merging partial configuration overlays. The forget() method removes keys (and their children) using dot notation.

All write methods that return self support method chaining.

Sources: app/ConfigManager.php111-193

---

Accessing in Application

The ConfigManager singleton is accessed via config('ai-commit') anywhere in the application. ConfigCommand retrieves it in its constructor and holds it as $this->configManager. Other commands and generators that need configuration access it the same way.

Sources: app/Commands/ConfigCommand.php43-47

Method Reference Table

Method	Type	Purpose	Returns
load()	Static	Create and register instance	ConfigManager
make(?array)	Static	Factory method	ConfigManager
makeFrom(string...)	Static	Load from specific files	ConfigManager
globalPath()	Static	Get global config path	string
localPath(string)	Static	Get local config path	string
putGlobal(int)	Instance	Save to global file	bool|int
putLocal(int)	Instance	Save to local file	bool|int
putFile(string, int)	Instance	Save to specific file	bool|int
replaceFrom(string)	Instance	Load and merge from file	ConfigManager
replace(array)	Instance	Merge configuration	ConfigManager
forget(mixed)	Instance	Remove keys	ConfigManager
jsonSerialize()	Instance	Convert to JSON-serializable	array
toDotArray()	Instance	Convert to dot notation	array
toArray()	Instance	Convert to plain array	array
toJson(mixed)	Instance	Convert to JSON string	string
__toString()	Instance	Cast to JSON string	string

Sources: app/ConfigManager.php1-270