Aphpsurd Bundle Laravel Package

Technical Evaluation

Architecture fit. The package provides typed task spawning — dispatching a job by handing an instance of a payload type to a spawner — which fits Laravel's job/queue idiom but is more opinionated than dispatch(new Job(...)). The 0.2.0 release strengthens the type contract: one payload type maps to exactly one task. That is a clean, stateless design and a good fit for teams already modelling commands as value objects. It is a poor fit for codebases that reuse a single DTO (e.g. OrderPayload, SyncPayload) across several handlers.

Integration feasibility. Low API surface — spawn a task with a payload instance — so a spike is cheap. The cost is not the API but the inventory and refactor: every payload type shared across tasks must be split or wrapped before 0.2.0 can boot. Feasibility is therefore medium: mechanically simple, but touchy in a mature codebase where payload classes have been reused as generic DTOs.

Technical risk.

• Breaking change with a fail-fast blast radius. The LogicException is described as thrown "at container compile time." In a Laravel context this phrase is ambiguous — Laravel's container does not have a compile phase, so this is either a custom compiled dispatcher registry, a cached-bindings artefact, or the package is a Symfony-style bundle wrapped for Laravel. If the exception surfaces during config:cache/route:cache or application boot, a single duplicate payload binding takes down every request and every queued worker, not just the offending task. That is a deploy-time, whole-application failure mode and the single largest risk in this release.
• Pre-1.0 versioning. 0.2.0 permits breaking changes in a minor. Expect more of these; budget for it.
• Unproven maintainership. hasel-at is a small publisher with no prior assessment baseline; no evidence yet of a support policy, deprecation window, or version matrix.
• Behavioural coupling. Binding payload type → task implicitly forbids polymorphism and inheritance-based payload hierarchies, which may collide with existing abstractions.

Key questions for the maintainer / spike.

1. Exactly when is the LogicException thrown — boot, cache warm, first dispatch, or artisan only? Can it be detected by a CI command rather than at runtime?
2. Is payload identity keyed on the concrete class name, the interface, or the instance? Does a subclass of a bound payload type count as a second binding?
3. Is the one-task-per-payload rule global, or scoped per dispatcher / queue connection? Can I run two isolated task registries?
4. What is the supported Laravel and PHP version matrix, and is 0.1.0 multi-task behaviour recoverable via a wrapper payload or an explicit opt-out?
5. How are payload instances serialised onto the queue — constructor properties, __serialize, or the container? This determines what is safe to put in a payload.
6. Test coverage and CI signal for the compile-time constraint specifically.

Integration Approach

Stack fit. Suitable for a Laravel service that already treats jobs as typed commands and is comfortable with a stricter contract than Laravel's default dispatcher. Unsuitable where payload DTOs are shared infrastructure across modules. Recommend adopting behind a thin internal TaskSpawner facade so the package remains swappable and the 1-task-per-payload rule is enforced in one place rather than scattered across feature code.

Migration path.

1. Pin to 0.1.0 on the current branch; do not upgrade in place on a shared codebase.
2. Run a static inventory: enumerate every payload class and count its spawn sites. Any payload with more than one task is a migration blocker.
3. For each collision, choose split (distinct payload classes) or wrap (a task-specific wrapper delegating to the shared DTO). Prefer splits — wrappers preserve the coupling the release is trying to remove.
4. Land refactors on 0.1.0 first, verified by tests, so the 0.2.0 bump is a version change and not a version change plus a refactor.
5. Add a CI gate that boots the container / warms caches, so the LogicException is caught pre-merge rather than at deploy.
6. Upgrade to 0.2.0 on a branch, soak in staging, then roll out.

Compatibility. Verify PHP and Laravel constraints, queue driver behaviour (database/Redis/SQS serialisation of payload instances), and interaction with config:cache and optimize in the deploy pipeline. Confirm Horizon/worker restart semantics if payload classes move namespace during the split.

Sequencing. Spike (1–2 days) → maintainer Q&A on the exception timing → payload inventory → refactor on 0.1.0 → CI boot gate → 0.2.0 upgrade in staging → production. Do not sequence the upgrade ahead of the inventory.

Operational Impact

Maintenance. Pre-1.0 with a demonstrated willingness to break in minor versions. Treat each release as potentially breaking and budget recurring upgrade effort; keep the internal facade to contain churn. Track the changelog as a standing item in dependency review.

Support. Single small publisher, no established support SLA. Mitigation: vendor-risk note, internal ownership assigned to a named engineer, and the facade ensuring a 1–2 day exit path to native Laravel dispatching if the package stalls.

Scaling. Spawning by payload instance is cheap; no runtime overhead concern. The scaling risk is organisational: as the task count grows, the one-payload-per-task rule pushes toward a large number of narrow payload classes. That is healthy for clarity but increases file count and demands naming conventions. Document the convention early or the codebase will drift and re-trip the constraint.

Failure modes.

• Boot-time outage: duplicate payload binding throws during container compile/cache warm, taking down all traffic and workers. Highest severity; mitigate with the CI boot gate and staged rollout.
• Silent behavioural drift: a payload refactored for one task still referenced by another, passing locally where caches are cold and failing in production where they are warm.
• Serialisation mismatch: payload instances carrying non-serialisable state fail at dispatch or on the worker rather than at spawn.
• Version skew: mixed 0.1.0/0.2.0 across services sharing a queue, where one service still relies on multi-task payloads.
• Abandonment: package unmaintained mid-adoption; facade limits the cost.

Ramp-up. API is small — an engineer is productive in under a day. The real ramp-up is the rule: engineers must internalise "one payload type, one task" and know that violating it fails at boot. Put this in the onboarding doc and encode it in the CI gate so it is learned by tooling rather than by incident. Estimate ~1 sprint for one engineer to complete inventory, refactor, and land the upgrade safely; add review time for the payload split if collisions exceed a handful.