Redirected from /minishlink/web-push
WebPush

https://github.com/web-push-libs/web-push-php
Admin
Web Push library for PHP to send push messages to endpoints according to RFC 8030, RFC 8291, and RFC...
Tokens:61,690
Snippets:405
Trust Score:8.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install web-push-php with Composer

Source: https://github.com/web-push-libs/web-push-php/blob/master/README.md

Install the web-push-php library and its dependencies using Composer.

```bash
composer require minishlink/web-push
```

--------------------------------

### queueNotification() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Example of queueing a notification with a payload and with per-notification options and custom VAPID auth.

```php
<?php

use Minishlink\WebPush\WebPush;
use Minishlink\WebPush\Subscription;

$webPush = new WebPush();
$subscription = Subscription::create($clientSidePushSubscriptionJSON);

// queue with payload (string) — array must be json_encoded
$webPush->queueNotification($subscription, json_encode(['message' => 'Hello World!']));

// queue with per-notification options and custom VAPID auth
$webPush->queueNotification($subscription, 'hello', [
    'TTL' => 5000,
    'urgency' => 'high',
], [
    'VAPID' => ['subject' => 'mailto:a@b.co', 'publicKey' => '...', 'privateKey' => '...'],
]);
```

--------------------------------

### Example: setReuseVAPIDHeaders() usage

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Example showing how to enable VAPID header reuse and verify the setting. The echo outputs 'reusing' when enabled, otherwise 'not'.

```php
<?php

$webPush->setReuseVAPIDHeaders(true);
echo $webPush->getReuseVAPIDHeaders() ? 'reusing' : 'not'; // 'reusing'
```

--------------------------------

### Subscription::create() usage examples

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/subscription.md

Three examples showing how to create a Subscription from different client-side PushSubscription formats: current W3C format with keys, legacy Firefox format with publicKey/authToken, and legacy Chrome endpoint-only format.

```php
<?php

use Minishlink\WebPush\Subscription;

// Current PushSubscription format (browsers might change this in the future)
$subscription = Subscription::create(json_decode($clientSidePushSubscriptionJSON, true));
// e.g. ['endpoint' => 'https://example.com/...', 'keys' => ['p256dh' => '...', 'auth' => '...']]

// Old Firefox PushSubscription format
$subscription = Subscription::create([
    'endpoint' => 'https://updates.push.services.mozilla.com/push/abc...',
    'publicKey' => 'BPcMbnWQL5GOYX/5LKZXT6sLmHiMsJSiEvIFvfcDvX7IZ9qqtq68onpTPEYmyxSQNiH7UD/98AUcQ12kBoxz/0s=',
    'authToken' => 'CxVX6QsVToEGEcjfYPqXQw==',
]);

// Old Chrome PushSubscription format (endpoint only)
$subscription = Subscription::create([
    'endpoint' => 'https://fcm.googleapis.com/fcm/send/abcdef...',
]);
```

--------------------------------

### flushPooled() error handling example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Example of handling the LogicException thrown when no async client is installed, falling back to sequential flush().

```php
<?php

// Error handling: no async client installed
try {
    $webPush->flushPooled($callback);
} catch (\LogicException $e) {
    // 'flushPooled() requires an HTTPlug async client for concurrent sending. ...'
    foreach ($webPush->flush() as $report) { /* fallback to sequential */ }
}
```

--------------------------------

### Example using all getters

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/subscription.md

Shows how to create a Subscription and use all getter methods to access its properties.

```php
<?php

$subscription = Subscription::create([
    'endpoint' => 'https://example.com/push/abc',
    'keys' => ['p256dh' => 'AAA...', 'auth' => 'BBB...'],
]);

echo $subscription->getEndpoint();             // https://example.com/push/abc
echo $subscription->getPublicKey();            // AAA...
echo $subscription->getAuthToken();            // BBB...
echo $subscription->getContentEncoding();      // "aesgcm"
$typed = $subscription->getContentEncodingTyped();
echo $typed === \Minishlink\WebPush\ContentEncoding::aesgcm ? 'aesgcm' : 'other';
```

--------------------------------

### Custom SubscriptionInterface implementation example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/subscription.md

Shows a custom implementation of SubscriptionInterface backed by a database row. The constructor takes an array, and each accessor returns the corresponding field or a default value. The example then queues a notification using the custom subscription.

```php
<?php

use Minishlink\WebPush\SubscriptionInterface;

class DbSubscription implements SubscriptionInterface
{
    public function __construct(private array $row) {}

    public function getEndpoint(): string { return $this->row['endpoint']; }
    public function getPublicKey(): ?string { return $this->row['p256dh'] ?? null; }
    public function getAuthToken(): ?string { return $this->row['auth'] ?? null; }
    public function getContentEncoding(): ?string { return $this->row['content_encoding'] ?? 'aesgcm'; }
}

$webPush->queueNotification(new DbSubscription($row), 'payload');
```

--------------------------------

### unserializePublicKey() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/utils.md

Example of calling the static method with a raw 65-byte uncompressed public key. Returns an array with two binary strings: X and Y coordinates.

```php
<?php

use Minishlink\WebPush\Utils;

[$x, $y] = Utils::unserializePublicKey($raw65ByteKey);
```

