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.5.0(2w ago)01331MITPHPPHP >=8.3

Since Nov 30Pushed 2w 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 today

READMEChangelog (6)Dependencies (65)Versions (10)Used By (1)

README (Root of the Project)
============================

[](#readme-root-of-the-project)

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

[](#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--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). Set `BIRD_FLOCK_DB_CONNECTION` to store package tables on a non-default Laravel connection.
- 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.
- LabsMobile HTTP/POST API available as SMS provider implementation.
- SendGrid (`sendgrid/sendgrid`) available as email provider implementation.
- Mailgun (`mailgun/mailgun-php`) available as email provider implementation.

Config-Driven Senders
---------------------

[](#config-driven-senders)

Bird Flock resolves outbound senders from `config/bird-flock.php`. Each channel has a `senders`map keyed by vendor id; that key is used for routing, logs, health checks, and circuit labels.

Simple external sender:

```
'channels' => [
    'sms' => [
        'strategy' => 'round_robin',
        'retry' => [
            'max_attempts' => env('BIRD_FLOCK_SMS_MAX_ATTEMPTS', 3),
            'base_delay_ms' => env('BIRD_FLOCK_SMS_BASE_DELAY_MS', 1000),
            'max_delay_ms' => env('BIRD_FLOCK_SMS_MAX_DELAY_MS', 60000),
        ],
        'senders' => [
            'acme' => App\Messaging\AcmeSmsSender::class,
        ],
    ],
],
```

Typed constructor dependencies are resolved through the Laravel container. For constructor scalars or package-specific validation, use a sender definition class:

```
'acme' => App\Messaging\AcmeSmsSenderDefinition::class
```

Definition classes implement `Equidna\BirdFlock\Contracts\SenderDefinitionInterface` and return the sender class, constructor arguments, and optional config validator. Argument values prefixed with `config:` are read from Laravel config; raw values are passed as-is.

Definitions can also implement `Equidna\BirdFlock\Contracts\SenderConfigValidatorInterface`; in that case `validator()` can return `self::class` so metadata and config validation stay together.

`strategy` controls which sender key is selected when a channel has multiple senders. The default is `round_robin`, which rotates through the configured sender keys in order using Laravel cache. `random` selects one configured sender with `random_int`. Any other value fails configuration at runtime with an `InvalidArgumentException`.

For complex SDK construction, bind the SDK or sender in the host app and keep the same config shape:

```
$this->app->singleton(App\Messaging\AcmeClient::class, function () {
    return new App\Messaging\AcmeClient(config('services.acme.api_key'));
});
```

External sender classes must implement `Equidna\BirdFlock\Contracts\MessageSenderInterface`. External webhooks remain the host app's responsibility.

Quick Start (High-Level)
------------------------

[](#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
-------------------

[](#documentation-index)

- [Deployment Instructions](doc/deployment-instructions.md)
- [API Documentation](doc/api-documentation.md)
- [Routes Documentation](doc/routes-documentation.md)
- [Artisan Commands](doc/artisan-commands.md)
- [Tests Documentation](doc/tests-documentation.md)
- [Architecture Diagrams](doc/architecture-diagrams.md)
- [Monitoring](doc/monitoring.md)
- [Business Logic & Core Processes](doc/business-logic-and-core-processes.md)
- [Open Questions & Assumptions](doc/open-questions-and-assumptions.md)

Note About Standards
--------------------

[](#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.

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance96

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 67.4% 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 ~33 days

Recently: every ~45 days

Total

7

Last Release

19d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/984800?v=4)[gruelas](/maintainers/gruelas)[@gruelas](https://github.com/gruelas)

---

Top Contributors

[![gruelasjr](https://avatars.githubusercontent.com/u/40619710?v=4)](https://github.com/gruelasjr "gruelasjr (31 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 (3 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

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[laravel/pulse

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

1.7k15.1M132](/packages/laravel-pulse)[api-platform/laravel

API Platform support for Laravel

58171.8k14](/packages/api-platform-laravel)[flarum/core

Delightfully simple forum software.

201.4M2.3k](/packages/flarum-core)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)

PHPackages © 2026

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