Onesignal Bundle Laravel Package

Technical Evaluation

Architecture Fit The birkof/onesignal-bundle is a Symfony bundle, not natively Laravel-compatible, but its underlying library (norkunas/onesignal-php-api) can be leveraged in Laravel via manual integration or Symfony bridge packages (e.g., symfony/bundle). Key considerations:

• Push Notifications: Fits Laravel’s real-time needs (e.g., user alerts, marketing campaigns) but requires event-driven architecture (e.g., Laravel Queues, Horizon) for scalability.
• Symfony Dependency: Laravel’s DI container is compatible with Symfony services, but bundle-specific features (e.g., config.yml) may need Laravel config file (config/onesignal.php) adapters.
• Laravel Ecosystem: Conflicts possible with Laravel’s Service Providers or Facades if the bundle assumes Symfony’s ContainerInterface.

Integration Feasibility

• Medium: The package is not Laravel-first, but its core API (norkunas/onesignal-php-api) is PHP-agnostic. Feasibility depends on:
  • Manual Wrapping: Create a Laravel Service Provider to bind the API to the container (e.g., OneSignal::api()).
  • Config Adaptation: Replace Symfony’s config.yml with Laravel’s config/onesignal.php.
  • Event Listeners: Use Laravel’s Bus or Events to trigger OneSignal notifications (e.g., user.registered → send welcome push).
• Dependencies: The bundle pulls in Symfony components (e.g., symfony/http-client). Test for conflicts with Laravel’s illuminate/http.

Technical Risk

• High:
  • Symfony Assumptions: The bundle may rely on Symfony’s Kernel, EventDispatcher, or DependencyInjection, requiring polyfills or custom implementations in Laravel.
  • PHP 8+ Only: Laravel 8.x/9.x support PHP 8, but the bundle’s v3.0.0 drops PHP 7.x. Risk: Legacy Laravel 7.x projects cannot use this without upgrading.
  • Undocumented Laravel Gaps: No examples for Laravel-specific use cases (e.g., integrating with Laravel Notifications, Queues).
• Mitigations:
  • Use norkunas/onesignal-php-api directly (skip the bundle) to avoid Symfony dependencies.
  • Test with Laravel’s HttpClient instead of Symfony’s HttpClient.

Key Questions

1. Laravel Compatibility: Does the bundle’s OneSignalBundle class extend Symfony’s Bundle in a way that’s incompatible with Laravel’s ServiceProvider?
2. Event Integration: How would you trigger OneSignal notifications from Laravel Events (e.g., auth.login) without tight coupling?
3. Queue Support: Does the bundle support Laravel Queues, or must notifications be sent synchronously (blocking requests)?
4. Testing: Are there Laravel-specific tests or examples for the underlying norkunas/onesignal-php-api library?
5. Maintenance Burden: Will the bundle’s Symfony dependencies require ongoing polyfills as Laravel evolves?

Integration Approach

Stack Fit

• Laravel 9/10: Best fit due to PHP 8+ support. Leverage Laravel’s Service Providers, Events, and Queues to integrate the bundle’s API.
• Laravel 8.x: Possible but requires PHP 8.0+ and manual adaptation of Symfony-specific code.
• Legacy Systems: Avoid if using Laravel <8.x or PHP <8.0.

Migration Path

1. Option A: Use the Bundle (Symfony) with Laravel

   • Install the bundle via Composer:

     composer require birkof/onesignal-bundle
     

   • Create a Laravel Service Provider to bridge Symfony’s OneSignalBundle:

     // app/Providers/OneSignalServiceProvider.php
     public function register()
     {
         $this->app->singleton('onesignal.api', function ($app) {
             return new \Adelplace\OneSignalBundle\Service\OneSignalApi(
                 config('onesignal.application_id'),
                 config('onesignal.auth_key')
             );
         });
     }
     

   • Replace Symfony’s config.yml with Laravel’s config/onesignal.php:

     // config/onesignal.php
     return [
         'application_id' => env('ONESIGNAL_APP_ID'),
         'auth_key' => env('ONESIGNAL_AUTH_KEY'),
     ];
     

   • Risk: Symfony-specific code (e.g., EventDispatcher) may fail.

