Spec 0021 — State machines

[glennjacobs]

Summary

Implements spec 0021 — spatie/laravel-model-states v2 across core:

• Channel — Active ⇄ Inactive
• Product / Collection — Draft ↔ Published ↔ Archived
• Order — three coordinated machines: PaymentState (5 states), FulfilmentState (7), OrderState (11) with OnHold / Cancelled as manual overrides.

OrderObserver rewritten to dispatch OrderStatusUpdated on payment/fulfilment changes, log activity, and resume computation when leaving a manual-override state. SendOrderStatusNotifications listener fan-outs to per-state notifications.

Retires SoftDeletes on Product, ProductVariant, Channel, Collection — the new Archived / Inactive states replace the soft-delete-as-archive pattern. Cart and Staff keep soft-deletes (different concern). Baseline migrations edited in place per the v2 pre-release rule (spec 0019 precedent).

Translations added across all 16 locales (states.php).

Extension seam

The abstract state bases (PaymentState, FulfilmentState, OrderState) read their catalogue, transitions and defaults from the bound OrderStateConfig at construction time — the contract is the single seam for everything order-state-related. Consumers extend DefaultOrderStateConfig, add states + transitions + notifications + resolver overrides, and bind the subclass in their service provider:

class MyOrderStateConfig extends DefaultOrderStateConfig
{
    public function paymentStates(): array
    {
        return [...parent::paymentStates(), PartiallyCaptured::class];
    }

    public function paymentTransitions(): array
    {
        return [
            ...parent::paymentTransitions(),
            Captured::class => [PartiallyCaptured::class, ...parent::paymentTransitions()[Captured::class]],
            PartiallyCaptured::class => [Captured::class],
        ];
    }

    public function resolveOrderState(PaymentState $payment, FulfilmentState $fulfilment): string
    {
        // map the new payment state, or delegate
        return parent::resolveOrderState($payment, $fulfilment);
    }
}

OrderStateConfigExtensionTest proves this works end-to-end — a custom config adds PartiallyCaptured, transitions into it, and round-trips through the cast without any core change.

Bind in register() (not boot()): Spatie's State base caches the resolved state mapping per class for the process lifetime, so the catalogue must be in place before any model uses the cast. Under Octane this cache survives between requests.

Notifications

State-status notifications are resolved through OrderStateConfig::notificationsFor(OrderState). DefaultOrderStateConfig reads from lunar.orders.notifications.{name}, so the simple "drop a class in config" case still works:

// config/orders.php
'notifications' => [
    'shipped' => [App\Notifications\OrderShipped::class],
    'complete' => [App\Notifications\OrderComplete::class],
],

Consumers needing programmatic resolution (database, feature flags, per-customer-group) override notificationsFor() in their subclass. Order gains Illuminate\Notifications\Notifiable so $order->notify() works directly.

Breaking changes

The public-contract changes will land in the upgrade package's Rector rules as a follow-up:

• Order::$status removed; replaced by payment_status, fulfilment_status, order_status (state-cast).
• Order::getStatusLabelAttribute() removed; use $order->order_status->label().
• SoftDeletes removed from Product, ProductVariant, Channel, Collection — withTrashed() / restore() callers must move to the relevant state.
• lunar.orders.statuses config block removed; replaced by lunar.orders.notifications (different shape, scoped to notifications).
• MarkOrderAsShipped action no longer takes UpdatesOrderStatus as a collaborator — transitions fulfilment_status directly.
• UpdateOrderStatus action signature unchanged but now mutates order_status and validates against the registered OrderState catalogue rather than lunar.orders.statuses config.

Tooling

Adding spatie/laravel-model-states exposed a matrix gap: no version supports both PHP 8.3 and Laravel 13 (2.12.2+ added L13 but bumped to PHP ^8.4; 2.11.x supports PHP 8.3 but caps at L12). Aligned with upstream by bumping the minimum to PHP 8.4 across all 9 package composer.json files; PHP 8.5 added to the matrix.

• tests.yml — matrix is now ["8.4", "8.5"] × ["12.*", "13.*"]
• static-analysis.yml — same shape
• fix-code-style.yml, document-facades.yml — bumped single-version 8.3 → 8.4

User-facing impact: anyone on PHP 8.3 cannot install v2 after this lands.

Test plan

• vendor/bin/pint --dirty --format agent — pass
• vendor/bin/phpstan analyse --no-progress — no errors
• vendor/bin/pest --testsuite=core — 689 passed, 1 skipped (incl. 78 new tests under tests/core/Unit/States/ and tests/core/Unit/Listeners/)
• vendor/bin/pest --testsuite=admin — 189 passed
• vendor/bin/pest --testsuite=filament — 40 passed
• vendor/bin/pest --testsuite=stripe — 40 passed
• vendor/bin/pest --testsuite=shipping — 98 passed
• vendor/bin/pest --testsuite=search — 4 passed
• vendor/bin/pest --testsuite=upgrade — 39 passed
• Custom-config extension proven by OrderStateConfigExtensionTest
• Notification fan-out proven by SendOrderStatusNotificationsTest
• Smoke-test the order resource end-to-end in the host app at https://lunar-v2.test
• Confirm payment/fulfilment selects only offer legal next states (Filament polish for stage 2)

🤖 Generated with Claude Code