README

Une bibliothèque PHP légère et sans dépendances pour la gestion centralisée de la configuration avec support des fichiers PHP et JSON.

Installation

composer require npds/config

Table des matières

Introduction
Classes principales
Configuration rapide
Utilisation de base
Chargement de fichiers
Gestion des environnements
Façade statique
Helpers globaux
Exemples complets
Bonnes pratiques
Référence complète de l'API

Introduction

Cette bibliothèque fournit une interface orientée objet pour gérer la configuration dans les applications PHP. Elle supporte le chargement de fichiers PHP et JSON, la notation par points, les environnements multiples (local, production, etc.), et offre une API simple et intuitive.

Caractéristiques principales :

Zéro dépendances
Support PHP et JSON
Notation par points pour l'accès aux valeurs imbriquées
Gestion des environnements (local, production, staging, etc.)
Façade statique pour accès facile
Fusion récursive de configurations
Sauvegarde en PHP ou JSON
Conversion de types automatique

Classes principales

Npds\Config\ConfigManager

Classe principale qui gère le chargement et l'accès aux fichiers de configuration.

Npds\Config\FileLoader

Charge les fichiers de configuration depuis le système de fichiers.

Npds\Config\Repository

Stocke et manipule les données de configuration avec support de la notation par points.

Npds\Config\Facades\Config

Façade statique pour un accès simplifié à la configuration.

Configuration rapide

Initialisation simple

use Npds\Config\ConfigManager;

// Créer un gestionnaire avec un chemin
$config = new ConfigManager('/chemin/vers/config');

// Les fichiers sont automatiquement chargés
$appName = $config->get('app.name');

Initialisation avec environnement

$config = new ConfigManager(
    '/chemin/vers/config',
    'local'  // Environnement actuel
);

// Charge les fichiers base + les fichiers local.*.php/json

Initialisation avec plusieurs chemins

$config = new ConfigManager([
    '/chemin/config',
    '/chemin/config-custom'
]);

// Les configurations des deux chemins sont fusionnées

Utilisation de base

Récupérer des valeurs

$config = new ConfigManager('/chemin/vers/config');

// Récupérer une valeur simple
$debug = $config->get('app.debug');

// Avec valeur par défaut
$theme = $config->get('app.theme', 'light');

// Vérifier l'existence
if ($config->has('database.host')) {
    $host = $config->get('database.host');
}

// Récupérer toutes les configurations
$all = $config->all();

// Récupérer une section (doit être un tableau)
$dbConfig = $config->getSection('database');

Définir des valeurs

// Ajouter une valeur simple
$config->set('app.version', '1.0.0');

// Ajouter une valeur imbriquée (crée les clés manquantes)
$config->set('cache.redis.host', 'localhost');

// Ajouter un tableau complet
$config->set('providers', [
    'App\\Providers\\AppServiceProvider',
    'App\\Providers\\AuthServiceProvider',
]);

Opérations avancées

// Récupérer et supprimer
$value = $config->pull('temporary.key', 'défaut');

// Supprimer une clé
$config->remove('old.setting');

// Vider tout
$config->clear();

// Fusionner de nouvelles données
$config->merge([
    'app' => [
        'version' => '2.0.0'
    ]
]);

// Vérifier si vide
if ($config->isEmpty()) {
    echo 'Aucune configuration';
}

Chargement de fichiers

Structure des fichiers

/config
  ├── app.php
  ├── database.php
  ├── cache.json
  └── local.app.php        (override pour environnement local)

Fichier PHP

<?php
// config/app.php

return [
    'name' => 'Mon Application',
    'debug' => true,
    'version' => '1.0.0',
    'settings' => [
        'timezone' => 'UTC',
        'locale' => 'fr',
    ],
];

Fichier JSON

{
    "default": "mysql",
    "connections": {
        "mysql": {
            "host": "localhost",
            "port": 3306,
            "database": "app_db"
        },
        "sqlite": {
            "database": "database.sqlite"
        }
    }
}

Chargement et rechargement

$config = new ConfigManager('/chemin/vers/config');

// Recharger après modification des fichiers
$config->reload();

// Charger depuis un autre chemin
$config->loadFrom('/nouveau/chemin');

// Charger depuis plusieurs chemins
$config->loadFrom(['/chemin1', '/chemin2']);

Gestion des environnements

Fichiers d'environnement

/config
  ├── app.php
  ├── database.php
  ├── local.app.php         (surcharge pour local)
  ├── local.database.php    (surcharge pour local)
  ├── prod.app.php          (surcharge pour production)
  └── prod.database.php     (surcharge pour production)

Utilisation

// Charger avec environnement local
$config = new ConfigManager('/config', 'local');

// Les valeurs de local.app.php surchargent app.php
$debug = $config->get('app.debug');

// Changer d'environnement
$config->setEnvironment('production');
$config->reload();