--------------------------------

### Example usage of deterministicEncrypt()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/encryption.md

Example showing how to call deterministicEncrypt() with a local JWK, user public key, auth token, content encoding, and salt. The salt is generated with random_bytes(16).

```php
<?php

use Jose\Component\Core\JWK;

$localJwk = new JWK(['kty' => 'EC', 'crv' => 'P-256', 'x' => '...', 'y' => '...', 'd' => '...']);
$result = Encryption::deterministicEncrypt(
    $paddedPayload,
    $userPublicKeyB64,
    $userAuthTokenB64,
    ContentEncoding::aesgcm,
    [$localJwk],
    random_bytes(16),
);
```

--------------------------------

### Example: Calling Utils::checkRequirement()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/utils.md

Example usage showing how to call the checkRequirement method directly, equivalent to what WebPush::__construct() does. It passes a PSR-3 logger and emits warnings/notices to the logger without throwing exceptions.

```php
<?php

use Minishlink\WebPush\Utils;

// Equivalent to what WebPush::__construct() does
Utils::checkRequirement($psr3Logger); // warnings/notices to the logger, no exceptions
```

--------------------------------

### serializePublicKeyFromJWK() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/utils.md

Example of calling the static method with a JWK instance. The JWK must contain 'kty' => 'EC', 'crv' => 'P-256', and x/y coordinates as Base64-URL encoded strings.

```php
<?php

use Minishlink\WebPush\Utils;
use Jose\Component\Core\JWK;

$jwk = new JWK(['kty' => 'EC', 'crv' => 'P-256', 'x' => '...', 'y' => '...']);
$hex = Utils::serializePublicKeyFromJWK($jwk);
```

--------------------------------

### getOptions() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/notification.md

Shows how to call getOptions() with a notification that has TTL set to 60, demonstrating that the own TTL wins over the default, while other keys fall back to defaults.

```php
<?php

$notification = new Notification($sub, null, ['TTL' => 60], []);
$options = $notification->getOptions(['TTL' => 2419200, 'urgency' => null, 'topic' => null, 'contentType' => 'application/octet-stream']);
// $options['TTL'] === 60 (own value wins), urgency/topic/contentType from defaults
```

--------------------------------

### Install HTTPlug async adapter for flushPooled()

Source: https://github.com/web-push-libs/web-push-php/blob/master/README.md

Installs the HTTPlug async adapter for Guzzle, required for flushPooled() to send notifications concurrently. Without an async client, flushPooled() throws a \LogicException. Use flush() if concurrency is not needed.

```bash
composer require php-http/guzzle7-adapter
```

--------------------------------

### encrypt() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/encryption.md

Example call to Encryption::encrypt() with a padded payload, Base64-encoded user public key and auth token, and ContentEncoding::aes128gcm. Returns an array with localPublicKey, salt, and cipherText.

```php
<?php

$result = Encryption::encrypt($paddedPayload, $userPublicKeyB64, $userAuthTokenB64, ContentEncoding::aes128gcm);
// ['localPublicKey' => <65 raw bytes>, 'salt' => <16 raw bytes>, 'cipherText' => <ciphertext+tag>]
```

--------------------------------

### Minimal construction and with VAPID auth

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Two examples: minimal construction with auto-discovery, and construction with VAPID auth and default options. The VAPID keys are placeholders; subject must be a mailto: or https: URL.

```php
<?php

use Minishlink\WebPush\WebPush;

// Minimal construction — everything auto-discovered
$webPush = new WebPush();

// With VAPID auth and default options
$webPush = new WebPush([
    'VAPID' => [
        'subject' => 'mailto:me@website.com',
        'publicKey' => '~88 chars (Base64-URL)',
        'privateKey' => '~44 chars (Base64-URL)',
    ],
], [
    'TTL' => 300,
    'urgency' => 'normal',
    'topic' => 'newEvent',
    'batchSize' => 200,
    'contentType' => 'application/json',
]);
```

--------------------------------

### flushPooled() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Example of using flushPooled() with an async client, queueing two notifications and processing the reports in a callback.

```php
<?php

$webPush = new WebPush([], [], null, null, null, $httpAsyncClient); // e.g. php-http/guzzle7-adapter
$webPush->queueNotification($subA, 'a');
$webPush->queueNotification($subB, 'b');

$webPush->flushPooled(function (MessageSentReport $report): void {
    if ($report->isSuccess()) {
        echo "[v] Sent to {$report->getEndpoint()}\n";
    } else {
        echo "[x] Failed: {$report->getReason()}\n";
    }
});
```

--------------------------------

### SubscriptionInterface

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/subscription.md

Documentation for the SubscriptionInterface, including its methods and an example custom implementation.

```APIDOC
## SubscriptionInterface

### Description
Interface defining the contract for push subscription objects. Any object implementing this interface can be passed to `WebPush::queueNotification()`, `WebPush::sendOneNotification()`, and `Notification`'s constructor.

### Methods

#### getEndpoint()
- **Return type**: `string`
- **Description**: Returns the push service endpoint URL.

#### getPublicKey()
- **Return type**: `?string`
- **Description**: Returns the P-256 public key, Base64-URL encoded, or `null`.

#### getAuthToken()
- **Return type**: `?string`
- **Description**: Returns the auth secret, Base64-URL encoded, or `null`.

#### getContentEncoding()
- **Return type**: `?string`
- **Description**: Returns the content encoding (`'aesgcm'`/`'aes128gcm'`) or `null`.

### Example: custom implementation

```php
<?php

