- How do I install and set up baks-dev/orders-order in a Laravel project?
- Run `composer require baks-dev/orders-order` along with its dependencies like `baks-dev/centrifugo` and `baks-dev/payment`. Then execute `php artisan baks:assets:install` to configure assets. Start the Messenger worker with `php artisan messenger:consume orders-order` for async processing.
- What Laravel versions does baks-dev/orders-order support?
- The package requires PHP 8.4+ and is built for Laravel 10+ (via Symfony components). Check the [GitHub releases](https://github.com/baks-dev/orders-order/releases) for version-specific compatibility notes, as Laravel 9.x may need adjustments due to Symfony Messenger changes.
- How do I add a custom order status like 'hold_for_approval'?
- Create a class implementing `OrderStatusInterface` and tag it with `#[AutoconfigureTag('baks.order.status')]`. Define transitions (e.g., `canTransitionFrom()`) and run migrations. Example: `php artisan doctrine:migrations:diff` followed by `php artisan doctrine:migrations:migrate`.
- Why isn’t my order status updating in real-time via Centrifugo?
- Verify the Centrifugo server is running and the WebSocket connection is active. Check if the Messenger worker (`orders-order`) is processing events. Debug with `php artisan orders-order:test-realtime` and inspect logs for failed pub/sub messages or WebSocket disconnections.
- Can I use this package without Centrifugo for real-time updates?
- Yes, but you’ll lose real-time features. Fall back to polling (e.g., AJAX checks) or use Laravel Echo/Pusher. Note: Async processing via Messenger still requires the worker (`orders-order`), but status changes won’t trigger WebSocket events.
- How do I handle failed Messenger jobs for orders?
- Set up a dead-letter queue (DLQ) by configuring `MESSENGER_TRANSPORT_DSN` with a `failed` transport in `.env`. Monitor failed jobs with `php artisan messenger:failed-table` and retry manually or via a cron job. Alert on queue depth > 1000 to prevent backlogs.
- Are there performance considerations for large-scale order processing?
- Optimize by scaling Messenger workers horizontally (e.g., Kubernetes HPA) and using read replicas for reporting. Add indexes to `status` and `transitioned_at` columns in the orders table. For Centrifugo, deploy multiple nodes with Redis pub/sub to handle WebSocket connection limits.
- How do I debug an order stuck in a transition (e.g., 'processing' → 'shipped')?
- Check the Messenger worker logs for failed jobs. Use `php artisan orders-order:test-realtime` to simulate transitions. Audit custom `OrderStatusInterface` logic for missing `canTransitionFrom()` rules. Enable event sourcing to trace transitions via `OrderStatusChanged` events in a separate table.
- What alternatives exist for Laravel order management with async support?
- Consider `spatie/laravel-activitylog` for audit trails, `laravel-queue` for custom async workflows, or `beberlei/doctrineextensions` for advanced Doctrine features. For real-time, compare Centrifugo with Laravel Echo (Pusher) or Ably. Note: Alternatives may lack the tight `OrderStatusInterface` integration.
- How do I test custom order status transitions in PHPUnit?
- Use the `--group=orders-order` flag: `php artisan test --group=orders-order`. Mock the Messenger transport and Centrifugo client in tests. Example: `Messenger::fake()` to assert dispatched messages. For status logic, test `canTransitionFrom()` methods with `assertTrue()`/`assertFalse()`.