// Vérifier l'environnement actuel
$env = $config->getEnvironment();

Exemple de surcharge

// config/app.php
return [
    'debug' => true,
    'cache_enabled' => false,
];

// config/prod.app.php
return [
    'debug' => false,      // Surcharge
    'cache_enabled' => true, // Surcharge
    'log_level' => 'error', // Nouveau
];

// En mode production
$config = new ConfigManager('/config', 'prod');
$config->get('app.debug');         // false (surchargé)
$config->get('app.cache_enabled'); // true (surchargé)
$config->get('app.log_level');     // 'error' (nouveau)

Façade statique

Initialisation

use Npds\Config\Facades\Config;

// Initialiser une seule fois
Config::init('/chemin/vers/config', 'local');

// Ou sans paramètres
Config::init();

Utilisation

use Npds\Config\Facades\Config;

// Récupérer
Config::get('app.name', 'défaut');
Config::has('database.host');
Config::all();

// Définir
Config::set('app.version', '1.0.0');

// Récupérer l'instance du manager
$manager = Config::getInstance();

// Réinitialiser (pour les tests)
Config::resetInstance();

Helpers globaux

Utilisation

// Charger les helpers (dans bootstrap ou autoload)
require 'vendor/npds/config/src/helpers.php';

// Utiliser config() partout
$name = config('app.name');
$debug = config('app.debug', false);

// Définir
config_set('app.version', '1.0.0');

// Vérifier
if (config_has('database.host')) {
    // ...
}

// Récupérer tout
$all = config();

Exemples complets

Exemple 1 : Configuration d'application

use Npds\Config\ConfigManager;

$env = $_ENV['APP_ENV'] ?? 'production';
$config = new ConfigManager(__DIR__ . '/config', $env);

class Application
{
    private ConfigManager $config;
    
    public function __construct(ConfigManager $config)
    {
        $this->config = $config;
    }
    
    public function getName(): string
    {
        return $this->config->get('app.name');
    }
    
    public function isDebugMode(): bool
    {
        return $this->config->boolean('app.debug', false);
    }
    
    public function getVersion(): string
    {
        return $this->config->string('app.version', '1.0.0');
    }
}

$app = new Application($config);
echo $app->getName();

Exemple 2 : Configuration multi-environnements

// config/app.php
return [
    'name' => 'Mon App',
    'debug' => true,
    'cache' => false,
];

// config/prod.app.php
return [
    'debug' => false,
    'cache' => true,
];

// config/local.app.php
return [
    'debug' => true,
    'log_level' => 'debug',
];

// Dans l'application
$env = getenv('ENV') ?: 'production';
$config = new ConfigManager(__DIR__ . '/config', $env);

if ($config->get('app.debug')) {
    error_reporting(E_ALL);
    ini_set('display_errors', '1');
}

Exemple 3 : Configuration de base de données

use Npds\Config\ConfigManager;

class DatabaseConfig
{
    private ConfigManager $config;
    
    public function __construct(ConfigManager $config)
    {
        $this->config = $config;
    }
    
    public function getConnection(string $name = null): array
    {
        $default = $config->get('database.default', 'mysql');
        $connectionName = $name ?? $default;
        
        return $this->config->getSection("database.connections.{$connectionName}");
    }
    
    public function getAllConnections(): array
    {
        return $this->config->getSection('database.connections');
    }
}

$config = new ConfigManager('/config');
$dbConfig = new DatabaseConfig($config);

$mysqlConn = $dbConfig->getConnection('mysql');

Exemple 4 : Conversion de types

use Npds\Config\ConfigManager;

$config = new ConfigManager('/config');

// Conversions de types disponibles
$debug = $config->boolean('app.debug', false);       // bool
$port = $config->integer('database.port', 3306);     // int
$timeout = $config->float('cache.timeout', 1.5);     // float
$name = $config->string('app.name', 'App');          // string
$providers = $config->array('app.providers', []);    // array

Exemple 5 : Sauvegarde de configuration

use Npds\Config\ConfigManager;

$config = new ConfigManager('/config');

// Ajouter une nouvelle configuration
$config->set('app.version', '2.0.0');
$config->set('features.new_ui', true);

// Sauvegarder tout en PHP
$config->save('/config/custom.php', 'php');

// Sauvegarder une section en JSON
$config->save('/config/database.json', 'json', 'database');

Bonnes pratiques

1. Organisation des fichiers

/config
  ├── app.php          # Paramètres généraux
  ├── database.php     # Configuration BD
  ├── cache.php        # Configuration cache
  ├── mail.php         # Configuration email
  │
  ├── local.app.php       # Surcharges local
  ├── local.database.php
  │
  ├── prod.app.php        # Surcharges production
  ├── prod.database.php
  │
  └── .gitignore       # Ignorer local.*

2. Initialisation centralisée

// bootstrap.php ou config.php

use Npds\Config\Facades\Config;

