Settings Bundle Laravel Package

Getting Started

Install with Composer:

composer require idmarinas/settings-bundle

Enable the bundle (this is a Symfony bundle, not a Laravel package — see Gotchas) by adding Idmarinas\SettingsBundle\SettingsBundle to config/bundles.php, then import the bundle's routing only if you intend to use its controller/UI.

Look first at:

1. config/packages/idmarinas_settings.yaml — the bundle's configuration tree (table name, cache, entity class overrides).
2. The SettingsInterface service — this is the entry point for reading and writing values.
3. The Doctrine entity/migration the bundle ships — run php bin/console doctrine:migrations:migrate after install to create the settings table.

First use case: replace hardcoded application settings (site name, contact email, feature flags, maintenance mode) with rows in the settings table, and read them through the injected settings service instead of env/config constants so operators can change them at runtime.

use Idmarinas\SettingsBundle\Settings\SettingsInterface;

class HomeController
{
    public function __construct(private SettingsInterface $settings) {}

    public function index(): Response
    {
        $title = $this->settings->get('site.name', 'Default');
        // ...
    }
}

Implementation Patterns

Typed access. Register settings with an explicit type (string, int, bool, float, array/json) rather than storing everything as strings. The bundle applies casts on read, so get('feature.enabled') returns a real bool, which keeps if checks and Twig conditions clean.

Grouped namespaces. Use dot-notation keys (mail.smtp.host, ui.theme) so you can later bulk-read a group and mirror that structure in your admin UI. This also makes it obvious which subsystem owns a value.

Seeding defaults. Create settings at install time (a data migration or a fixture/console command) instead of scattering if ($settings->has(...)) fallbacks across your code. The bundle will then always return a value with the correct type.

Read-through service, not static calls. Inject SettingsInterface into controllers, services, and form types. This keeps settings mockable in tests and avoids the global-state problems that plague config-constant approaches.

Admin editing surface. The bundle ships a controller for a settings administration UI — wire it under a protected firewall (e.g., ^/admin/settings requires ROLE_ADMIN) rather than exposing it with the default access controls. Edit forms should be built from the same type registry so a bool is a checkbox, an int is a number input, and an array is a JSON textarea with validation.

Cache-aware reads. For hot paths, fetch once per request into a local property rather than calling get() repeatedly; the bundle's cache helps, but the service call itself is not free.

Twig integration. Expose settings to templates via a Twig extension or by passing them from the controller — avoid letting templates query the service ad hoc, which couples view code to the bundle's API.

Gotchas and Tips

• Symfony vs Laravel. Despite being evaluated as a "Laravel developer" package, idmarinas/settings-bundle is a Symfony bundle. There is no Laravel service provider, no config/settings.php publish tag, and no facade. If you're on Laravel, you'd either use the underlying entity/model directly via a thin service, or use a Laravel-native package instead; budget time for this translation before committing.
• Cache invalidation. The bundle layers caching over the database. If you write via raw SQL or a separate admin tool, cached values will go stale until the cache is cleared. Always mutate through the service (or call the cache-clear hook) so both layers stay in sync.
• Doctrine coupling. The bundle is built around Doctrine ORM. In a Laravel app using Eloquent, you'll need to either install Doctrine alongside Eloquent (painful) or reimplement the storage layer — check this before adopting.
• Migrations ordering. If you override the entity or table name, make sure your own migration runs after the bundle's, or the schema will mismatch on fresh installs. Pin the bundle version in composer.json so an upgrade can't silently alter the shipped migration.
• Type drift. Settings edited by hand in the database can violate the declared type (e.g., "yes" in a bool field). The bundle casts on read, but casts can be lossy; validate on save from your admin UI to prevent this.
• Serialization of complex values. Arrays are usually JSON-encoded. Avoid storing objects or closures — they won't round-trip cleanly and will break casts on upgrade.
• Extension points. Most overrides happen through configuration: swap the entity class, the repository, or the cache pool in idmarinas_settings.yaml. If you need custom behaviour, decorate SettingsInterface rather than subclassing the concrete service, so the bundle's own wiring continues to work.
• Version pinning. The 1.2.0 release notes are minimal (documentation link + changelog), so treat minor bumps as potentially behaviour-changing until you've read the full changelog at github.com/idmarinas/settings-bundle/compare/1.1.0...1.2.0. Lock to ~1.2 and review release notes before upgrading in production.