README

CONFIG MANAGER
^{BY JAMES GOBER}

A Flexible PHP Configuration Manager

Config is a lightweight yet powerful PHP library designed to handle your application's configuration needs with ease and efficiency. Supporting multiple formats like JSON, XML, YAML, INI, and PHP arrays out of the box, it provides the flexibility to add custom parsers tailored to your specific requirements. With robust error handling, performance-focused design, and a modular architecture, JG\Config simplifies configuration management for modern PHP projects.

Key Features

• Multi-Format Support: Seamlessly load configurations from JSON, XML, YAML, INI, PHP, and CONF files.
• Custom Parsers: Extend functionality by adding support for any file format with ease.
• Performance Optimizations: Designed for speed, even with large or deeply nested configurations.
• Advanced Features: Includes caching, dynamic flattening control, and stream parsing for modern workflows.
• Robust Error Handling: Custom exceptions provide clear and actionable feedback for debugging.
• Lightweight and Intuitive: A simple yet powerful API designed for minimal overhead and ease of use.

Why Choose This Library?

JG\Config is built for developers who demand efficiency, reliability, and flexibility in their projects:

• High Performance: Optimized for speed with low overhead, making it ideal for high-load scenarios.
• Modular Design: Extend or replace parsers effortlessly to meet custom needs.
• Error-Resilient: Provides comprehensive error handling with meaningful exception messages.
• Extensively Tested: Rigorously tested with PHPUnit for predictable and stable performance.
• Built on Principles: Adheres to S.O.L.I.D design principles and emphasizes maintainability and extensibility.

Whether you're building a small application or managing a large-scale project, JG\Config provides a robust solution to streamline your configuration management.

Installation

Install via composer:

$ composer require jamesgober/config

Quick Start

Load Configurations

Effortlessly load multiple configuration files in various formats:

use JG\Config\Config;

$config = new Config('/path/to/config/files');

// Load files
$config->load('database.json');
$config->load('app.xml');

// Access values
$dbHost = $config->get('database.host', 'default_host');

// Check keys
if ($config->has('app.debug')) {
    echo "Debug mode is enabled!";
}

// Add or update values
$config->add('app.name', 'MyApp');

Manage Configurations

Easily delete individual values or entire groups:

// Delete specific values
$config->delete('app.version'); // Removes app.version

// Delete groups
$config->delete('app'); // Removes app.name, app.debug, etc.

Extend with Custom Parsers

Add support for new file formats via custom parsers:

use JG\Config\ConfigParserFactory;

// Register a parser for .custom files
ConfigParserFactory::registerParser('custom', MyCustomParser::class);

Supported Formats

For more examples, see our Advanced Usage guide.

Error Handling

Custom Exceptions

JG\Config uses custom exceptions for intuitive error handling:

Example Usage:

use JG\Config\Exceptions\ConfigException;

try {
    $config->load('missing_file.json');
} catch (ConfigException $e) {
    echo "Error: " . $e->getMessage();
}

Advanced Features

Explore advanced capabilities like caching, custom parsers, and dynamic flattening in our Advanced Guide.

Directory Structure

src/
├── Config.php                  # Core configuration management class
├── ConfigParserFactory.php     # Factory for parser resolution
├── Exceptions/                 # Custom exceptions for robust error handling
│   ├── ConfigException.php
│   ├── ConfigParseException.php
│   └── InvalidParserException.php
├── Parsers/                    # Built-in parsers for supported formats
│   ├── ParserInterface.php
│   ├── PhpParser.php
│   ├── JsonParser.php
│   ├── IniParser.php
│   ├── XmlParser.php
│   └── YamlParser.php
tests/                          # Unit and integration tests

Reporting Security Issues

We take security seriously. If you find a vulnerability, please consult our SECURITY POLICY and follow the instructions for reporting.

Do not use public issue trackers or forums to disclose sensitive information.

Reporting Bugs and Feature Requests

For non-security issues, such as bugs or feature requests, please use our Issue Tracker. Providing detailed information will help us resolve issues efficiently.

Design Philosophy

Learn about the principles that guide the development of JG\Config in our Design Philosophy.

Contributing

Contributions are welcome! Check out the Contribution Guidelines and review our Code of Conduct for more information.

License

This library is open-source software licensed under the MIT license.

COPYRIGHT © 2024 JAMES GOBER & JAMESGOBER.COM.