Settings Bundle Laravel Package

Getting Started

• Install with Composer: composer require ongr/settings-bundle — target the 1.0.0 line, the first stable major release. It pairs with ongr/elasticsearch-bundle, so you will likely pull that in too; the settings themselves live in an Elasticsearch index, not a relational table.
• Register the bundle the Symfony 2/3 way (AppKernel::registerBundles). The 1.0.0 release is a stabilization of the 2016-era codebase, so expect old-style bundle registration rather than Symfony Flex auto-wiring. (This is a Symfony bundle — in a Laravel app you would have to build a bridge or cherry-pick the pieces, not just composer require it.)
• Configure it under the ongr_settings key: point it at your ES manager and declare your setting keys/defaults. Read the bundle's own DependencyInjection/Configuration.php first — the config shape is the authoritative documentation, and the README is thin.
• First use case: treat it as a small, ES-backed key/value config store for things that differ per site/storefront — pagination sizes, currency, feature flags, display options. Pull the manager service (ongr_settings.settings_manager) and read a SettingsCollection:

$settings = $this->get('ongr_settings.settings_manager')->getSettings('default');
$limit = $settings->get('pagination_limit');

• Where to look first: SettingsManager (read/write API), SettingsCollection (the value object you actually touch), the Settings ES document (storage shape), and the bundled console command / REST controller for bulk updates. Since 1.0.0 also look at the newly added events — they are now a first-class part of the public API and the cleanest integration seam.
• Make sure the ES index and mapping exist before the first read — otherwise you get an empty collection rather than an error, which is confusing.

Implementation Patterns

• Read settings through the manager, not the repository. Inject SettingsManagerInterface (or the ongr_settings.settings_manager service) into your services so you can swap/mock it in tests. Do not sprinkle $container->get(...) calls through controllers.
• Domain scoping for multi-site. Settings are keyed by a "domain" (site, store, locale). Read getSettings($domain) at the edge of a request (a request listener or a controller base class) and pass the SettingsCollection down. Fall back to a default domain when a specific one is missing.
• Writes are collection-wide. You call updateSettings(array $values, $domain), which persists the whole settings document. Build the array from the current collection plus your changes; there is no field-level patch API.
• Admin form pattern. Bind a Symfony form to a plain array of settings, then on submit map form fields onto the array and call updateSettings. Because writes hit ES, wrap the call in a transaction-like try/catch and flush any cache afterward.
• Command-driven changes. Use the bundle's ongr:settings:update-style command for initial population or migrations, and wire it into your deploy pipeline after the ES index is created.
• Cache-warming. Because ES reads are relatively expensive, cache the SettingsCollection (e.g., in a Redis/Symfony cache provider keyed by domain) and invalidate on write. A small decorator around the manager that reads from cache and delegates writes to ES is the cleanest integration.
• Events over direct coupling. Since 1.0.0 the bundle ships settings-update events as a supported API — subscribe to them to propagate changes (clear app caches, invalidate Varnish, etc.) rather than hard-coding side effects in controllers.
• REST surface. The bundle ships a controller for reading/updating settings over HTTP; if you expose it, put it behind your existing auth/firewall and API key config — it was not designed with a modern security stack in mind.
• Testing. Because SettingsCollection is a simple array-backed object, unit-test consumers of settings without ES at all. For the manager, mock the interface or point at an in-memory/test ES index.

Gotchas and Tips

• Still a Symfony 2/3-era package. The 1.0.0 release is labelled "stable major version," but it stabilizes a 2016-era codebase still built for Symfony 2/3 and Elasticsearch 1.x/2.x. Project activity remains low (small star count, few dependents). Modern Symfony (4+) and ES 7/8 will require forking or patching — budget for that before committing.
• Empty collection ≠ missing setting. A misconfigured index or absent mapping returns an empty SettingsCollection, so get() returns null silently. Always check ES directly (GET <index>/_search) when a value "disappears."
• Stale reads after writes. If you add a cache layer, the most common bug is reading old values after updateSettings. Invalidate synchronously on write; don't rely on TTL alone in admin flows.
• Lost updates. Whole-document writes mean two concurrent admin saves will clobber each other. Keep admin edits serialized (single form, optimistic version check) if settings matter.
• No type coercion guarantees. Values round-trip through JSON/ES; booleans and integers can come back as strings. Cast at the boundary ((int), filter_var(..., FILTER_VALIDATE_BOOLEAN)) rather than trusting the stored type.
• Defaults live in two places. Config defaults and the stored document can diverge — decide whether the collection merges defaults at read time or whether defaults are seeded once by the command. Document it.
• Index lifecycle. Settings live in ES, so they're not in your SQL migrations and not backed up by your normal DB dump. Add the settings index to your backup/mapping-management story.
• Events are the new extension point. The 1.0.0 events are the intended way to react to changes — prefer subscribing to them over editing the bundle in vendor/.
• Debugging tips. The bundle relies on ES logging — raise ongr_elasticsearch logger verbosity and watch the actual query/response when debugging a read. Also dump the raw Settings document to confirm the domain key you wrote matches the one you read.
• Extension points. The realistic places to customize are: decorate SettingsManagerInterface, provide a custom settings provider/cache, and hook the settings-update events. Avoid patching the bundle in vendor/; fork it (MIT license permits this) or copy the small pieces you need into your app.
• Deploy ordering matters. Because ongr:settings:update runs against ES, it must run after index creation and after the new code is deployed, otherwise the command may use stale config or write to a missing index.