use Minishlink\WebPush\SubscriptionInterface;

class DbSubscription implements SubscriptionInterface
{
    public function __construct(private array $row) {}

    public function getEndpoint(): string { return $this->row['endpoint']; }
    public function getPublicKey(): ?string { return $this->row['p256dh'] ?? null; }
    public function getAuthToken(): ?string { return $this->row['auth'] ?? null; }
    public function getContentEncoding(): ?string { return $this->row['content_encoding'] ?? 'aesgcm'; }
}

$webPush->queueNotification(new DbSubscription($row), 'payload');
```
```

--------------------------------

### Creating a Notification instance

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/notification.md

Shows how to instantiate a Notification object with a subscription, a padded payload string, options (TTL), and auth (VAPID). This example is for direct construction, though typically instances are created by WebPush::queueNotification().

```php
<?php

use Minishlink\WebPush\Notification;

$notification = new Notification($subscription, 'padded-payload-bytes', ['TTL' => 300], ['VAPID' => [...]]);
```

--------------------------------

### Example: countPendingNotifications() usage

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Example usage of countPendingNotifications(). Queues two notifications and echoes the count, which is 2. Use this to check how many notifications are pending before flushing.

```php
<?php

$webPush->queueNotification($subA);
$webPush->queueNotification($subB);
echo $webPush->countPendingNotifications(); // 2
```

--------------------------------

### getAuth() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/notification.md

Shows how to call getAuth() with a fallback VAPID configuration. Returns the notification's own VAPID config if set, otherwise the default.

```php
<?php

$notification = new Notification($sub, null, [], ['VAPID' => $myVapid]);
$auth = $notification->getAuth(['VAPID' => $defaultVapid]);
// returns the notification's own VAPID config; falls back when the own auth is empty
```

--------------------------------

### MessageSentReport instantiation example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Creates a new MessageSentReport instance with a request, response, success flag, and reason. Requires the MessageSentReport class and PSR-7 interfaces.

```php
<?php

use Minishlink\WebPush\MessageSentReport;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

$report = new MessageSentReport($request, $response, true, 'OK');
```

--------------------------------

### Full failure inspection example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Shows how to inspect a failed push notification report. Checks isSuccess(), prints the reason, and if a response exists, outputs the HTTP status code and the response content. Also checks isSubscriptionExpired() to handle unsubscribing.

```php
<?php

$report = $webPush->sendOneNotification($subscription, 'payload');

if ($report->isSuccess()) {
    echo "[v] Sent successfully to {$report->getEndpoint()}";
} else {
    echo "[x] Failed: {$report->getReason()}";

    /** @var \Psr\Http\Message\RequestInterface $request */
    $request = $report->getRequest();
    /** @var \Psr\Http\Message\ResponseInterface|null $response */
    $response = $report->getResponse();

    if ($response) {
        echo 'HTTP '.$response->getStatusCode();
        echo $report->getResponseContent(); // error body from the push service
    }
    if ($report->isSubscriptionExpired()) {
        // unsubscribe / delete
    }
}
```

--------------------------------

### Using getContentCodingHeader() to build wire body

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/encryption.md

Example usage of getContentCodingHeader() to build the wire body for WebPush::prepare(). The prefix is prepended to the ciphertext.

```php
<?php

$prefix = Encryption::getContentCodingHeader($salt, $localKey, ContentEncoding::aes128gcm);
$wireBody = $prefix . $cipherText; // what WebPush::prepare() sends as the request body
```

--------------------------------

### flush(100) with custom batch size and expired subscription handling

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Flush with a custom batch size of 100 to reduce memory usage. The example checks isSubscriptionExpired() to handle 404/410 responses from the push service, typically by deleting the subscription from a database.

```php
<?php

// Custom batch size for one flush (e.g. lower memory usage)
foreach ($webPush->flush(100) as $report) {
    if ($report->isSubscriptionExpired()) {
        // delete subscription from your database: 404/410 from push service
    }
}
```

--------------------------------

### PHP example: Catching errors and inspecting failure reports

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/errors.md

Use this snippet to handle errors when queueing and flushing notifications. It catches \ErrorException for payload, encoding, VAPID, or audience issues, and \Random\RandomException for random salt generation failures. For per-notification failures, it inspects the MessageSentReport to check success, subscription expiry, and reason.

```php
<?php

use Minishlink\WebPush\WebPush;

$webPush = new WebPush();
try {
    $webPush->queueNotification($subscription, 'payload');
    foreach ($webPush->flush() as $report) {
        if ($report->isSuccess()) {
            echo "[v] sent";
        } elseif ($report->isSubscriptionExpired()) {
            deleteSubscription($report->getEndpoint());
        } else {
            error_log($report->getReason());
        }
    }
} catch (\ErrorException $e) {
    // payload too large / missing content encoding / bad VAPID / bad audience
    error_log($e->getMessage());
} catch (\Random\RandomException $e) {
    // random salt generation failed
}
```

