Cloud Pubsub Laravel Package

Technical Evaluation

Architecture fit

• google/cloud-pubsub is a vendor SDK, not a Laravel package. It ships no ServiceProvider, facade, config stub, or publishable assets. Everything — client construction, credential resolution, topic/subscription naming, worker lifecycle — becomes application code your team owns.
• It is a transport-layer client, not a queue abstraction. Laravel's queue subsystem is built around Illuminate\Contracts\Queue\Queue (push, pop, later, delete, release). Pub/Sub's model — push subscriptions to HTTP endpoints, or pull/streaming-pull with explicit ack deadlines — does not map cleanly onto that contract. You either write a custom queue driver (moderate complexity, ongoing maintenance) or bypass the queue contract and treat Pub/Sub as an event bus with dedicated consumers.
• Two integration shapes, with materially different risk profiles:
  1. Push subscription → Laravel HTTP route. Idiomatic Laravel, works with FPM/Octane, no long-running workers, no gRPC extension. Recommended default.
  2. Streaming pull → artisan worker under Supervisor. Higher throughput, but requires the grpc PHP extension, blocking I/O, careful lease management, and a worker process model that diverges from queue:work.
• The sample code targets the generated GAPIC surface (PublisherClient, GetTopicRequest, proto messages). The library also exposes a simpler hand-written Google\Cloud\PubSub\PubSub / Topic / Subscription API. Pick one and standardize — mixing them across a codebase is a common source of confusion.

Integration feasibility

• Install is trivial: composer require google/cloud-pubsub. No framework version constraints, no conflicts with Laravel's dependency tree in practice (it pulls google/gax, google/protobuf, google/common-protos, grpc/grpc if present).
• PHP 8.4 compatibility was explicitly fixed in v2.8.2, and the client is actively tested against current PHP — a green flag for teams on modern Laravel (11/12).
• Credentials are the real friction point. The library relies on Application Default Credentials; the keyFile / keyFilePath options were deprecated in v2.15.0. On GKE/Cloud Run this is fine (Workload Identity). Off-GCP — a Laravel app on Laravel Forge, Ploi, or a colo box — you must either mount a service-account JSON and set GOOGLE_APPLICATION_CREDENTIALS or configure Workload Identity Federation. That is a secrets-management decision, not a code decision, and it should be made before the first commit.
• No first-party Laravel integration means no config/queue.php connection, no Horizon support, no queue:failed visibility out of the box. If operations expect the standard Laravel queue tooling, that expectation must be reset early.

Technical risk

• At-least-once delivery is the dominant risk. Pub/Sub guarantees at-least-once, so duplicate processing is guaranteed under retry, redelivery, and nack scenarios. Every consumer must be idempotent. Laravel jobs written for Redis/SQS semantics will silently double-charge, double-email, or double-write unless audited.
• Streaming pull under PHP is the weakest link. The client is synchronous and blocking; a worker holds an open stream per process. PHP has no native async runtime, so concurrency comes from process count (Supervisor), not from the library. Memory growth in long-lived workers and reconnect behavior after idle stream drops are both real operational concerns — v2.19.3's "increase streaming pull timeout" bugfix is evidence this area still moves.
• Release churn is high and mostly generated. 20+ minor releases in the v2 line, driven by upstream proto changes (AI inference transforms, Bigtable config, Kafka ingestion sources, schema imports). Most are additive and irrelevant to a Laravel app, but it means frequent dependency-update PRs and a non-trivial CI surface. Note v2.4.0 shipped an accidental breaking change — the GA stability guarantee held in intent but not perfectly in execution.
• Ecosystem signal is misleading. The 93 stars and 0 Packagist dependents reflect the fact that this is a read-only subtree split of the google-cloud-php monorepo, not a standalone project. Real-world usage flows through the monorepo. Do not read the low score as abandonment — but equally, do not read it as community validation within Laravel, because there is none. You will be the first team in your Slack to hit any integration edge case.
• Vendor lock-in is moderate. Pub/Sub's feature set (ordering keys, schemas, dead-letter topics, message transforms, BigQuery/Cloud Storage subscriptions, exactly-once pull delivery) is genuinely differentiated. Once you adopt schema validation and message transforms, exit cost rises sharply.

Key questions

