Tomato Forms Module Laravel Package

Getting Started

Install the module into an existing TomatoPHP/Filament application:

composer require tomatophp/tomato-forms-module
php artisan vendor:publish --tag=tomato-forms-config
php artisan vendor:publish --tag=tomato-forms-migrations
php artisan migrate

First places to look:

• config/tomato-forms.php — toggles for routes, middleware, upload disk, and which Filament panel should expose the resources.
• src/Models/ — Form and FormEntry/submission models define the schema you will query against.
• database/migrations/ — the canonical shape of the forms and fields tables; read these before writing any custom query.
• src/Filament/Resources/ — the admin UI (Form resource and field repeater) that gives you the builder experience for free.

The first real-world use case is: build a form in the admin panel, embed it on a public or authenticated page, capture submissions, and browse/export entries from the Filament resource. Do that end-to-end before customising anything — it validates your panel registration, storage disk, and migration state in one pass.

Implementation Patterns

Builder-first, code-second. Define forms through the Filament resource rather than hand-seeding rows. Reserve programmatic creation for reproducible environments (seeders, tests), and if you do it, populate the field schema through the model's own API rather than mass-assigning raw JSON.

Embedding forms. Expose a Livewire/Filament component or a Blade include wired to the form's slug/ID. Keep the embed route behind configurable middleware so the same module serves both a marketing contact form (public) and an internal intake form (auth + policy).

Submission handling. Treat submissions as domain events: listen for the module's entry-created event (or observe the entry model) and dispatch your own jobs for notifications, CRM sync, or file post-processing. This keeps you out of the vendor's controller and survives upgrades.

Validation ownership. Put per-field rules on the field definition at build time, and layer application-specific rules in a form request or a policy-backed component. Never rely solely on client-side rules from the builder.

Multi-panel and multi-tenant setups. Register the resources conditionally per panel in your PanelProvider, and scope entries by tenant in a global scope on the entry model if you run tenancy. This is the single most common integration point where the module needs adapting.

Export and reporting. Wrap the entry model in your own query/export layer (FromQuery, CSV, or a Filament action) instead of extending vendor resources — you get stable column naming and can add computed fields.

Gotchas and Tips

• v1.0.0 is a debut release. Release notes contain only a changelog link, so there is no migration guide and no documented BC policy yet. Pin the version ("^1.0") and read composer.json constraints before assuming Laravel/Filament compatibility on older apps.
• Publish tags drift. If vendor:publish reports no matching tag, run php artisan vendor:publish interactively and inspect src/Providers/ for the actual tag names — module packages frequently rename tags between minor releases.
• Migration ordering. The module's migrations must run after your users table. If you see a foreign-key error, move the published migration files into a later timestamp prefix rather than editing the vendor copy.
• Config caching. After changing config/tomato-forms.php, run php artisan config:clear. Stale cached config is the usual cause of "route not found" and "disk not found" reports.
• File uploads. Set the disk explicitly in config and verify storage:link for public-facing forms; the default disk rarely matches production S3 setups.
• Field schema is JSON. Querying individual fields via SQL is awkward across drivers. Index or mirror the values you need to filter on into real columns in your own listener/observer instead of relying on JSON path queries.
• Filament upgrades break resources. Because the admin UI inherits Filament internals, treat Filament minor upgrades as requiring a smoke test of the builder screens; this is the most likely breakage surface.
• Extension points to prefer: model observers, Laravel events, policies, custom Filament actions, and config overrides. Avoid subclassing vendor resources or editing published migrations — both make future updates painful.
• Debugging submissions: log the entry ID and form ID together at creation time. Support requests about "the form didn't submit" are almost always validation rules on a single field, and that pairing makes the fix a one-query job.