Kafka Transport Laravel Package

Product Decisions This Supports

• Delivery-semantics decision — this is the headline change. 0.2.5 commits offsets on receive and leaves the consumer group before handling the message. That flips the consumption path from the at-least-once assumption in the previous assessment to at-most-once: if the handler throws, the process crashes, or the pod is evicted after the commit, that message is gone. Any use case greenlit on "at-least-once is acceptable" must be re-reviewed against "message loss on handler failure is acceptable."
• Use cases to greenlight (revised): telemetry/metrics ingestion, audit-log fan-in, cache invalidation, notification dispatch where a duplicate is worse than a miss, and any workload with its own durable store or idempotent reconciliation downstream. Do not greenlight with this release alone: payments/ledger events, outbox/CDC relay as the system of record, cross-service domain events that drive state transitions, or anything where a dropped message requires manual reconciliation.
• Ordering guarantees are now in question. If a consumer leaves the group before handling, another consumer can be assigned that partition and process later records while the first is still working. Per-partition ordering — the usual reason to pick Kafka over SQS — is no longer something you can assume. This is a decision input for any workflow that depends on key-ordered processing.
• Backpressure and throughput architecture. Decoupling handling from group membership means handlers can run longer than max.poll.interval.ms without being evicted — a real win for slow handlers. The cost is that you no longer get rebalance-driven backpressure: you must own prefetch limits, in-flight concurrency, and shutdown drain behavior yourself.
• Observability and autoscaling. A consumer that has left the group is invisible to consumer-group lag metrics and to group-size-based autoscalers. If your scaling policy or alerting keys off group membership or lag, it will under-report during exactly the periods you care about. This is an SRE/runbook decision, not a code detail.
• Dependency risk and release cadence. We are now three patch releases past the last assessment (0.2.2 -> 0.2.5) with a semantics-changing behavior landing in a patch version. That is a strong signal to pin exact versions, wrap the transport behind your own interface, and budget for re-reading behavior on every bump rather than assuming semver protects you.
• Roadmap sequencing: still pre-1.0 and now demonstrably willing to change delivery semantics in a patch. Scope adoption as a bounded pilot with a documented fallback, not a platform commitment.

When to Consider This Package

Adopt it when:

• Your stack is Laravel/PHP and you want Kafka consumption without hand-rolling offset management, deserialization, and rebalance handling.
• Rebalance churn is a real pain point: large consumer groups, frequent deploys, aggressive autoscaling. Cooperative rebalancing (0.2.2) plus leave-before-handle (0.2.5) together drastically reduce group disruption.
• You have long-running handlers that previously risked max.poll.interval.ms eviction and thundering rebalances. This release is explicitly aimed at that.
• You have explicitly accepted at-most-once on the consume path, or your handlers are idempotent and you have a separate mechanism (reconciliation job, upstream replay, durable outbox) that recovers dropped messages.
• You are comfortable on a pre-1.0 dependency: pin the exact version, wrap the transport behind your own interface, expect breaking behavior changes in patch releases, and re-verify semantics on every upgrade.

Look elsewhere when:

• Message loss is unacceptable. With commit-on-receive, a crash mid-handler loses the message. If you need at-least-once, you either stay on an older pinned version, configure this behavior off (confirm it is configurable), or consume via php-rdkafka / Confluent's client directly.
• You need per-partition ordering. Confirm — from the README, not the changelog — whether leave-before-handle can result in concurrent processing of the same partition.
• You need Kafka transactions, exactly-once semantics, Streams-style processing, or Schema Registry integration. Nothing in this release note speaks to these.
• You need a mature, heavily documented, commercially supported client.
• Your organization lacks Kafka operational experience; a thin wrapper does not substitute for it.
• You are not on Laravel, or you need a broad queue abstraction rather than a Kafka-specific one.
• Single-maintainer / small-org risk is unacceptable for a Tier-1 system. The cadence here (multiple patch releases, semantics changes in patches) makes this a live concern, not a theoretical one.

Due diligence before committing (updated):

• I have the changelog for 0.2.2 and 0.2.5 only — 0.2.3 and 0.2.4 release notes are missing and must be reviewed before any pilot; they may contain further behavior changes.
• Is commit-on-receive-and-leave-before-handle the default, opt-in, or configurable? Can we restore at-least-once with a config flag?
• Where is the offset actually committed — before or after the handler returns, and is the commit synchronous or fire-and-forget? A commit that silently fails on a leave is worse than no commit.
• What happens to in-flight messages on SIGTERM / pod eviction: are offsets already committed and messages dropped, or is there a drain path?
• Confirm partition-ordering behavior under leave-before-handle: can two consumers process the same partition concurrently?
• How do we get lag and health visibility for consumers that are not in the group? What metrics does the package expose?
• Confirm cooperative rebalancing configuration and mixed-version group behavior, as before.

How to Pitch It (Stakeholders)

For executives: This is a small open-source Laravel package that lets our PHP services talk to Kafka using normal framework conventions instead of bespoke low-level code. The 0.2.5 release changes how we acknowledge messages: the service now records "I've got it" as soon as a message arrives, then steps out of the consumer group to do the work, and rejoins afterwards. The upside is operational: deploys and scaling no longer stall the whole group, and slow handlers no longer get kicked out mid-work — shorter processing stalls and less message lag during releases. The trade-off is a real one and needs a decision from us: if a handler fails after that acknowledgement, the message is lost rather than retried. So this release is a good fit for telemetry, audit, cache and notification pipelines, and a poor fit for anything financial or state-changing without an independent safety net. It is also still pre-1.0 with a small maintainer base, and this behavior change arrived in a patch release — so we should treat version bumps as reviewable events, not routine. Recommended path: pilot on one non-critical event pipeline with an explicitly at-most-once-tolerant workload, pin the exact version, wrap the transport behind our own interface, and keep a documented fallback to the underlying Kafka client.

For engineering: 0.2.5 changes the consumer lifecycle in two coupled moves: it commits the offset on receive, then leaves the consumer group before invoking the handler, and rejoins after. Consequences you need to reason about before adopting:

1. Delivery semantics are now at-most-once on the consume path. A throw, a fatal, an OOM kill, or a SIGTERM between commit and handler completion loses that record. Any handler that previously relied on redelivery for retry needs its own retry/compensation, or the package needs a config flag to restore commit-after-handle — verify which.
2. Ordering. Because the consumer is not a group member while handling, another consumer can take that partition and process later records concurrently. Kafka's per-partition ordering guarantee no longer holds at the application level unless the package serializes per key elsewhere. Confirm against the README; this is the single most likely surprise for anyone using keyed messages.
3. Where it genuinely helps: max.poll.interval.ms evictions from slow handlers disappear, rebalance storms shrink further on top of the cooperative protocol from 0.2.2, and rolling deploys stop being a group-wide pause.
4. What you now own: backpressure and prefetch limits (no rebalance-driven throttle), graceful-shutdown drain semantics, and observability — a non-member consumer won't show up in group lag or group-size metrics, so lag alerting and group-size-based autoscaling will under-report. Budget for custom lag/heartbeat metrics.
5. Process: 0.2.3 and 0.2.4 notes are missing from what we've reviewed; read them and the diff for PR #15 before piloting. Keep the transport behind our own interface so a swap to php-rdkafka — or a revert to commit-after-handle — stays a contained change.