Pushok

https://github.com/edamov/pushok
Admin
Pushok is a simple PHP library for sending push notifications to Apple Push Notification service...
Tokens:63,549
Snippets:574
Trust Score:8.7
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### get method example

Source: https://github.com/edamov/pushok

Example usage of get() to retrieve the token and create a new Client with Token::useExisting.

```php
$tokenString = $authProvider->get();
$client = new Client(Token::useExisting($tokenString, $options));
```

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

### Install via Composer

Source: https://github.com/edamov/pushok/blob/master/README.md

Install the Pushok library using Composer with the command 'composer require edamov/pushok'.

```bash
$ composer require edamov/pushok
```

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

### Getting started with JWT authentication

Source: https://github.com/edamov/pushok

Shows the basic flow for sending a push notification using JWT authentication. Requires a private key (.p8) and the key/team/app bundle IDs.

```php
use Pushok\AuthProvider;
use Pushok\Notification;
use Pushok\Payload;

$authProvider = AuthProvider\Token::create([
    'key_id' => 'AAAABBBBCC',
    'team_id' => 'DDDDEEEEFF',
    'app_bundle_id' => 'com.app.Test',
    'private_key_path' => __DIR__ . '/private_key.p8',
    'private_key_secret' => null,
]);

$payload = Payload::create()->setAlert('Hello')->setSound('default');
$notification = new Notification($payload, '<device_token>');

$client = new Client($authProvider, false);
$client->addNotification($notification);
$response = $client->push()[0];
```

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

### Send push notification using certificate authentication

Source: https://github.com/edamov/pushok/blob/master/README.md

Example of initializing the auth provider with a certificate (.pem or .p12) instead of JWT. Only the initialization differs from the JWT example; the rest of the code (payload, client, push) must be added by yourself. Note the SSL verification issue referenced in the linked post.

```php
<?php

$options = [
    'app_bundle_id' => 'com.app.Test', // The bundle ID for app obtained from Apple developer account
    'certificate_path' => __DIR__ . '/private_key.pem', // Path to private key
    'certificate_secret' => null // Private key secret
];

$authProvider = AuthProvider\Certificate::create($options);

...
```

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

### addOptions usage example

Source: https://github.com/edamov/pushok

Example of using addOptions to set curl options like CURLOPT_SSLCERT and CURLOPT_SSL_VERIFYPEER.

```php
$request->addOptions([CURLOPT_SSLCERT => $path, CURLOPT_SSL_VERIFYPEER => true]);
```

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

### toJson basic usage example

Source: https://github.com/edamov/pushok

Shows how to call `toJson()` to get the JSON string. The output is a JSON object with an `aps` key.

```php
$json = $payload->toJson();
// {"aps":{"alert":{...},"sound":"default"},...}
```

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

### Basic Payload creation example

Source: https://github.com/edamov/pushok

Creates a payload, sets alert, sound, and a custom value.

```php
$payload = Payload::create();
$payload->setAlert('Hello');
$payload->setSound('default');
$payload->setCustomValue('key', 'value');
```

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

### Example: priority usage

Source: https://github.com/edamov/pushok

Shows how to set low priority on a notification, e.g., for background sync.

```php
$silent = new Notification($payload, $token);
$silent->setLowPriority(); // e.g. background sync
```

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

### generateApnsTopic example

Source: https://github.com/edamov/pushok

Example usage of generateApnsTopic with 'voip' push type, returning 'com.app.Test.voip'.

```php
$topic = $provider->generateApnsTopic('voip'); // "com.app.Test.voip"
```

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

### Example: full notification configuration

Source: https://github.com/edamov/pushok

Demonstrates configuring a notification with ID, expiration, high priority, and collapse ID, then adding it to a client.

```php
use Pushok\Notification;

$notification = new Notification($payload, $deviceToken);
$notification
    ->setId('123e4567-e89b-12d3-a456-4266554400a0')
    ->setExpirationAt(new DateTime('+1 day'))
    ->setHighPriority()
    ->setCollapseId('news-update');

$client->addNotification($notification);
```

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

### Example: setting a sound

Source: https://github.com/edamov/pushok

Creates a `Sound` object with name 'alarm.caf', critical flag, and volume, then assigns it to the payload.

```php
$sound = Sound::create()->setName('alarm.caf')->setCritical(1)->setVolume(0.8);
$payload->setSound($sound);
```

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

### getReasonPhrase example usage

Source: https://github.com/edamov/pushok

Example showing the phrase returned for status codes 200 and 410.

```php
$phrase = $response->getReasonPhrase();
// 200 -> "Success." | 410 -> "The device token is no longer active for the topic."
```

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

### setAutoCloseConnections usage example

Source: https://github.com/edamov/pushok

Example showing how to keep connections alive for high-frequency sending by setting auto-close to false, then pushing notifications in a loop and closing manually.

```php
// Keep connections alive for high-frequency sending
$client->setAutoCloseConnections(false);

while ($moreWork) {
    $client->addNotifications($batch);
    $client->push();
}
$client->close();
```

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

### toJson example with error handling

Source: https://github.com/edamov/pushok

Creates an alert with title, body, and launch image, then outputs the JSON.

