Skip to content

Releases: EquidnaMX/bird-flock

Release v1.4.0 "Hawk"

16 Jun 03:48
@gruelasjr gruelasjr
1.4.0
fb1d0d7
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Release v1.4.0 "Hawk" Latest
Latest

Bird Flock v1.4.0 introduces a flexible, vendor-agnostic sender architecture with support for multiple SMS and email providers per channel, plus a brand-new LabsMobile integration.

Release Date: 2026-06-15
Codename: Hawk
Version: 1.4.0

Highlights

  • 🔀 Multi-vendor routing: Configure multiple senders per channel (SMS, email) with automatic selection via round-robin or random strategies.
  • 📦 Modular vendor configs: Per-vendor config files make it easy to enable/disable providers and switch routing strategies.
  • 🚀 LabsMobile SMS: New LabsMobile provider with full webhook support and HTTP client integration.
  • 🏗️ Better organization: Senders reorganized by vendor with cleaner contracts and definitions.
  • 🔧 SenderDefinitionInterface: Custom vendor definitions can now validate configuration and construct senders with type safety.
  • 🎯 Backward compatible: Existing single-vendor setups continue to work unchanged.

Major Features

Vendor-Based Sender Configuration

Define multiple senders per channel in config/bird-flock.php:

'channels' => [
    'sms' => [
        'strategy' => 'round_robin',  // or 'random'
        'senders' => [
            'twilio' => \Equidna\BirdFlock\Senders\Twilio\TwilioSmsSenderDefinition::class,
            'vonage' => \Equidna\BirdFlock\Senders\Vonage\VonageSmsSenderDefinition::class,
            'labsmobile' => \Equidna\BirdFlock\Senders\Labsmobile\LabsmobileSmsSenderDefinition::class,
        ],
    ],
    'email' => [
        'strategy' => 'round_robin',
        'senders' => [
            'mailgun' => \Equidna\BirdFlock\Senders\Mailgun\MailgunEmailSenderDefinition::class,
            'sendgrid' => \Equidna\BirdFlock\Senders\Sendgrid\SendgridEmailSenderDefinition::class,
        ],
    ],
],

Per-Vendor Configuration Files

Each vendor now has its own config file for cleaner setup:

  • config/bird-flock-twilio.php
  • config/bird-flock-vonage.php
  • config/bird-flock-sendgrid.php
  • config/bird-flock-mailgun.php
  • config/bird-flock-labsmobile.php

Publish them with: php artisan vendor:publish --tag=bird-flock-config

LabsMobile SMS Provider

Full-featured LabsMobile integration:

  • LabsmobileSmsSender: HTTP-based SMS dispatcher
  • Webhook controller with request validation
  • Complete test coverage
  • Integrated with circuit breaker and retry logic

New Contracts

  • SenderDefinitionInterface: Enables custom vendor definitions with constructor dependency injection.
  • SenderConfigValidatorInterface: Optional validation of vendor-specific configuration at boot time.

Added

  • Vendor-based sender configuration with multiple senders per channel.
  • round_robin and random selection strategies for multi-vendor setups.
  • Per-vendor config files and centralized vendor binding in service provider.
  • LabsMobile SMS provider with full webhook integration.
  • SenderResolver service for runtime sender instantiation.
  • VendorSelector service for strategy-based vendor selection.
  • Sender-specific definitions and validators.
  • Enhanced HealthService with per-vendor circuit-breaker diagnostics.
  • MessageFactoryVendorRoutingTest and comprehensive sender/strategy tests.

Changed

  • Sender directory structure: Senders now organized into vendor folders (Senders/Twilio/, Senders/Vonage/, etc.).
  • MessageFactory: Simplified to delegate to SenderResolver for vendor-agnostic sender creation.
  • BirdFlockServiceProvider: Extended to merge vendor configs and bind vendor-specific clients.
  • ConfigValidator: Enhanced to validate channels.*.senders and sender definitions.
  • Documentation: README and deployment guides updated with vendor-based routing examples.
  • Webhook routes: Split into vendor-specific files for better isolation and maintainability.

Fixed

  • Batch FlightPlan deduplication now properly checks for existing idempotency keys before dispatch.
  • Webhook routing is cleaner and less prone to conflicts.
  • Configuration validation catches strategy misconfigurations at startup.

Security

  • No security-related changes in this release.

Compatibility

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

Migration Guide

