Getting Started

Install with composer require hasel-at/aphpsurd-bundle:^0.2 and register the bundle/service provider using the package README (this is a Symfony-style bundle, so in Laravel you will typically need a bridge/service provider or use it in a Symfony service container context).
Look first at:
1. The README for task and payload registration examples.
2. The 0.2.0 changelog note: typed payloads are now one-to-one with tasks.
3. Your container configuration (services.yaml, service provider, or package config) because payload/task binding errors surface at container compile time.
First use case: define one task class and one payload class, bind them, then spawn the task by passing an instance of that payload type. Do not start by sharing a payload DTO across multiple tasks — that is the main breaking change in 0.2.0.
After upgrading from 0.1.0, run a full container rebuild (cache:clear, container:compile, or your framework equivalent) before exercising tasks.

Implementation Patterns

One payload type per task. Treat each payload class as belonging to exactly one task. If two tasks need the same data shape, create two distinct payload classes (even if their properties are identical), or compose a shared value object inside each payload.
Spawn with a payload instance. In 0.2.0 the intended flow is to construct the payload and hand that instance to the spawn mechanism, rather than passing loose scalars or reusing a generic DTO.
Explicit task/payload wiring. Register each task/payload pair in the container. Keep the mapping visible in config so the compile-time validation is easy to reason about.
Separate payloads at boundaries. For workflows with multiple steps, model CreateOrderPayload, ShipOrderPayload, etc. rather than a single OrderPayload reused across tasks. This keeps you compatible with the new binding rule and makes future task-specific fields easier to add.
Integration tip: if you are calling this from Laravel, wrap dispatch/spawn calls behind a small application service so the Symfony container binding and the Laravel-side call sites stay decoupled.
Testing: add a container-compile test (boot the container in CI) so a reused payload type fails fast rather than at deploy time. Unit-test payload construction and task spawning separately.
Version pinning: pin ^0.2 and review the 0.1.0 → 0.2.0 diff before upgrading existing task definitions.

Breaking change — payload reuse now fails. Reusing the same typed payload across multiple tasks throws a LogicException at container compile time, not at runtime. Your app may build fine in dev if the container is cached; always clear/rebuild caches in CI and deployment.
Error location is misleading. The LogicException appears during container compilation, so stack traces point at DI/container code rather than the offending task. Search your task registrations for duplicate payload types when you see it.
Distinct classes are the fix, not inheritance tricks. Subclassing or aliasing one payload for two tasks is likely to hit the same one-to-one binding rule. Use separate concrete payload classes.
Debugging checklist: run container compilation as a standalone step; grep payload class names across task definitions; confirm no shared DTO was left over from 0.1.0.
Config quirks: because binding is validated at compile time, dynamic/runtime task registration may not be supported cleanly. Prefer static container registration.
Extension point: payload instances are now the spawning input, so keep payload constructors cheap and serializable; avoid injecting services into payloads.
Migration tip: when upgrading, split any shared payload into per-task payloads first, then rebuild the container. Do not mix 0.1.0 and 0.2.0 task conventions in the same codebase.