--------------------------------

### Example: checking for expired subscriptions

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Iterates over flush() results and deletes subscriptions that are expired (HTTP 404/410). The deleteSubscriptionByEndpoint() function is a placeholder for your own storage removal logic.

```php
<?php

foreach ($webPush->flush() as $report) {
    if ($report->isSubscriptionExpired()) {
        // 404/410 → remove the subscription from storage
        deleteSubscriptionByEndpoint($report->getEndpoint());
    }
}
```

--------------------------------

### unserializePublicKey() method implementation

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/utils.md

Static method that splits a raw binary uncompressed EC public key (65 bytes starting with 0x04) into its X and Y coordinate binaries. Throws InvalidArgumentException if the first byte is not 0x04.

```php
public static function unserializePublicKey(string $data): array
{
    $data = bin2hex($data);
    if (mb_substr($data, 0, 2, '8bit') !== '04') {
        throw new \InvalidArgumentException('Invalid data: only uncompressed keys are supported.');
    }
    $data = mb_substr($data, 2, null, '8bit');
    $dataLength = self::safeStrlen($data);

    return [
        hex2bin(mb_substr($data, 0, $dataLength / 2, '8bit')),
        hex2bin(mb_substr($data, $dataLength / 2, null, '8bit')),
    ];
}
```

--------------------------------

### queueNotification() oversized payload exception example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Example of catching the \ErrorException thrown when the payload exceeds 4078 octets.

```php
<?php

$webPush = new WebPush();

try {
    $webPush->queueNotification($subscription, str_repeat('x', 5000)); // exceeds 4078 octets
} catch (\ErrorException $e) {
    echo 'Payload too large: '.$e->getMessage();
    // "Size of payload must not be greater than 4078 octets."
}
```

--------------------------------

### WebPush::__construct

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Initializes a new WebPush instance with optional authentication, default options, HTTP client, factories, async client, and logger. All dependencies are auto-discovered if not provided.

```APIDOC
## WebPush::__construct

### Description
Initializes a new WebPush instance with optional authentication, default options, HTTP client, factories, async client, and logger. All dependencies are auto-discovered if not provided.

### Method
Constructor

### Signature
```php
public function __construct(
    array $auth = [],
    array $defaultOptions = [],
    ?ClientInterface $client = null,
    ?RequestFactoryInterface $requestFactory = null,
    ?StreamFactoryInterface $streamFactory = null,
    ?HttpAsyncClient $asyncClient = null,
    ?LoggerInterface $logger = null
)
```

### Parameters
- **$auth** (array) - Optional - Auth details keyed by provider, e.g. `['VAPID' => ['subject' => ..., 'publicKey' => ..., 'privateKey' => ...]]`. If `VAPID` is present it is passed through `VAPID::validate()`.
- **$defaultOptions** (array) - Optional - Keys: `TTL`, `urgency`, `topic`, `batchSize`, `requestConcurrency`, `contentType`. Merged into `setDefaultOptions()`.
- **$client** (?ClientInterface) - Optional - PSR-18 HTTP client. Defaults to `Psr18ClientDiscovery::find()`.
- **$requestFactory** (?RequestFactoryInterface) - Optional - Defaults to `Psr17FactoryDiscovery::findRequestFactory()`.
- **$streamFactory** (?StreamFactoryInterface) - Optional - Defaults to `Psr17FactoryDiscovery::findStreamFactory()`.
- **$asyncClient** (?HttpAsyncClient) - Optional - HTTPlug async client. If `null`, tries `HttpAsyncClientDiscovery::find()`, swallowing any throwable and leaving it `null`.
- **$logger** (?LoggerInterface) - Optional - Replaces `trigger_error()` in `Utils::checkRequirement()` with `$logger->warning()` / `$logger->notice()`.

### Throws
- **\ErrorException** - If `$auth['VAPID']` is set and `VAPID::validate()` rejects it (missing subject/publicKey/privateKey, bad PEM, wrong key lengths).

### Examples
```php
<?php

use Minishlink\WebPush\WebPush;

// Minimal construction — everything auto-discovered
$webPush = new WebPush();

// With VAPID auth and default options
$webPush = new WebPush([
    'VAPID' => [
        'subject' => 'mailto:me@website.com',
        'publicKey' => '~88 chars (Base64-URL)',
        'privateKey' => '~44 chars (Base64-URL)',
    ],
], [
    'TTL' => 300,
    'urgency' => 'normal',
    'topic' => 'newEvent',
    'batchSize' => 200,
    'contentType' => 'application/json',
]);
```

```php
<?php

use GuzzleHttp\Client;
use Minishlink\WebPush\WebPush;

// Custom PSR-18 client with a timeout — error handling left to your PSR-3 logger
$client = new Client(['timeout' => 20]);

$logger = new \Monolog\Logger('webpush'); // any PSR-3 logger
$webPush = new WebPush([], [], $client, null, null, null, $logger);
```
```

--------------------------------

### Send push messages with WebPush and Subscription::create

Source: https://github.com/web-push-libs/web-push-php/blob/master/README.md

