Enhance documentation for FastForward Config

- Updated providers documentation to clarify provider-based configuration and usage examples.
- Added detailed sections on exceptions, helpers, and traits to improve understanding of the package's capabilities.
- Expanded API reference with clear descriptions of interfaces and classes, including their responsibilities and use cases.
- Improved installation instructions with requirements and package details.
- Enhanced quick start guide with practical examples for loading configurations from various sources.
- Introduced a new section on compatibility, outlining supported capabilities and practical notes.
- Added a FAQ section addressing common questions and clarifying usage scenarios.
- Created a new page for common use cases to provide realistic examples of configuration patterns.
- Improved directory structure documentation to clarify loading and organizing configuration files.
- Added links for coverage reports and dependencies for better resource navigation.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

README.md

@@ -6,7 +6,7 @@
 
 ## ✨ Features
 
-- 🔑 Dot notation access: `config->get('app.env')`
+- 🔑 Dot notation access: `$config->get('app.env')`
 - 📁 Load from arrays, directories, or providers
 - ♻️ Lazy-loading with `__invoke()`
 - 🧩 Aggregation of multiple sources
@@ -29,8 +29,7 @@ composer require fast-forward/config
 ### Load configuration from multiple sources:
 
 ```php
-use FastForward\Config\{config, configDir, configCache};
-use Symfony\Component\Cache\Simple\FilesystemCache;
+use function FastForward\Config\config;
 
 $config = config(
     ['app' => ['env' => 'production']],
@@ -46,12 +45,10 @@ echo $config->get('app.env'); // "production"
 ### Cache configuration using PSR-16:
 
 ```php
-$cache = new FilesystemCache();
+use function FastForward\Config\configCache;
 
-$config = configCache(
-    cache: $cache,
-    ['foo' => 'bar']
-);
+/** @var \Psr\SimpleCache\CacheInterface $cache */
+$config = configCache($cache, ['foo' => 'bar']);
 
 echo $config->get('foo'); // "bar"
 ```
@@ -61,6 +58,8 @@ echo $config->get('foo'); // "bar"
 ### Load from a recursive directory:
 
 ```php
+use function FastForward\Config\configDir;
+
 $config = configDir(__DIR__ . '/config', recursive: true);
 ```
 
@@ -69,6 +68,8 @@ $config = configDir(__DIR__ . '/config', recursive: true);
 ### Use Laminas-style providers:
 
 ```php
