Push Notification Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require norkunas/onesignal-php-api:"1.0.x-dev" dmytrof/push-notification-bundle
   

2. Enable Bundle Add to app/AppKernel.php:

   new Dmytrof\PushNotificationBundle\DmytrofPushNotificationBundle(),
   

3. Configure Add to config.yml:

   dmytrof_push_notification:
       provider: one_signal
       one_signal:
           app_id: "%onesignal.app_id%"
           app_auth_key: "%onesignal.auth_key%"
   

4. First Use Case Trigger a notification in a controller:

   $this->get('dmytrof_push_notification.provider')->sendNotification(
       'Your title here',
       'Your message here',
       ['include_player_ids' => ['user_device_id_1', 'user_device_id_2']]
   );
   

Implementation Patterns

Core Workflows

1. Sending Notifications

   • Basic Notification:

     $this->get('dmytrof_push_notification.provider')->sendNotification(
         'Title',
         'Message',
         ['include_player_ids' => ['id1', 'id2']]
     );
     

   • Segmented Pushes:

     $this->get('dmytrof_push_notification.provider')->sendNotification(
         'Title',
         'Message',
         ['filter' => ['field' => 'tag', 'key' => 'user_type', 'relation' => '=', 'value' => 'premium']]
     );
     

2. Tagging Users

   • Add/Remove Tags:

     $this->get('dmytrof_push_notification.provider')->addTag('user_id_123', 'premium');
     $this->get('dmytrof_push_notification.provider')->removeTag('user_id_123', 'premium');
     

3. Web SDK Integration

   • Embed in Twig templates:

     {{ dmytrof_push_notification_web_sdk() }}
     

   • Customize with options:

     {{ dmytrof_push_notification_web_sdk({
         'appId': 'your-app-id',
         'autoRegister': false,
         'notifyButton': {
             'enable': true,
             'position': 'bottom-right'
         }
     }) }}
     

4. Event-Based Triggers

   • Use Symfony events (e.g., kernel.request) to send notifications dynamically:

     $this->get('dmytrof_push_notification.provider')->sendNotification(
         'Welcome!',
         'Thanks for signing up!',
         ['include_player_ids' => [$user->device_id]]
     );
     

Integration Tips

• User Device Tracking Store player_id (from OneSignal registration) in your user model for targeted pushes. Example:

  $user->device_id = $request->request->get('player_id');
  $user->save();
  

• Batch Processing For large user bases, use OneSignal’s segments or filters instead of looping through all player_ids.

• Fallback for Offline Users Combine with a queue system (e.g., Symfony Messenger) to retry failed notifications.

• Testing Use OneSignal’s sandbox mode (via subdomain config) to test without real devices.

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies

   • The underlying norkunas/onesignal-php-api is outdated (last updated 2017). Expect compatibility issues with newer OneSignal APIs.
   • Workaround: Extend the bundle or use the official OneSignal PHP SDK directly.

2. Configuration Overrides

   • Hardcoded provider: one_signal in the bundle means no easy switching to other providers (e.g., Firebase).
   • Tip: Override the service definition in config/services.yml if extending functionality.

3. Web SDK Limitations

   • The Twig helper dmytrof_push_notification_web_sdk() lacks flexibility for custom OneSignal SDK options.
   • Fix: Manually include the SDK script and initialize it via JavaScript.

4. Rate Limits

   • OneSignal imposes rate limits. Batch requests to avoid hitting them.
   • Tip: Use sendNotification() with include_player_ids for small groups; use filter for larger segments.

5. Safari Web Push Quirks

   • Safari requires safari_web_id and additional setup. Test thoroughly on Safari devices.

Debugging

1. Enable Logging Add to config.yml:

   dmytrof_push_notification:
       debug: true
   

   Logs will appear in app/logs/dev.log.

2. Validate API Responses OneSignal returns JSON responses. Inspect the raw output for errors:

   $response = $this->get('dmytrof_push_notification.provider')->sendNotification(...);
   $data = json_decode($response->getContent(), true);
   if (isset($data->errors)) {
       // Handle errors
   }
   

3. Check Player IDs

   • Ensure player_id values are correct (e.g., not null or malformed). Use OneSignal’s dashboard to verify.

Extension Points

1. Custom Providers Override the Dmytrof\PushNotificationBundle\Provider\OneSignalProvider to support other services (e.g., Firebase):

   # config/services.yml
   dmytrof_push_notification.provider:
       class: AppBundle\Service\CustomPushProvider
       arguments: ['@service_container']
   

2. Event Listeners Extend functionality by listening to bundle events (if documented) or hooking into Symfony’s kernel.response event.

3. Twig Extensions Override the dmytrof_push_notification_web_sdk() helper for advanced customization:

   {% macro customWebSdk(options) %}
       <script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async></script>
       <script>
           OneSignal.init({{ options|raw }});
       </script>
   {% endmacro %}
   

4. Queue Notifications Integrate with Symfony Messenger to defer notifications:

   $message = new PushNotificationMessage(
       'Title',
       'Message',
       ['include_player_ids' => [$user->device_id]]
   );
   $this->get('messenger.default_bus')->dispatch($message);