Shows how to create subscriptions from various PushSubscription formats, queue multiple notifications, flush them, and send a single notification directly. The payload is optional and defaults to null. The flush loop checks each report's success and prints the reason on failure.

```php
<?php

use Minishlink\WebPush\WebPush;
use Minishlink\WebPush\Subscription;

// store the client-side `PushSubscription` object (calling `.toJSON` on it) as-is and then create a WebPush\Subscription from it
$subscription = Subscription::create(json_decode($clientSidePushSubscriptionJSON, true));

// array of notifications
$notifications = [
    [
        'subscription' => $subscription,
        'payload' => '{"message":"Hello World!"}',
    ], [
          // current PushSubscription format (browsers might change this in the future)
          'subscription' => Subscription::create([
              "endpoint" => "https://example.com/other/endpoint/of/another/vendor/abcdef...",
              "keys" => [
                  'p256dh' => '(stringOf88Chars)',
                  'auth' => '(stringOf24Chars)'
              ],
              // key 'contentEncoding' is optional and defaults to Subscription::defaultContentEncoding
          ]),
          'payload' => '{"message":"Hello World!"}',
    ], [
        // old Firefox PushSubscription format
        'subscription' => Subscription::create([
            'endpoint' => 'https://updates.push.services.mozilla.com/push/abc...', // Firefox 43+,
            'publicKey' => 'BPcMbnWQL5GOYX/5LKZXT6sLmHiMsJSiEvIFvfcDvX7IZ9qqtq68onpTPEYmyxSQNiH7UD/98AUcQ12kBoxz/0s=', // base 64 encoded, should be 88 chars
            'authToken' => 'CxVX6QsVToEGEcjfYPqXQw==', // base 64 encoded, should be 24 chars
        ]),
        'payload' => 'hello !',
    ], [
        // old Chrome PushSubscription format
        'subscription' => Subscription::create([
            'endpoint' => 'https://fcm.googleapis.com/fcm/send/abcdef...',
        ]),
        'payload' => null,
    ], [
        // old PushSubscription format
        'subscription' => Subscription::create([
            'endpoint' => 'https://example.com/other/endpoint/of/another/vendor/abcdef...',
            'publicKey' => '(stringOf88Chars)',
            'authToken' => '(stringOf24Chars)',
            'contentEncoding' => 'aesgcm', // one of PushManager.supportedContentEncodings
        ]),
        'payload' => '{"message":"test"}',
    ]
];

$webPush = new WebPush();

// send multiple notifications with payload
foreach ($notifications as $notification) {
    $webPush->queueNotification(
        $notification['subscription'],
        $notification['payload'] // optional (defaults null)
    );
}

/**
 * Check sent results
 * @var MessageSentReport $report
 */
foreach ($webPush->flush() as $report) {
    $endpoint = $report->getRequest()->getUri()->__toString();

    if ($report->isSuccess()) {
        echo "[v] Message sent successfully for subscription {$endpoint}.";
    } else {
        echo "[x] Message failed to sent for subscription {$endpoint}: {$report->getReason()}";
    }
}

/**
 * send one notification and flush directly
 * @var MessageSentReport $report
 */
$report = $webPush->sendOneNotification(
    $notifications[0]['subscription'],
    $notifications[0]['payload'], // optional (defaults null)
);
```

--------------------------------

### Example: VAPID::getVapidHeaders() with aes128gcm

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/vapid.md

Example call to VAPID::getVapidHeaders() with a Firebase Cloud Messaging endpoint and a mailto: subject. Uses ContentEncoding::aes128gcm, which produces an 'Authorization' header in the format 'vapid t=<JWT>, k=<Base64Url public key>' and omits the 'Crypto-Key' header. The commented output shows the resulting Authorization header.

```php
<?php

use Minishlink\WebPush\VAPID;
use Minishlink\WebPush\ContentEncoding;

$headers = VAPID::getVapidHeaders(
    'https://fcm.googleapis.com',
    'mailto:me@website.com',
    $validated['publicKey'],
    $validated['privateKey'],
    ContentEncoding::aes128gcm,
);
// ['Authorization' => 'vapid t=eyJ...JWT..., k=BPcM...']
```

--------------------------------

### getResponse() / setResponse()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Gets or sets the push service response. getResponse() returns the ResponseInterface or null for transport-level failures. setResponse() is fluent.

```APIDOC
## getResponse() / setResponse()

### Description
Gets or sets the push service response. `getResponse()` returns the `ResponseInterface` object or `null` for transport-level failures (no response received). `setResponse()` sets the response and returns the report instance for fluent chaining.

### Methods

#### `getResponse()`
- **Return:** `?ResponseInterface` - The push service response; `null` for transport-level failures (no response received).

#### `setResponse(ResponseInterface $response)`
- **Parameters:**
  - `$response` (ResponseInterface) - Required - The response object to set.
- **Return:** `MessageSentReport` - The report instance for fluent chaining.

### Example
```php
$response = $report->getResponse();
if ($response !== null) {
    // handle response
}
```
```

--------------------------------

### new Subscription()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/subscription.md

Creates a new Subscription instance representing a browser push subscription. No key validation is performed on construction.

