Filament Ecommerce Laravel Package

Technical Evaluation

Architecture Fit

• FilamentPHP Alignment: The package leverages FilamentPHP v3, a modern Laravel admin panel framework, making it a natural fit for teams already using Filament for backend management. It extends Filament’s resource-based architecture to ecommerce, reducing context-switching between admin and storefront tools.
• Tomato CMS Integration: Built atop Tomato CMS Builder, it inherits modularity for content management (e.g., product attributes, categories, and CMS pages). This aligns well with headless or decoupled ecommerce architectures where content and commerce are managed separately but synced via APIs.
• Laravel Ecosystem: Compatible with Laravel’s service container, Eloquent ORM, and Blade/Inertia/Vue/React frontends. Works with Laravel’s built-in features like Cashier (subscriptions), Sanctum/Passport (auth), and Horizon (queues).
• Policy-Driven Authorization (new in v1.1.3): Order printing is now gated behind a Laravel policy (view ability on TomatoPHP\FilamentEcommerce\Models\Order), which means the package now leans harder into native Laravel authorization. Teams using Filament Shield get policy generation for free; teams with bespoke permission models must wire this explicitly. This is a net architectural improvement (standard Laravel gate/policy semantics) but introduces a hard dependency on policy registration for admin functionality.
• Microservice Potential: The package’s modular design (separate plugins for media, settings, accounts) still suggests adaptability for a microservices approach, though signed-URL printing requires shared app key/config if order printing is served from multiple instances.

Integration Feasibility

• Core Ecommerce Features: Out-of-the-box support for:
  • Product catalogs (SKUs, variants, inventory).
  • Shopping cart, checkout, and orders.
  • Customer accounts and roles (via Filament Accounts).
  • Payments (Stripe/PayPal via Laravel Cashier or custom gateways).
  • Taxes, shipping, and discounts.
  • Order printing via temporary signed URLs (v1.1.3), gated by policy.
• Extensibility: Uses Filament’s resource system, allowing customization via:
  • Overriding resource classes (e.g., ProductResource).
  • Hooking into Filament’s widgets, pages, and notifications.
  • Extending Tomato CMS’s content blocks for dynamic storefronts.
  • Registering/overriding the Order policy to control print access.
• Frontend Agnostic: Backend-agnostic; can pair with:
  • Laravel Blade (traditional server-rendered).
  • Inertia.js (React/Vue SPAs).
  • Livewire (progressive enhancement).
  • API-first (headless with Next.js, Nuxt, etc.).

Technical Risk

• BREAKING (v1.1.3) — Order Print Access: Order print links are now temporary signed URLs and require the app’s Order policy view ability. Without a registered policy for TomatoPHP\FilamentEcommerce\Models\Order, printing will stop working for existing installs. Mitigation: run php artisan make:policy (or use Filament Shield’s generator), implement view, and test print flows in staging before rollout.
• NEW CONFIG SURFACE (v1.1.3): filament-ecommerce.print (enabled, middleware, expires). Misconfiguration (e.g., enabled=false, restrictive middleware, or a very short expires) will silently degrade printing. Teams behind proxies/CDNs must confirm signed URLs are generated against the externally reachable host.
• BEHAVIORAL CHANGE (v1.1.3) — Cart Amounts: Cart amounts are now always computed from the product, not from stored/session values. This hardens pricing integrity (good for security and consistency) but may surface discrepancies in historical carts or custom pricing/discount logic that wrote directly to cart line amounts. Any bespoke promotions, negotiated pricing, or B2B price lists that mutate cart totals need re-validation.
• Filament Version Lock: Tied to FilamentPHP v3.x; upgrading Filament may require package updates. Risk mitigated by monitoring Filament’s release cycle and forking (MIT license permits this).
• Tomato CMS Dependency: Relies on Tomato CMS Builder for content management. If the project doesn’t need CMS features, this adds unnecessary complexity.
• Media Library Requirement: Mandates Spatie MediaLibrary, which may conflict with existing media handling (e.g., Vapor, custom storage).
• Database Schema: Heavy migrations (e.g., filament-accounts-model) could clash with existing schemas. Use --force cautiously or review migrations pre-install.
• Performance: Filament’s admin panel is resource-intensive. For high-traffic stores: enable caching (filament-cache:clear tags), offload static assets to a CDN, and use queue workers for order processing. Signed print URLs add negligible overhead but should not be minted in bulk loops.