```php
$alert = Alert::create()
    ->setTitle('Game')
    ->setBody('Your turn')
    ->setLaunchImage('Default.png');

$json = $alert->toJson();
echo $json; // {"title":"Game","body":"Your turn","launch-image":"Default.png"}
```

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

### Create a basic Sound object

Source: https://github.com/edamov/pushok

Static factory `create()` returns a new empty `Sound`. The constructor is protected, so use `create()` to instantiate. This example chains `setName()`, `setCritical()`, and `setVolume()` to configure a sound.

```php
$sound = Sound::create()
    ->setName('alarm.caf')
    ->setCritical(1)
    ->setVolume(0.8);
```

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

### Token::create basic example

Source: https://github.com/edamov/pushok

Creates a Token provider using a private key file path. Requires key_id, team_id, app_bundle_id, and private_key_path options.

```php
$authProvider = Token::create([
    'key_id' => 'AAAABBBBCC',
    'team_id' => 'DDDDEEEEFF',
    'app_bundle_id' => 'com.app.Test',
    'private_key_path' => __DIR__ . '/private_key.p8',
    'private_key_secret' => null,
]);
```

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

### setMaxConcurrentConnections usage example

Source: https://github.com/edamov/pushok

Example call to set the maximum number of concurrent connections to 5.

```php
$client->setMaxConcurrentConnections(5);
```

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

### setNbConcurrentRequests usage example

Source: https://github.com/edamov/pushok

Example call to set the number of concurrent requests to 40.

```php
$client->setNbConcurrentRequests(40);
```

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

### Basic Request instantiation example

Source: https://github.com/edamov/pushok

Creates a Request for a development environment. The resulting URI points to the APNs development server with the device token.

```php
$request = new Request($notification, $production = false);
// $request->getUri() === 'https://api.development.push.apple.com/3/device/<device_token>'
```

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

### Send push notification using JWT token authentication

Source: https://github.com/edamov/pushok/blob/master/README.md

Complete example of sending push notifications using JWT token authentication. Requires the private key, key ID, team ID, and app bundle ID. The token expires after one hour, so regenerate it for long-running tasks. The example shows how to create the auth provider, build a payload, add notifications, and handle responses.

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use Pushok\AuthProvider;
use Pushok\Client;
use Pushok\Notification;
use Pushok\Payload;
use Pushok\Payload\Alert;

$options = [
    'key_id' => 'AAAABBBBCC', // The Key ID obtained from Apple developer account
    'team_id' => 'DDDDEEEEFF', // The Team ID obtained from Apple developer account
    'app_bundle_id' => 'com.app.Test', // The bundle ID for app obtained from Apple developer account
    'private_key_path' => __DIR__ . '/private_key.p8', // Path to private key
    'private_key_secret' => null // Private key secret
];

// Be aware of thing that Token will stale after one hour, so you should generate it again.
// Can be useful when trying to send pushes during long-running tasks
$authProvider = AuthProvider\Token::create($options);

$alert = Alert::create()->setTitle('Hello!');
$alert = $alert->setBody('First push notification');

$payload = Payload::create()->setAlert($alert);

//set notification sound to default
$payload->setSound('default');

//add custom value to your notification, needs to be customized
$payload->setCustomValue('key', 'value');

$deviceTokens = ['<device_token_1>', '<device_token_2>', '<device_token_3>'];

$notifications = [];
foreach ($deviceTokens as $deviceToken) {
    $notifications[] = new Notification($payload,$deviceToken);
}

// If you have issues with ssl-verification, you can temporarily disable it. Please see attached note.
// Disable ssl verification
// $client = new Client($authProvider, $production = false, [CURLOPT_SSL_VERIFYPEER=>false] );
$client = new Client($authProvider, $production = false);
$client->addNotifications($notifications);



$responses = $client->push(); // returns an array of ApnsResponseInterface (one Response per Notification)

foreach ($responses as $response) {
    // The device token
    $response->getDeviceToken();
    // A canonical UUID that is the unique ID for the notification. E.g. 123e4567-e89b-12d3-a456-4266554400a0
    $response->getApnsId();
    
    // Status code. E.g. 200 (Success), 410 (The device token is no longer active for the topic.)
    $response->getStatusCode();
    // E.g. The device token is no longer active for the topic.
    $response->getReasonPhrase();
    // E.g. Unregistered
    $response->getErrorReason();
    // E.g. The device token is inactive for the specified topic.
    $response->getErrorDescription();
    $response->get410Timestamp();
}
```

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

### Basic Notification example

Source: https://github.com/edamov/pushok

Instantiates a Notification with a payload and a device token placeholder. The device token should be replaced with an actual token.

```php
$notification = new Notification($payload, '<device_token>');
```

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

### setCustomValue error handling example

Source: https://github.com/edamov/pushok

Example of catching InvalidPayloadException when attempting to set the reserved 'aps' key. Outputs the exception message.

```php
try {
    $payload->setCustomValue('aps', 'blocked'); // reserved
} catch (\Pushok\InvalidPayloadException $e) {
    echo $e->getMessage(); // "Key aps is reserved and can't be used for custom property."
}
```

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

### setCustomValue example

Source: https://github.com/edamov/pushok

Example usage of setCustomValue to add a custom key-value pair to the payload.

```php
$payload->setCustomValue('key', 'value');
```

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

### Example: using getDecoratedHeaders with curl_setopt

Source: https://github.com/edamov/pushok

Shows how to pass the decorated headers to CURLOPT_HTTPHEADER.

```php
curl_setopt($ch, CURLOPT_HTTPHEADER, $request->getDecoratedHeaders());
```

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

### Example using Alert object with setAlert

Source: https://github.com/edamov/pushok

Creates an Alert with title and body, then assigns it to the payload.

```php
$alert = Alert::create()->setTitle('Hello!')->setBody('First push');
$payload->setAlert($alert);
```

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

### Example: passing AuthProviderInterface to Client

Source: https://github.com/edamov/pushok

Shows how to build a `Client` with an `AuthProviderInterface` instance. The `Client` constructor requires the provider and `prepareHandle()` invokes `authenticateClient($request)` before sending.

```php
use Pushok\AuthProviderInterface;
use Pushok\Client;