```APIDOC
## Constructor: `new Subscription()`

### Description
Creates a new `Subscription` instance. This is a data class; no key validation is performed.

### Signature
```php
public function __construct(
    private string  $endpoint,
    private ?string $publicKey = null,
    private ?string $authToken = null,
    ContentEncoding|string|null $contentEncoding = null,
)
```

### Parameters
- **$endpoint** (string) - Required - The push service endpoint URL (from the client-side `PushSubscription.endpoint`).
- **$publicKey** (?string) - Optional - The client's P-256 public key, Base64-URL encoded (`p256dh`). Defaults to `null`.
- **$authToken** (?string) - Optional - The client's authentication secret, Base64-URL encoded (`auth`). Defaults to `null`.
- **$contentEncoding** (ContentEncoding|string|null) - Optional - `'aesgcm'`, `'aes128gcm'`, a `ContentEncoding` enum case, or `null`. Defaults to `null`.

### Content Encoding Resolution
- If `$publicKey` OR `$authToken` OR `$contentEncoding` is truthy, the content encoding is resolved:
  - empty string → `self::defaultContentEncoding` (`aesgcm`);
  - any other string → `ContentEncoding::from($contentEncoding)`;
  - `null` → `self::defaultContentEncoding`;
  - a `ContentEncoding` enum case is used as-is.
- Otherwise (all three absent), `$this->contentEncoding` stays `null` — `getContentEncoding()` then returns `null`.

### Throws
- `\ValueError` - If `$contentEncoding` is a string that is not `'aesgcm'` or `'aes128gcm'` (re-thrown from `ContentEncoding::from()` with message `'This content encoding ('.$contentEncoding.') is not supported.'`).

### Example
```php
<?php

use Minishlink\WebPush\Subscription;
use Minishlink\WebPush\ContentEncoding;

// Direct construction with all fields
$subscription = new Subscription(
    'https://fcm.googleapis.com/fcm/send/abcdef...',
    'BPcMbnWQL5GOYX/5LKZXT6sLmHiMsJSiEvIFvfcDvX7IZ9qqtq68onpTPEYmyxSQNiH7UD/98AUcQ12kBoxz/0s=',
    'CxVX6QsVToEGEcjfYPqXQw==',
    ContentEncoding::aes128gcm,
);

// Endpoint-only (old Chrome format) — contentEncoding stays null
$subscription = new Subscription('https://fcm.googleapis.com/fcm/send/abcdef...');
```

### Error Example
```php
<?php

// Invalid content encoding string
try {
    new Subscription('https://example.com', null, null, 'aesgcm-typo');
} catch (\ValueError $e) {
    echo $e->getMessage(); // "This content encoding (aesgcm-typo) is not supported."
}
```
```

--------------------------------

### getRequest() / setRequest()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Gets or sets the full request sent to the push service. getRequest() returns the RequestInterface object, and setRequest() is fluent.

```APIDOC
## getRequest() / setRequest()

### Description
Gets or sets the full request sent to the push service. `getRequest()` returns the `RequestInterface` object containing the endpoint URI, headers, and encrypted body. `setRequest()` sets the request and returns the report instance for fluent chaining.

### Methods

#### `getRequest()`
- **Return:** `RequestInterface` - The full request sent to the push service (endpoint URI, headers, encrypted body). Useful for inspecting the endpoint via `$report->getRequest()->getUri()`.

#### `setRequest(RequestInterface $request)`
- **Parameters:**
  - `$request` (RequestInterface) - Required - The request object to set.
- **Return:** `MessageSentReport` - The report instance for fluent chaining.

### Example
```php
$request = $report->getRequest();
$uri = $request->getUri();
```
```

--------------------------------

### jsonSerialize() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Demonstrates serializing a report with json_encode(). The output shows the JSON structure with success, expired, reason, endpoint, and payload fields.

```php
<?php

$report = $webPush->sendOneNotification($subscription, 'hi');
echo json_encode($report);
// {"success":true,"expired":false,"reason":"OK","endpoint":"https://...","payload":"..."}
```

--------------------------------

### Constructing Subscription with all fields and endpoint-only

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/subscription.md

Shows two ways to construct a Subscription: with all fields including a `ContentEncoding::aes128gcm` enum case, and with only an endpoint (old Chrome format) where `contentEncoding` stays `null`.

```php
<?php

use Minishlink\WebPush\Subscription;
use Minishlink\WebPush\ContentEncoding;

// Direct construction with all fields
$subscription = new Subscription(
    'https://fcm.googleapis.com/fcm/send/abcdef...',
    'BPcMbnWQL5GOYX/5LKZXT6sLmHiMsJSiEvIFvfcDvX7IZ9qqtq68onpTPEYmyxSQNiH7UD/98AUcQ12kBoxz/0s=',
    'CxVX6QsVToEGEcjfYPqXQw==',
    ContentEncoding::aes128gcm,
);

// Endpoint-only (old Chrome format) — contentEncoding stays null
$subscription = new Subscription('https://fcm.googleapis.com/fcm/send/abcdef...');
```

--------------------------------

### createVapidKeys() (static)

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/vapid.md