• Is the target workload queue semantics (jobs, retries, delays, Horizon dashboards) or event distribution (fan-out to multiple independent consumers)? Queue semantics argue for SQS/Redis; event distribution argues for Pub/Sub.
• Where does the app run — GCP (Workload Identity available) or elsewhere (credential mounting required)?
• Can we mandate push subscriptions and avoid the gRPC extension and long-running worker model entirely? If yes, risk drops substantially.
• Are consumers provably idempotent today, or does that need to be built?
• Do we need ordering keys? If so, PHP's process-per-worker model constrains effective parallelism per ordering key.
• Who owns Pub/Sub infrastructure — Terraform, the Laravel app, or a separate platform team? Topic/subscription provisioning must have a clear owner.
• Is there appetite for a thin internal package (acme/laravel-pubsub) wrapping the SDK with config, service provider, and a typed publish API? This is the single highest-leverage decision for maintainability.

Integration Approach

Stack fit

• Publisher: clean fit. A PubSubServiceProvider binding a singleton PubSub client, a config file for project ID and credential path, and a small typed wrapper around Topic::publish() covers 90% of publishing needs. Publishing from HTTP requests is fast and non-blocking enough for typical Laravel request budgets; for latency-sensitive paths, publish via a queued job.
• Consumer, push model: route → Route::post('/pubsub/handler', ...) → verify the OIDC JWT from the Authorization: Bearer header against Google's public keys → dispatch to a Laravel job → return 2xx. Pub/Sub retries non-2xx automatically, which gives you retry semantics almost for free. This is the most Laravel-native shape and should be the default architecture.
• Consumer, pull model: an artisan command using Subscription::pull() or the streaming puller, run under Supervisor. Treat it as a separate deployable concern from queue:work — different restart policy, different memory ceiling, different scaling metric (subscription backlog, not queue depth).
• Dead-lettering: configure a dead-letter topic + maxDeliveryAttempts on the subscription rather than relying on Laravel's failed_jobs. This is a Pub/Sub-native control that Laravel's tooling does not expose.

Migration path

• Greenfield: push subscription + Laravel job dispatch. Lowest total cost, no gRPC, no worker rewrite.
• From Redis/SQS: do not attempt a big-bang driver swap. Recommended sequence:
  1. Stand up Pub/Sub publishing behind an interface (EventPublisher), keeping the existing queue driver live. Dual-write or shadow-publish; verify message shape and volume.
  2. Move one non-critical consumer to a push endpoint. Measure duplicate rate and handler latency.
  3. Cut over remaining consumers one at a time, with the old path retained behind a feature flag for one release cycle.
  4. Decommission the old driver only after backlog reaches zero on both paths.
• From google/cloud-pubsub V1: the library ships a MIGRATING.md; the V1→V2 move is largely mechanical (client class renames, proto message objects replacing arrays). Budget a half-day per integration surface plus a full regression pass — argument-shape changes fail at runtime, not compile time.

Compatibility

• Composer constraints are permissive; the main compatibility axis is the grpc PHP extension. It is optional for REST transport and required for streaming pull. If your build images are managed (Laravel Vapor, Forge, container base images), confirm the extension can be installed before committing to a pull architecture. Vapor in particular is a poor fit for long-running pullers.
• Octane: a singleton PubSub client is generally safe to hold across requests, but gRPC channel state under a forked/worker-recycling server needs validation. Push-model consumers sidestep this entirely.
• Laravel version: no constraint conflicts expected on 10/11/12. Verify against your locked google/protobuf version — v2.19.1 bumped protobuf 25.7→31.0, which can collide with other Google SDKs in a larger dependency graph.

Sequencing

1. Decide push vs. pull. (Week 0, architecture decision, hard to reverse.)
2. Land credentials strategy — Workload Identity or secret-mounted SA, with rotation plan. (Week 0–1)
3. Build the internal wrapper package: service provider, config, publisher interface, push-endpoint JWT verification middleware. (Week 1–2)
4. Terraform (or equivalent) for topics, subscriptions, dead-letter policies, IAM. (Week 1–2)
5. Pilot one low-risk publisher + one consumer in staging under synthetic load, including forced failure injection. (Week 3)
6. Production rollout per consumer, with idempotency audit as a gate. (Week 4+)