No breaking changes — existing configurations work as-is. To adopt vendor-based routing:

  1. Publish vendor config files: php artisan vendor:publish --tag=bird-flock-config
  2. Update your channels configuration to define multiple senders (optional).
  3. Set your preferred strategy (round_robin or random).
  4. Gradual migration is supported; old and new configs can coexist.

References

Assets 2
Loading

Release v1.3.0 "Falcon"

05 Jun 17:30
@gruelasjr gruelasjr
V1.3.0
9d18388
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Release v1.3.0 "Falcon"

Bird Flock v1.3.0 focuses on platform compatibility and email rendering flexibility. This release introduces Laravel 13 support, adds inline email attachment handling for Mailgun and SendGrid flows, and refreshes core operational documentation.

Release Date: 2026-06-05
Codename: Falcon
Version: 1.3.0

Highlights

  • Official Laravel 13 compatibility while preserving Laravel 10-12 support.
  • Inline email attachment support (inline disposition + CID) in sender and mailable conversion flows.
  • Documentation refresh across deployment, API/routes, commands, architecture, monitoring, and testing guides.

Added

  • Laravel 13 support in Composer constraints.
  • Inline attachment capabilities for Mailgun and SendGrid sender payloads.
  • Embedded-asset collection support in MailableConverter for inline email rendering workflows.

Changed

  • Composer constraints expanded to allow Laravel/Illuminate 10, 11, 12, and 13.
  • Removed direct symfony/uid dependency.
  • Relaxed psr/log requirement from exact 3.0 to ^3.0.
  • Root and package docs were rewritten for implementation-aligned guidance.

Fixed

  • Attachment validation now rejects invalid dispositions and inline attachments without content_id.
  • Test support fakes were adjusted for Laravel 13 contract compatibility.

Security

  • No security-related changes in this release.

Compatibility

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

References

Loading

v1.2.0 - Condor

15 Dec 20:48
@gruelasjr gruelasjr
v1.2.0
ed1f3e0

Choose a tag to compare

View all tags
v1.2.0 - Condor

Release v1.2.0 "Condor"

Bird Flock now officially supports Laravel 12.x while remaining compatible with Laravel 10.x and 11.x. This release widens Composer constraints and updates documentation to reflect broader framework support. No breaking changes.

Release Date: December 15, 2025
Codename: Condor
Version: 1.2.0

Highlights

  • Laravel 12 compatibility
  • Composer constraints widened for laravel/framework and illuminate/database
  • README updated to state Laravel 10–12 support

Added

  • Official compatibility with Laravel 12.x.

Changed

  • Composer constraints: laravel/framework ^10 || ^11 || ^12, illuminate/database ^10 || ^11 || ^12.
  • Documentation updated for supported versions.

Reliability Features

  • Circuit Breakers: Automatic provider failure detection and fail-fast
  • Dead-Letter Queue: Capture failed messages for manual replay
  • Exponential Backoff: Intelligent retry with jitter (1s–60s)
  • Webhook Processing: Automatic status updates from provider callbacks

Developer Tools

  • 6 Artisan commands for testing and management
  • 2 health check endpoints
  • 8 webhook endpoints with rate limiting
  • Comprehensive event system for extensibility

Observability

  • PII-masked structured logging
  • Metrics collection interface
  • Circuit breaker status monitoring
  • Dead-letter queue statistics

📝 Documentation

This release includes comprehensive documentation (10+ detailed guides):

🔧 What's Included

Files Added/Updated in This Release

  • ✨ doc/mailable-usage.md — Comprehensive Mailables guide
  • ✨ doc/examples/ — Working example Mailable, templates, usage script
  • ✨ CHANGELOG.md — Updated for v1.1.0 (Albatross)
  • ✨ RELEASE_NOTES.md — This file updated for v1.1.0

Version Updates

  • ✨ composer.json — Version remains aligned to tags (update when tagging)

Recent Additions

  • ✨ Mailables conversion pipeline and dispatch API

Fixed

  • Consistency in documentation around framework versions.

Security

No changes.

Links

  • See CHANGELOG for full history: CHANGELOG.md
  • Migration guidance (breaking changes): BREAKING_CHANGES.md

🚦 Testing

Unit Test Coverage

  • ✅ Core dispatch logic and idempotency
  • ✅ Circuit breaker behavior (including concurrency tests)
  • ✅ Job processing and retry logic
  • ✅ All provider sender implementations
  • ✅ Webhook processing and signature validation
  • ✅ Support utilities (backoff, normalization, validation)

Test Framework: PHPUnit 10.x
Coverage: ~75-85%
Test Speed: < 100ms per test

Run tests:

./vendor/bin/phpunit

