## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require dabsquared/dabsquared-push-notifications-bundle

Enable the bundle in config/bundles.php:

Dabsquared\PushNotificationsBundle\DabsquaredPushNotificationsBundle::class => ['all' => true],

Configuration: Update config/packages/dabsquared_push_notifications.yaml with your API keys (GCM, APNS, etc.) and database settings.
First Use Case: Register a device via the admin interface (accessible at /admin/push_notifications/devices). Use the provided UI to:
- Add a new device (e.g., iOS/Android token).
- Assign the device to a user (via user_id field).
- Send a test notification to verify setup.
Sending a Notification: Use the admin panel (/admin/push_notifications/messages) to create a new message:
- Select target devices/users.
- Define payload (title, message, custom data).
- Click "Send" to dispatch via the configured providers (GCM/APNS).

Implementation Patterns

Core Workflows

Device Registration:
- Frontend: Capture device tokens (e.g., from FCM or APNS) via JavaScript (e.g., Firebase SDK or PushNotification plugin).
- Backend: POST to /api/push_notifications/devices with:
```
{
  "token": "device_token_here",
  "user_id": 123,
  "platform": "ios" // or "android", "blackberry", "safari"
}
```
- Validation: Ensure tokens are unique and platform-specific.

Sending Notifications:

Admin UI: Use the built-in dashboard to craft and send messages.

Programmatic API:

use Dabsquared\PushNotificationsBundle\Manager\PushNotificationManager;

$manager = $this->get('dabsquared_push_notifications.manager');
$message = $manager->createMessage();
$message->setTitle('Hello!');
$message->setMessage('Check this out!');
$message->addDevice($deviceEntity); // or addUser($userEntity)
$manager->send($message);

Bulk Sending: Target users/devices via:

$message->addUser($user); // Sends to all devices linked to the user
$message->addDevice($device); // Sends to a specific device

Payload Customization:

Extend the Message entity to include custom data:

$message->setData(['key' => 'value']); // Passed to the device as-is

For Android (GCM), use:

$message->setAndroidData(['sound' => 'default', 'priority' => 'high']);

For iOS (APNS), use:

$message->setIosData(['badge' => 1, 'sound' => 'default']);

Event Listeners:

Hook into notification lifecycle via Symfony events:

# config/services.yaml
Dabsquared\PushNotificationsBundle\EventListener\PushNotificationListener:
  tags:
    - { name: kernel.event_listener, event: dabsquared.push_notifications.send, method: onSend }

Example listener:

public function onSend(PushNotificationEvent $event) {
    $message = $event->getMessage();
    // Log, analyze, or modify the message before sending
}

Scheduled Notifications:
- Use Symfony’s CronBundle or Laravel Tasks to queue delayed messages:
```
$message->setScheduledAt(new \DateTime('+1 hour'));
$manager->send($message);
```

Gotchas and Tips

Pitfalls

Deprecated Dependencies:
- The bundle relies on GCM (now Firebase Cloud Messaging) and C2DM (shut down in 2012). Replace GCM references with FCM in your code:
```
// Old (GCM):
$message->setGcmApiKey('your_key');
// New (FCM):
$message->setFcmApiKey('your_fcm_key');
```
- For iOS, ensure you’re using APNs (not MPNS) and have valid .pem certificates.

Database Schema:

The bundle assumes a device table with columns: id, token, user_id, platform, created_at. Customize migrations if needed:

// Example migration for custom fields
Schema::table('device', function (Blueprint $table) {
    $table->string('app_version')->nullable();
    $table->boolean('is_active')->default(true);
});

Token Expiry:
- Device tokens (especially APNS) expire. Implement a token refresh workflow:
  - Frontend: Detect token changes and POST new tokens to /api/push_notifications/devices/{id}.
  - Backend: Invalidate old tokens via a PushNotificationEvent listener.

Rate Limits:

APNS/FCM have strict rate limits. Implement exponential backoff in your PushNotificationManager:

try {
    $manager->send($message);
} catch (RateLimitExceededException $e) {
    sleep(2 ** $attempt); // Exponential backoff
    $manager->send($message);
}

Admin Panel Quirks:

The admin UI is basic. Extend it with EasyAdmin or SonataAdmin for better UX:

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        Dabsquared\PushNotificationsBundle\Entity\Device:
            class: Device
            list: [id, token, platform, user]
            form: [token, platform, user, is_active]

Debugging

Logging:
- Enable debug mode in config/packages/dabsquared_push_notifications.yaml:
```
debug: true
```
- Check logs at var/log/dev.log for failed sends.
Payload Validation:
- Use tools like APNs Debugger or FCM DebugView to validate payloads.
Common Errors:
- APNS: "Invalid Token" → Regenerate certificates in Apple Developer Portal.
- FCM: "InvalidRegistration" → Token expired; request a new one from the device.
- Database: "Column not found" → Run migrations or adjust schema.

Extension Points

Custom Providers:

Extend Dabsquared\PushNotificationsBundle\Provider\AbstractProvider to support new platforms (e.g., Web Push):

class WebPushProvider extends AbstractProvider {
    public function send($message, $device) {
        // Implement Web Push logic
    }
}

Dabsquared\PushNotificationsBundle\Provider\WebPushProvider:
    tags:
        - { name: dabsquared.push_notifications.provider, platform: 'web' }

Message Transformers:

Override payload formatting for specific platforms:

$manager->addTransformer('ios', function ($message, $device) {
    $message->setData(array_merge($message->getData(), ['category' => 'news']));
});

Webhooks:
- Integrate with third-party services (e.g., Slack, Twilio) via post-send events:
```
$event->getMessage()->getData()['webhook_url'] = 'https://your-service.com/webhook';
```

Analytics:

Track delivery status by extending the Device entity:

// Add to Device entity
/**
 * @ORM\Column(type="boolean", nullable=true)
 */
private $lastDeliveryStatus;

// Update via listener
public function onSend(PushNotificationEvent $event) {
    $device = $event->getDevice();
    $device->setLastDeliveryStatus($event->getStatus());
    $em->persist($device);
}

Performance Tips

Batch Processing:

Use Symfony’s Messenger component to queue notifications:

$messageBus->dispatch(new SendPushNotification($message));

Process in bulk via a worker:

$manager->sendBatch($messages); // Hypothetical batch method

Caching:

Cache user-device mappings to reduce DB queries:

$cache->set("user_{$userId}_devices", $devices, 3600);

Async Sending:

Dabsquared Push Notifications Bundle Laravel Package