Push Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cmnty/push-bundle
   

   Add to AppKernel.php (Symfony 2/3):

   new Cmnty\PushBundle\CmntyPushBundle(),
   

2. Basic Configuration (config/packages/cmnty_push.yaml):

   cmnty_push:
       push_services:
           google:
               enabled: true
               api_key: "%env(GCM_API_KEY)%"
   

3. First Use Case: Inject the Cmnty\PushBundle\Service\PushService and send a notification:

   use Cmnty\PushBundle\Service\PushService;
   
   class MyController {
       public function __construct(private PushService $pushService) {}
   
       public function sendNotification() {
           $notification = new \Cmnty\Push\Notification('Hello World!');
           $endPoint = new \Cmnty\Push\EndPoint('device_token_here');
           $this->pushService->send($endPoint, $notification);
       }
   }
   

Implementation Patterns

Core Workflows

1. Service Integration:

   • Use dependency injection to access PushService in controllers/services.
   • Configure multiple push services (Google, Mozilla) in cmnty_push.push_services.

2. Subscription Management:

   • Store subscriptions in Doctrine via the provided PushSubscription embeddable:

     doctrine:
         orm:
             mappings:
                 PushSubscription: { type: xml, dir: "%kernel.root_dir%/../vendor/cmnty/push-bundle/src/Resources/config/embeddable" }
     

   • Example entity:

     use Cmnty\Push\EndPoint;
     use Doctrine\ORM\Mapping as ORM;
     
     #[ORM\Entity]
     class UserDevice {
         #[ORM\Embedded(class: 'Cmnty\Push\EndPoint')]
         private $endPoint;
     }
     

3. Batch Sending:

   • Loop through subscriptions and send notifications:

     foreach ($userDevices as $device) {
         $this->pushService->send($device->getEndPoint(), $notification);
     }
     

4. Custom Notifications:

   • Extend \Cmnty\Push\Notification for payload customization:

     class CustomNotification extends Notification {
         public function __construct(string $message, array $customData) {
             parent::__construct($message);
             $this->setData($customData);
         }
     }
     

Integration Tips

• Environment Variables: Store API keys in .env (e.g., GCM_API_KEY).
• Error Handling: Wrap send() calls in try-catch to handle failed deliveries:

  try {
      $this->pushService->send($endPoint, $notification);
  } catch (\Cmnty\Push\Exception\PushException $e) {
      // Log or retry logic
  }
  

• Testing: Use mock services in PHPUnit to avoid hitting real push APIs.

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • Last release in 2016—assume no active maintenance. Use at your own risk.
   • Consider alternatives like symfony/push-notification for modern projects.

2. Doctrine Mapping Issues:

   • The binary_string DBAL type may cause conflicts with existing projects. Test thoroughly.
   • Ensure PushSubscription mappings are correctly referenced in config/packages/doctrine.yaml.

3. Configuration Quirks:

   • enabled: true is not auto-set if api_key is missing. Explicitly configure required services.
   • Mozilla service defaults to enabled: true—disable if unused to avoid unnecessary overhead.

4. Crypto Dependencies:

   • The underlying cmnty/push library relies on openssl. Ensure your server has OpenSSL support.

Debugging Tips

• Logs: Enable debug mode to inspect failed push attempts:

  monolog:
      handlers:
          main:
              level: debug
  

• Payload Validation: Use tools like GCM HTTP API Validator to verify payloads.
• Token Management: Invalid device tokens cause silent failures. Implement token refresh logic or validation.

Extension Points

1. Custom Push Services:

   • Extend \Cmnty\PushBundle\Service\PushService to add new providers (e.g., Firebase):

     class FirebasePushService extends PushService {
         protected function getProvider(): \Cmnty\Push\Provider\ProviderInterface {
             return new \Cmnty\Push\Provider\FirebaseProvider($this->apiKey);
         }
     }
     

   • Register the service in services.yaml:

     services:
         App\Service\FirebasePushService:
             arguments: ['%env(FIREBASE_API_KEY)%']
             tags: ['cmnty_push.service']
     

2. Event Listeners:

   • Listen for push events (e.g., cmnty_push.send) to log or analyze deliveries:

     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class PushEventSubscriber implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 'cmnty_push.send' => 'onPushSent',
             ];
         }
     
         public function onPushSent(\Cmnty\PushBundle\Event\PushEvent $event) {
             // Custom logic
         }
     }
     

3. Fallback Mechanisms:

   • Implement retry logic for failed pushes using Symfony’s Messenger component:

     $this->messenger->dispatch(new RetryPushMessage($endPoint, $notification));