Key Questions

1. Upgrade Driver: Is v1.1.3 being adopted primarily for the security hardening, and is there a remediation window/ticket already tracking the policy requirement?
2. Policy Ownership: Who owns the Order policy — Filament Shield (auto-generated) or a hand-rolled permission model? Is view mapped to the correct roles (fulfillment staff, support, finance)?
3. Print Pipeline: Are order print links consumed by internal staff only, or embedded in emails/PDFs/integrations? If third parties, does the expires window and middleware config accommodate their access patterns?
4. Cart Pricing Integrity: Do any bespoke flows (B2B price lists, negotiated rates, promotional overrides) write cart line amounts directly? These must be reconciled with the “always compute from product” behavior.
5. Frontend Strategy: Will the storefront use Blade, Inertia, or a headless API? If headless, how will product variants/attributes sync (GraphQL/REST)?
6. Authentication: Will customer accounts integrate with Sanctum, Passport, or a third-party (e.g., Supabase Auth)?
7. Payments: Are custom gateways needed beyond Cashier, and how do they integrate with checkout?
8. Scaling: Will the admin panel need horizontal scaling? If so, confirm APP_KEY and config parity across instances so signed print URLs validate everywhere.
9. Localization: Does the project require multi-language support (e.g., Spatie Laravel Translatable)?
10. Analytics & Compliance: How will order/behavioral data be captured, and are there GDPR/PCI-DSS obligations requiring audits of data handling?

Integration Approach

Stack Fit

• Backend:
  • Laravel 10+ (LTS recommended for stability).
  • FilamentPHP v3.x (core dependency; v1.1.3 targets the 3 line).
  • Tomato CMS Builder (if content-heavy storefronts are needed).
  • Spatie MediaLibrary (for media handling).
  • Laravel Settings (for admin configurations).
  • Filament Shield (recommended — generates the Order policy needed for printing).
• Database:
  • MySQL 8.0+ or PostgreSQL 13+ (recommended for Filament’s performance).
  • Review migrations for conflicts (e.g., existing users table).
• Frontend:
  • Inertia.js + Vue/React (recommended for SPAs).
  • Blade (server-rendered) or Livewire (progressive enhancement).
• DevOps:
  • Docker for consistent environments; Forge/Vapor for deployment; queue workers for order processing.
  • Ensure consistent APP_KEY, host/domain, and trusted-proxy config across all nodes so temporary signed print URLs work behind load balancers.

Migration Path

1. Prerequisites: Confirm Laravel v10.x and Filament v3.x. Install Filament if absent (composer require filament/filament:"^3.0"), then set up Filament auth (filament:install).
2. Package Installation / Upgrade:

   composer require tomatophp/filament-ecommerce
   # or, for existing installs:
   composer update tomatophp/filament-ecommerce
   

   Publish required migrations (MediaLibrary, Laravel Settings, settings hub, accounts model), then run the installer:

   php artisan filament-ecommerce:install
   

3. v1.1.3 Remediation Steps (required):
   • Register the Order policy with a view ability. If using Filament Shield:

     php artisan shield:generate --resource=TomatoPHP\\FilamentEcommerce\\Models\\Order
     

     Otherwise create the policy manually and register it (Laravel 10+ auto-discovery, or explicitly in AuthServiceProvider).
   • Publish and tune print config: config/filament-ecommerce.php → print.enabled, print.middleware, print.expires. Align expires with how long staff/emails need link validity.
   • Verify trusted proxies / URL generation so signed URLs use the public host (APP_URL, TrustProxies).
   • Audit cart pricing for any custom code writing line amounts; confirm totals now derive from the product as expected, and re-test promo/discount paths.
4. Configuration: Customize Filament resources (e.g., ProductResource), override Tomato CMS templates if used, configure payment gateways (Stripe keys in .env).
5. Frontend Integration: Inertia/Vue pages via API routes, or Blade partials via @include('filament-ecommerce::...').
6. Testing: Run migrations in staging first. Add regression tests for (a) order printing as authorized vs. unauthorized users, (b) expired signed URLs, and (c) cart totals under discount/promo scenarios.

Compatibility

