Pbjx Bundle Laravel Package

Technical Evaluation

What the package actually is. gdbots/pbjx-bundle is a Symfony bundle, not a Laravel package. It is the dependency-injection glue layer that wires gdbots/pbjx messaging primitives (command bus, event bus, request bus, service locators, tagged handler discovery) into a Symfony application's container via a bundle class, an extension/config tree, and compiler passes. The messaging engine itself lives in gdbots/pbjx; the message contracts live in gdbots/pbj and are generated from .proto schemas. Adopting this bundle means adopting that whole stack.

Architecture fit. Poor for a Laravel codebase, strong for a Symfony one. Laravel has no concept of bundles, Extension classes, config/bundles.php, tagged-service collection, or compiler passes — and the compiler passes here are not cosmetic, they are how handlers get discovered and registered. Laravel's container is PSR-11 compatible, but that only solves get(), not service wiring. Second-order assumption: the bundle presumes a schema-first, event-sourced/CQRS domain model. If the target work is conventional CRUD or queue jobs, this is a heavy mismatch.

What changed in v5.0.0. The release is a single, unmitigated breaking change: Symfony 8.x required, PHP 8.5+ required. No features, no deprecations, no migration shims. This is a version-floor jump that simultaneously (a) invalidates every existing Symfony 6/7 deployment, (b) moves the package onto a PHP minor that is not yet in most managed runtimes or base images, and (c) pushes the package to the newest Symfony major on day one. It is the exact "deep transitive coupling / lockstep upgrades land on you" risk from the prior assessment, now materialised as fact rather than speculation.

Integration feasibility.

• Symfony 8 / PHP 8.5 host: high in principle, but you must first get your platform there — see operational section.
• Symfony 6/7 host (the realistic majority): blocked on v5. You must pin to the v4.x line and accept that v4 is now a legacy branch of unknown support duration.
• Laravel host: now structurally impossible, not merely unsupported. Laravel's framework dependencies resolve against Symfony 7.x components. A composer require of v5 will fail dependency resolution outright rather than requiring a hand-rolled shim. This removes option (c) below from consideration entirely — which is arguably a favour, since it was the option most likely to rot silently.
• Honest path if capability is genuinely needed: Symfony sidecar service, boundary crossed via HTTP/queue. Unchanged from before, but the case for a native reimplementation inside Laravel is now stronger, not weaker.

Technical risk. Material, and increased by this release:

• Platform availability is now the top risk. PHP 8.5 must exist in your base images, CI runners, developer machines, and — critically — any managed/PaaS PHP host. Managed platforms typically lag new PHP minors by quarters. Verify before scoping anything.
• Symfony 8 ecosystem immaturity. Third-party bundles and adapters you depend on (including symfony/messenger transports you may not control) need to be Symfony-8-ready. On release week, expect gaps.
• Legacy-branch exposure. v4.x is now the only viable line for Symfony 6/7 hosts. There is no published LTS policy and no community pressure to create one. If v4 stops receiving fixes, you are forking.
• 0 stars, 0 dependents, single vendor org → no community validation, no third-party tutorials, no Stack Overflow corpus. Unchanged, and now more consequential because you are absorbing a major-version jump with no public migration write-ups.
• Bus factor concentrated in one organization; Apache-2.0 gives you the fork right but not the roadmap.
• Debugging a compiled, third-party DI container you did not write is slow and opaque.
• Protobuf schema evolution discipline is a hard prerequisite; the bundle cannot protect you from breaking a message contract.

Key questions.

1. Is the consuming application actually Symfony, or are we evaluating a Symfony artifact against a Laravel brief? (v5 makes this question terminal — if Laravel, decline.)
2. Is PHP 8.5 available in our runtime images, CI, and hosting today? If not, when? This now gates the entire evaluation.
3. Is the v4.x branch still maintained with security and bug fixes, and for how long? Get a written answer, not an inference.
4. Do we have a real requirement for schema-defined messages and CQRS/event sourcing, or is this résumé-driven?
5. Can we commit CI to the schema toolchain (protoc / pbjc codegen) as a first-class build step?
6. Who owns this if upstream goes quiet — do we have a fork-and-maintain budget?
7. Is interop with an existing Triniti/gdbots deployment a requirement? If yes, this becomes near-mandatory; if no, most of the value evaporates.

Integration Approach

Stack fit. Only justifiable in a Symfony service. A new Symfony 8 / PHP 8.5 service is now the only native fit for v5; every other combination is either pinned to v4 or unsupported.

Migration path. Do not retrofit this into an existing Laravel monolith. The realistic paths, in ascending order of cost and descending order of pragmatism:

1. Port the pattern, not the package. Implement a command/event bus using Laravel's own bus and event dispatcher, with message DTOs generated from the same .proto contracts. Keeps the architectural benefit, drops the framework mismatch. Now the default recommendation, since v5 has closed the shim option.
2. Extract a Symfony service. Stand up a new Symfony 8 application on PHP 8.5 that uses the bundle natively; the Laravel app talks to it over HTTP or a shared queue. Clean boundary, honest ownership.
3. Laravel service provider shim. Removed. v5's dependency floor cannot resolve inside a Laravel application. Do not scope this.

