Laravel Site Settings Laravel Package

Getting Started

1. composer require visual-ideas/laravel-site-settings — pin the version in composer.json ("visual-ideas/laravel-site-settings": "^x.y") before you build on it; the package is small and low-traffic.
2. Publish and migrate. Run php artisan vendor:publish and pick the package's provider/tags (config + migrations), then php artisan migrate. Confirm the created table shape (key/value columns, whether there is a group, type, or JSON column) — that schema tells you what the package can and cannot store.
3. Look first at, in this order: the README's read API (helper vs. Facade), config/site-settings.php (cache store, TTL, table name, model binding), the migration, and the Filament/MoonShine resource classes. Those four files are essentially the whole package.
4. Smoke-test the read path in tinker: insert a row via the admin UI (or the model), then read it through the helper/facade. Verify the value survives a second read and appears in your cache store.
5. First real use case: global, low-churn, non-secret values that non-developers need to change without a deploy — site name, logo path, contact email, footer links, social URLs, and a couple of boolean feature toggles.
6. If you want the admin GUI, register exactly one panel integration (Filament plugin in your PanelProvider, or the MoonShine resource/menu item) and gate it behind an authorization check before shipping.

Implementation Patterns

Wrap it immediately. Put every read behind one small class of your own (App\Support\Settings) with typed methods (siteName(): string, featureEnabled(string $key): bool). The package's read API becomes an implementation detail; when the package stalls or you outgrow it, you swap one file.

Read-through cache, not query-per-read. The point of the package is that reads hit the cache after the first hit. Structure code so hot paths read once: share global chrome values (site name, logo, nav links) via a view composer or middleware once per request rather than calling the helper inside every Blade partial.

Batch reads for pages. If the API exposes a "get many" or "all" method, use it when rendering a settings-heavy page; otherwise you're paying N cache round-trips per request even when each one is cheap.

Always code a fallback. Fresh environments, migrate:fresh in CI, and rollbacks will produce missing keys. Treat every read as nullable: site_setting('contact_email') ?? config('mail.from.address'). Seed your defaults in a seeder so local and staging match production, but never rely on the seed alone.

Cast at the boundary. Store booleans and arrays as strings/JSON unless the package handles types, and cast in your wrapper. This keeps Blade and controllers free of === '1' checks.

Feature flags as a stepping stone. Boolean settings make a perfectly good v1 flag system. Keep the flag names and defaults in one enum/class so migrating to LaunchDarkly/ConfigCat later is mechanical.

Admin GUI integration. For Filament, register the plugin in the panel you already protect with ->authGuard()/canAccessPanel; don't stand up a second panel just for settings. For MoonShine, add the resource to the menu and restrict it by role. Whoever edits settings is effectively deploying config changes — treat that permission accordingly.

Testing. Set CACHE_DRIVER=array (or call Cache::flush() in setUp) so tests don't see stale values from a previous test. Use RefreshDatabase plus your defaults seeder. Write one test asserting that saving through the model/GUI invalidates the cache — that's the package's only real logic.

Deployment. After migrate and your seeder on each deploy, warm the cache with a tiny artisan command that reads all keys, so the first user request doesn't pay the cold-cache cost — and so a broken cache store surfaces in the deploy log, not in production traffic.

Gotchas and Tips

Maintenance risk is the headline. 14 stars, a single maintainer, last release Feb 2024. Read the source (it's small enough to do in an afternoon), pin the version, and check composer.json for the Laravel versions it actually declares — if it caps below your Laravel major, expect composer update friction and plan to fork.

MySQL-specific by design. The description says MySQL; running your test suite on SQLite may fail on column types or JSON handling. Keep CI on MySQL (or at least run this package's path there) if you use the package in tests.

The cache is where every bug will be. Three failure modes dominate:

• Multi-node skew: file cache on several app servers means each node holds its own copy. An admin edit invalidates one node. Use Redis/Memcached in production, full stop.
• Bypassed invalidation: only writes that go through the model/GUI forget the key. A DBA running UPDATE settings SET ... leaves production stale indefinitely. Add a settings:flush artisan command and document it in your runbook.
• Cached nulls: if the package uses Cache::rememberForever and you read a key before it's seeded, some implementations cache null permanently. Verify this; if it happens, seed in the migration or flush on deploy.

Don't put secrets in it. Values live in plaintext in MySQL, render in the admin UI, and land in every DB dump and staging clone. API keys, SMTP passwords, and anything rotating belong in env/secrets manager.

Don't put per-user or high-churn data in it. It's global site settings. Per-user preferences and anything written on every request will thrash the cache and the table.

Helper autoload issues. If you get "Call to undefined function", run composer dump-autoload and confirm the package registers its helper via files in composer.json. This bites hardest after a composer install --no-dev on a host where the package was previously dev-only.

Published migrations are yours now. Once you publish, package upgrades won't alter your table. New columns need hand-written migrations; re-publishing risks a duplicate-table error. Note the package version you published at.

GUI version coupling. The Filament/MoonShine integration is pinned to a panel major. A Filament 3→4 (or MoonShine 2→3) upgrade may strand you on an unmaintained plugin. Check the panel integration is the reason you chose this package; if not, consider the settings core plus a hand-rolled Filament resource — it's roughly 60 lines and removes the dependency that ages worst.

Debugging recipe. In tinker: read the value, then Cache::has($key) / Redis::keys('*setting*') to confirm caching is active. Enable query logging for one request to prove you're not hitting the DB per read. If the admin UI shows a value the frontend doesn't, it's almost always cache store mismatch between the web and queue/CLI environments.

Extension points to check before adopting. Config-swappable model, configurable cache store and TTL, and a publishable config are the three that matter. If the model isn't swappable, you can't add columns cleanly; if the cache store isn't configurable, you can't fix node skew without a fork.