+use function FastForward\Config\configProvider;
+
 $config = configProvider([
     new Vendor\Package\Provider1(),
     new Vendor\Package\Provider2(),
@@ -106,8 +107,8 @@ config/
 
 - `config(...$configs): ConfigInterface`
 - `configCache(CacheInterface $cache, ...$configs): ConfigInterface`
-- `configDir(string $dir, bool $recursive = false, ?string $cache = null): ConfigInterface`
-- `configProvider(iterable $providers, ?string $cache = null): ConfigInterface`
+- `configDir(string $rootDirectory, bool $recursive = false, ?string $cachedConfigFile = null): ConfigInterface`
+- `configProvider(iterable $providers, ?string $cachedConfigFile = null): ConfigInterface`
 
 ---
 

composer.json

@@ -43,7 +43,8 @@
             "ergebnis/composer-normalize": true,
             "fast-forward/dev-tools": true,
             "phpdocumentor/shim": true,
-            "phpro/grumphp": true
+            "phpro/grumphp": true,
+            "pyrech/composer-changelogs": true
         },
         "platform": {
             "php": "8.3.0"

docs/advanced/caching.rst

@@ -1,30 +1,77 @@
 Caching
 =======
 
-FastForward Config supports PSR-16 caching for configuration data. This allows you to cache the merged configuration, improving performance for large or complex setups.
+FastForward Config supports two different caching approaches. They solve related problems, but they are not the same feature.
 
-How it works
-------------
-- Wrap your config with ``configCache($cache, ...)``.
-- The first access will store the merged config in the cache.
-- Subsequent accesses will read from cache, unless you clear it.
-- Any PSR-16 compatible cache (e.g., Symfony, Doctrine, etc) is supported.
+.. list-table:: Cache options
+   :header-rows: 1
 
-Example
--------
+   * - Option
+     - Best for
+     - Storage
+   * - ``configCache()`` or ``CachedConfig``
+     - Caching the final merged config behind any PSR-16 backend.
+     - Your cache implementation.
+   * - ``cachedConfigFile`` on ``configDir()`` or ``configProvider()``
+     - Reusing a generated PHP cache file for directory or provider aggregation.
+     - A file on disk handled by Laminas ConfigAggregator.
+
+Caching With PSR-16
+-------------------
+
+Use ``configCache()`` when your application already has a PSR-16 cache backend:
+
+.. code-block:: php
+
+   use Psr\SimpleCache\CacheInterface;
+   use function FastForward\Config\configCache;
+
+   /** @var CacheInterface $cache */
+   $config = configCache($cache, __DIR__ . '/config');
+
+On the first resolution, the merged configuration is stored in the cache. Later resolutions read from the same cache key.
+
+Using A Custom Cache Key Or Persistent Writes
+---------------------------------------------
+
+Instantiate ``CachedConfig`` directly when you need more control:
+
+.. code-block:: php
+
+   use FastForward\Config\CachedConfig;
+   use Psr\SimpleCache\CacheInterface;
+   use function FastForward\Config\configDir;
+
+   /** @var CacheInterface $cache */
+   $config = new CachedConfig(
+       cache: $cache,
+       defaultConfig: configDir(__DIR__ . '/config', recursive: true),
+       persistent: true,
+       cacheKey: 'app-config',
+   );
+
+.. warning::
+
+   ``configCache()`` creates ``CachedConfig`` with the default ``persistent: false`` behavior. That means ``set()`` and ``remove()`` update the resolved in-memory config, but they do not write the modified result back to the cache backend unless you instantiate ``CachedConfig`` yourself with ``persistent: true``.
+
+Caching Provider Or Directory Aggregation To A File
+---------------------------------------------------
+
+If you want Laminas ConfigAggregator to write a cache file, use ``cachedConfigFile``:
 
 .. code-block:: php
 
-   use Symfony\Component\Cache\Simple\FilesystemCache;
+   use function FastForward\Config\configDir;
 
-   $cache = new FilesystemCache();
-   $config = configCache($cache, ['foo' => 'bar']);
+   $config = configDir(
+       __DIR__ . '/config',
+       recursive: true,
+       cachedConfigFile: __DIR__ . '/../var/cache/config.php',
+   );
 
-Tips
-----
-- Use caching in production for best performance.
-- You can combine caching with any config aggregation.
+Choose The Right Strategy
+-------------------------
 
-See also:
-- `PSR-16 Simple Cache <https://www.php-fig.org/psr/psr-16/>`_
-- `Live Coverage Report <../../public/coverage/index.html>`_
+- Use ``configCache()`` when you already have a PSR-16 cache service.
+- Use ``cachedConfigFile`` when you want an explicit generated file for directory or provider aggregation.
+- Clear or rebuild your chosen cache when configuration sources change between deployments.

docs/advanced/index.rst

@@ -1,11 +1,12 @@
 Advanced Topics
 ===============
 
-This section covers advanced usage, such as lazy loading, custom providers, and caching strategies. For implementation details, see the `GitHub repository <https://github.com/php-fast-forward/config>`_ and the `Live Coverage Report <../public/coverage/index.html>`_.
+These pages explain how the package behaves once you move past the first examples. They are especially useful when you want to integrate FastForward Config into a framework, optimize startup work, or control caching more precisely.
 
 .. toctree::
    :maxdepth: 2
 
+   integration
    lazy-loading
    providers
    caching

docs/advanced/integration.rst

@@ -0,0 +1,61 @@
+Integration
+===========
+
+This page focuses on the main integration hook exposed by the package: ``ConfigContainer``.
+
+Using ConfigContainer
+---------------------
+
+``FastForward\\Config\\Container\\ConfigContainer`` adapts any ``ConfigInterface`` instance to ``Psr\Container\ContainerInterface``.
+
+.. code-block:: php
+
+   use FastForward\Config\ConfigInterface;
+   use FastForward\Config\Container\ConfigContainer;
+   use function FastForward\Config\config;
+
+   $config = config([
+       'database.host' => 'localhost',
+       'database.port' => 3306,
+   ]);
+
+   $container = new ConfigContainer($config);
+
+   $sameConfig = $container->get('config');
+   $sameConfigAgain = $container->get(ConfigInterface::class);
+   $host = $container->get('config.database.host');
+
+Resolved Identifiers
+--------------------
+
+.. list-table:: Identifiers handled by ConfigContainer
+   :header-rows: 1
+
+   * - Identifier
+     - Returns
+   * - ``config``
+     - The wrapped config object.
+   * - ``FastForward\\Config\\ConfigInterface``
+     - The wrapped config object.
+   * - The concrete config class name
+     - The wrapped config object.
+   * - ``config.some.key``
+     - The resolved configuration value.
+   * - ``FastForward\\Config\\Container\\ConfigContainer``
+     - The container wrapper itself.
+
+When To Use It
+--------------
+
+``ConfigContainer`` is most useful when:
+
+- a part of your application already expects ``ContainerInterface``;
+- you want container-style lookup for config values such as ``config.database.host``;
+- you want to expose the config object itself under a stable alias.
+
+Troubleshooting
+---------------
+
+- If ``has('config.some.key')`` is false, confirm that the key exists in the wrapped config object.
+- If ``get()`` cannot resolve an identifier, ``ContainerNotFoundException`` is thrown.
+- If your application already has its own container, you can still use ``ConfigContainer`` as a small adapter or register the wrapped config object under similar service names there.

docs/advanced/lazy-loading.rst

@@ -1,29 +1,57 @@
 Lazy Loading
 ============
 
-FastForward Config uses lazy loading to defer the loading and merging of configuration data until it is actually needed. This is achieved via the ``__invoke()`` method on config objects, which builds the final configuration only on first access.
+Most config objects in this package delay work until you actually use them. This keeps bootstrap code light and lets you compose multiple sources before paying the cost of loading and merging them.
 
-How it works
-------------
+Which Types Are Lazy
+--------------------
 
-- When you create a config object (e.g., with ``config()`` or ``configDir()``), no files or providers are loaded immediately.
-- The actual loading and merging only happens when you call a method like ``get()``, ``set()``, or use the object as an array.
-- This is implemented via the ``LazyLoadConfigTrait`` (see `source <https://github.com/php-fast-forward/config/blob/main/src/LazyLoadConfigTrait.php>`_).
+The following types resolve themselves on first use:
 
-Benefits
---------
-- Faster application startup.
-- Only loads what you actually use.
-- Supports dynamic and late-bound config sources.
+- ``AggregateConfig``
+- ``DirectoryConfig``
+- ``RecursiveDirectoryConfig``
+- ``LamiasConfigAggregatorConfig``
+- ``CachedConfig``
+
+``ArrayConfig`` is the main eager implementation because it already has all data in memory.
+
+What Triggers Resolution
+------------------------
+
+The first call to any of the operations below will build the underlying config object:
+
+- ``get()``
+- ``has()``
+- ``set()``
+- ``remove()``
+- ``toArray()``
+- iteration with ``foreach``
+- array access such as ``$config['app.env']``
+
+After the first resolution, the trait reuses the same internal config instance.
 
 Example
 -------
 
 .. code-block:: php
 
-	$config = configDir(__DIR__ . '/config');
-	// At this point, nothing is loaded yet!
-	$env = $config->get('app.env'); // Now the config is loaded and merged.
+   use function FastForward\Config\configDir;
+
+   $config = configDir(__DIR__ . '/config', recursive: true);
+   // No files have been merged yet.
+
+   $environment = $config->get('app.env');
+   // The directory is read and merged here, on first access.
+
+Why This Matters
+----------------
+
+- Startup stays simple even when you aggregate several sources.
+- Errors from unreadable directories or broken providers may appear on first use instead of object creation.
+- You can force resolution early by calling ``toArray()`` during bootstrap if that better matches your application's error handling.
+
+For Library Authors
+-------------------
 
-See also:
-- `Live Coverage Report <../../public/coverage/index.html>`_
+The lazy behavior is implemented through ``LazyLoadConfigTrait``. This is mainly useful if you build your own ``ConfigInterface`` implementation and want it to defer work until first access.