README

Consume real-time AT Protocol events in your Laravel application.

What is Signal?

Signal is a Laravel package that lets you respond to real-time events from the AT Protocol network. Build reactive applications, custom feeds, moderation tools, analytics systems, and AppViews by listening to posts, likes, follows, and other social interactions as they happen across Bluesky and the entire AT Protocol ecosystem.

Think of it as Laravel's event listeners, but for the decentralized social web.

Why use Signal?

• Laravel-style code - Familiar patterns you already know
• Real-time processing - React to events as they happen
• Dual-mode support - Choose Jetstream (efficient JSON) or Firehose (comprehensive CBOR)
• AppView ready - Full support for custom collections and protocols
• Production features - Queue integration, cursor management, auto-reconnection
• Easy filtering - Target specific collections, operations, and users with wildcards
• Built-in testing - Test your signals with sample data

Quick Example

use SocialDept\Signal\Events\SignalEvent;
use SocialDept\Signal\Signals\Signal;

class NewPostSignal extends Signal
{
    public function eventTypes(): array
    {
        return ['commit'];
    }

    public function collections(): ?array
    {
        return ['app.bsky.feed.post'];
    }

    public function handle(SignalEvent $event): void
    {
        $record = $event->getRecord();

        logger()->info('New post created', [
            'did' => $event->did,
            'text' => $record->text ?? null,
        ]);
    }
}

Run php artisan signal:consume and start responding to every post on Bluesky in real-time.

Installation

composer require socialdept/signal
php artisan signal:install

That's it. Read the installation docs →

Getting Started

Once installed, you're three steps away from consuming AT Protocol events:

1. Create a Signal

php artisan make:signal NewPostSignal

2. Define What to Listen For

public function collections(): ?array
{
    return ['app.bsky.feed.post'];
}

3. Start Consuming

php artisan signal:consume

Your Signal will now handle every matching event from the network. Read the quickstart guide →

What can you build?

• Custom feeds - Curate content based on your own algorithms
• Moderation tools - Detect and flag problematic content automatically
• Analytics platforms - Track engagement, trends, and network growth
• Social integrations - Mirror content to other platforms in real-time
• Notification systems - Alert users about relevant activity
• AppViews - Build custom AT Protocol applications with your own collections

Documentation

Getting Started

• Installation - Detailed setup instructions
• Quickstart Guide - Build your first Signal
• Jetstream vs Firehose - Choose the right mode

Building Signals

• Creating Signals - Complete Signal reference
• Filtering Events - Target specific collections and operations
• Queue Integration - Process events asynchronously

Advanced

• Configuration - All config options explained
• Testing - Test your Signals
• Examples - Real-world use cases

Example Use Cases

Track User Growth

public function collections(): ?array
{
    return ['app.bsky.graph.follow'];
}

Monitor Content Moderation

public function collections(): ?array
{
    return ['app.bsky.feed.*'];
}

public function shouldQueue(): bool
{
    return true; // Process in background
}

Build Custom Collections (AppView)

public function collections(): ?array
{
    return ['app.yourapp.custom.collection'];
}

See more examples →

Key Features Explained

Jetstream vs Firehose

Signal supports two modes for consuming AT Protocol events:

• Jetstream (default) - Simplified JSON events with server-side filtering
• Firehose - Raw CBOR/CAR format with client-side filtering

Learn more about modes →

Wildcard Filtering

Match multiple collections with patterns:

public function collections(): ?array
{
    return [
        'app.bsky.feed.*',      // All feed events
        'app.bsky.graph.*',     // All graph events
        'app.yourapp.*',        // All your custom collections
    ];
}

Learn more about filtering →

Queue Integration

Process events asynchronously for better performance:

public function shouldQueue(): bool
{
    return true;
}

Learn more about queues →

Available Commands

# Install Signal
php artisan signal:install

# Create a new Signal
php artisan make:signal YourSignal

# List all registered Signals
php artisan signal:list

# Start consuming events
php artisan signal:consume

# Test a Signal with sample data
php artisan signal:test YourSignal

Requirements

• PHP 8.2+
• Laravel 11+
• WebSocket support (enabled by default)

Resources

• AT Protocol Documentation
• Bluesky API Docs
• Firehose Documentation
• Jetstream Documentation

Support & Contributing

Found a bug or have a feature request? Open an issue.

Want to contribute? We'd love your help! Check out the contribution guidelines.

Credits

• Miguel Batres - founder & lead maintainer
• All contributors

License

Signal is open-source software licensed under the MIT license.

Built for the Federation • By Social Dept.