equidna/bird-flock

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

1.0.0 2025-11-30 21:03 UTC

Requires

• php: >=8.3
• guzzlehttp/guzzle: ^7.0
• illuminate/config: ^10 || ^11 || ^12
• illuminate/events: ^10 || ^11 || ^12
• illuminate/http: ^10 || ^11 || ^12
• illuminate/queue: ^10 || ^11 || ^12
• illuminate/routing: ^10 || ^11 || ^12
• illuminate/support: ^10 || ^11 || ^12
• laravel/framework: ^11.0
• mailgun/mailgun-php: ^4.3
• psr/log: 3.0
• sendgrid/sendgrid: ^7.0
• symfony/uid: ^7.0
• twilio/sdk: ^6.0
• vonage/client: ^4.2

Requires (Dev)

• illuminate/database: ^11.0
• phpstan/extension-installer: ^1.3
• phpstan/phpstan: ^1.10
• phpstan/phpstan-phpunit: ^1.3
• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^4.0

MIT

• Gabriel Ruelas

README

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

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

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

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

• 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

Type: Laravel Package (Library)

Tech Stack:

• PHP: 8.3+
• Laravel Framework: 11.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

1. Install via Composer

composer require equidna/bird-flock

2. Publish Configuration and Migrations

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

3. Run Migrations

php artisan migrate

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=[phone]
TWILIO_FROM_WHATSAPP=whatsapp:[phone]

# SendGrid (Email)
SENDGRID_API_KEY=your_api_key
SENDGRID_FROM_EMAIL=[e-mail]
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=[e-mail]

5. Start Queue Worker

php artisan queue:work --queue=default

6. Dispatch Your First Message

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

$plan = new FlightPlan(
    channel: 'sms',
    to: '[phone]',
    body: 'Hello from Bird Flock!',
    idempotencyKey: 'user:123:welcome-sms'
);

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

Documentation Index

Detailed guides and references:

• Deployment Instructions
  Environment setup, system requirements, configuration, deployment workflows

• API Documentation
  Public HTTP API endpoints, request/response formats

• Routes Documentation
  All HTTP routes (webhooks, health checks), middleware, and route registration

• Artisan Commands
  Custom CLI commands for testing, dead-letter management, and config validation

• Tests Documentation
  Test suite structure, how to run tests, coverage overview

• Architecture Diagrams
  System context, container, and component diagrams (Mermaid)

• Monitoring
  Logging, metrics, health checks, troubleshooting, recommended alerts

• Business Logic & Core Processes
  Message dispatch flow, idempotency, retry logic, dead-letter handling, webhook processing

• Open Questions & Assumptions
  Unresolved items and clarifications needed from maintainers

License

MIT License. See LICENSE file for details.

Author

Gabriel Ruelas — [e-mail]