Tomato Settings Module Laravel Package

Getting Started

This is the initial v1.0.0 release of TomatoPHP's settings module, so treat it as a fresh integration rather than an upgrade. There is no prior assessment history and the release notes contain only the changelog link — meaning the public surface area is exactly what's in the repository README and source at tag v1.0.0.

Minimal setup:

1. Require it via Composer alongside its TomatoPHP dependencies (typically filament/filament and tomatophp/console / tomatophp/filament-* siblings). Check composer.json in the tag for the exact constraint matrix before installing into an existing app — the module will pin versions of the Filament major it targets.
2. Publish the package's assets and config (php artisan vendor:publish --tag=tomato-settings-module-* — confirm the actual tag names in the package's ServiceProvider since TomatoPHP modules vary). Run php artisan migrate to create the settings table.
3. Register the module in your panel provider (Filament plugin or module registry, depending on how the package exposes it).
4. Seed a first setting to confirm the round trip.

First use case: a single key/value settings store for global app config (site name, contact email, feature flags) editable from a Filament admin page, read from application code via the package's helper. That's the lowest-risk way to validate the module before wiring it into anything else.

Where to look first: the package's config/ file (source of truth for defaults and table names), the Filament page/resource classes under src/, and the helper functions in the service provider or a helpers.php — that's where the read API lives.

Implementation Patterns

Database-backed settings with typed values. The typical TomatoPHP settings pattern is a key/value table with a type column (string, integer, boolean, json, file). Prefer storing structured data as json rather than serializing into strings yourself; it keeps the Filament form widgets working and avoids double-encoding bugs when you round-trip.

Read via helper, write via UI or service. In application code, read through the package helper (e.g. settings('site.name')) so caching and default fallbacks apply consistently. Mutations should go through the package's model/service rather than DB::table('settings')->update(...), otherwise you'll bypass cache invalidation and type casting. If you must write programmatically, wrap it in the same model the Filament resource uses.

Defaults belong in config, not the database. Put fallback values in the published config file and let the DB row override them. This makes fresh deployments work before anyone has opened the admin settings page, and makes your test suite deterministic. Pattern: config('tomato-settings.defaults.site.name') as the fallback inside your own accessor.

Scoping / grouping. Use the group or section field to namespace settings (mail.*, billing.*, seo.*). This keeps the Filament settings page navigable as the list grows and lets you cache per group rather than invalidating everything on one change.

Caching layer. Settings are read far more often than written. Wrap reads in Cache::remember keyed by group or key, and register a model saved/deleted observer to bust the cache. If the package ships its own cache, confirm its TTL and forget-on-save behaviour before adding a second layer — doubled caching is the most common cause of "my change didn't apply" in settings modules.

Testing integration. In feature tests, use RefreshDatabase and seed the settings you assert against via the package factory or model directly. For unit tests of business logic that reads settings, bind a fake by populating the config defaults instead of hitting the DB — it keeps tests fast and avoids ordering issues.

Pairing with Filament panels. Register the module only in the panels that need it (usually an admin panel, not a customer-facing one). If you run multiple panels, gate the settings page behind a policy rather than relying on panel registration alone.

Gotchas and Tips

• Empty changelog on a 1.0 tag. The only release note is a link to the commit list. Before adopting, read the tag's diff, not the notes — assume nothing about API stability. Pin the exact version ("tomatophp/tomato-settings-module": "1.0.0") rather than a caret constraint until you've reviewed how it evolves.
• Filament version coupling. TomatoPHP modules are tightly bound to a Filament major. A settings module built for Filament 3 will not load cleanly under Filament 2, and the failure mode is often a confusing class-not-found rather than a clear composer conflict. Check composer.json first.
• Cache invalidation is the #1 debugging trap. If a saved setting doesn't reflect immediately, it's almost always a stale cache. Run php artisan cache:clear and php artisan config:clear to confirm, then find the actual forget call and check it fires on the updated event, not just created.
• Publish tags vary between modules. Don't assume vendor:publish --provider=... will grab everything. List available tags with php artisan vendor:publish interactively the first time and note what gets published (config, migrations, views, translations).
• Migration conflicts. If the module ships its own settings migration and you already have a settings table from spatie/laravel-settings or similar, you'll get a collision. Decide up front whether this module owns the table or coexists; they will not share storage.
• Type coercion on read. Boolean settings stored as "1"/"0" or "true"/"false" will bite you in strict comparisons. Verify how the package casts on retrieval — if it returns raw strings, add your own typed accessor layer.
• Config caching in production. After changing anything in the published config, run php artisan config:cache as part of deploy, and remember that env vars read at config-load time won't update without a re-cache.
• Extension points. The most reliable customization seams in TomatoPHP modules are: overriding the published config, swapping the Filament page class via panel registration, and extending the settings model if the package exposes it as a bound contract. Avoid editing vendor files — there is no upgrade path from there.
• Watch the sibling packages. Settings modules in this ecosystem frequently depend on tomatophp/console and account/translation modules. A "settings module" install can pull in a large chunk of the TomatoPHP stack; audit composer why after install if you're keeping the dependency footprint small.