README

A comprehensive Google Cloud Pub/Sub integration for Laravel that goes beyond a basic queue driver — a complete toolkit for event-driven architectures, microservice communication, and real-time data pipelines.

Features

• Full Laravel queue driver — drop-in replacement for any other queue connection
• Publisher / Subscriber services — direct publishing with compression, metadata, and batch support
• Event integration — bidirectional flow between Laravel events and Pub/Sub topics
• Webhook support — handle push subscriptions with built-in IP allowlist and token verification
• Schema validation — JSON Schema validation for message contracts
• Streaming support — real-time, lower-latency processing with StreamingPull
• CloudEvents support — industry-standard event formatting with v1.0 compatibility
• Dead-letter topics & retry policies — auto-wired for resilient message delivery
• Emulator support — local development with the Google Cloud Pub/Sub emulator
• Laravel Octane compatible — connection pooling and warm bindings
• Rich Artisan command set — manage topics, subscriptions, publishing, and listening from the CLI

Table of Contents

• Requirements
• Installation
• Quick Start
  • Basic Queue Usage
  • Direct Publishing
  • Event Integration
  • Subscribing to Messages
• Full Documentation
• AI Coding Assistant Skill
• Testing
• Contributing
• Security
• License

Requirements

• PHP 8.3+
• Laravel 11 / 12 / 13
• A Google Cloud project with the Pub/Sub API enabled (or the Pub/Sub emulator for local development)

Installation

composer require offload-project/laravel-google-pubsub

php artisan vendor:publish --provider="OffloadProject\GooglePubSub\PubSubServiceProvider" --tag="config"

Add the basics to your .env:

QUEUE_CONNECTION=pubsub
GOOGLE_CLOUD_PROJECT_ID=your-project-id

# Authentication — pick one
PUBSUB_AUTH_METHOD=application_default
# or
PUBSUB_AUTH_METHOD=key_file
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Then add a pubsub connection to config/queue.php:

'connections' => [
    'pubsub' => [
        'driver' => 'pubsub',
        'project_id' => env('GOOGLE_CLOUD_PROJECT_ID'),
        'queue' => env('PUBSUB_DEFAULT_QUEUE', 'default'),
        'auth_method' => env('PUBSUB_AUTH_METHOD', 'application_default'),
        'key_file' => env('GOOGLE_APPLICATION_CREDENTIALS'),
        'auto_create_topics' => true,
        'auto_create_subscriptions' => true,
        'subscription_suffix' => '-laravel',
        'enable_message_ordering' => false,
    ],
],

See the Configuration reference for every option.

Quick Start

1. Basic Queue Usage

Use it exactly like any other Laravel queue:

ProcessPodcast::dispatch($podcast);

// Dispatch to a specific topic
ProcessPodcast::dispatch($podcast)->onQueue('audio-processing');

2. Direct Publishing

use OffloadProject\GooglePubSub\Facades\PubSub;

PubSub::publish('orders', [
    'order_id' => 123,
    'total' => 99.99,
    'customer_id' => 456,
]);

// With attributes and an ordering key
PubSub::publish('orders', $data, [
    'priority' => 'high',
    'source' => 'api',
], [
    'ordering_key' => 'customer-456',
]);

3. Event Integration

use OffloadProject\GooglePubSub\Attributes\PublishTo;
use OffloadProject\GooglePubSub\Contracts\ShouldPublishToPubSub;

#[PublishTo('orders')]
class OrderPlaced implements ShouldPublishToPubSub
{
    public function __construct(public Order $order) {}

    public function pubsubTopic(): string
    {
        return 'orders';
    }

    public function toPubSub(): array
    {
        return [
            'order_id' => $this->order->id,
            'total' => $this->order->total,
            'customer_id' => $this->order->customer_id,
        ];
    }
}

event(new OrderPlaced($order));

4. Subscribing to Messages

use OffloadProject\GooglePubSub\Facades\PubSub;

$subscriber = PubSub::subscribe('orders-processor', 'orders');

$subscriber->handler(function ($data, $message) {
    processOrder($data);
});

$subscriber->listen();

Full Documentation

• Installation
• Configuration — every config key, with defaults
• Queue Driver
• Publisher & Subscriber
• Event Integration
• Webhooks (Push Subscriptions)
• Message Schemas and Validation
• CloudEvents
• Artisan Commands
• Monitoring & Debugging — performance tuning and troubleshooting
• Testing
• Examples

AI Coding Assistant Skill

This package ships a Laravel Boost skill so coding assistants (Claude Code, Cursor, etc.) follow the package's conventions when generating code. Install it in your app with:

php artisan boost:add-skill offload-project/laravel-google-pubsub

The skill source lives at skills/SKILL.md.

Testing

composer test

Contributing

Contributions are welcome! Please see the documents below before getting started.

• Contributing Guide — setup, workflow, commit conventions, and PR process
• Code of Conduct — expectations for participation in this project

Security

• Security Policy — how to report a vulnerability privately

License

The MIT License (MIT). Please see License File for more information.