Pbjx Laravel Package

Technical Evaluation

What it is. gdbots/pbjx is the messaging kernel of the Gdbots platform: a command bus, event bus, request bus, and message bus built around PBJ (a schema-defined, JSON-serializable message format), with dispatcher plumbing, enrichers, listeners, subscribers, and transport abstractions. It is not a general-purpose Laravel package; it is one layer of an opinionated, schema-first CQRS/event-driven stack whose other pieces (gdbots/pbj, schema tooling, transports, and a Symfony bundle) live outside this repository.

Architecture fit. Reasonable only if the target architecture is genuinely CQRS/event-sourced with schema-contracted messages shared across services. For a conventional Laravel monolith or a modest modular monolith, it duplicates capabilities Laravel already provides (event dispatcher, queue workers, broadcasting) and imposes a schema toolchain and message lifecycle that the team does not otherwise need. Fit also depends on whether other services in the estate speak PBJ; if not, pbjx becomes an isolated island requiring translation at every boundary.

Integration feasibility. Composer-installable and Apache-2.0, so legal friction is low. Real cost sits in the prerequisites: a PBJ schema build step, generated message classes, container wiring for buses and dispatchers, transport configuration, and a persistence/projection strategy. There is a Symfony bundle in the ecosystem but no Laravel service provider, facade, or config publishing — a bridge is ours to write and own. Expect to pin and vendor if the upstream stalls.

Technical risk. High, driven by adoption rather than code quality:

Key questions to resolve before commitment.

1. Does upstream commit to semantic versioning, and what is the observed release cadence and breaking-change history?
2. Which transports are actually implemented (SQS/SNS, RabbitMQ, in-memory) and are they production-hardened?
3. Is there a supported schema registry/versioning story, and how are breaking message changes handled?
4. What is the PHP and Laravel compatibility matrix, and is there a CI pipeline we can inspect?
5. Are Gdbots' other services a hard dependency, or can pbjx run standalone?
6. Is commercial support or a maintenance agreement available?
7. What is our fallback if upstream is archived — fork under Apache-2.0, or replace with Symfony Messenger/Ecotone?

Integration Approach

Stack fit. Assume Laravel 10/11/12 on PHP 8.1+. pbjx can sit beneath the framework as a domain-layer library: buses resolved from the container, dispatchers invoked from thin application services, HTTP controllers and jobs never touching pbjx directly. Laravel keeps its responsibilities (routing, auth, Eloquent, scheduling); pbjx owns only intra-domain message dispatch. Crucially, do not run two parallel event systems over the same state — either pbjx events are the source of truth for a bounded context, or Laravel events are, never both.

Migration path (strangler fig, not big bang).

1. Spike (1–2 sprints). One bounded context, one command, one event, one subscriber, in-memory transport, no production traffic. Success criteria: schema build reproducible in CI, message round-trip verified, failure semantics understood.
2. Bridge package. Internal acme/pbjx-laravel service provider: config publishing, bus bindings, transport driver selection, exception-to-HTTP mapping, and a command/event artisan generator. This is the artifact we actually maintain.
3. Persistence and outbox. Introduce a transactional outbox so domain writes and event publication share a transaction; projections read from the outbox, not from Eloquent observers.
4. Transport cutover. Move from in-memory to the real broker with idempotent consumers, retry policy, and a dead-letter queue. Run in shadow mode against existing flows before trusting it.
5. Expand context by context. No second context until the first has run in production for a full quarter.

Compatibility work. Verify Composer constraints against the Laravel skeleton early; if Symfony component versions conflict, isolate pbjx behind an adapter interface so the transport and dispatcher are swappable. Keep generated message classes out of the application namespace and out of hand-editing reach.

Sequencing dependencies. Schema toolchain must be stable before any bridge work; the bridge must exist before transport work; observability must land before the second consumer, otherwise debugging cross-context flows is guesswork. Treat each as a gate, not a parallel track.

Operational Impact

Maintenance. Budget for ownership, not consumption. Realistic steady state: one engineer at roughly 10–20% capacity to track upstream, refresh vendored code, and keep the Laravel bridge current with framework upgrades. Pin exact versions, vendor the dependency, and record a fork point so an upstream archive is an inconvenience rather than an incident. Apache-2.0 permits the fork; it does not supply the maintainer.

Support. No community, no forum, no commercial channel visible. Support is internal only, which means the knowledge must be deliberately concentrated and documented — design records, runbooks, and a named secondary maintainer. Escalation paths for message-layer bugs end at our own team.

Scaling. The model scales the way message buses do: stateless workers, horizontal consumer scale, broker-backed backpressure. Constraint points are ordering guarantees per aggregate, consumer idempotency (mandatory — at-least-once is the realistic delivery semantic), and projection rebuild cost as event volume compounds. The package itself will not be the bottleneck; our schema and consumer design will be.

Failure modes to instrument and rehearse.

• Poison messages — unbounded retry starving consumers; needs max-attempt caps and a DLQ with an operator runbook.
• Schema drift — a producer deploying a new message shape against an old consumer; needs contract tests in CI, not code review.
• Silent consumer absence — events published with no listener after a deploy; needs consumer-lag and publish-without-consume alerting.
• Projection divergence — read models drifting from the event log; needs periodic rebuild verification and replay drills.
• Dual-write inconsistency — the classic bug the outbox exists to prevent; enforce it before scale, not after.
• Bridge breakage on framework upgrade — the highest-frequency real-world failure; covered by an integration test suite that exercises the bridge, not just the domain.

Ramp-up. Steep, and mostly for reasons unrelated to code volume. A senior PHP engineer needs roughly two to four weeks to be productive on one flow, and that estimate assumes a mentor and a working spike to read. Required concepts: PBJ schemas and code generation, CQRS/event-sourcing discipline (immutability, replay, projections), and the gdbots conventions that are documented only in source. Frontend and CRUD-oriented engineers will be slower. Without a reference implementation in-repo, the ramp-up cost recurs with every hire.

TPM recommendation. Score 17.9 with zero stars and zero dependents is an accurate read: technically coherent, strategically orphaned. Adopt only if the organization is already committed to the Gdbots/PBJ ecosystem, or if the spike proves the schema-first contract model delivers value our team cannot get from Symfony Messenger or Ecotone at lower ownership cost. Otherwise, mine it for design patterns and decline the dependency.