function buildClient(AuthProviderInterface $provider): Client {
    return new Client($provider, false);
}

$client = buildClient(AuthProvider\Token::create($options));
```

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

### setLaunchImage / getLaunchImage

Source: https://github.com/edamov/pushok

Sets or gets the filename of an image file in the app bundle.

```APIDOC
## setLaunchImage / getLaunchImage

### Description
Sets or gets the filename of an image file in the app bundle (with or without the extension).

### Methods
- `setLaunchImage(string $value)`
- `getLaunchImage()`

### Parameters
- `$value` (string) - Required - Filename of the image.

### Returns
- `setLaunchImage`: Returns the instance (`$this`) for chaining.
- `getLaunchImage`: The filename.
```

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

### Token::useExisting example

Source: https://github.com/edamov/pushok

Creates a Token provider with an existing JWT token string. Only key_id, team_id, app_bundle_id, and private_key_* options matter since no new key is generated.

```php
$authProvider = Token::useExisting($token, [
    'key_id' => 'AAAABBBBCC',
    'team_id' => 'DDDDEEEEFF',
    'app_bundle_id' => 'com.app.Test',
    'private_key_path' => __DIR__ . '/private_key.p8',
]);
```

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

### Iterate over responses from Client::push()

Source: https://github.com/edamov/pushok

Basic example showing how to iterate over the responses returned by Client::push() and output the status code and device token for each response.

```php
$responses = $client->push();
foreach ($responses as $response) {
    echo $response->getStatusCode();
    echo $response->getDeviceToken();
}
```

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

### Create a critical Sound and serialize to JSON

Source: https://github.com/edamov/pushok

Advanced example: creates a `Sound` with critical flag, name, and volume, then sets it on a `Payload` and calls `toJson()`. The output shows the JSON structure with all three properties set.

```php
$sound = Sound::create()->setName('critical.caf')->setCritical(1)->setVolume(1.0);

// Use it as the payload sound
$payload->setSound($sound);
echo $sound->toJson(); // {"critical":1,"name":"critical.caf","volume":1.0}
```

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

### setId usage example

Source: https://github.com/edamov/pushok

Sets the notification UUID and collapse ID in a fluent chain.

```php
$notification
    ->setId('123e4567-e89b-12d3-a456-4266554400a0')
    ->setCollapseId('a-game');
```

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

### setPushType usage example

Source: https://github.com/edamov/pushok

Sets the push type to 'voip'.

```php
$payload->setPushType('voip');
```

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

### getUrlArgs / setUrlArgs

Source: https://github.com/edamov/pushok

Gets or sets the `url-args` for Safari notifications.

```APIDOC
## getUrlArgs / setUrlArgs

### Description
Gets or sets the `url-args` for Safari notifications.

### Method
getUrlArgs()
setUrlArgs(array $value): Payload

### Parameters
- **$value** (array) - Required - The URL arguments array.

### Returns
- `getUrlArgs` returns `array|null`; `setUrlArgs` returns `Payload`.
```

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

### Example: iterating responses from Client::push()

Source: https://github.com/edamov/pushok

Shows how to iterate over the array of `ApnsResponseInterface` returned by `Client::push()` and access each response's device token, APNs id, status code, and error description.

```php
$responses = $client->push(); // array of ApnsResponseInterface
foreach ($responses as $response) {
    echo $response->getDeviceToken();
    echo $response->getApnsId();
    echo $response->getStatusCode();
    echo $response->getErrorDescription();
}
```

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

### setLocKey / getLocKey

Source: https://github.com/edamov/pushok

Sets or gets the key to an alert-message string in Localizable.strings.

```APIDOC
## setLocKey / getLocKey

### Description
Sets or gets the key to an alert-message string in `Localizable.strings`.

### Methods
- `setLocKey(string $value): Alert`
- `getLocKey()`

### Parameters
- `$value` (string) - Required - The key to the alert-message string.

### Returns
- `setLocKey`: Alert instance for chaining.
- `getLocKey`: The key value.
```

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

### setLocKey / getLocKey methods

Source: https://github.com/edamov/pushok

Set or get the key to an alert-message string in Localizable.strings.

```php
public function setLocKey(string $value): Alert
```

```php
public function getLocKey()
```

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

### authenticateClient() example

Source: https://github.com/edamov/pushok

Decorates a Request with the TLS client certificate and apns-topic header. The request is created with a notification and false for the second argument.

```php
$request = new Request($notification, false);
$authProvider->authenticateClient($request);
```

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

### Payload::create()

Source: https://github.com/edamov/pushok

Creates a new Payload instance for building the push notification payload. This is the starting point for constructing the notification content.

```APIDOC
## Payload::create()

