Push Notification Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony2 Bundle for OneSignal: The package is a Symfony2-specific bundle, which may introduce tight coupling with legacy Symfony2 architecture. If the project is Laravel-based, direct integration is not feasible without significant abstraction or middleware layers.
• Push Notification Abstraction: The core functionality (OneSignal API integration) is reusable, but the Symfony2 bundle structure is not Laravel-compatible. A wrapper or facade would be needed to abstract the OneSignal logic.
• Web Push SDK: The Twig-based SDK injection (dmytrof_push_notification_web_sdk()) is Symfony2-specific and would require replacement with Laravel Blade directives or JavaScript asset management.

Integration Feasibility

• OneSignal PHP SDK Dependency: The bundle relies on norkunas/onesignal-php-api (v1.0.x-dev), which is abandoned (last commit ~2017). This introduces compatibility risks with modern OneSignal APIs.
• Configuration Overhead: The bundle enforces Symfony2 YAML/configuration, which Laravel (using .env + config/) would need to map manually (e.g., via service providers).
• No Laravel-Specific Features: Lacks queue support, event listeners, or Laravel’s service container integration, requiring custom implementation.

Technical Risk

• Deprecated Dependencies: norkunas/onesignal-php-api may break with OneSignal’s API changes. A modern alternative (e.g., onesignal/onesignal-php-sdk) should be evaluated.
• Symfony2 Lock-in: The bundle’s Twig integration and kernel registration are non-portable. Rewriting for Laravel would require significant effort.
• No Active Maintenance: Last release in 2017 suggests security/bug risks. A custom wrapper would need to handle updates.
• Missing Documentation: Poor README and no tests increase implementation uncertainty.

Key Questions

1. Is OneSignal the only provider needed? If so, should we replace the bundle entirely with a Laravel-compatible OneSignal SDK (e.g., a custom service)?
2. What’s the push notification scale? If high-volume, queue-based sending (Laravel Queues) should be designed upfront.
3. Do we need web push SDK injection? If yes, how will we replace Twig with Blade or a JavaScript asset pipeline?
4. What’s the migration path for existing Symfony2 configs? Will we rewrite configs or build a compatibility layer?
5. Are there alternatives? Should we evaluate Firebase Cloud Messaging (FCM) or native Laravel packages like spatie/laravel-onesignal?

Integration Approach

Stack Fit

• Laravel Compatibility: The bundle is incompatible with Laravel’s architecture. A custom service provider or facade is required to wrap OneSignal logic.
• Recommended Stack:
  • Service Provider: Register OneSignal client (using a modern SDK like onesignal/onesignal-php-sdk).
  • Config Files: Replace YAML with Laravel’s .env + config/onesignal.php.
  • Queue Jobs: Use Laravel Queues for asynchronous push sending.
  • Blade Directives: Replace Twig with Blade for SDK injection (or use Laravel Mix for JS assets).
  • Event System: Leverage Laravel Events for notification triggers (e.g., NotificationSent).

Migration Path

1. Phase 1: Dependency Replacement
   • Drop dmytrof/push-notification-bundle and norkunas/onesignal-php-api.
   • Install a modern OneSignal SDK (e.g., onesignal/onesignal-php-sdk or a custom wrapper).
2. Phase 2: Laravel Service Integration
   • Create a Laravel Service Provider (AppServiceProvider or dedicated) to bind OneSignal client.
   • Example:

     $this->app->singleton(OneSignal::class, function ($app) {
         return new OneSignal(config('onesignal.app_id'), config('onesignal.auth_key'));
     });
     

3. Phase 3: Configuration Migration
   • Move OneSignal keys to .env:

     ONESIGNAL_APP_ID=...
     ONESIGNAL_AUTH_KEY=...
     

   • Define config/onesignal.php:

     return [
         'app_id' => env('ONESIGNAL_APP_ID'),
         'auth_key' => env('ONESIGNAL_AUTH_KEY'),
         'safari_web_id' => env('ONESIGNAL_SAFARI_WEB_ID', null),
     ];
     

4. Phase 4: Feature Replacement
   • Tagging: Replace addTag() with a Laravel service method or direct OneSignal API call.
   • Web SDK: Use Laravel Mix to inject OneSignal JS SDK or create a Blade component.
5. Phase 5: Testing & Deprecation
   • Write Pest/PHPUnit tests for the new service.
   • Deprecate old Symfony2 bundle references.

Compatibility

• OneSignal API Changes: The new SDK must handle rate limits, payload validation, and error responses.
• Laravel Version Support: Ensure compatibility with Laravel 10.x/11.x (if using newer features like enums, attributes).
• Database Storage: If storing push tokens/user data, use Laravel’s Eloquent or database migrations.

Sequencing

Operational Impact

Maintenance

• Reduced Vendor Lock-in: A custom service is easier to maintain than a deprecated Symfony2 bundle.
• Update Strategy:
  • OneSignal SDK: Monitor for breaking changes; update via Composer.
  • Laravel: Leverage Laravel’s dependency management for core updates.
• Logging & Monitoring:
  • Add Laravel Log integration for push failures.
  • Use Laravel Horizon (if using queues) to monitor job status.

Support

• Debugging:
  • OneSignal API errors can be logged with context (e.g., user ID, payload).
  • Queue failures should trigger Slack/email alerts (Laravel Notifications).
• Documentation:
  • Update internal docs with Laravel-specific usage (e.g., OneSignal::send() examples).
  • Add Swagger/OpenAPI docs if exposing an API.
• Support Team Training:
  • Train devs on Laravel service containers, queues, and OneSignal API limits.

Scaling

• Horizontal Scaling:
  • Queue-based sends (Laravel Queues + Redis/SQS) allow distributed processing.
  • Rate limiting: Implement exponential backoff for API retries.
• Performance:
  • Batch sends: Use OneSignal’s batch API to reduce calls.
  • Caching: Cache frequently used player IDs/tags (if applicable).
• Database:
  • Index push-related tables (e.g., users with push_token column).
  • Partition large user tables if storing metadata.

Failure Modes

Ramp-Up

• Onboarding New Devs:
  • Provide a Laravel-specific cheat sheet (e.g., "How to send a push notification").
  • Include example commands (e.g., php artisan push:send --user=123).
• CI/CD Impact:
  • Add tests for push logic to the pipeline.
  • Deploy SDK updates via Composer (no manual steps).
• Training Materials:
  • Video demo of sending a push notification in