2. Option B: Use Underlying Library Directly

   • Install the core library:

     composer require norkunas/onesignal-php-api
     

   • Create a Laravel facade or helper:

     // app/Helpers/OneSignal.php
     use Norkunas\OneSignal\OneSignal;
     
     class OneSignalHelper {
         public static function sendNotification($title, $message, $includePlayerIds = []) {
             $api = new OneSignal(
                 config('onesignal.application_id'),
                 config('onesignal.auth_key')
             );
             return $api->notifications->create($title, $message, $includePlayerIds);
         }
     }
     

   • Pros: No Symfony dependencies, full Laravel control.
   • Cons: Lose bundle-specific features (e.g., config management).

Compatibility

• Laravel Services: The bundle’s API can be bound to Laravel’s container, but Symfony-specific services (e.g., HttpClient) may need replacements.
• Environment Variables: Ensure .env keys match the bundle’s expected config (e.g., ONESIGNAL_APP_ID).
• Testing: Use Laravel’s Mockery or PHPUnit to test OneSignal interactions without hitting the real API.

Sequencing

1. Phase 1: Core Integration
   • Implement the Service Provider and config.
   • Test basic API calls (e.g., getAll(), create()).
2. Phase 2: Event-Driven Notifications
   • Attach OneSignal calls to Laravel Events (e.g., registered, password.reseted).
   • Example:

     // app/Listeners/SendWelcomePush.php
     public function handle($event) {
         OneSignalHelper::sendNotification(
             'Welcome!',
             'Thanks for registering!',
             [$event->user->device_id]
         );
     }
     

3. Phase 3: Queue-Based Scaling
   • Wrap OneSignal calls in a ShouldQueue job to avoid blocking requests.
   • Example:

     // app/Jobs/SendPushNotification.php
     public function handle() {
         $api->notifications->create($this->title, $this->message, $this->players);
     }
     

Operational Impact

Maintenance

• Pros:
  • Centralized Config: Laravel’s config/onesignal.php simplifies management vs. Symfony’s config.yml.
  • Laravel Ecosystem: Easier to debug with Laravel’s tools (e.g., telescope, laravel-debugbar).
• Cons:
  • Symfony Dependencies: If using the bundle, maintain polyfills for Symfony-specific code.
  • API Changes: The underlying norkunas/onesignal-php-api may introduce breaking changes (monitor GitHub issues).

Support

• Documentation Gaps: The bundle lacks Laravel-specific guides. Create internal docs for:
  • Service Provider setup.
  • Event-to-OneSignal mapping.
  • Queue job examples.
• Vendor Support: The bundle is unmaintained (last release 2022). Rely on the core library (norkunas/onesignal-php-api) for updates.
• Error Handling: Laravel’s exception handler may not catch OneSignal API errors. Add custom logic:

  try {
      $api->notifications->create(...);
  } catch (\Norkunas\OneSignal\Exception\OneSignalException $e) {
      Log::error("OneSignal failed: " . $e->getMessage());
      // Retry or notify admins
  }
  

Scaling

• Performance:
  • Synchronous Calls: Avoid in high-traffic routes (use Queues).
  • Batch Processing: Use OneSignal’s API batch endpoints (e.g., sendToMultiple) for bulk notifications.
• Database: No direct impact, but store device_ids in Laravel’s users table for targeting.
• Rate Limits: OneSignal’s API has limits (e.g., 1000 requests/hour). Implement exponential backoff in retries.

Failure Modes

• API Downtime: OneSignal’s service outages will block notifications. Implement:
  • Fallback Queues: Store unsent notifications in failed_jobs table.
  • Retry Logic: Use Laravel’s retryAfter() in jobs.
• Configuration Errors: Invalid application_id/auth_key will fail silently.