### Description
Creates a new Payload instance for building the push notification payload. This is the starting point for constructing the notification content.

### Method
create

### Endpoint
Payload::create()

### Parameters
None explicitly documented.

### Response
Returns a Payload instance.

### Request Example
```php
$payload = Payload::create()->setAlert('Hello')->setSound('default');
```
```

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

### setLaunchImage / getLaunchImage methods

Source: https://github.com/edamov/pushok

Set or get the filename of an image file in the app bundle (with or without extension). setLaunchImage has no declared return type but returns the instance ($this).

```php
public function setLaunchImage(string $value)
```

```php
public function getLaunchImage()
```

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

### get(): string

Source: https://github.com/edamov/pushok

Returns the token currently held by the provider (the last generated or supplied token).

```APIDOC
## get(): string

### Description
Returns the token currently held by the provider (the last generated or supplied token).

### Method
`get`

### Returns
- **string** - The JWT token.

### Example
```php
$tokenString = $authProvider->get();
$client = new Client(Token::useExisting($tokenString, $options));
```

### Source
`src/AuthProvider/Token.php:175`
```

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

### setLocArgs / getLocArgs

Source: https://github.com/edamov/pushok

Sets or gets variable strings that replace format specifiers in loc-key.

```APIDOC
## setLocArgs / getLocArgs

### Description
Sets or gets variable strings that replace format specifiers in `loc-key`.

### Methods
- `setLocArgs(array $value): Alert`
- `getLocArgs()`

### Parameters
- `$value` (array) - Required - Array of variable strings.

### Returns
- `setLocArgs`: Alert instance for chaining.
- `getLocArgs`: `string[]` - Array of variable strings.
```

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

### setName / getName

Source: https://github.com/edamov/pushok

Sets or gets the sound file name (e.g., 'default' or a bundled .caf file). The setter is fluent and returns the Sound instance for chaining.

```APIDOC
## setName / getName

### Description
Sets or gets the sound file name (e.g., 'default' or a bundled .caf file). The setter is fluent and returns the Sound instance for chaining.

### Methods
- `public function setName(string $value): Sound`
- `public function getName()`

### Parameters
#### setName
- `$value` (string) - Required - The sound file name.

### Returns
- `setName` returns `Sound` (fluent).
- `getName` returns the sound file name (string).
```

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

### setVolume / getVolume

Source: https://github.com/edamov/pushok

Sets or gets the sound playback volume (0.0 – 1.0). The setter is fluent and returns the Sound instance for chaining.

```APIDOC
## setVolume / getVolume

### Description
Sets or gets the sound playback volume (0.0 – 1.0). The setter is fluent and returns the Sound instance for chaining.

### Methods
- `public function setVolume(float $value): Sound`
- `public function getVolume()`

### Parameters
#### setVolume
- `$value` (float) - Required - The volume value between 0.0 and 1.0.

### Returns
- `setVolume` returns `Sound` (fluent).
- `getVolume` returns the volume value (float).
```

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

### Example using get410Timestamp

Source: https://github.com/edamov/pushok

Echoes the timestamp when the response status code is APNS_NOT_ACTIVE_DEVICE_TOKEN_, indicating when the device token was last active.

```php
if ($response->getStatusCode() === Response::APNS_NOT_ACTIVE_DEVICE_TOKEN_) {
    echo $response->get410Timestamp(); // when the device token was last active
}
```

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

### getCustomValue error handling example

Source: https://github.com/edamov/pushok

Shows how to catch InvalidPayloadException when the key is missing. The exception message is "Custom value with key 'missing-key' doesn't exist."

```php
try {
    $value = $payload->getCustomValue('missing-key');
} catch (\Pushok\InvalidPayloadException $e) {
    echo $e->getMessage(); // "Custom value with key 'missing-key' doesn't exist."
}
```

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

### setLocArgs / getLocArgs methods

Source: https://github.com/edamov/pushok

Set or get variable strings replacing format specifiers in loc-key. Returns string[].

```php
public function setLocArgs(array $value): Alert
```

```php
public function getLocArgs()
```

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

### toJson error handling example

Source: https://github.com/edamov/pushok

Demonstrates catching `InvalidPayloadException` when the payload exceeds size limits. The error message is either "Payload size limit exceeded" or "Voip Payload size limit exceeded".

```php
try {
    $json = $payload->toJson();
} catch (\Pushok\InvalidPayloadException $e) {
    // "Payload size limit exceeded" or "Voip Payload size limit exceeded"
    fwrite(STDERR, $e->getMessage());
}
```

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

### Error handling example using getErrorDescription

Source: https://github.com/edamov/pushok

Logs an error when the response status code is not APNS_SUCCESS, including status code, reason phrase, error reason, and error description.

```php
if ($response->getStatusCode() !== Response::APNS_SUCCESS) {
    error_log(sprintf(
        '[%d] %s (%s): %s',
        $response->getStatusCode(),
        $response->getReasonPhrase(),
        $response->getErrorReason(),
        $response->getErrorDescription()
    ));
}
```

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

### Configure client concurrency and push notifications

Source: https://github.com/edamov/pushok/blob/master/README.md

Shows how to create a client, add notifications, and adjust concurrency settings. The default number of concurrent requests is 20, and the default maximum concurrent connections is 1. The push() method returns an array of responses.

```php
<?php