Operational Impact

Maintenance

• Steady-state maintenance is dependency hygiene plus wrapper ownership. The vendor maintains the SDK; you maintain the glue. Realistically 1–2 days per quarter for SDK bumps (the release cadence is high, so pin with ~2.22 and upgrade deliberately rather than floating).
• The internal wrapper is the real asset and the real liability. Budget ownership explicitly — an unowned wrapper becomes an undocumented snowflake within two quarters.
• Watch for proto-level additions you do not need (AI inference transforms, Bigtable config, Kafka ingestion). Keeping the dependency current does not require adopting them, but changelog review is a recurring task.

Support

• Upstream: Google Cloud support plans cover the SDK; GitHub issues route to the monorepo. Responsiveness on genuine bugs is good (see the streaming pull timeout and PHP 8.4 fixes). There is no Laravel-specific support channel — no Slack, no maintainer who will review your service provider.
• Internal: assume a single-owner bus factor unless you deliberately spread knowledge. The push-endpoint pattern is small enough that two engineers can own it comfortably; the streaming-pull worker is not.
• Community: near-zero Laravel-ecosystem precedent means Stack Overflow answers will be about Google Cloud Pub/Sub generally, not about Laravel integration. Debugging is first-principles work.

Scaling

• Publisher scale is a non-issue; it is an HTTP/gRPC call to a fully managed service. Watch request-level batching (the library batches by default) and per-request latency budget in synchronous paths.
• Push consumer scale maps directly onto your existing Laravel web tier and autoscaling rules. This is a genuine advantage: no new scaling model to learn. The constraint is per-request timeout — Pub/Sub's ack deadline defaults to 10s and caps at 600s, so any handler exceeding the deadline must hand off to a queued job and return 2xx immediately.
• Pull consumer scale is linear in worker processes. Each process is one stream; scale by adding Supervisor processes or replicas, driven by subscription/backlog_bytes rather than CPU. Throughput per PHP process is modest — this is the weakest scaling story in the package and the main argument against pull.
• Cost at volume is consumption-based and generally competitive for fan-out, but egress and cross-region delivery can surprise. Model it against your current Redis/SQS spend before committing.

Failure modes

• Duplicate delivery → duplicate side effects. Highest-probability, highest-impact. Mitigate with idempotency keys derived from messageId, unique constraints, and idempotent downstream APIs.
• Ack deadline exceeded → redelivery storm. A slow handler produces retries that pile onto an already-saturated tier. Mitigate with fast-ack-then-queue, maxDeliveryAttempts, and dead-letter topics.
• Expired or absent credentials → total publish/consume outage. Fails loudly but all at once. Alert on publish error rate, not just on 5xx.
• JWT verification skipped on push endpoints. The endpoint is public by definition. Failing to verify the OIDC token turns your consumer into an unauthenticated write path — this is a security failure, not an availability one, and it is the most commonly missed step in push integrations.
• Streaming pull stream drop / silent stall. The puller can stop receiving without the process dying. Mitigate with heartbeat metrics on "time since last message" and a supervisor restart policy.
• Long-lived worker memory growth. PHP workers under streaming pull accumulate memory; enforce memory_limit and periodic recycling.
• Ordering violations if ordering keys are enabled and consumers run in parallel. Ordering is per-key and only guaranteed within a subscription's ack window — do not assume global order.
• ApiException swallowing. The README sample catches and prints; production code must classify retryable vs. terminal (quota exceeded, permission denied, not found) and behave differently.

Ramp-up

• Expect 1–2 weeks for a mid-level Laravel engineer to become productive: Pub/Sub concepts (topics, subscriptions, ack deadlines, at-least-once, dead-letter), GCP IAM and ADC, and the difference between the GAPIC and hand-written client surfaces.
• The push-endpoint architecture is learnable in days — it looks like a normal Laravel route with JWT middleware. The streaming-pull worker is a multi-week ramp and should be assigned to a senior engineer.
• Institutional knowledge that must be written down, not assumed: credential rotation procedure, push JWT verification recipe, dead-letter replay runbook, and the idempotency contract every consumer must satisfy.
• Recommend a 1-hour internal walkthrough of at-least-once semantics for the whole team before any consumer ships. It is cheap and prevents the most expensive class of bug in this integration.