• Laravel Packages: Cashier (payments/subscriptions), Horizon (queues), Scout (search), Filament Shield (policies — now recommended), Nova (if migrating).
• Third-Party Services: Stripe/PayPal via Cashier; Shippo/ShipStation for shipping (custom code); Algolia/Meilisearch for advanced search.
• Legacy Systems: Data migration scripts needed if moving from Nova ecommerce or Cartalyst Sentinel.
• Upgrade Compatibility: v1.1.3 is a patch-level release with breaking behavioral changes for order printing. Pin to ^1.1.3 once policy and print config are validated; do not roll forward to production without the policy in place.

Sequencing

1. Phase 0: v1.1.3 Remediation (do first) — register Order policy, publish/tune filament-ecommerce.print config, verify signed URL host generation, regression-test printing and cart totals. This unblocks all subsequent work.
2. Phase 1: Backend Setup — Laravel + Filament, database/migrations, integrate filament-ecommerce, configure core features (products, orders, customers).
3. Phase 2: Admin Panel Customization — extend Filament resources, add dashboards/widgets, map print permissions to roles.
4. Phase 3: Frontend Development — build storefront (Inertia/Blade/Livewire), integrate checkout with APIs.
5. Phase 4: Testing & Optimization — load test admin panel and checkout, index products, validate signed-URL behavior under load.
6. Phase 5: Deployment — staged rollout (admin → catalog → checkout), monitor errors and print failures.

Operational Impact

Maintenance

• Package Updates: Monitor tomatophp/filament-ecommerce and FilamentPHP for breaking changes. Note that v1.1.3 demonstrates the package will ship security patches with behavioral changes at patch level — treat every 1.1.x bump as requiring a changelog review rather than a blind composer update.
• Policy Drift: The Order policy becomes a maintained artifact. Ensure it survives refactors, is covered by tests, and is included in any Filament Shield regeneration workflow.
• Config Ownership: filament-ecommerce.print should live in version-controlled config with documented rationale for expires and middleware values.
• Dependency Hygiene: Track Filament, Spatie MediaLibrary, and Laravel Settings versions; schedule quarterly upgrade windows.

Support

• New Support Surface: “Print isn’t working” is now a top-tier support category with three common causes — missing/incorrect policy, print.enabled=false, or expired links. Publish an internal runbook with triage steps.
• Vendor Reliance: Small maintainer team; keep the fork option (MIT) available and budget for occasional self-patching.
• Documentation Gap: v1.1.3 points to a README section (“Order Print Page”) — confirm the team has read it and captured config defaults internally.

Scaling

• Signed URL Validity Across Nodes: All app instances must share APP_KEY and consistent URL generation so print links validate regardless of which node serves the request.
• CDN/Proxy Considerations: Host-header and trusted-proxy misconfiguration is the most likely cause of signed-URL failures at scale.
• Admin Panel Load: Filament remains resource-intensive; cache aggressively, offload assets, and avoid bulk-minting print URLs in loops.
• Cart Recomputation: Computing cart amounts from product on every read may increase query load on high-traffic carts — verify eager loading and caching for product pricing.

Failure Modes

• Print Lockout (High): Missing Order policy → all print links 403. Mitigated by Phase 0 remediation and a staging smoke test.
• Silent Print Disable (Medium): print.enabled=false or over-restrictive middleware blocks legitimate requests. Mitigated by config review and monitoring print endpoint error rates.
• Expired Link Complaints (Medium): Short expires values break emailed/queued print workflows. Mitigated by aligning expiry with actual usage patterns.
• Pricing Discrepancy (Medium): Custom pricing logic that wrote cart amounts now diverges from product-derived totals. Mitigated by auditing discount/promo paths and adding regression tests.
• Filament Upgrade Breakage (Medium): Version lock to Filament v3 — plan upgrades deliberately.

Ramp-Up

• Engineering: ~0.5–1 day for v1.1.3 remediation (policy, config, tests) for a team already on Filament; 0.5 day for cart-total audit if custom pricing exists.
• QA: Add explicit test cases for authorized/unauthorized printing, expired URLs, and cart totals under discounts.
• Support/Ops: 1–2 hours to train on the print runbook and signed-URL troubleshooting; update on-call docs.
• Overall: Low incremental ramp-up — the release is small in surface area but high in consequence if the policy step is skipped. Gate the upgrade on Phase 0 completion.