$client = new Client($authProvider, $production = false);
$client->addNotifications($notifications);


// Set the number of concurrent requests sent through the multiplexed connections. Default : 20
$client->setNbConcurrentRequests( 40 );

// Set the number of maximum concurrent connections established to the APNS servers. Default : 1
$client->setMaxConcurrentConnections( 5 );


$responses = $client->push();
```

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

### setExpirationAt usage example

Source: https://github.com/edamov/pushok

Sets the expiration date to one hour from now.

```php
$notification->setExpirationAt(new DateTime('+1 hour'));
```

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

### Basic Client instantiation with Token auth provider

Source: https://github.com/edamov/pushok

Creates a Token auth provider and a Client for the APNs sandbox environment. The $production variable is set to false, directing requests to the development server.

```php
use Pushok\AuthProvider;
use Pushok\Client;

$authProvider = AuthProvider\Token::create([
    'key_id' => 'AAAABBBBCC',
    'team_id' => 'DDDDEEEEFF',
    'app_bundle_id' => 'com.app.Test',
    'private_key_path' => __DIR__ . '/private_key.p8',
    'private_key_secret' => null,
]);

// Sandbox environment for development
$client = new Client($authProvider, $production = false);
```

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

### getDismissalDate(): int|null

Source: https://github.com/edamov/pushok

Gets the `dismissal-date` attribute. Returns null if not set.

```APIDOC
## `getDismissalDate`

### Description
Gets the `dismissal-date` attribute.

### Method
`getDismissalDate`

### Signature
```php
public function getDismissalDate(): int|null
```

### Returns
- `int|null` - The dismissal date value, or null if not set.

```

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

### getThreadId / setThreadId

Source: https://github.com/edamov/pushok

Gets or sets the app-specific identifier for grouping notifications.

```APIDOC
## getThreadId / setThreadId

### Description
Gets or sets the app-specific identifier for grouping notifications.

### Method
getThreadId()
setThreadId(string $value): Payload

### Parameters
- **$value** (string) - Required - The thread identifier.

### Returns
- `getThreadId` returns the thread identifier; `setThreadId` returns `Payload`.
```

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

### getCategory / setCategory

Source: https://github.com/edamov/pushok

Gets or sets the notification category (action identifier).

```APIDOC
## getCategory / setCategory

### Description
Gets or sets the notification category (action identifier).

### Method
getCategory()
setCategory(string $value): Payload

### Parameters
- **$value** (string) - Required - The category identifier.

### Returns
- `getCategory` returns the category value; `setCategory` returns `Payload`.
```

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

### Pushok\Client::__construct(...)

Source: https://github.com/edamov/pushok

Constructs a Pushok Client instance with an auth provider, environment flag, and optional curl options.

```APIDOC
## Client::__construct(...)

### Description
Constructs a Pushok Client instance for sending push notifications to APNs.

### Method
__construct

### Parameters
- **$authProvider** (AuthProviderInterface) - Required - Auth provider instance.
- **$isProductionEnv** (bool) - Optional - `true` → production APNs; `false` → sandbox/development APNs. Default: `false`.
- **$curlOptions** (array) - Optional - Extra curl options merged (`array +`) over the per-request defaults, e.g. `[CURLOPT_SSL_VERIFYPEER => false]`. Default: `[]`.

### Response
#### Success Response
Returns a `Client` instance.
```

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

### Sound::create

Source: https://github.com/edamov/pushok

Static factory method that creates a new empty Sound object. The constructor is protected, so this is the only way to instantiate a Sound.

```APIDOC
## Sound::create

### Description
Static factory method that creates a new empty Sound object. The constructor is protected, so this is the only way to instantiate a Sound.

### Method
`public static function create()`

### Returns
- `Sound` - A new empty sound object.

### Request Example
```php
$sound = Sound::create()
    ->setName('alarm.caf')
    ->setCritical(1)
    ->setVolume(0.8);
```
```

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

### Create Alert with title and body

Source: https://github.com/edamov/pushok

Use the static factory `Alert::create()` to instantiate a new alert, then chain `setTitle()` and `setBody()` to set the notification content. The constructor is protected, so `create()` is the only way to instantiate.

```php
$alert = Alert::create()
    ->setTitle('Hello!')
    ->setBody('First push notification');
```

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

### Basic push() usage

Source: https://github.com/edamov/pushok

Add notifications to the client, call push(), and iterate over the responses to print each status code.

```php
$client->addNotifications($notifications);
$responses = $client->push(); // array of Response

foreach ($responses as $response) {
    echo $response->getStatusCode();
}
```

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

### Pushok\AuthProvider\Certificate::create($options)

Source: https://github.com/edamov/pushok

Creates a Certificate auth provider instance using certificate-based authentication. Accepts an options array with certificate_path, certificate_secret, and optionally app_bundle_id.

```APIDOC
## Certificate::create($options)

