Driver Config Laravel Package

Getting Started

1. Install alongside the ADK. This is a driver package, not a standalone library — it is a dependency of kipchak/adk. Pull it in with Composer and let the ADK discover it:

   composer require kipchak/adk kipchak/driver-config
   

   Verify the driver is registered by checking your ADK config for a config driver key or a driver registry entry.

2. Look here first.

   • The package's src/ directory: expect a driver class implementing the ADK's config-driver contract (typically a DriverInterface or similar) plus a service provider.
   • The config/ directory shipped by the package: this is where source paths, environment overlays, and any defaults live.
   • The ADK's own documentation on drivers — the package is intentionally thin, so most behavior is defined by the ADK contract.

3. First use case. Register a config source (a PHP array file, a directory of config files, or a config store) with the ADK so that your API endpoints can resolve runtime configuration — feature flags, per-endpoint schemas, rate-limit values, or environment-specific settings — without hard-coding them into controllers. In a Laravel app you would typically do this in a service provider that calls the ADK's driver manager with the config driver.

Implementation Patterns

• Explicit driver registration. In config/kipchak.php (or the ADK's equivalent) map 'config' => Kipchak\Driver\Config\ConfigDriver::class and pass the source path or repository. Doing this explicitly in your own config avoids surprises when the ADK is upgraded.
• Source layering. Use the driver to compose configuration: base defaults → environment overrides → per-request or per-tenant values. Keep each layer as a distinct registered source so you can debug which layer won a given key.
• Laravel service provider bridge. If the ADK is framework-agnostic, wrap driver construction in a singleton binding ($this->app->singleton(...)) so the same driver instance — and any in-memory cache it holds — is reused across the request lifecycle.
• Testing. Because the driver is just config resolution, replace it in tests with an in-memory source and assert that your endpoint layer reads the expected keys. Do not test against the filesystem driver unless you are testing the driver itself.
• Cache-aware bootstrapping. In config-cached Laravel environments, resolve the driver lazily (via app() inside boot) rather than at class-load time, so the ADK does not read config sources before Laravel has registered them.
• Contract-first extension. If your application needs database- or Vault-backed config, implement the ADK's driver contract yourself and reuse this package's source-resolution conventions rather than forking it. This package is small enough that extension is cheap.

Gotchas and Tips

• Zero dependents is a signal, not a blocker. With no downstream packages you are on the bleeding edge. Pin to an exact minor version and read the changelog before every bump; there is effectively no community bug-fix stream behind you.
• Driver resolution order. The ADK will likely pick the first registered driver matching a key. If you register both config and another driver, be explicit about which one handles which source — do not rely on load order.
• Config caching. Laravel's php artisan config:cache snapshots config at build time. If your driver reads from the filesystem at request time, remember that cached Laravel config and driver-resolved config are two separate stores and can diverge.
• Debugging. Enable the ADK's driver logging first. If keys resolve unexpectedly, log which source won each key — layered sources are the most common source of "why is this value wrong?" tickets.
• Extension points. The ADK's driver interface is the intended seam. Subclass or wrap the driver rather than editing vendor code; vendor edits will be lost on the next composer update.
• No stars / no docs. You will largely be reading source. Spend thirty minutes on the driver class and its tests (if present) before integrating — that is faster than inferring behavior from the ADK docs alone.
• Watch for tight coupling to the ADK version. This package's contract tracks the ADK's driver interface; a major ADK bump can silently break the driver. Add a smoke test that resolves a known config key on boot so upgrades fail loudly.