Laravel Config Laravel Package

Getting Started

Install and publish

composer require tarfin-labs/laravel-config
php artisan vendor:publish --tag="laravel-config-config"   # config file
php artisan vendor:publish --tag="laravel-config-migrations" # table for stored values
php artisan migrate

Where to look first

1. README.md – the public API surface (helper functions / facade) is small; read it end-to-end before writing wrappers.
2. config/laravel-config.php – table name, model override, cache settings, and any connection option. This is the file you will touch most.
3. The published migration – tells you the schema (key/value columns, type column, timestamps) and therefore what you can query directly.
4. The service provider – shows what is bound into the container and whether anything is registered at boot (relevant for the boot-order gotchas below).

First use case

Migrate a small set of runtime-tunable settings out of config/*.php and .env and into the database so non-developers can change them without a deploy: site contact email, support phone, maintenance-mode banner text, feature toggles, per-environment third-party keys. Keep genuinely structural config (queue driver, DB credentials, mail transport) in files — the package is for values that change on a business cadence, not application wiring.

Laravel 13 note (6.1.0): this release only adds Laravel 13 support. If you are starting on Laravel 13, require ^6.1; if you are on Laravel 12, ^6.0 is fine and there is nothing to migrate.

Implementation Patterns

Hybrid resolution with a fallback chain. The strongest pattern is DB value → config() file value → hard default, exposed through one accessor in your app (a thin service class or a settings() helper) rather than calling the package directly from fifty places. That gives you a single seam to swap the backend later and one place to add casting and logging.

Typed reads. Store the type alongside the value (or infer it) and always cast on read — booleans in particular arrive as "1"/"0" strings from the DB. Centralise casts for bool, int, json/array, and null. Validate on write, not on read; a bad value written once should not poison every request.

Cache warm-up and invalidation. Reads happen on nearly every request, so depend on the package's cache layer rather than the DB. Add a deploy step that warms the cache, and make sure writes invalidate it (if the package does not do this for direct model writes, wrap writes in a repository that flushes explicitly). For multi-server setups, prefer a shared cache store (redis/memcached) over file so invalidation propagates.

Seeding defaults as part of the schema. Put default values into a seeder or into the migration that creates the table so a fresh environment boots with known-good values and no null-handling branches. Make seeds idempotent (updateOrCreate on key) so they are safe to re-run on deploy.

Multi-tenant / scoped settings. If settings differ per tenant, add a tenant_id (or group/scope column) via your own migration on top of the package table and always resolve through a scoped repository. Do not fork the package for this; scope in your wrapper.

Admin surface. The stored values are just an Eloquent model, so a simple Filament/Nova/Blade CRUD over it is usually enough. Group keys by prefix (mail.*, features.*) and render an appropriate input type per key — this is the part that delivers the actual business value, so budget for it.

Testing. Use RefreshDatabase plus a base TestCase that seeds the default settings, so feature tests see a realistic config. For pure unit tests, bind a fake implementation of your wrapper rather than hitting the table. Never let a test depend on ambient DB state for config.

CI matrix. With 6.1.0 the only supported-version change is Laravel 13; run the suite against both the current and next major if you publish this package internally, and pin laravel/framework constraints in composer.json to match what you actually test.

Gotchas and Tips

• Boot order / config:cache. Anything read during application boot (service providers, config/*.php files, package discovery) may run before the database is available. Never call the package from inside a config file or from a provider's register(). Reading in a middleware, controller, or lazily-resolved service is safe.
• Migrations vs. the settings table. A migration that queries settings (e.g. to backfill) will fail on a fresh install where the table does not exist yet. Order migrations by timestamp and guard with Schema::hasTable().
• Stale config in long-running processes. Octane, queue workers, and php artisan serve daemons keep resolved values in memory. Restart workers after changing settings, or read through the cache with a TTL.
• config:cache does not know about the DB. php artisan config:cache snapshots file config only; DB-backed values stay dynamic. Do not assume clearing the config cache refreshes them — clear the package cache too, and document that in your deploy script.
• Direct DB writes bypass invalidation. Editing rows in TablePlus/Adminer leaves the cache stale. Route all writes through the model/repository, or make cache invalidation a model event.
• Secrets. If you store API keys here, use an encrypted cast and remember the DB dump is now a secret-bearing artefact — broader blast radius than a .env file. Consider keeping credentials in .env and only non-secret tunables in the DB.
• Type juggling. Values round-trip as strings. "false" is truthy in PHP; always cast explicitly and add a test for the boolean false case.
• Extension points to prefer over forking: the model class and table name in the config file, a custom cache store via the config, and your own repository/wrapper for scoping and casting. Subclassing the model is usually enough for tenant scoping and audit columns.
• Upgrading. 6.1.0 is additive and non-breaking; the real upgrade risk is the 5.x → 6.0 jump, so read the 6.0.0 changelog before adopting. Check the PHP constraint that ships with the Laravel 13 support before bumping on older PHP runtimes.
• Debugging tip. When a value "will not change", check in this order: is it cached (flush package cache), is a file-config fallback shadowing it, is a worker holding it in memory, and only then inspect the row.