### Description
Creates a Certificate auth provider instance for certificate-based authentication with Apple Push Notification service.

### Method
create

### Parameters
#### Options Array
- **certificate_path** (string) - Required - Path to the `.pem` / `.der` / `.p12` certificate.
- **certificate_secret** (string) - Required - Certificate passphrase.
- **app_bundle_id** (string) - Optional - App bundle ID (basis for the `apns-topic` header).

### Response
#### Success Response
Returns a `Certificate` instance.
```

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

### Token::create with inline key content and error handling

Source: https://github.com/edamov/pushok

Creates a Token provider using inline private key content read from a file. Catches \InvalidArgumentException and prints the message, e.g., 'Unable to find private key.' if the key cannot be located.

```php
try {
    $authProvider = Token::create([
        'key_id' => 'AAAABBBBCC',
        'team_id' => 'DDDDEEEEFF',
        'app_bundle_id' => 'com.app.Test',
        'private_key_content' => file_get_contents('private_key.p8'),
    ]);
} catch (\InvalidArgumentException $e) {
    // "Unable to find private key." if the key cannot be located
    echo $e->getMessage();
}
```

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

### setContentState / getContentState

Source: https://github.com/edamov/pushok

Sets or gets the content-state for the payload, an array serialized only when countable and non-empty.

```APIDOC
## setContentState / getContentState

### Description
Sets or gets `content-state` (an `array`). Serialized only when countable and non-empty.

### Method
- `setContentState($contentState)` - Sets the content state.
- `getContentState()` - Gets the content state.

### Parameters
#### setContentState
- `$contentState` (mixed) - Required - The content state array.

### Response
#### getContentState
Returns the content state array.
```

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

### setTimestamp / getTimestamp

Source: https://github.com/edamov/pushok

Sets or gets the timestamp for the payload, a double value only serialized when it is an integer.

```APIDOC
## setTimestamp / getTimestamp

### Description
Sets or gets `timestamp` (a `double`). Only serialized when the value is an `int`.

### Method
- `setTimestamp($timestamp)` - Sets the timestamp.
- `getTimestamp()` - Gets the timestamp.

### Parameters
#### setTimestamp
- `$timestamp` (mixed) - Required - The timestamp value.

### Response
#### getTimestamp
Returns the timestamp value.
```

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

### Client instantiation with production environment and curl options

Source: https://github.com/edamov/pushok

Creates a Client for the production APNs server with custom curl options, disabling SSL peer verification. The $authProvider variable is assumed to be defined earlier.

```php
$client = new Client($authProvider, true, [CURLOPT_SSL_VERIFYPEER => false]);
```

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

### Pushok\AuthProvider\Token::create($options)

Source: https://github.com/edamov/pushok

Creates a Token auth provider instance using JWT-based authentication. Accepts an options array with key_id, team_id, app_bundle_id, and either private_key_path or private_key_content.

```APIDOC
## Token::create($options)

### Description
Creates a Token auth provider instance for JWT-based authentication with Apple Push Notification service.

### Method
create

### Parameters
#### Options Array
- **key_id** (string) - Required - Key ID from Apple developer account (JWT `kid`).
- **team_id** (string) - Required - Team ID from Apple developer account (JWT `iss`).
- **app_bundle_id** (string) - Required - App bundle ID (basis for the `apns-topic` header).
- **private_key_path** (string|null) - One of `private_key_path` / `private_key_content` - Path to the `.p8` private key.
- **private_key_content** (string|null) - One of `private_key_path` / `private_key_content` - Inline private key data (takes precedence when both are set).
- **private_key_secret** (string|null) - Optional - Private key passphrase.

### Response
#### Success Response
Returns a `Token` instance.

#### Error Response
Throws `\InvalidArgumentException` if neither `private_key_path` nor `private_key_content` is provided.
```

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

### AuthProvider\Token::create()

Source: https://github.com/edamov/pushok

Creates a JWT-based authentication provider using the provided options array. This is used to authenticate with APNs using a private key.

```APIDOC
## AuthProvider\Token::create()

### Description
Creates a JWT-based authentication provider using the provided options array. This is used to authenticate with APNs using a private key.

### Method
create

### Endpoint
AuthProvider\Token::create()

### Parameters
#### Request Body
- **key_id** (string) - Required - The key ID from Apple.
- **team_id** (string) - Required - The team ID.
- **app_bundle_id** (string) - Required - The app bundle identifier.
- **private_key_path** (string) - Required - Path to the private key file.
- **private_key_secret** (string|null) - Optional - The private key secret.

### Response
Returns an AuthProvider\Token instance.

### Request Example
```php
$authProvider = AuthProvider\Token::create([
    'key_id' => 'AAAABBBBCC',
    'team_id' => 'DDDDEEEEFF',
    'app_bundle_id' => 'com.app.Test',
    'private_key_path' => __DIR__ . '/private_key.p8',
    'private_key_secret' => null,
]);
```
```

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

### setEvent / getEvent

Source: https://github.com/edamov/pushok

Sets or gets the event for the payload, a string used with content-state for Live Activities.

```APIDOC
## setEvent / getEvent

