Configuration Module Laravel Package

Getting Started

This is a Streams Platform module, not a standalone settings package. Before you install it, confirm you're already running anomaly/streams-platform (PyroCMS 3.x) — the module leans on Streams namespaces, admin routing, and the module discovery system, so it will not boot in a bare Laravel app.

Minimal steps:

1. composer require anomaly/configuration-module
2. Register the provider (or rely on Streams' module auto-discovery if anomaly/streams-platform is installed): add Anomaly\ConfigurationModule\ConfigurationModuleServiceProvider::class to config/app.php.
3. Publish the module's config and migrations if the service provider exposes them:

   php artisan vendor:publish --provider="Anomaly\ConfigurationModule\ConfigurationModuleServiceProvider"
   php artisan migrate
   

4. Log into the control panel and look for the Configuration section in the admin sidebar.

Where to look first when reading the source:

• src/ConfigurationModuleServiceProvider.php — bindings, config merging, route registration.
• src/Configuration/ConfigurationRepository.php (or similarly named) — the read/write API you'll use in code.
• resources/config/ — default config keys and groups.
• migrations/ — the schema backing stored values; this tells you the shape of what you can persist.

First use case: store a handful of global, admin-editable settings (site name, contact email, feature flags) that must persist in the database and be readable anywhere in your app without hardcoding values. That's the sweet spot for this module — not per-request, per-tenant data.

Implementation Patterns

Read through the repository, not the model. Resolve the configuration repository from the container so you get caching and defaults for free:

$config = app(\Anomaly\ConfigurationModule\Configuration\ConfigurationRepository::class);
$value  = $config->get('anomaly.module.configuration::mail.from_address');

Avoid querying the underlying Eloquent model directly — you'll skip whatever normalization, default handling, or cache layer the module provides.

Group settings by namespace. Every config key is namespaced (vendor.module::group.key). When you add your own settings, pick a stable namespace matching your addon and use it consistently across code and admin forms. This makes it trivial to dump, migrate, or clear one addon's settings at a time.

Write settings programmatically in seeders, install migration hooks, or admin commands rather than hand-editing rows. This keeps you inside whatever validation/locking the repository does and survives schema changes:

$config->set('vendor.module::mail.from_address', '[email protected]');

Fall back to Laravel config when a DB value isn't set. A common pattern is a thin service class that checks the configuration repository first, then config(), then a hardcoded default — so fresh installs work without a full settings seed:

public function mailFrom(): string
{
    return $this->config->get('vendor.module::mail.from_address')
        ?? config('mail.from.address', '[email protected]');
}

Inject settings where they're needed, not globally. Bind a Settings value object in your service provider that pulls from the repository once per request, and inject that into controllers/services. This keeps tests simple (mock the value object) and avoids facade calls sprinkled everywhere.

Pair with feature flags. For boolean settings, expose them as methods (featureEnabled('beta_checkout')) so you can later swap the implementation for a real flag service without touching call sites.

Gotchas and Tips

Cache invalidation is the number-one pitfall. After writing a setting, clear whatever cache the repository wraps (usually php artisan config:clear won't help — use the module's cache or php artisan cache:clear). If admin changes don't show up immediately, suspect a stale cache before anything else.

Key naming collisions. Namespaces are the only thing stopping mail.from from two addons overwriting each other. Always include the vendor segment. If you find duplicate keys in the DB, you almost certainly wrote without a namespace.

Migration ordering matters. This module's migrations must run before any addon migration that seeds settings into it. If you're building an addon that depends on it, declare anomaly/configuration-module as a composer dependency and rely on Streams' install ordering rather than calling migrate yourself.

Don't use this as a general-purpose key-value store. It's designed for a bounded set of admin-managed configuration. High-write, per-user, or high-cardinality data belongs in your own table — you'll fight the admin UI and caching otherwise.

Debugging: use php artisan tinker and inspect the repository's get() output for a known key. If it returns null, check (a) the key is namespaced exactly as stored, (b) the migration ran, (c) cache isn't stale. Log the raw row if needed — the admin form and the repository may disagree on key format.

Extension points: the service provider is your hook for custom config groups and form fields. If the admin UI lacks a field type you need, register a custom field via the Streams field system rather than forking the module — it's the intended extension path and survives upgrades.

Version pinning. With zero stars and effectively no community signal, treat upgrades as breaking until proven otherwise. Pin the exact version in composer.json, and add an integration test that boots the provider and reads one setting so a silent incompatibility with a new Streams release fails loudly instead of at runtime in production.