Php Sdk Laravel Package

Product Decisions This Supports

Build vs. buy on the queue wire format. The core question this package answers: do we design our own cross-language job envelope, or adopt one? Rolling your own means a versioned spec, golden fixtures, and conformance tests across every SDK we ship. BabelQueue hands you a frozen schema_version: 1 envelope ({job, trace_id, data, meta, attempts}) with published conformance fixtures — the reusable artifact is the contract, not the code.

Polyglot queue strategy / language-mixing roadmap. Laravel's queue payload is PHP serialize() — a Go, Python or Node consumer cannot read it. This package is the escape hatch. That directly enables decisions like "can we let the data team write that consumer in Python?" without a queue re-architecture. If your roadmap includes any non-PHP service touching async work, this changes the sequencing from "rewrite the queue layer" to "publish a JSON envelope."

Producer/consumer deploy decoupling. Because the envelope is language-neutral and header-based extensions ride beside the frozen body (replay-bypass, W3C traceparent), producers and consumers can ship independently and on different runtimes.

Reliability roadmap, in layers. Each capability maps to a concrete product decision and can be adopted independently:

Observability spend. Tracing + trace_id preservation end-to-end answers "do we need to buy APM coverage for our async paths, or is OTel enough?" — and gives you a defensible correlation story for incident review.

Sequencing signal from the package split. The core is framework-agnostic; the practical install is the adapter (babelqueue/laravel). That's an architectural vote for keeping queue contracts out of framework code — worth mirroring in your own internal libraries regardless of whether you adopt this.

When to Consider This Package

Adopt when most of these are true:

• You have — or will have within ~12 months — two or more languages producing or consuming the same queue. This is the whole point; without it the value collapses.
• You are on Redis or RabbitMQ, or willing to implement the one-method Transport interface (it's literally an rpush for phpredis). The reference transports are deliberately thin.
• You need cross-language DLQ replay or a safe replay story, and today's answer is "SSH in and re-push by hand."
• Your handlers fire non-idempotent external effects and you've been avoiding DLQ replay because of it — ReplayBypass is the most differentiated thing here.
• You need idempotent consumers at fleet scale and would otherwise build a dedupe table with an atomic claim yourself. PdoStore/RedisStore with a unique-INSERT / SET NX PX claim is a solved pattern here.
• You want the transactional outbox without adopting Debezium or a heavyweight framework — OutboxStore is four methods bound to your own DB, no schema ownership imposed.
• You have a compliance requirement (GDPR) to carry PII through the queue and want field-level encryption that keeps the envelope byte-compatible for hops that lack the key.
• You are comfortable being an early adopter and can pin/fork.

Look elsewhere when:

• Monolingual Laravel shop. Use the native queue, Horizon, ShouldBeUnique and failed_jobs. This package's entire premise is language neutrality you don't need. Non-trivial integration cost, zero payoff.
• You need a first-party transport for SQS, Kafka, or Google Pub/Sub today. Only Redis and AMQP ship as references. Kafka in particular inverts the model — this is a per-message envelope, not a log.
• You need vendor support, an SLA, an SOC 2 report, or a community. 1 star, 0 dependents, single-maintainer risk, and releases dated into the future (worth verifying cadence and provenance before committing). Treat this as internal-forkable open source, not a vendor relationship.
• You need exactly-once. The docs are refreshingly honest: this is at-least-once with a documented claim-TTL window. If the business requires exactly-once semantics, no package solves that — fix it at the handler or product level.
• You need an ops dashboard / UI. There's a RedriveIO seam and a CLI-ish Redrive::run, not a console. Budget for building or buying the surface.
• You need a fully managed, batteries-included DLQ service (e.g. a hosted queue with replay built in). Buying the platform beats assembling the primitives.

Adoption guardrails if you proceed: pin the adapter version, vendor the golden fixtures into your own conformance CI, verify a PHP/Laravel version matrix against the adapter, and write down a fork-and-own contingency in the ADR. MIT license makes that viable — say so explicitly, because it's the answer to the "one-star repo" objection.

How to Pitch It (Stakeholders)

To executives — one paragraph. Our queue payload is PHP-specific, which means every new non-PHP service we add either can't consume our jobs or forces a rewrite of that layer. BabelQueue is an MIT-licensed, language-neutral JSON envelope with a published spec and conformance tests, plus ready-made pieces for the things that bite us operationally: dead-letter replay that won't double-charge customers, duplicate-delivery protection across a fleet, an outbox that eliminates the dual-write gap, and field-level encryption for PII. The decision is adopt a contract now versus design our own in six months under deadline. Cost is near-zero in licensing; the real cost is integration and owning an early-stage dependency.

To engineering — the shape of it. It's a small dependency-free core (ext-json only; every crypto, broker and OTel dependency is a suggest), consumed through a framework adapter. Nothing is mandatory: if we never call Gdpr::protect() or Idempotent::wrap(), behaviour is identical to today. The envelope is deliberately frozen — extensions (replay-bypass marker, traceparent) ride out-of-band transport headers, so schema_version stays 1 and a hop that doesn't understand a feature still carries the message byte-for-byte. Transports are a one-method interface, so our broker choice isn't locked in. The pieces we'd actually wire: EnvelopeCodec on the wire, EnvelopeValidator before dispatch (quarantine unknown schema versions rather than drop), ClaimingDispatch around handlers that must not double-run, Redrive + ReplayBypass for DLQ, and Outbox if we want to close the produce-side dual write.

The honest risk statement — say it in the same breath. This is a pre-traction package: 1 star, 0 dependents, single maintainer, no support channel. We would be the first serious production user. Mitigations: MIT license and a small, readable surface make a fork cheap; the golden fixtures let us prove conformance ourselves; the envelope is plain JSON so extraction is a codec swap, not a migration. If those mitigations aren't acceptable, the correct alternative is to copy the envelope spec into an internal package and implement the codec ourselves — we lose the library, keep the design, and take on maybe a week of work. That option should be presented alongside adoption so the decision is genuinely build-vs-buy rather than a fait accompli.