### Description
Sets or gets `event` (a `string`, used with `content-state` for Live Activities).

### Method
- `setEvent($event)` - Sets the event.
- `getEvent()` - Gets the event.

### Parameters
#### setEvent
- `$event` (mixed) - Required - The event string.

### Response
#### getEvent
Returns the event string.
```

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

### setRelevanceScore / getRelevanceScore

Source: https://github.com/edamov/pushok

Sets or gets the relevance-score for the payload, a double value serialized as a float when numeric.

```APIDOC
## setRelevanceScore / getRelevanceScore

### Description
Sets or gets the `relevance-score` (a `double`; serialized via `(float)` cast when `is_numeric`).

### Method
- `setRelevanceScore($relevanceScore)` - Sets the relevance score.
- `getRelevanceScore()` - Gets the relevance score.

### Parameters
#### setRelevanceScore
- `$relevanceScore` (mixed) - Required - The relevance score value.

### Response
#### getRelevanceScore
Returns the relevance score value.
```

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

### getOptions method

Source: https://github.com/edamov/pushok

Returns the current curl options as an array.

```php
public function getOptions(): array
```

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

### Request::prepareApnsHeaders()

Source: https://github.com/edamov/pushok

Prepares the APNs request headers for a notification. It sets the apns-push-type, apns-id, apns-expiration, apns-priority, apns-collapse-id, apns-topic, and Authorization headers based on the notification and auth provider.

```APIDOC
## Request::prepareApnsHeaders()

### Description
Prepares the APNs request headers for a notification. It sets the apns-push-type, apns-id, apns-expiration, apns-priority, apns-collapse-id, apns-topic, and Authorization headers based on the notification and auth provider.

### Method
N/A (PHP method)

### Endpoint
N/A (PHP method)

### Parameters
#### Headers
- **apns-push-type** (string) - Required - Payload push type if set; else `background` when content-available; else `alert`
- **apns-id** (string) - Optional - `Notification::getId()`; only when non-empty
- **apns-expiration** (integer) - Optional - `Notification::getExpirationAt()` epoch timestamp; only when a `DateTime` was set
- **apns-priority** (integer) - Optional - Notification priority; else `5` if content-available; only when set
- **apns-collapse-id** (string) - Optional - `Notification::getCollapseId()`; only when non-empty
- **apns-topic** (string) - Required - Auth provider `generateApnsTopic(pushType)`; always (added by provider)
- **Authorization** (string) - Required - `bearer <jwt>` (Token provider); always for JWT auth

### Response
#### Success Response (200)
No response body; headers are set on the request object.
```

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

### getCollapseId / setCollapseId

Source: https://github.com/edamov/pushok

Gets or sets the coalescing identifier used to group similar notifications, sent as the apns-collapse-id header.

```APIDOC
## getCollapseId / setCollapseId

### Description
Gets or sets the coalescing identifier used to group similar notifications, sent as the apns-collapse-id header.

### Methods
- `getCollapseId()`
- `setCollapseId(string $collapseId): Notification`

### Parameters
#### setCollapseId
- `$collapseId` (string) - Required - Coalescing identifier.

### Returns
- `setCollapseId` returns `Notification` (fluent); `getCollapseId` returns `string|null`.

### Example (full notification configuration)
```php
use Pushok\Notification;

$notification = new Notification($payload, $deviceToken);
$notification
    ->setId('123e4567-e89b-12d3-a456-4266554400a0')
    ->setExpirationAt(new DateTime('+1 day'))
    ->setHighPriority()
    ->setCollapseId('news-update');

$client->addNotification($notification);
```
```

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

### Alert::create()

Source: https://github.com/edamov/pushok

Static factory method that creates a new empty Alert instance. The constructor is protected, so this is the primary way to instantiate an Alert object.

```APIDOC
## Alert::create()

### Description
Static factory method that creates a new empty Alert instance. The constructor is protected, so this is the primary way to instantiate an Alert object.

### Method
`create` (static)

### Signature
```php
public static function create()
```

### Returns
- **Alert** - A new empty alert.

### Request Example
```php
$alert = Alert::create()
    ->setTitle('Hello!')
    ->setBody('First push notification');
```
```

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

### setDismissalDate and getDismissalDate method signatures

Source: https://github.com/edamov/pushok

Sets and gets the `dismissal-date` attribute. The value is serialized (cast to int) when truthy.

```php
public function setDismissalDate(int $value): Payload
```

```php
public function getDismissalDate(): int|null
```

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

### Client::__construct

Source: https://github.com/edamov/pushok

Creates a new Client instance for sending push notifications to APNs. The constructor stores the authentication provider, environment flag, and curl options without opening any connection.

```APIDOC
## Client::__construct

### Description
Creates a new Client instance for sending push notifications to APNs. The constructor stores the authentication provider, environment flag, and curl options without opening any connection.

### Method
Constructor

### Signature
```php
public function __construct(AuthProviderInterface $authProvider, bool $isProductionEnv = false, array $curlOptions = array())
```

