Skip to content

Release v1.0.0 - Phoenix

Choose a tag to compare

View all tags
@gruelasjr gruelasjr released this 30 Nov 21:17
· 40 commits to main since this release
v1.0.0
26ed827

🎉 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! 🚀

Assets 2
Loading