Settingsbundle Laravel Package

Getting Started

The package installs as a Symfony bundle, so treat it as drop-in service wiring around a Doctrine-backed setting table.

1. Install: composer require lexxpavlov/settingsbundle
2. Register the bundle: add Lexxpavlov\SettingsBundle\LexxpavlovSettingsBundle to config/bundles.php (or AppKernel on older Symfony).
3. Ensure Doctrine is configured — the bundle persists settings through Doctrine, so you need a working DBAL/ORM connection.
4. Create the schema: either php bin/console doctrine:schema:update --force in dev, or generate a migration and run it. Don't rely on schema:update in production.
5. Autowire the manager: the core entry point is Lexxpavlov\SettingsBundle\Settings\SettingsManager. Inject it into a controller or service.

public function __construct(private SettingsManager $settings) {}

$perPage = $this->settings->get('catalog.per_page', 20); // read with default
$this->settings->set('catalog.per_page', 50);            // persist override

Where to look first:

• SettingsManager — the public read/write API.
• The Setting entity and its repository — how rows are persisted and scoped.
• config/packages/lexxpavlov_settings.yaml (default bundle config) — table name, owner class, type definitions.

First realistic use case: replace the hard-coded items_per_page, maintenance_mode, or mail.from value in config/ with a persisted setting the admin can edit from a back-office form, without a redeploy.

Implementation Patterns

Centralize key names. Don't scatter string keys through the codebase. Define them once (class constants, an enum, or a small settings catalog) and reference the constant everywhere; this is the cheapest way to prevent silent typos that fall back to defaults.

Namespace by domain. Use dotted keys grouped by area — catalog.per_page, billing.currency, mail.from — so admin screens can list and group settings by prefix rather than dumping a flat table.

Treat the DB as an override layer. Always pass a default on get(). The static config/ stays the source of truth for sane values; the settings table only records deviations. This makes a fresh install behave correctly before anyone touches the admin UI.

Scope per-owner when it makes sense. The bundle supports attaching a setting to an owner entity (e.g., User, Tenant). Use ownerless rows for global/site settings and owner-scoped rows for per-user preferences. Wrap the owner-aware read/write in a small service so callers never confuse the two.

Admin editing form. Build a controller that loads settings by group, renders a Symfony form, and writes back via SettingsManager. Batch the writes and flush once per request — avoid a set()/flush per field.

Cache the hot reads. If settings are read on every request, don't hit the DB for each one. Hydrate a plain settings object at kernel boot (or in a warmup cache) and read from that; invalidate on write. A Doctrine listener (postPersist/postUpdate on the Setting entity) is the natural hook for cache invalidation.

Expose a Twig function / view model. Templates shouldn't inject the manager. Register a Twig function like setting('catalog.per_page') backed by the cached reader, or pass values into the view from the controller.

Test with a real DB or a mocked manager. For unit tests, mock the manager interface. For integration tests, seed default settings via fixtures so the "default + override" behavior is covered.

Gotchas and Tips

• Unmaintained since 2021. Check PHP and Symfony version constraints (composer why-not) before committing; you may need config-level backports or a fork for Symfony 6/7.
• It pulls in Doctrine. The "lightweight" claim is only true if you're already on Doctrine ORM/DBAL. If you're not, the integration cost is real.
• Type coercion. Values are commonly stored as strings; booleans and integers won't come back typed. Be explicit — cast on read or configure the setting type — otherwise get('feature.enabled') returns "0"/"1" rather than false/true.
• Stale cache after edits is the classic bug. After updating a setting from admin, verify the read path actually sees the new value. Add an explicit invalidate on write or a listener; don't assume it "just works."
• Silent failures on typos. A wrong key returns the default — no exception. Constants for keys plus a lint/seed step catch this early.
• Migration discipline. The setting table must exist. Generate a migration in dev and ship it; don't let production depend on schema:update.
• Owner scoping needs ownership checks. If you store per-user settings, verify the current user owns the row before reading/writing, or you'll leak preferences across accounts.
• Extension point: custom setting types. If the bundle exposes a type registry, define a custom type class encapsulating cast/serialize logic (e.g., a JSON or serialized-array setting) rather than doing it in every caller.
• Laravel developer note. This is a Symfony bundle; the wiring (bundle registration, autowiring, Doctrine) is Symfony-specific. If you're on Laravel, either port the manager/entity directly or pick a Laravel-native settings package — the concept transfers, the service provider and DB layer do not.