nkamuo/notification-tracker-bundle

[EXPERIMENTAL] Notification and email tracking bundle for Symfony with webhook support - DO NOT USE IN PRODUCTION

v0.11.1 2025-09-22 21:24 UTC

Requires

• php: >=8.2
• api-platform/core: ^4.2
• doctrine/doctrine-bundle: ^2.11
• doctrine/orm: ^2.11|^3.0
• symfony/cache: ^7.3
• symfony/framework-bundle: ^7.3
• symfony/mailer: ^7.3
• symfony/messenger: ^7.3
• symfony/notifier: ^7.3
• symfony/orm-pack: ^2.4
• symfony/property-access: ^7.3
• symfony/property-info: ^7.3
• symfony/serializer: ^7.3
• symfony/twig-bundle: ^7.3
• symfony/uid: ^7.3
• symfony/validator: ^7.3
• symfony/webhook: ^7.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.48
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.5
• symfony/browser-kit: ^7.3
• symfony/css-selector: ^7.3
• symfony/debug-bundle: ^7.3
• symfony/maker-bundle: ^1.52
• symfony/phpunit-bridge: ^7.3
• symfony/test-pack: ^1.0
• symfony/yaml: ^7.3

MIT

• nkamuo

• mailer
• symfony
• email
• bundle
• notification
• notifier
• webhook
• tracking

README

⚠️ EXPERIMENTAL - This project is in active development and should not be used in production environments. APIs and features may change without notice.

Automatically track and analyze all emails and notifications sent through Symfony Mailer and Notifier components.

🎯 What This Bundle Does

This bundle automatically captures and tracks notifications sent through:

• ✅ Symfony Mailer - All emails sent via $mailer->send()
• ✅ Symfony Notifier - All notifications sent via $notifier->send()
• ✅ Manual API - Custom notifications via REST API

No code changes required! Just install, configure, and start tracking.

🚀 Quick Start

1. Install: composer require nkamuo/notification-tracker-bundle
2. Configure: Add to bundles.php
3. Migrate: Run doctrine:migrations:migrate
4. Use: Send emails/notifications as normal - they're automatically tracked!

📚 Documentation

👉 START HERE: Complete Documentation

Essential Links

• 📖 Main Guide - Complete setup and usage
• 🌐 API Reference - REST API documentation
• 🔍 Custom Filters - Advanced API filtering
• ⚠️ Experimental Notice - Important warnings

🧪 Experimental Status

This is an experimental project - use at your own risk:

• ✅ Core tracking functionality works
• ⚠️ APIs may change without notice
• 🚧 Active development in progress
• 🔬 Suitable for testing and evaluation only

🎯 Key Features

• 📧 Multi-channel Support: Email, SMS, Slack, Telegram, Push notifications
• 🔄 Native Symfony Integration: Works seamlessly with Symfony Mailer and Notifier events
• 📊 Complete Tracking: Track sent, delivered, opened, clicked, bounced, and failed messages
• 🔗 Webhook Support: Integrate with SendGrid, Twilio, Mailgun, and more
• 🚀 Async Processing: Built-in Symfony Messenger support
• 🔍 API Platform Integration: Rich REST API for browsing and managing notifications
• 📈 Real-time Analytics: Performance metrics and engagement statistics
• ⚙️ Highly Configurable: Environment-based configuration with sensible defaults

💻 Installation

composer require nkamuo/notification-tracker-bundle

Register the Bundle

If not using Symfony Flex, register the bundle in config/bundles.php:

return [
    // ...
    Nkamuo\NotificationTrackerBundle\NotificationTrackerBundle::class => ['all' => true],
];

Run Migrations

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

⚙️ Basic Configuration

Create config/packages/notification_tracker.yaml:

notification_tracker:
    enabled: true
    tracking:
        enabled: true
        track_opens: true
        track_clicks: true

📊 Usage Examples

Automatic Tracking

The bundle automatically tracks all emails and notifications sent through Symfony's components:

// Emails are automatically tracked
$email = (new Email())
    ->from('[e-mail]')
    ->to('[e-mail]')
    ->subject('Time for Symfony Mailer!')
    ->html('<p>See Twig integration for better HTML integration!</p>');

$mailer->send($email);

API Access

Browse and manage notifications via API Platform:

# List tracked messages
GET /api/notification-tracker/messages

# Get message details  
GET /api/notification-tracker/messages/{id}

# Retry failed message
POST /api/notification-tracker/messages/{id}/retry

# View analytics
GET /api/notification-tracker/analytics

Console Commands

# Process failed messages
php bin/console notification-tracker:process-failed

# View analytics
php bin/console notification-tracker:analytics

# Clean up old messages
php bin/console notification-tracker:cleanup --days=90

🔗 Webhook Setup

Configure your webhook endpoints with your providers:

• SendGrid: https://your-domain.com/webhooks/notification-tracker/sendgrid
• Twilio: https://your-domain.com/webhooks/notification-tracker/twilio
• Mailgun: https://your-domain.com/webhooks/notification-tracker/mailgun

🧪 Testing

composer test
composer cs-fix
composer phpstan

🤝 Support

For issues and feature requests, please use the GitHub issue tracker.

📄 License

MIT

Ready to enhance your notification system with comprehensive tracking and analytics? 🚀

Check out the complete documentation to get started!