Settings Bundle Laravel Package

Getting Started

Install and register (check the archive status first). Earlier releases of hexanet/settings-bundle were frozen since 2018, but v2.0.0 has since been published, so re-check whether the repository is still archived before you commit to forking. If it is archived, fork under your own vendor namespace and pin the tag explicitly; if it is alive, a normal constraint works:

"require": { "hexanet/settings-bundle": "^2.0" }

Version 2.0.0 requires Symfony >= 3.4 — there is no support for 3.0–3.3 (stay on 1.x there) and no sign of Symfony 5/6 support, so on a modern app you are still pinning to an old framework line. Then enable the bundle in config/bundles.php (or AppKernel on the 3.4/4.x codebase it targets) and import its service/routing config if the bundle ships an admin editing UI.

Where to look first. Read, in this order: the bundle's DependencyInjection/Configuration.php (what options you can tune), its Entity/ directory (the persisted setting model and schema), and the manager/service class you'll inject everywhere. The Doctrine mapping and the manager are the whole product; everything else is glue. On v2.0.0 also skim the service definition file — it changed shape (see gotchas), and knowing the new service ids saves an hour of debug:container later.

The first real use case. Site-wide, operator-editable values that shouldn't live in parameters.yml: site name, contact email, items-per-page, a maintenance-mode toggle. Create the setting rows (fixtures or an admin form), inject the manager into a controller, and render the value. Because v2.0.0 autowires its services, you should be able to type-hint the manager interface in your constructor and have it resolve with no manual wiring. If that round-trip works — read, edit, persist, re-read — you've validated the bundle end to end.

Implementation Patterns

Inject the manager, not the entity. Treat the settings service as your read API and keep it out of controllers where a service can own the lookup. v2.0.0's autowiring makes this frictionless — type-hint the interface, don't reach into the container. Cache the resolved value in the calling service's constructor if the setting is required at boot (e.g. mailer from address) — but see the circular-dependency warning below.

Defaults at the call site. Always read with an explicit fallback. Settings tables are frequently empty on a fresh deploy (migrations run before fixtures), and an unguarded read turns a missing row into a null in production.

Type discipline is your job. Settings bundles of this era generally store a stringified value plus a type hint. Pick a convention — booleans as '1'/'0', arrays as JSON — and encode/decode in one place, ideally a small wrapper service around the bundle manager rather than scattered json_decode calls.

Twig extension for display values. If the bundle exposes a Twig function, use it for presentation-only settings; for anything that changes behaviour (feature flag, threshold), resolve it in PHP so the logic is testable and not buried in templates.

Admin editing via form types. The natural workflow is a SettingType form per setting (or a generated settings page grouped by section). Attach validation constraints on the form, not the entity — the underlying column is almost certainly a string, so length/email/range constraints belong at the editing boundary.

Seeding and environments. Ship a fixtures/doctrine:fixtures set or an idempotent console command that upserts default settings. This makes "what settings exist" a reviewable diff rather than tribal knowledge, and lets staging and prod start from the same baseline.

Scoping / multi-tenant. If you need per-tenant values, don't fork the bundle — prefix keys (tenant_42.items_per_page) or maintain a parallel table keyed by tenant. The bundle's single-table assumption is the main structural limit.

Caching layer. The read path should be cached (a Symfony cache pool) with write-through invalidation on save. Wire the invalidation to the persistence event (Doctrine postPersist/postUpdate) so the manager, the admin form, and any console command all invalidate consistently.

Gotchas and Tips

v2.0.0 is a breaking release, even though the notes are two lines. Moving services to autowire almost always changes service ids, visibility, or aliases. Anything that referenced the old ids — $container->get('hexanet_settings.manager'), @hexanet_settings.* in your YAML, or a compiler pass that decorated a specific id — is the thing that breaks on upgrade, not the PHP API. Run bin/console debug:container | grep -i settings before and after the bump and diff the output, then re-point your references at the new alias or interface.

Autowire only helps if your classes are autowired too. If your app still registers the consuming services with explicit arguments: YAML, you gain nothing from v2.0.0. Convert the consumers first, then upgrade the bundle — doing it in the other order leaves you debugging "no service for type" errors that look like the bundle's fault.

Unmaintained (or barely maintained) means you own the upgrade path. Even with v2.0.0 shipping, expect Symfony 3.4-era constraints, possibly @Route annotations, and PHP version ceilings that block PHP 8. Budget time to modernise the fork (attributes or YAML routing, services.yaml, PHP 8 types) before promising it to the team. Check the license file survives your fork — MIT is permissive, so this is fine, but keep the attribution.

Stringly-typed traps. 'false' is truthy in PHP. Any if ($settings->get('x')) on a stored boolean is a latent bug. Normalise on the way in and out with a single helper.

Cache invalidation across servers. If the bundle caches to the filesystem, two web nodes will disagree after an edit. Point it at Redis or the database-backed pool, and verify by editing on node A and reading on node B.

Container build vs database. Reading settings inside a compiler pass or service constructor that runs during cache warmup will fail on a cold database (fresh CI, first deploy). Resolve lazily — a closure or a getter called at request time — never at container compile time. This is unchanged by the autowiring work: autowire affects how the service is constructed, not when it runs.

Missing rows are silent. There is no schema-level guarantee a key exists. Add a startup check (a console command you can run in CI) that asserts every key your code references is either present or has a declared default.

N+1 reads. If the manager hits the database per get(), a template rendering ten settings produces ten queries. Look for a bulk-load/all() method and hydrate the cache from it once per request.

Extension points to prefer. Custom value transformers (encode/decode per type), a decorated manager for your domain-specific helpers, and overriding the admin templates — these survive a fork rebase far better than editing the bundle's internals directly. Decorating is now cleaner: alias the bundle's interface to your decorator instead of matching a concrete service id, so the next release's service rewiring can't break you.

Testing. Mock the manager interface in unit tests; run integration tests against SQLite in-memory with migrations applied. Assert the round-trip (write then read) and the default-fallback path, since those are the two failures you'll actually hit in production. Add one boot-level test that builds the container and resolves the manager by interface — that's the test that catches a v2.0.0-style service-id change before deploy.