Getting Started

Install with composer require whitedigital-eu/settings-bundle:^0.1.2 and inspect the package README plus src/ for the service provider, facade/helper, config file, and any publishable migrations.
Publish package assets only if the README calls for it: config first, then migrations. Run php artisan migrate before using persisted settings.
Look first at the settings repository/API and the config file. Confirm how keys, defaults, scopes, and casts are resolved before wiring it into application code.
First use case: add a runtime boolean feature flag, e.g. settings()->set('features.new_checkout', true) and read it with a boolean-safe getter such as settings()->boolean('features.new_checkout', false) if supported by the package API. Version 0.1.2 specifically adds boolean support, so start by verifying the documented boolean read/write path.
Treat this as a pre-1.0 package: pin the version in composer.json until the API stabilises.

Implementation Patterns

Centralise setting keys in constants, enums, or a small settings class rather than scattering string keys through controllers and jobs.
Use the package for runtime, operator-editable settings; keep deployment-time configuration in config/*.php and .env.
For booleans added in 0.1.2, write native booleans through the package API and retrieve them through the package’s boolean cast/getter. Avoid storing "true", "1", or "false" manually unless the package explicitly normalises them.
Always provide defaults at the read site. Example pattern: $enabled = settings()->boolean('features.checkout_v2', config('features.checkout_v2'));
Wrap writes in a service class or action so cache invalidation, validation, and audit logging happen consistently.
If the package supports scopes/tenants, resolve the current tenant/context in one place, such as middleware or a scoped repository, rather than passing tenant IDs through every call.
In tests, use RefreshDatabase for persisted settings and clear the settings cache between tests. Prefer setting values through the package API instead of inserting rows directly.
For admin UI integration, validate boolean inputs with $request->validate(['enabled' => ['required', 'boolean']]) and convert to a real boolean before saving.
If settings affect expensive behaviour, read them once per request/job and pass the resolved value down rather than repeatedly hitting the repository.

0.1.2 is a patch release on a 0.1.x line; do not assume API stability. Check the changelog and source before upgrading, and pin exact or narrow constraints in production.
Boolean support is only useful if storage and retrieval agree. Verify the database column type, package casting behaviour, and whether true/false, 1/0, or strings are returned.
Cache is the most likely source of confusion: after changing a setting, confirm the package invalidates its cache. If you update the underlying table directly, clear the settings cache manually.
Watch for php artisan config:cache interactions. If the package merges config at boot, deploy scripts must rebuild caches after config changes.
Publishing migrations is often required but easy to miss. Confirm the table exists and rollback works before relying on persisted settings in staging.
Defaults can hide missing keys. Add a test or diagnostic command that lists known setting keys and verifies expected types, especially booleans.
Avoid using settings as a general-purpose database. Keep high-churn data and per-user preferences in dedicated tables; reserve this package for application-level configuration.
Extension points to inspect: custom repositories/stores, value casters, cache drivers, and scoped resolution. These are the safest places to adapt the package without forking it.