Generates a fresh P-256 EC key via JWKFactory::createECKey('P-256') and returns it encoded in Base64-URL. This method should be called once and the keys reused, not on every request.

```APIDOC
## createVapidKeys() (static)

### Description
Generates a fresh P-256 EC key via `JWKFactory::createECKey('P-256')` and returns it encoded in Base64-URL. This method should be called once and the keys reused, not on every request.

### Method
static

### Endpoint
`VAPID::createVapidKeys()`

### Parameters
None

### Return
- **array** - An associative array with two keys:
  - `publicKey` (string) - Base64-URL encoded public key, ~88 characters, uncompressed 65-byte point.
  - `privateKey` (string) - Base64-URL encoded private key, ~44 characters, 32-byte secret.

### Throws
- `\ErrorException` - If `hex2bin()` conversion of the serialized public key fails (message: 'Failed to convert VAPID public key from hexadecimal to binary.').
- `\ErrorException` - If `hex2bin()` conversion of the padded private key fails (message: 'Failed to convert VAPID private key from hexadecimal to binary.').

### Example
```php
<?php

use Minishlink\WebPush\VAPID;

$keys = VAPID::createVapidKeys();
// ['publicKey' => 'BPcM...', 'privateKey' => 'CxVX...']
// Store these once and reuse — never call createVapidKeys() on every request.
```
```

--------------------------------

### Using ContentEncoding enum

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/contentencoding.md

Shows how to create an enum instance from a string, access the backing value, and use it in a switch statement.

```php
<?php

use Minishlink\WebPush\ContentEncoding;

// From a string (e.g. stored subscription data)
$encoding = ContentEncoding::from('aes128gcm'); // throws \ValueError for unknown strings

// Backing value
echo ContentEncoding::aesgcm->value; // "aesgcm"

// Enum switch
$encoding = $subscription->getContentEncodingTyped();
if ($encoding === ContentEncoding::aes128gcm) {
    // RFC 8291 path
}
```

--------------------------------

### Validate VAPID config with publicKey and privateKey

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/vapid.md

Validates a VAPID configuration with decoded keys. The publicKey must decode to exactly 65 bytes and the privateKey to exactly 32 bytes; otherwise an \ErrorException is thrown.

```php
<?php

use Minishlink\WebPush\VAPID;

$config = VAPID::validate([
    'subject' => 'mailto:me@website.com',
    'publicKey' => '~88 chars Base64-URL',
    'privateKey' => '~44 chars Base64-URL',
]);
// ['subject' => ..., 'publicKey' => <65 raw bytes>, 'privateKey' => <32 raw bytes>]
```

--------------------------------

### padPayload() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/encryption.md

Pads a JSON payload to 512 bytes using aes128gcm encoding. The result is 512 bytes: payload + chr(2) + right null padding.

```php
<?php

use Minishlink\WebPush\Encryption;
use Minishlink\WebPush\ContentEncoding;

$padded = Encryption::padPayload('{"msg":"hi"}', 512, ContentEncoding::aes128gcm);
// 512 bytes: payload + chr(2) + right null padding
```

--------------------------------

### Subscription::create()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/subscription.md

Static factory method that creates a Subscription instance from an associative array representing a client-side PushSubscription. It supports current W3C, legacy Firefox, and legacy Chrome formats.

```APIDOC
## `Subscription::create()` (static factory)

### Description
Builds a `Subscription` (late-static bound — returns `static`) from the associative array produced by calling `.toJSON()` on a client-side `PushSubscription` object.

### Method
`Subscription::create(array $associativeArray): static`

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `$associativeArray` | `array` | yes | Decoded JSON of the client-side subscription. Recognized keys: `endpoint` (required), `keys.p256dh`, `keys.auth`, `publicKey`, `authToken`, `contentEncoding`. |

### Return
`static` — a new `Subscription` (or subclass, due to `static` return type).

### Throws
`@throws \ErrorException` annotation is present in the docblock, but the current implementation does not throw; it only reads array keys with `??`/`array_key_exists()`. An undefined `endpoint` key would raise a PHP `\Error`/warning from array access on the missing key.

### Input Shape Resolution
1. If the array has a `keys` key that is an array (current W3C PushSubscription format): `endpoint`, `keys['p256dh']`, `keys['auth']`, `contentEncoding ?? ContentEncoding::aesgcm`.
2. Else if the array has `publicKey` OR `authToken` OR `contentEncoding` (legacy Firefox format): `endpoint`, `publicKey ?? null`, `authToken ?? null`, `contentEncoding ?? ContentEncoding::aesgcm`.
3. Else (endpoint-only, legacy Chrome format): `new static($associativeArray['endpoint'])` — content encoding stays `null`.

### Examples

php
<?php

use Minishlink\WebPush\Subscription;

// Current PushSubscription format (browsers might change this in the future)
$subscription = Subscription::create(json_decode($clientSidePushSubscriptionJSON, true));
// e.g. ['endpoint' => 'https://example.com/...', 'keys' => ['p256dh' => '...', 'auth' => '...']]

// Old Firefox PushSubscription format
$subscription = Subscription::create([
    'endpoint' => 'https://updates.push.services.mozilla.com/push/abc...',
    'publicKey' => 'BPcMbnWQL5GOYX/5LKZXT6sLmHiMsJSiEvIFvfcDvX7IZ9qqtq68onpTPEYmyxSQNiH7UD/98AUcQ12kBoxz/0s=',
    'authToken' => 'CxVX6QsVToEGEcjfYPqXQw==',
]);

// Old Chrome PushSubscription format (endpoint only)
$subscription = Subscription::create([
    'endpoint' => 'https://fcm.googleapis.com/fcm/send/abcdef...',
]);

```