Config::init(
    __DIR__ . '/config',
    $_ENV['APP_ENV'] ?? 'production'
);

// Puis utiliser partout
config('app.debug');

3. Validation de configuration

$config = new ConfigManager('/config');

// Vérifier les clés requises
$required = ['app.name', 'database.host', 'cache.driver'];

foreach ($required as $key) {
    if (!$config->has($key)) {
        throw new Exception("Configuration manquante: {$key}");
    }
}

4. Configuration avec variables d'environnement

// config/app.php
return [
    'name' => $_ENV['APP_NAME'] ?? 'App',
    'debug' => $_ENV['APP_DEBUG'] === 'true',
    'version' => $_ENV['APP_VERSION'] ?? '1.0.0',
];

Référence complète de l'API

ConfigManager

Chargement

__construct($paths, ?string $environment) - Initialiser avec chemin(s) et environnement
load(string $path): void - Charger depuis un chemin
loadFrom($paths): void - Charger depuis un ou plusieurs chemins
reload(): void - Recharger les fichiers

Accès aux données

get(string $key, $default = null) - Récupérer une valeur
set(string $key, $value): void - Définir une valeur
has(string $key): bool - Vérifier l'existence
all(): array - Récupérer tout
getSection(string $key): array - Récupérer une section
pull(string $key, $default = null) - Récupérer et supprimer
remove(string $key): void - Supprimer une clé
clear(): void - Vider tout

Environnement

setEnvironment(?string $environment): self - Définir l'environnement
getEnvironment(): ?string - Récupérer l'environnement actuel

Extensions

addSupportedExtension(string $extension): self - Ajouter extension
removeSupportedExtension(string $extension): self - Retirer extension
getSupportedExtensions(): array - Lister les extensions

Sauvegarde

save(string $file, string $format = 'php', ?string $key = null): bool - Sauvegarder

Conversion de types

boolean(string $key, bool $default = false): bool
integer(string $key, int $default = 0): int
float(string $key, float $default = 0.0): float
string(string $key, string $default = ''): string
array(string $key, array $default = []): array

Repository

Données

get(string $key, $default = null) - Récupérer
set(string $key, $value): void - Définir
has(string $key): bool - Vérifier
all(): array - Tout récupérer
clear(): void - Vider

Opérations

merge(array $items, bool $recursive = true): void - Fusionner
pull(string $key, $default = null) - Récupérer et supprimer
remove(string $key): void - Supprimer
isEmpty(): bool - Vérifier si vide

Délimiteur

setDelimiter(string $delimiter): self - Changer le délimiteur
getDelimiter(): string - Récupérer le délimiteur

Façade Config

init($paths, ?string $environment): ConfigManager
getInstance(): ConfigManager
resetInstance(): void
Toutes les méthodes de ConfigManager en static

Helpers

config(?string $key = null, $default = null) - Récupérer ou tout
config_set(string $key, $value): void - Définir
config_has(string $key): bool - Vérifier

Conclusion

La bibliothèque npds-config fournit une solution légère et complète pour la gestion de configuration en PHP. Avec support des fichiers PHP et JSON, gestion des environnements, et API intuitive, elle est parfaite pour tous les types d'applications.

Points clés :

✅ Zéro dépendances
✅ Notation par points pour accès facile
✅ Support multi-environnements
✅ Chargement automatique de fichiers
✅ Façade statique pratique
✅ Helpers globaux
✅ Fusion récursive
✅ Conversion de types
✅ 53 tests qui passent

Pour plus d'informations, visitez le dépôt GitHub.

nicolas2-dev / npds-config

Maintainers

Details

README

Installation

Table des matières

Introduction

Classes principales

Npds\Config\ConfigManager

Npds\Config\FileLoader

Npds\Config\Repository

Npds\Config\Facades\Config

Configuration rapide

Initialisation simple

Initialisation avec environnement

Initialisation avec plusieurs chemins

Utilisation de base

Récupérer des valeurs

Définir des valeurs

Opérations avancées

Chargement de fichiers

Structure des fichiers

Fichier PHP

Fichier JSON

Chargement et rechargement

Gestion des environnements

Fichiers d'environnement

Utilisation

Exemple de surcharge

Façade statique

Initialisation

Utilisation

Helpers globaux

Utilisation

Exemples complets

Exemple 1 : Configuration d'application

Exemple 2 : Configuration multi-environnements

Exemple 3 : Configuration de base de données

Exemple 4 : Conversion de types

Exemple 5 : Sauvegarde de configuration

Bonnes pratiques

1. Organisation des fichiers

2. Initialisation centralisée

3. Validation de configuration

4. Configuration avec variables d'environnement

Référence complète de l'API

ConfigManager

Chargement

Accès aux données

Environnement

Extensions

Sauvegarde

Conversion de types

Repository

Données

Opérations

Délimiteur

Façade Config

Helpers

Conclusion