Settings Bundle Laravel Package

Getting Started

Groups are the headline of v2.1.0-beta: instead of one flat settings bag, you can now bucket related settings under a named group and load/resolve them independently. Treat this as the default way to organize anything beyond a handful of keys.

First steps:

1. Upgrade with composer require <vendor>/<package>:2.1.0-beta (or bump the constraint) and re-publish config/migrations — group support typically ships with a schema or config change. Diff the published files rather than overwriting.
2. Read the release notes' group section and the package's group test file first; that is the fastest way to see the canonical API surface for this beta.
3. Create one group for your first real use case: mail, billing, or features. Keep it small (3–8 settings) so you can validate resolution, caching, and defaults before scaling out.
4. Resolve the group in a single place (a service provider binding or a typed accessor) and consume it from there. Do not scatter group lookups across controllers.

First useful win: move existing flat settings into logical groups and expose each group to its own admin form / API resource. That is where the beta pays for itself immediately.

Implementation Patterns

Group-per-domain, not group-per-model. Organize by bounded context (mail, notifications, billing, integrations.stripe). Per-model groups tend to explode in count and fight caching.

Typed accessor per group. Wrap each group in a small class or a container binding so callers get a typed object rather than an array:

// AppServiceProvider
$this->app->singleton(MailSettings::class, fn ($app) => $app->make(Settings::class)->group('mail'));

Then inject MailSettings into jobs, listeners, and controllers. This keeps the group API in one file if the beta changes shape.

Resolve lazily, cache aggressively. Load groups on demand inside the consumer, not eagerly in a service provider — otherwise every request pays for every group. Pair group access with the package's cache layer and invalidate at the group boundary on save, not globally.

One form request / one resource per group. Admin UI and API exposure both map cleanly: UpdateMailSettingsRequest validates only mail.*, MailSettingsResource serializes only that group. This is the pattern that makes groups worth adopting.

Seeder and factory helpers. Seed group defaults in a dedicated seeder so local, staging, and production start from a known baseline. Tests should set groups explicitly in setUp rather than relying on persisted state.

Feature groups as an on/off surface. If the package supports boolean settings well, a features group is a low-risk way to trial the beta — failures are visible and reversible.

Multi-tenant scoping. If you scope settings per tenant, decide now whether groups are scoped too. Confirm the scoping key applies to group-level reads and writes; test it explicitly.

Gotchas and Tips

Beta API stability. Group naming, resolution method names, and config keys can change between 2.1.0-beta and stable. Isolate group access behind your own accessor classes so an API rename touches one file, not fifty. Pin the exact beta version in composer.json.

Publish-then-diff. vendor:publish --force will silently clobber your customized config. Always publish to a temp path or diff first, especially on a minor that adds a groups key.

Cache invalidation is per-group now. A global flush hides bugs in development and hurts in production. Verify that saving one group does not evict all groups, and that it does evict the group you changed plus any aggregate view you built on top.

Group name collisions and typos. String-keyed groups fail silently — a misspelled group returns empty rather than throwing. Add a constants class or enum for group names and assert non-empty in tests.

Missing defaults return null, not errors. New groups added in a deploy have no persisted rows. Ship a migration or seeder with defaults in the same release, or the first read returns nulls in production. Test the "group does not exist yet" path.

Encrypted / sensitive settings. If a group mixes plaintext and encrypted values, confirm encryption is applied per-property, not per-group, and that serialization does not leak encrypted payloads into API resources.

Config caching. php artisan config:cache can mask newly published group definitions. Clear config cache after deploy and after any group config change.

Performance with many groups. Each group resolution may hit the database or cache separately. Batch related reads where the package allows, and measure before adding a tenth group.

Extension points. The stable surface for extending groups (custom repositories, casters, validation) is likely still moving in beta. Keep customizations in your own layer — decorators around the group accessor — rather than subclassing package internals.

Rollback plan. Because this is a beta, keep the previous release's settings shape readable. Write migrations so a downgrade does not orphan data, and confirm whether group data lives in the same table or a new one.