Tactician Laravel Package

Getting Started

Start by installing the core package: composer require league/tactician. Define simple, plain PHP objects as commands (no interfaces needed since v0.4.0). Create handler classes with a public handle() method (or custom-named methods using inflectors). Set up a minimal command bus using League\Tactician\Core\CommandBus and the included CommandHandlerMiddleware, passing in a ClassNameExtractor and a HandlerLocator (e.g., CallableLocator for basic setups or ContainerLocator via league/tactician-container for DI integration). The README’s quick example shows this pattern clearly—start there for your first working bus.

Implementation Patterns

• Use middleware stacks to compose cross-cutting concerns (e.g., logging, transactions, locking, event dispatching) via the MiddlewarePluginManager or manual stacking.
• Integrate containers via league/tactician-container to lazy-load handlers—especially critical in production for performance.
• Leverage inflectors like HandleClassNameWithoutSuffix to decouple handler method names from command class names (e.g., RentMovieCommand → handleRentMovie() instead of handle()), useful when renaming or aligning with domain semantics.
• Use plugins for bounded contexts: tactician-doctrine for per-command DB transactions, tactician-logger for structured logging, tactician-bernard for async jobs.
• Test strategies: Mock the command bus for integration tests; unit-test handlers in isolation using injected dependencies. Commands are data objects—focus tests on business logic in handlers.
• Framework integration: Though not widely adopted in modern Laravel (where commands are often dispatched directly), Tactician shines in Slim, Silex (legacy), or custom microservices where explicit command-to-handler mapping improves clarity.

Gotchas and Tips

• PHP 7/8 compatibility: Ensure your PHP version matches the latest supported ones (v1.2.0 added PHP 8.1/8.5 support)—check the changelog before upgrading.
• ClassNameExtractor is mandatory: For CommandHandlerMiddleware, forgetting to pass it (or misconfiguring the locator signature) leads to runtime errors—double-check constructor parameters.
• Handler naming pitfalls: The default handle() method works, but inflectors like HandleClassNameWithoutSuffix require strict naming conventions; mismatched methods cause “no handler found” exceptions. Use handleXXX pattern consistently.
• Middleware order matters: Transactional or locking middleware must wrap handler execution (often inside other middleware like logging) to be effective—misordering breaks intended behavior (e.g., lock applied after DB commit).
• CallableLocator limitation: Great for prototyping, but doesn’t support DI—switch to container-based locators early in development to avoid refactoring later.
• Error handling: Prior to v0.6.1, LockingMiddleware could cause permanent locks—ensure you’re on v1.2.0+ and wrap bus execution in try/catch (Throwable).
• Debugging tip: Add a logging middleware early; observing the command class name and handler resolution helps trace misconfigurations quickly.