equidna/bird-flock

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

V1.3.0 2026-06-05 17:29 UTC

Requires

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

Requires (Dev)

• illuminate/database: ^10 || ^11 || ^12 || ^13
• 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

Project Overview

Bird Flock is a Laravel package for outbound multi-channel messaging with queue-first delivery, idempotency, retries, dead-letter handling, provider webhooks, and health endpoints.

Primary audience:

• Internal development teams integrating reliable messaging into Laravel applications.
• Maintainers and contributors extending providers, routing, and operational tooling.

Main value:

• One API (Equidna\BirdFlock\BirdFlock) to dispatch SMS, WhatsApp, and email workloads.
• Operational safety via idempotency keys, retry policies, and dead-letter replay commands.
• Visibility via events, structured logs, and health/circuit-breaker diagnostics.

Project Type & Tech Summary

Project type:

• Laravel package/library (composer.json has "type": "library").

Version/runtime summary:

• PHP: >=8.3.
• Laravel/Illuminate: ^10 || ^11 || ^12 || ^13.

Infrastructure model:

• Database: package uses Eloquent models and migrations; supported by host Laravel DB driver (commonly MySQL/PostgreSQL/SQLite).
• Cache: package uses Laravel cache for circuit-breaker state.
• Queue: package dispatches Laravel queue jobs; host queue driver is used.

External integrations:

• Twilio (twilio/sdk) for SMS and WhatsApp senders.
• Vonage (vonage/client) available as SMS provider implementation.
• SendGrid (sendgrid/sendgrid) available as email provider implementation.
• Mailgun (mailgun/mailgun-php) available as email provider implementation.

Quick Start (High-Level)

1. Install the package in your host Laravel app:
   • composer require equidna/bird-flock
2. Publish package assets:
   • php artisan vendor:publish --tag=bird-flock-config
   • php artisan vendor:publish --tag=bird-flock-migrations
3. Configure provider credentials and package settings in .env.
4. Validate configuration:
   • php artisan bird-flock:config:validate
5. Run migrations:
   • php artisan migrate
6. Start queue workers for the target queue:
   • php artisan queue:work --queue=default
7. Dispatch messages via BirdFlock::dispatch(), BirdFlock::dispatchBatch(), or BirdFlock::dispatchMailable().

Detailed deployment and operations guidance is in doc/deployment-instructions.md.

Documentation Index

• Deployment Instructions
• API Documentation
• Routes Documentation
• Artisan Commands
• Tests Documentation
• Architecture Diagrams
• Monitoring
• Business Logic & Core Processes
• Open Questions & Assumptions

Note About Standards

This documentation follows the project's Coding Standards Guide and PHPDoc Style Guide. Where guide files are not visible in this repository snapshot, naming and examples were aligned to the existing package code style and namespace conventions.