PHPackages                             equidna/bird-flock - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. equidna/bird-flock

ActiveLibrary[Queues & Workers](/categories/queues)

equidna/bird-flock
==================

Bird Flock - messaging bus for multi-channel outbound messaging (SMS, WhatsApp, Email) with DLQ and idempotency

1.2.0(4mo ago)0104[1 PRs](https://github.com/EquidnaMX/bird-flock/pulls)1MITPHPPHP >=8.3

Since Nov 30Pushed 1mo agoCompare

[ Source](https://github.com/EquidnaMX/bird-flock)[ Packagist](https://packagist.org/packages/equidna/bird-flock)[ RSS](/packages/equidna-bird-flock/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (22)Versions (6)Used By (1)

Bird Flock — Multi-Channel Messaging Bus
========================================

[](#bird-flock--multi-channel-messaging-bus)

**Bird Flock** is a Laravel package for reliable, multi-channel outbound messaging (SMS, WhatsApp, Email) with built-in idempotency, dead-letter queue support, circuit breakers, and provider abstraction.

This documentation follows the project's Coding Standards and PHPDoc Style Guide.

---

Project Overview
----------------

[](#project-overview)

**Bird Flock** orchestrates outbound message delivery across multiple channels and providers:

- **SMS**: Twilio, Vonage (Nexmo)
- **WhatsApp**: Twilio
- **Email**: SendGrid, Mailgun

### Key Features

[](#key-features)

- **Idempotency**: Prevent duplicate sends via configurable idempotency keys
- **Dead-Letter Queue (DLQ)**: Capture and replay failed messages
- **Circuit Breakers**: Automatically suspend failing providers
- **Queue-Based**: Asynchronous delivery with configurable retry policies
- **Webhook Handlers**: Process delivery receipts and status updates from providers
- **Multi-Provider Support**: Seamlessly switch or extend providers
- **Rate Limiting**: Built-in webhook rate limiting
- **Monitoring**: Health checks and circuit breaker status endpoints

### Primary Use Cases

[](#primary-use-cases)

- Transactional notifications (OTPs, receipts, alerts)
- Marketing campaigns (scheduled bulk sends)
- Multi-channel user engagement
- Reliable messaging with automatic retries and failure tracking

---

Project Type & Tech Summary
-------------------------------

[](#project-type--tech-summary)

**Type**: Laravel Package (Library)

**Tech Stack**:

- **PHP**: 8.3+
- **Laravel Framework**: 10.x–12.x (supports Illuminate components 10.x–12.x)
- **Database**: MySQL, PostgreSQL, SQLite (Eloquent-based; driver-agnostic)
- **Cache**: Any Laravel-supported driver (Redis, Memcached, File, etc.)
- **Queue**: Any Laravel queue driver (Redis, Database, SQS, Beanstalkd, etc.)
- **External Services**:
    - Twilio SDK (`twilio/sdk ^6.0`)
    - SendGrid (`sendgrid/sendgrid ^7.0`)
    - Vonage Client (`vonage/client ^4.2`)
    - Mailgun PHP (`mailgun/mailgun-php ^4.3`)
    - Guzzle HTTP (`guzzlehttp/guzzle ^7.0`)

---

Quick Start
-----------

[](#quick-start)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require equidna/bird-flock
```

### 2. Publish Configuration and Migrations

[](#2-publish-configuration-and-migrations)

```
php artisan vendor:publish --tag=bird-flock-config
php artisan vendor:publish --tag=bird-flock-migrations
```

### 3. Run Migrations

[](#3-run-migrations)

```
php artisan migrate
```

### 4. Configure Environment

[](#4-configure-environment)

Add provider credentials to `.env`:

```
# Twilio (SMS & WhatsApp)
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_FROM_SMS=+1234567890
TWILIO_FROM_WHATSAPP=whatsapp:+1234567890

# SendGrid (Email)
SENDGRID_API_KEY=your_api_key
SENDGRID_FROM_EMAIL=noreply@example.com
SENDGRID_FROM_NAME="Example App"

# Vonage (SMS)
VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_FROM_SMS=YourBrand

# Mailgun (Email)
MAILGUN_API_KEY=your_api_key
MAILGUN_DOMAIN=mg.example.com
MAILGUN_FROM_EMAIL=noreply@example.com
```

### 5. Start Queue Worker

[](#5-start-queue-worker)

```
php artisan queue:work --queue=default
```

### 6. Dispatch Your First Message

[](#6-dispatch-your-first-message)

#### Option A: Using FlightPlan (Direct Message)

[](#option-a-using-flightplan-direct-message)

```
use Equidna\BirdFlock\BirdFlock;
use Equidna\BirdFlock\DTO\FlightPlan;

$plan = new FlightPlan(
    channel: 'sms',
    to: '+1234567890',
    text: 'Hello from Bird Flock!',
    idempotencyKey: 'user:123:welcome-sms'
);

$messageId = BirdFlock::dispatch($plan);
```

#### Option B: Using Laravel Mailables (Email)

[](#option-b-using-laravel-mailables-email)

```
use Equidna\BirdFlock\BirdFlock;
use App\Mail\WelcomeEmail;

// Create your Laravel Mailable as usual
$mailable = new WelcomeEmail($user);

// Dispatch it through Bird Flock
$messageId = BirdFlock::dispatchMailable(
    mailable: $mailable,
    to: 'user@example.com',
    idempotencyKey: 'user:123:welcome-email'
);
```

**Benefits of using Mailables:**

- Use familiar Laravel Mailable classes
- Leverage Blade templates and view rendering
- Automatic HTML-to-text conversion
- Support for attachments
- Full idempotency and retry logic
- Dead-letter queue support

### 7. Monitor Health Status

[](#7-monitor-health-status)

**For Centralized Dashboards**:

```
use Equidna\BirdFlock\Services\HealthService;

class DashboardController extends Controller
{
    public function __construct(private HealthService $healthService)
    {
    }

    public function index()
    {
        // Get complete health status
        $health = $this->healthService->getHealthStatus();

        // Check if system is healthy
        if ($health['status'] !== 'healthy') {
            // Alert on degraded status
        }

        return view('dashboard', compact('health'));
    }
}
```

**Or via HTTP endpoint**:

```
curl https://yourdomain.com/bird-flock/health
```

See the [Health API Integration Guide](doc/health-api-integration.md) for complete dashboard integration examples.

---

Documentation Index
-------------------

[](#documentation-index)

Detailed guides and references:

- **[Deployment Instructions](doc/deployment-instructions.md)**
    Environment setup, system requirements, configuration, deployment workflows
- **[API Documentation](doc/api-documentation.md)**
    Public HTTP API endpoints, request/response formats
- **[Routes Documentation](doc/routes-documentation.md)**
    All HTTP routes (webhooks, health checks), middleware, and route registration
- **[Artisan Commands](doc/artisan-commands.md)**
    Custom CLI commands for testing, dead-letter management, and config validation
- **[Tests Documentation](doc/tests-documentation.md)**
    Test suite structure, how to run tests, coverage overview
- **[Architecture Diagrams](doc/architecture-diagrams.md)**
    System context, container, and component diagrams (Mermaid)
- **[Monitoring](doc/monitoring.md)**
    Logging, metrics, health checks, troubleshooting, recommended alerts
- **[Health API Integration](doc/health-api-integration.md)**
    Guide for integrating Bird Flock health monitoring into centralized dashboards
- **[Business Logic & Core Processes](doc/business-logic-and-core-processes.md)**
    Message dispatch flow, idempotency, retry logic, dead-letter handling, webhook processing
- **[Open Questions & Assumptions](doc/open-questions-and-assumptions.md)**
    Unresolved items and clarifications needed from maintainers

---

License
-------

[](#license)

MIT License. See `LICENSE` file for details.

---

Author
------

[](#author)

**Gabriel Ruelas** —

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance83

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 58.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

3

Last Release

147d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/21aa1f99daa17783331e507c7fa7ffd1fb5d9e93450069209d2c43e6d5c8ca1a?d=identicon)[gruelas](/maintainers/gruelas)

---

Top Contributors

[![gruelasjr](https://avatars.githubusercontent.com/u/40619710?v=4)](https://github.com/gruelasjr "gruelasjr (20 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (12 commits)")[![Chenminsuyi](https://avatars.githubusercontent.com/u/104664610?v=4)](https://github.com/Chenminsuyi "Chenminsuyi (2 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/equidna-bird-flock/health.svg)

```
[![Health](https://phpackages.com/badges/equidna-bird-flock/health.svg)](https://phpackages.com/packages/equidna-bird-flock)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[psalm/plugin-laravel

Psalm plugin for Laravel

3274.9M308](/packages/psalm-plugin-laravel)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[laravel-zero/framework

The Laravel Zero Framework.

3371.4M369](/packages/laravel-zero-framework)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)