Compatibility. Pin deliberately and record the decision in the ADR:

• v5.0.0 → Symfony 8.x, PHP 8.5+. Greenfield only, and only once your platform supports it.
• v4.x → Symfony 6/7, older PHP. The pragmatic choice for existing hosts; flag explicitly as a legacy branch with unquantified support horizon.
• Verify ext-protobuf availability in the runtime image (PHP-userland fallback exists but is slower), and transport pinning (symfony/messenger and/or AWS SQS/SNS adapters) against Symfony 8.
• Note explicitly that Laravel/Lumen is not a supported host and now cannot be made one by dependency resolution — this is the finding most likely to be buried.

Sequencing.

1. Platform availability check (days, not weeks): confirm PHP 8.5 in base images, CI, developer tooling, and any managed host. If blocked, the decision becomes "v4.x now, v5 later" and everything downstream reshapes.
2. Spike (1–2 weeks): prove the schema toolchain end-to-end — author a .proto, generate PHP classes, dispatch one command, handle one event. On v4 for existing hosts, on v5 for greenfield. This de-risks 80% of the unknowns.
3. Skeleton service: minimal Symfony app, bundle registered, one handler, one transport, health checks.
4. Transport + durability: wire Messenger and the broker; confirm retry and dead-letter configuration — and confirm the transport adapters are Symfony-8-compatible if you took v5.
5. Persistence: event store / snapshot strategy — this is not provided by the bundle and is usually the largest unestimated line item.
6. Boundary contract tests: automated verification that messages exchanged with the existing Laravel system round-trip correctly.
7. Broaden only after steps 1–6 are green.

Operational Impact

Maintenance. Low churn in steady state, high cost at upgrade time — and v5 demonstrates the cost is real and is paid on the vendor's schedule, not yours. Pin exact versions. Treat Symfony major upgrades as dedicated work items with their own budget line. Expect to read upstream source, because documentation is thin relative to the surface area and there is no v5 migration guide.

Support. Apache-2.0, no commercial SLA implied, community support effectively nil. Treat this as internally-owned OSS: assign a named maintainer and budget engineering days per quarter for dependency hygiene. v5 raises the stakes on one specific question: who keeps v4.x patched while you are unable to move to PHP 8.5? If the answer is "nobody", you have inherited a fork obligation that was not previously visible.

Scaling. The bundle is not the bottleneck — it is a thin wiring layer. Throughput, backpressure, and ordering are properties of the chosen transport and the event store. Operational work that matters is per-handler idempotency, consumer concurrency tuning, and partitioning strategy — all of which you own. Unchanged by v5.

Failure modes (ranked by likelihood × impact):

• Runtime unavailability. PHP 8.5 not present in a managed host or base image; the service cannot be deployed despite compiling locally. New, and now the highest-likelihood blocker. Mitigate by validating the platform before committing.
• Symfony 8 ecosystem gaps. A required third-party bundle or transport adapter is not yet Symfony-8-ready; discovered at integration, not at install. Mitigate with an early composer-resolution spike of the full dependency set.
• Silent handler non-registration. Tag or compiler-pass misconfiguration means messages dispatch and nothing consumes. Mitigate with a startup assertion enumerating registered handlers.
• Schema version skew. A producer ships a changed contract; consumers break in production. Mitigate with backward-compatibility linting in CI and contract tests.
• Poison messages / retry storms. One malformed message saturates consumers. Requires dead-letter queues and retry ceilings configured from day one.
• Container compile failures on upgrade. Symfony or pbjx version drift breaks boot, not a request. Catch in CI, never in a deploy.
• Fork abandonment. Upstream goes quiet while you sit on the legacy v4 line. Mitigate by naming an internal owner and recording the exit criteria.
• DI cache staleness. Cached containers in immutable images must be rebuilt per release.

Ramp-up. Engineers need three competencies that rarely overlap: PBJ schema authoring, pbjx bus semantics, and Symfony DI internals. Realistic ramp is 1–2 sprints before a competent engineer is productive, and higher than usual because documentation scarcity pushes learning into source reading. v5 adds a fourth, unwelcome competency: tracking Symfony major-version migration details yourself, since no community corpus exists to lean on. On a Laravel team, add the framework-context cost on top.

Bottom line. v5.0.0 changes the verdict from "cautious maybe if you are in the gdbots ecosystem" to "only viable for greenfield Symfony 8 / PHP 8.5 services, and only once your platform supports that floor." For every other scenario — Laravel hosts, Symfony 6/7 hosts, teams without a Symfony 8 upgrade budget — the release narrows the usable surface rather than expanding it. It also removes the Laravel shim option outright, which sharpens the recommendation: adopt the pattern, not the package. Run the schema-toolchain spike only if interop with an existing gdbots/Triniti system is a stated requirement and the PHP 8.5 platform check passes; if interop is not a requirement, decline and document the framework mismatch as the deciding factor. If interop is required but the platform is not ready, pin to v4.x, get a written statement on its support horizon, and treat the eventual jump to v5 as a separately-funded migration project rather than a routine dependency bump.