ConfigLoader

The ConfigLoader provides an easy way to load and customize Data Helpers configuration in Plain PHP projects without Laravel or Symfony.

Features

Deep Merging - Merges user config with package defaults (similar to Laravel)
Partial Configuration - Only specify values you want to change
File or Array - Load from config file or pass array directly
Config Publishing - Generate minimal config file for your project
Type-Safe - Full PHPStan level 9 support
Plain PHP Only - Laravel and Symfony use native config systems

Basic Usage

Load with Config File

Create a config file in your project:

<?php

return [
    'performance_mode' => 'safe',
    'cache' => [
        'ttl' => 3600,
    ],
];

Load and initialize:

use event4u\DataHelpers\Config\ConfigLoader;
use event4u\DataHelpers\DataHelpersConfig;

// Load config with deep merging
$config = ConfigLoader::load(__DIR__ . '/config/data-helpers.php');

// Initialize DataHelpersConfig
DataHelpersConfig::initialize($config);

Load with Array

You can also pass configuration directly as an array:

use event4u\DataHelpers\Config\ConfigLoader;
use event4u\DataHelpers\DataHelpersConfig;

$config = ConfigLoader::load([
    'performance_mode' => 'safe',
    'cache' => [
        'ttl' => 3600,
        'code_generation' => true,
    ],
    'logging' => [
        'enabled' => true,
        'level' => 'debug',
    ],
]);

DataHelpersConfig::initialize($config);

Deep Merging

The ConfigLoader performs deep merging of configuration arrays, similar to Laravel’s config system.

How It Works

// Package default config
[
    'cache' => [
        'path' => './.event4u/data-helpers/cache/',
        'driver' => 'auto',
        'ttl' => null,
        'code_generation' => true,
    ],
]

// Your config (only what you want to change)
[
    'cache' => [
        'ttl' => 3600,
    ],
]

// Result after merging
[
    'cache' => [
        'path' => './.event4u/data-helpers/cache/',  // ✅ Preserved from default
        'driver' => 'auto',                           // ✅ Preserved from default
        'ttl' => 3600,                                // ✅ Overridden by your config
        'code_generation' => true,                    // ✅ Preserved from default
    ],
]

Multi-Level Nesting

Deep merging works at any nesting level:

$config = ConfigLoader::load([
    'logging' => [
        'events' => [
            'mapping_error' => false,  // Override just this one event
        ],
        'sampling' => [
            'errors' => 0.5,           // Override just this one sampling rate
        ],
    ],
]);

// All other logging.events.* and logging.sampling.* values are preserved!

Publishing Config File

Generate a minimal config file for your project:

use event4u\DataHelpers\Config\ConfigLoader;

// Publish to your project
ConfigLoader::publish('./config/data-helpers.php');

// Overwrite existing file
ConfigLoader::publish('./config/data-helpers.php', overwrite: true);

The published config file contains only commonly changed settings with helpful comments.

Bootstrap Example

Here’s a complete example of bootstrapping Data Helpers in a Plain PHP project:

<?php

require_once __DIR__ . '/vendor/autoload.php';

use event4u\DataHelpers\Config\ConfigLoader;
use event4u\DataHelpers\DataHelpersConfig;

// Load configuration
$config = ConfigLoader::load(__DIR__ . '/config/data-helpers.php');

// Initialize Data Helpers
DataHelpersConfig::initialize($config);

// Now you can use Data Helpers
use event4u\DataHelpers\SimpleDto;

class UserDto extends SimpleDto
{
    public function __construct(
        public string $name,
        public string $email,
    ) {}
}

$user = UserDto::fromArray([
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);

Environment Variables

The default config file uses env() helper for environment variables. If you don’t have this helper, you can use PHP’s native $_ENV or getenv():

<?php

return [
    'performance_mode' => $_ENV['DATA_HELPERS_PERFORMANCE_MODE'] ?? 'fast',
    'cache' => [
        'ttl' => isset($_ENV['DATA_HELPERS_CACHE_TTL'])
            ? (int) $_ENV['DATA_HELPERS_CACHE_TTL']
            : null,
    ],
];

Or use the package’s EnvHelper:

use event4u\DataHelpers\Helpers\EnvHelper;

return [
    'performance_mode' => EnvHelper::string('DATA_HELPERS_PERFORMANCE_MODE', 'fast'),
    'cache' => [
        'ttl' => EnvHelper::integer('DATA_HELPERS_CACHE_TTL', null),
    ],
];

API Reference

`ConfigLoader::load()`

Load configuration with deep merging.

public static function load(string|array $userConfig = []): array

Parameters:

$userConfig - Path to config file or config array

Returns: Merged configuration array

Throws: RuntimeException if config file not found

`ConfigLoader::getDefaultConfigPath()`

Get the path to the package default config file.

public static function getDefaultConfigPath(): string

Returns: Absolute path to config/data-helpers.php

`ConfigLoader::publish()`

Create a minimal config file.

public static function publish(string $targetPath, bool $overwrite = false): bool

Parameters:

$targetPath - Where to create the config file
$overwrite - Whether to overwrite existing file (default: false)

Returns: true if file was created, false if file exists and overwrite is false

Examples

Minimal Config

Only change what you need:

$config = ConfigLoader::load([
    'performance_mode' => 'safe',
]);

Production Config

Optimize for production:

$config = ConfigLoader::load([
    'performance_mode' => 'fast',
    'cache' => [
        'code_generation' => true,
        'invalidation' => 'manual',
    ],
    'logging' => [
        'enabled' => true,
        'level' => 'error',
    ],
]);

Development Config

Enable debugging:

$config = ConfigLoader::load([
    'performance_mode' => 'safe',
    'cache' => [
        'invalidation' => 'mtime',
    ],
    'logging' => [
        'enabled' => true,
        'level' => 'debug',
    ],
]);