### Parameters
- `$authProvider` (AuthProviderInterface) - Required - Authentication provider used to add `apns-topic` and credential headers to each request.
- `$isProductionEnv` (bool) - Optional - Default: `false` - When `false` requests go to the APNs sandbox (development) server; when `true` they go to the production server.
- `$curlOptions` (array) - Optional - Default: `[]` - Extra curl options (e.g. `[CURLOPT_SSL_VERIFYPEER => false]`) merged over the options the library builds per request.

### Request Example
```php
use Pushok\AuthProvider;
use Pushok\Client;

$authProvider = AuthProvider\Token::create([
    'key_id' => 'AAAABBBBCC',
    'team_id' => 'DDDDEEEEFF',
    'app_bundle_id' => 'com.app.Test',
    'private_key_path' => __DIR__ . '/private_key.p8',
    'private_key_secret' => null,
]);

// Sandbox environment for development
$client = new Client($authProvider, $production = false);
```

### Request Example (production + per-request curl options)
```php
$client = new Client($authProvider, true, [CURLOPT_SSL_VERIFYPEER => false]);
```
```

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

### setAttributesType / getAttributesType

Source: https://github.com/edamov/pushok

Sets or gets the attributes-type interpreter for Live Activities. When attributesType is truthy, both attributes-type and attributes are serialized.

```APIDOC
## setAttributesType / getAttributesType

### Description
Sets the interpreter for the `attributes`-type (used with Live Activities). When `attributesType` is truthy, both `attributes-type` and `attributes` are serialized.

### Method
- `setAttributesType(string $attributesType): self` - Sets the attributes type.
- `getAttributesType(): string|null` - Gets the attributes type.

### Parameters
#### setAttributesType
- `$attributesType` (string) - Required - The attributes type string.

### Response
#### getAttributesType
Returns the attributes type string or null.
```

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

### Token::create()

Source: https://github.com/edamov/pushok

Creates a new Token authentication provider instance using the provided options array. This is the primary factory method for obtaining a Token instance.

```APIDOC
## Token::create()

### Description
Creates a new Token authentication provider instance using the provided options array. This is the primary factory method for obtaining a Token instance.

### Method
`Token::create()`

### Parameters
#### Options Array
- **key_id** (string) - Required - The Key ID obtained from Apple developer account (used as JWT `kid`).
- **team_id** (string) - Required - The Team ID obtained from Apple developer account (used as JWT `iss`).
- **app_bundle_id** (string) - Required - The app bundle ID (used to build the `apns-topic` header).
- **private_key_path** (string|null) - Optional (one of path/content) - Path to the `.p8` private key.
- **private_key_content** (string|null) - Optional (one of path/content) - Inline private key data (alternative to `private_key_path`).
- **private_key_secret** (string|null) - Optional - Private key secret (passphrase) — defaults to `null`.

### Response
Returns a new `Token` instance.
```

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

### setStaleDate / getStaleDate

Source: https://github.com/edamov/pushok

Sets or gets the stale-date for the payload, a double value only serialized when it is an integer (whole-number epoch timestamp).

```APIDOC
## setStaleDate / getStaleDate

### Description
Sets or gets `stale-date` (a `double`). Only serialized when the value is an `int` (i.e. a whole-number epoch timestamp).

### Method
- `setStaleDate($staleDate)` - Sets the stale date.
- `getStaleDate()` - Gets the stale date.

### Parameters
#### setStaleDate
- `$staleDate` (mixed) - Required - The stale date value.

### Response
#### getStaleDate
Returns the stale date value.
```

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

### Certificate::create

Source: https://github.com/edamov/pushok

Creates a Certificate auth provider instance. This static factory method is the only way to instantiate the provider since the constructor is private.

```APIDOC
## Certificate::create

### Description
Creates a Certificate auth provider instance. This static factory method is the only way to instantiate the provider since the constructor is private.

### Method
`public static function create(array $options): Certificate`

### Parameters
- `$options` (array) - Required - Provider options. Supported keys:
  - `certificate_path` (string) - Required - Path to the certificate file (`.pem`, `.der`, or `.p12`).
  - `certificate_secret` (string) - Required - Certificate passphrase / secret.
  - `app_bundle_id` (string) - Optional - The app bundle ID, used to build the `apns-topic` header.

### Returns
- `Certificate` - A configured certificate provider.

### Request Example
```php
$authProvider = Certificate::create([
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/private_key.pem',
    'certificate_secret' => null,
]);
```
```

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

### setCritical / getCritical

Source: https://github.com/edamov/pushok

Sets or gets whether the sound plays as a critical alert. The setter is fluent and returns the Sound instance for chaining.

```APIDOC
## setCritical / getCritical

### Description
Sets or gets whether the sound plays as a critical alert. The setter is fluent and returns the Sound instance for chaining.

### Methods
- `public function setCritical(int $value): Sound`
- `public function getCritical()`

### Parameters
#### setCritical
- `$value` (int) - Required - The critical flag value (1 for critical, 0 otherwise).

### Returns
- `setCritical` returns `Sound` (fluent).
- `getCritical` returns the critical value (int).
```

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

### Certificate::create() basic usage

Source: https://github.com/edamov/pushok

Creates a certificate-based APNs auth provider. The constructor is private, so use this static factory. The certificate_secret can be null.

```php
$authProvider = Certificate::create([
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/private_key.pem',
    'certificate_secret' => null,
]);
```
Tokens:
Raw