- How do I install and configure this package in a Laravel project?
- First, require the package via Composer: `composer require simple-bus/doctrine-orm-bridge`. Then, register the Doctrine ORM bridge middleware in your SimpleBus pipeline using the `DoctrineTransactionMiddleware` and `DoctrineDomainEventMiddleware`. Ensure your Doctrine EntityManager is available in the container, typically via a custom Laravel service provider.
- Does this work with Laravel’s native queue system or only SimpleBus?
- This package is designed specifically for SimpleBus/MessageBus. While it can coexist with Laravel queues, it doesn’t integrate directly with them. Use SimpleBus for structured command/handler separation and middleware-based retries, which Laravel’s queues lack natively.
- Can I use this with Eloquent instead of Doctrine ORM?
- No, this package requires Doctrine ORM. If your Laravel app uses Eloquent, you’d need to migrate to Doctrine ORM, which may introduce friction (e.g., DQL vs. Query Builder). Consider alternatives like `spatie/laravel-activitylog` for Eloquent-based event tracking.
- How does the transaction middleware handle rollbacks?
- The `DoctrineTransactionMiddleware` wraps command handling in a Doctrine-managed transaction. If an exception occurs, the transaction rolls back automatically, ensuring data consistency. This is ideal for financial or stateful operations where partial updates are unacceptable.
- Will this conflict with Laravel’s built-in event system?
- Yes, this package focuses on *domain events* (e.g., `OrderCreated`) emitted by Doctrine entities, while Laravel’s event system handles model events (e.g., `created`). Clarify your architecture: domain events are for business logic, while Laravel events are for framework-level concerns. They can coexist but serve different purposes.
- How do I handle domain events from Doctrine entities?
- The `DoctrineDomainEventMiddleware` collects events emitted by entities (e.g., `PrePersist`, `PostUpdate`) and dispatches them via SimpleBus. Configure your entities to emit events using Doctrine’s lifecycle callbacks, then ensure the middleware is placed *after* your command handler in the pipeline.
- Is this package compatible with Laravel 10 and Doctrine ORM 3.x?
- The package depends on SimpleBus 1.x, which may not fully align with Laravel 10’s latest features or Doctrine ORM 3.x updates. Test thoroughly, especially if using newer Laravel features like model macros or Doctrine’s hydration strategies. Monitor the [SimpleBus repo](https://github.com/SimpleBus/SimpleBus) for compatibility notes.
- How do I test commands wrapped in transactions?
- Mock Doctrine’s `EntityManager` and `Connection` for unit tests, but focus on integration tests with a test database. Use SimpleBus’s built-in test utilities to verify command execution and event dispatching. Avoid mocking transactions—test the real behavior under controlled conditions.
- Can I conditionally apply the transaction middleware?
- Yes, leverage SimpleBus’s middleware stack to conditionally wrap commands. For example, use a `TransactionGuardMiddleware` to apply transactions only to specific command types (e.g., `TransferFundsCommand`). This avoids unnecessary transaction overhead for non-critical commands.
- What are the alternatives if I don’t want to use SimpleBus?
- For transactional commands, consider Laravel’s `DB::transaction()` or packages like `spatie/laravel-transactional-filesystem`. For domain events, use Doctrine’s lifecycle callbacks with Laravel’s event system or `spatie/laravel-event-sourcing`. However, these lack SimpleBus’s middleware-based retries and structured messaging.