Tomato Orders Module Laravel Package

Getting Started

• Install through Composer alongside the TomatoPHP admin stack (typically tomato-admin, tomato-settings, and a compatible Filament version). This module is not a standalone e-commerce system; it is an orders domain module intended to plug into the broader TomatoPHP ecosystem.
• Publish and inspect the package configuration, migrations, and language files first:

  php artisan vendor:publish --provider="TomatoPHP\TomatoOrders\TomatoOrdersServiceProvider"
  php artisan migrate
  

• Look first at:
  • config/tomato-orders.php for model bindings, table names, and route/Filament integration.
  • src/Models/Order.php and related order item/payment/status models for the domain surface.
  • src/Filament (or equivalent resource directory) for the admin CRUD screens.
  • resources/lang for translation keys and expected labels.
  • Migration files for required columns and foreign-key assumptions.
• First practical use case: stand up an admin order-management screen where staff can list orders, inspect line items, update order status, and filter by customer or date. From there, wire checkout or an external sales channel into the module by creating orders programmatically through its models/services.
• Because the package is at v1.0.x, treat the public model and Filament resource APIs as early-stage. Pin the version in composer.json and review minor releases before upgrading.

Implementation Patterns

• Admin-first integration: Register the module’s Filament resources through the TomatoPHP plugin/provider mechanism. Use the supplied resources for standard order CRUD, then extend them with custom actions such as “mark as shipped”, “refund”, or “resend confirmation” rather than building a parallel admin screen.
• Programmatic order creation: Encapsulate order creation in your own application service and call the module’s models inside a database transaction. Create the order header, line items, totals, and initial status together so the admin UI never sees partially constructed orders.
• Model extension via configuration: Prefer extending the package’s Order model or swapping the configured model class over editing vendor files. Add application-specific fields through your own migration and a subclass, then point the package config at the subclass. This keeps upgrades feasible.
• Status workflows: Treat statuses as application-level state, not just database strings. Define allowed transitions in a small service or enum-backed policy, and call that service from both Filament actions and API/checkout code. The module’s admin actions should be a presentation layer over the same transition rules.
• Events and listeners: If the module dispatches order lifecycle events, listen for them to trigger emails, inventory adjustments, invoices, or webhook delivery. Keep listeners idempotent and queue long-running side effects.
• Filament customization: Override table columns, filters, and form schemas in your own resource classes where possible. Use Filament policies for authorization and TomatoPHP permission seeding to expose order screens only to appropriate roles.
• Localization: Publish language files and add application-specific translations in your own lang/vendor directory. Keep translation changes out of vendor files so Composer updates do not overwrite them.
• Testing: Use RefreshDatabase with the package migrations, factories for orders and order items, and feature tests around status transitions, totals calculation, and Filament resource access. Mock external payment/shipping integrations at the service boundary.

Gotchas and Tips

• No functional changes in v1.0.2: The release is a translation update only, with a new contributor. There are no breaking changes, new features, or deprecations. Existing integrations should be unaffected; clear translation and view caches after upgrading:

  php artisan optimize:clear
  

• Ecosystem coupling: This module assumes TomatoPHP conventions and likely a specific Filament major version. Check composer.json constraints before installing into an existing Laravel app; mismatched Filament versions are a common source of broken resources and navigation registration.
• Migration order: Orders reference customers, products, payments, and addresses. Run dependency migrations first and verify foreign-key column types match the related modules, especially if you use UUIDs or custom primary keys.
• Model swapping is sticky: Changing the configured Order model can break relationships, policies, factories, and Filament resource type hints. If you swap models, update every reference and add an integration test that loads an order through the admin resource.
• Translation gaps: A translation-only release can still leave keys missing in some locales. Compare published language files against the vendor source and provide fallbacks; do not assume every label is translated.
• Status integrity: Do not rely on the admin UI alone to enforce valid status changes. Direct model updates, imports, or API calls can bypass Filament actions, so enforce transitions in the domain layer.
• Money and rounding: Confirm how the module stores totals (integer minor units vs decimal) before writing reporting queries. Mixing conventions between your checkout code and the admin module causes subtle reconciliation errors.
• Extension points: Prefer config-driven model bindings, published migrations, custom Filament resources, policies, and event listeners. Avoid modifying files under vendor/tomatophp/tomato-orders-module; those changes disappear on the next Composer update.
• Upgrade discipline: At v1.0.x, review changelogs and diffs before each update. Keep the package pinned and run your order-related test suite after upgrades, particularly around Filament resource registration and translated labels.