fast-forward / config

v1.7.3 2026-10-20 15:00 UTC

Requires

• php: ^8.3
• brick/varexporter: ^0.5 || ^0.6 || ^0.7
• laminas/laminas-config-aggregator: ^1.13
• psr/container: ^1.0 || ^2.0
• psr/simple-cache: ^3.0

Requires (Dev)

• fast-forward/dev-tools: dev-main
• symfony/cache: ^7.4

Suggests

• llm/skills: Optionally synchronize the bundled agent skill in consumer projects.

MIT

• Felipe Sayão Lobato Abreu

Published on Packagist.org on 2026-10-20 15:01 UTC

README

FastForward Config is a flexible and modern PHP configuration library built for performance, extendability, and lazy-loading behavior. It supports dot-notation keys, recursive directory loading, Laminas-compliant configuration providers, and optional PSR-16 caching.

✨ Features

• 🔑 Dot notation access: $config->get('app.env')
• 📁 Load from arrays, PHP files, directories, or providers
• 💾 Optional persistence for single PHP files and PSR-16 cache
• ♻️ Lazy-loading with __invoke()
• 🧩 Aggregation of multiple sources
• 🗂 Recursive directory support
• 🔌 Compatible with Laminas ConfigProviders

📦 Installation

composer require fast-forward/config

🚀 Quick Start

Load configuration from multiple sources

use function FastForward\Config\config;

$config = config(
    ['app' => ['env' => 'production']],
    __DIR__ . '/config',
    \Vendor\Package\ConfigProvider::class
);

echo $config->get('app.env'); // "production"

Combine module lists

$config = config(
    ['console' => ['commands' => ['A', 'B']]],
    ['console' => ['commands' => ['C', 'A']]],
);

$config->get('console.commands'); // ['A', 'B', 'C', 'A']

Source aggregation concatenates sequential lists in source order, retains duplicates, merges maps recursively, and lets later scalar values win. Arrays, config objects, PHP files, directories, and invokable provider class names use this behavior. Direct set() retains its existing index-replacement behavior. See the merge and boundary semantics.

Cache configuration using PSR-16

use function FastForward\Config\configCache;

/** @var \Psr\SimpleCache\CacheInterface $cache */
$config = configCache($cache, ['foo' => 'bar']);

echo $config->get('foo'); // "bar"

Load from a single PHP file (with optional persistence)

use function FastForward\Config\configFile;

$config = configFile(__DIR__ . '/config.php', persistent: true);

$config->set('app.env', 'staging'); // Persists changes back to config.php

Load from a recursive directory

use function FastForward\Config\configDir;

$config = configDir(__DIR__ . '/config', recursive: true);

Use Laminas-style providers

use function FastForward\Config\configProvider;

$config = configProvider([
    new Vendor\Package\Provider1(),
    new Vendor\Package\Provider2(),
]);

🧪 Access & Mutation

$config->set('db.host', 'localhost');
echo $config->get('db.host'); // "localhost"

$config->has('app.debug'); // true/false

print_r($config->toArray());

📁 Directory Structure Example

config/
├── app.php
├── db.php
└── services/
    └── mail.php

🧰 API Summary

• config(...$configs): ConfigInterface
• configFile(string $file, bool $persistent = false, array|ConfigInterface|null $defaultConfig = null): ConfigInterface
• configCache(CacheInterface $cache, ...$configs): ConfigInterface
• configDir(string $rootDirectory, bool $recursive = false, ?string $cachedConfigFile = null): ConfigInterface
• configProvider(iterable $providers, ?string $cachedConfigFile = null): ConfigInterface

Agent skill

The portable fast-forward-config skill guides coding agents consuming the library, including version checks, composition, paths, persistence, cache identities and PSR-11 integration. Its supported contract is fast-forward/config ^1.7 on PHP 8.3+; inspect the application's installed version before selecting APIs. See the installation guide for manual project/global copies, optional llm/skills project synchronization, pinned Skills CLI commands, updates, rollback and removal. Composer ships the source files; the consumer chooses installation and activation.

🛡 License

MIT © 2025 Felipe Sayão Lobato Abreu