📦 Dependencies

Production Dependencies

  • Laravel Framework 11.x (Illuminate 10.x–12.x supported)
  • Symfony UID 7.x
  • Guzzle HTTP 7.x
  • Twilio SDK 6.x
  • SendGrid 7.x
  • Vonage Client 4.2+
  • Mailgun PHP 4.3+

Development Dependencies

  • PHPUnit 10.x
  • PHPStan 1.10+
  • PHP_CodeSniffer 4.x

🔮 Future Roadmap

See Open Questions & Assumptions for planned features:

  • Multi-tenancy support
  • Multi-provider routing and failover
  • Message cancellation for scheduled sends
  • Rate limiting per recipient
  • Idempotency key expiration policies
  • Template management system
  • GDPR/PII compliance helpers

📄 License

MIT License - See LICENSE file

👤 Author

Gabriel Ruelas
Email: gruelas@gruelas.com
Organization: Equidna

🙏 Thank You

Thank you for using Bird Flock! We're excited to see what you build with it.

For issues, questions, or contributions:

🎯 Next Steps

  1. ⭐ Star this repository
  2. 📖 Read the Deployment Instructions
  3. 🚀 Deploy to production
  4. 📊 Set up monitoring using the Monitoring Guide
  5. 🐛 Report issues or request features on GitHub

Happy Messaging! 🚀

Loading

v1.1.0 - Albatross

12 Dec 03:12
@gruelasjr gruelasjr
v1.1.0
8c0b2d2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v1.1.0 - Albatross

Release v1.1.0 - Albatross
Motivation
Introduce first-class support for Laravel Mailables to streamline email dispatch while retaining Bird Flock's reliability features (idempotency, retries, circuit breakers, DLQ).

Summary of Changes
Added BirdFlock::dispatchMailable() API
Implemented Support/MailableConverter to convert Mailables → FlightPlan
Automatic HTML→text fallback when only HTML view is provided
Attachment support (base64 encoding and metadata)
Documentation: doc/mailable-usage.md with detailed examples
Examples: doc/examples/WelcomeEmail.php, welcome.blade.php, welcome-text.blade.php, usage-example.php
Updated CHANGELOG.md with v1.1.0 (Albatross)
Updated RELEASE_NOTES.md to v1.1.0
Testing Checklist
All unit tests pass: ./vendor/bin/phpunit
Static analysis clean or acceptable: vendor/bin/phpstan analyse
Example scripts run without errors
Webhook endpoints unaffected; signatures still validated
Queue worker processes Mailables correctly
Risk / Impact
Low risk; changes are additive. Email dispatch via Mailable classes now supported alongside existing FlightPlan-based dispatch. Ensure payload size limits are respected for large attachments.
Links
CHANGELOG.md
RELEASE_NOTES.md
BREAKING_CHANGES.md (none for this release)

Loading

Release v1.0.0 - Phoenix

30 Nov 21:17
@gruelasjr gruelasjr
v1.0.0
26ed827

Choose a tag to compare

View all tags
Release v1.0.0 - Phoenix

🎉 Release v1.0.0 - "Phoenix"

First Stable Release

This is the inaugural stable release of Bird Flock, a production-ready multi-channel messaging bus for Laravel applications.

Release Date: November 30, 2025
Codename: Phoenix
Version: 1.0.0

🚀 What is Bird Flock?

Bird Flock is a comprehensive Laravel package that orchestrates reliable outbound messaging across SMS, WhatsApp, and Email channels. It provides enterprise-grade features including idempotency, circuit breakers, dead-letter queues, and automatic retry handling.

Key Highlights

✅ Multi-Channel Support: SMS (Twilio, Vonage), WhatsApp (Twilio), Email (SendGrid, Mailgun)
✅ Production-Ready: Circuit breakers, DLQ, exponential backoff, comprehensive error handling
✅ Developer-Friendly: Simple API, extensive documentation, CLI commands for testing
✅ Observable: Structured logging, metrics collection, health check endpoints
✅ Secure: Webhook signature validation, PII masking, HTTPS enforcement
✅ Well-Tested: 75-85% unit test coverage with PHPUnit 10.x

📦 Installation

composer require equidna/bird-flock
php artisan vendor:publish --tag=bird-flock-config
php artisan migrate

🎯 Core Features

Messaging Capabilities

  • Idempotency: Prevent duplicate sends with unique keys
  • Batch Dispatch: Send up to thousands of messages efficiently
  • Scheduled Delivery: Schedule messages for future delivery
  • Multi-Provider: Seamlessly switch between Twilio, SendGrid, Vonage, Mailgun