--------------------------------

### isSuccess() / setSuccess()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Gets or sets whether the push service accepted the message. isSuccess() returns true when the HTTP status is below 400. setSuccess() is fluent and returns the report instance.

```APIDOC
## isSuccess() / setSuccess()

### Description
Gets or sets whether the push service accepted the message. `isSuccess()` returns `true` when the push service accepted the message (HTTP status < 400), `false` otherwise. `setSuccess()` sets the success flag and returns the report instance for fluent chaining.

### Methods

#### `isSuccess()`
- **Return:** `bool` - `true` when the push service accepted the message (HTTP status < 400), `false` otherwise.

#### `setSuccess(bool $success)`
- **Parameters:**
  - `$success` (bool) - Required - The success flag to set.
- **Return:** `MessageSentReport` - The report instance for fluent chaining.

### Example
```php
$report->setSuccess(true);
$isSuccess = $report->isSuccess();
```
```

--------------------------------

### Validate VAPID config with pemFile and error handling

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/vapid.md

Validates a VAPID configuration using a PEM file path. If the file cannot be read, an \ErrorException with message '[VAPID] Error loading PEM file.' is thrown and caught here.

```php
<?php

// PEM file alternative + error handling
try {
    $config = VAPID::validate([
        'subject' => 'mailto:me@website.com',
        'pemFile' => __DIR__.'/vapid.pem',
    ]);
} catch (\ErrorException $e) {
    error_log($e->getMessage()); // e.g. "[VAPID] Error loading PEM file."
}
```

--------------------------------

### Create VAPID keys with VAPID::createVapidKeys()

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/vapid.md

Generates a fresh P-256 EC key pair encoded in Base64-URL. The returned array contains 'publicKey' (~88 chars) and 'privateKey' (~44 chars). Store these keys once and reuse them; do not call this method on every request. Throws \ErrorException if hex2bin() conversion fails.

```php
<?php

use Minishlink\WebPush\VAPID;

$keys = VAPID::createVapidKeys();
// ['publicKey' => 'BPcM...', 'privateKey' => 'CxVX...']
// Store these once and reuse — never call createVapidKeys() on every request.
```

--------------------------------

### Configure Guzzle HTTP client with timeout and redirect options

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/configuration.md

Use this snippet to create a Guzzle client with a 20-second timeout and redirects disabled, then inject it into the WebPush constructor. The library itself defines no HTTP options, so all client configuration is done on the injected instance.

```php
<?php

use Minishlink\WebPush\WebPush;

$client = new \GuzzleHttp\Client([
    'timeout' => 20,
    \GuzzleHttp\RequestOptions::ALLOW_REDIRECTS => false,
]);
$webPush = new WebPush([], [], $client);
```

--------------------------------

### getReason() and setReason() methods

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

getReason() returns the reason string, defaulting to 'OK' on success. setReason() sets the reason and returns the MessageSentReport instance for fluent chaining.

```php
public function getReason(): string
{
    return $this->reason;
}

public function setReason(string $reason): MessageSentReport
{
    $this->reason = $reason;
    return $this;
}
```

--------------------------------

### setAutomaticPadding() usage example

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Shows how to set automatic padding on a WebPush instance. Passing false disables padding, an integer sets the max padded length, and true uses the default 2820 bytes. Passing a value greater than 4078 or less than 0 throws a \ValueError.

```php
<?php

$webPush->setAutomaticPadding(false);          // max performance, no padding
$webPush->setAutomaticPadding(512);            // pad to 512 bytes
$webPush->setAutomaticPadding(true);           // pad to 2820 bytes (default)
try {
    $webPush->setAutomaticPadding(5000);
} catch (\ValueError $e) {
    echo $e->getMessage(); // "Automatic padding is too large. Max is 4078. ..."
}

```

--------------------------------

### isAutomaticPadding() and getAutomaticPadding() implementation

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/webpush.md

Implementation of the getter methods for automatic padding. isAutomaticPadding() returns true unless padding is disabled (0), and getAutomaticPadding() returns the current max padding length in bytes.

```php
public function isAutomaticPadding(): bool
{
    return $this->automaticPadding !== 0;
}

public function getAutomaticPadding(): int
{
    return $this->automaticPadding;
}

```

--------------------------------

### getResponse() and setResponse() methods

Source: https://github.com/web-push-libs/web-push-php/blob/master/_autodocs/api-reference/messagesentreport.md

Returns the push service response, or null for transport-level failures, and sets it. setResponse() returns MessageSentReport for fluent chaining.

```php
public function getResponse(): ?ResponseInterface
{
    return $this->response;
}

public function setResponse(ResponseInterface $response): MessageSentReport
{
    $this->response = $response;
    return $this;
}
```
Tokens:
Raw