Tomato Ecommerce Module Laravel Package

Getting Started

This is the initial v1.0.0 release of tomatophp/tomato-ecommerce-module, so treat the public API as stabilising rather than stable. Start by reading the package README and the commit history linked in the changelog — at 1.0.0 there is no migration guide yet, so the README is the source of truth for required Laravel, Filament, and tomato-admin/tomato-* dependency versions.

Minimal install:

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

Then register the Filament plugin in your panel provider:

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(\TomatoPHP\TomatoEcommerce\EcommercePlugin::make());
}

Where to look first: the published config file (currency, tax, model bindings) and the Filament resources registered by the plugin — these define the day-to-day surface area (products, categories, orders, carts). First use case: stand up a product catalogue and an order list inside an existing TomatoPHP/Filament admin, then wire your storefront to the package's Eloquent models rather than building CRUD yourself.

Implementation Patterns

• Plugin-per-panel registration. Register EcommercePlugin::make() only on the panels that need commerce. Avoid registering it on a customer-facing panel unless you intend to expose resources there.
• Admin-first workflow. The package's value is the Filament resource layer. Use it for back-office CRUD (products, categories, orders, order items) and keep storefront controllers in your app, resolving models via the container so you can swap implementations.
• Model swapping via config. Override the bound models in config/tomato-ecommerce.php (or via Model::resolveRelationUsing / container bindings) and extend the package models when you need custom fields. This is the cleanest extension path at 1.0.0 — prefer it over editing vendor resources.
• Order lifecycle hooks. Drive post-purchase behaviour (stock decrement, notifications, invoices) through Eloquent observers or events on the order model rather than editing the admin resources. Keeps upgrades to the module low-risk.
• Compose with adjacent TomatoPHP modules. This module is designed to sit alongside tomato-pos, payment, and shipping modules. Register plugins in a deliberate order and verify resource navigation groups don't collide.
• Seed for local dev. Add factories/seeders for products and orders in your own DatabaseSeeder rather than relying on package demo data, so your test suite is deterministic.
• Feature-test the admin. Use Filament's livewire() testing helpers against the registered resources — at 1.0.0 this catches regressions faster than manual clicking after each upgrade.

Gotchas and Tips

• Pin the version. "tomatophp/tomato-ecommerce-module": "1.0.*" — at 1.0.0, minor releases can still contain breaking changes. Read the changelog commit-by-commit before bumping.
• Publish before migrating. Migrations ship inside the package; if you run php artisan migrate first you may end up with an untracked schema that later conflicts when you publish. Publish, review timestamps, then migrate.
• Filament version mismatch is the most common failure. Check the composer.json constraints — a Filament v3-only release will silently break resource registration on a v4 panel. Verify before installing.
• Clear caches after install. php artisan optimize:clear (config, route, view) — Filament plugin and resource discovery is cached aggressively and stale caches produce "resource not found" symptoms.
• Permissions. If you use Filament Shield or the TomatoPHP roles layer, new resources will have no permissions until you re-run the permission generator; otherwise the menu items appear but 403 on access.
• Check the config key names against the README, not against guesswork. Naming in TomatoPHP configs has historically differed between modules (tomato-ecommerce vs ecommerce tags). Use php artisan vendor:publish without a tag once to see the exact tag list.
• Debugging: php artisan about plus the published config diff is usually enough to isolate install issues; for resource-level issues, check php artisan filament:cache-components output and confirm the plugin is listed for the panel.
• Extension points to prefer: config model bindings → subclassed resources registered in your own panel → observers/events. Avoid modifying vendor files; there is no upgrade-safe override mechanism documented at 1.0.0.