Reliability Features

  • Circuit Breakers: Automatic provider failure detection and fail-fast
  • Dead-Letter Queue: Capture failed messages for manual replay
  • Exponential Backoff: Intelligent retry with jitter (1s–60s)
  • Webhook Processing: Automatic status updates from provider callbacks

Developer Tools

  • 6 Artisan commands for testing and management
  • 2 health check endpoints
  • 8 webhook endpoints with rate limiting
  • Comprehensive event system for extensibility

Observability

  • PII-masked structured logging
  • Metrics collection interface
  • Circuit breaker status monitoring
  • Dead-letter queue statistics

📝 Documentation

This release includes comprehensive documentation (9 detailed guides):

🔧 What's Included

Files Added in This Release

  • ✨ CHANGELOG.md - Authoritative changelog (MUST be respected by all AI agents)
  • ✨ BREAKING_CHANGES.md - Breaking changes documentation and migration guides
  • ✨ RELEASE_NOTES.md - This file

Version Updates

  • ✨ composer.json - Added "version": "1.0.0"

Recent Bug Fixes (Included)

  • 🐛 Fixed DispatchMessageJob delay calculation (milliseconds → seconds conversion)
  • 💅 Complete PHPDoc standardization across 48+ files
  • 🔒 Enabled webhook signature validation by default
  • 🔒 Replaced Cache::forever() with TTL-based caching

🎨 Code Quality Improvements

PHPDoc Standardization

  • ✅ File-level DocBlocks added to all 48+ PHP files
  • ✅ Aligned all PHPDoc tags per PHPDocStyle.instructions.md
  • ✅ Added missing @throws documentation
  • ✅ Fixed constructor DocBlocks for promoted properties
  • ✅ PHPStan errors reduced from 26 → 13

Code Style

  • ✅ Consistent trailing commas in multi-line constructs
  • ✅ Anonymous class spacing normalization
  • ✅ Empty constructor body formatting fixes

🔐 Security Enhancements

  • ✅ Webhook signature validation enabled by default for all providers
  • ✅ PII masking in all log statements (phone numbers, email addresses)
  • ✅ Circuit breaker cache TTL (24 hours) to prevent cache bloat
  • ✅ Rate limiting on webhook endpoints (60 requests/min per IP)

📋 System Requirements

  • PHP: 8.3 or higher
  • Laravel: 11.x
  • Database: MySQL 5.7+, PostgreSQL 11+, or SQLite 3.26+
  • Cache: Any Laravel-supported driver (Redis recommended)
  • Queue: Any Laravel queue driver (Redis recommended)

🚦 Testing

Unit Test Coverage

  • ✅ Core dispatch logic and idempotency
  • ✅ Circuit breaker behavior (including concurrency tests)
  • ✅ Job processing and retry logic
  • ✅ All provider sender implementations
  • ✅ Webhook processing and signature validation
  • ✅ Support utilities (backoff, normalization, validation)

Test Framework: PHPUnit 10.x
Coverage: ~75-85%
Test Speed: < 100ms per test

Run tests:

./vendor/bin/phpunit

📦 Dependencies

Production Dependencies

  • Laravel Framework 11.x (Illuminate 10.x–12.x supported)
  • Symfony UID 7.x
  • Guzzle HTTP 7.x
  • Twilio SDK 6.x
  • SendGrid 7.x
  • Vonage Client 4.2+
  • Mailgun PHP 4.3+

Development Dependencies

  • PHPUnit 10.x
  • PHPStan 1.10+
  • PHP_CodeSniffer 4.x

🔮 Future Roadmap

See Open Questions & Assumptions for planned features:

  • Multi-tenancy support
  • Multi-provider routing and failover
  • Message cancellation for scheduled sends
  • Rate limiting per recipient
  • Idempotency key expiration policies
  • Template management system
  • GDPR/PII compliance helpers

📄 License

MIT License - See LICENSE file

👤 Author

Gabriel Ruelas
Email: gruelas@gruelas.com
Organization: Equidna

🙏 Thank You

Thank you for using Bird Flock! We're excited to see what you build with it.

For issues, questions, or contributions:

🎯 Next Steps

  1. ⭐ Star this repository
  2. 📖 Read the Deployment Instructions
  3. 🚀 Deploy to production
  4. 📊 Set up monitoring using the Monitoring Guide
  5. 🐛 Report issues or request features on GitHub

Happy Messaging! 🚀

Loading