### 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
```

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

### generateApnsTopic() usage examples

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Token.md

Shows example calls to generateApnsTopic with different push types, producing the documented suffixed bundle IDs.

```php
$authProvider->generateApnsTopic('voip');          // com.app.Test.voip
$authProvider->generateApnsTopic('liveactivity');  // com.app.Test.push-type.liveactivity
$authProvider->generateApnsTopic('alert');         // com.app.Test
```

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

### Custom values with error handling example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Shows how to set and get custom values, catching InvalidPayloadException for missing keys and reserved key 'aps'. The first try block echoes 42 and then throws for 'missing'; the second try block throws for 'aps'.

```php
use Pushok\InvalidPayloadException;

$payload = Payload::create()->setCustomValue('user_id', 42);

try {
    echo $payload->getCustomValue('user_id');     // 42
    echo $payload->getCustomValue('missing');     // throws
} catch (InvalidPayloadException $e) {
    // "Custom value with key 'missing' doesn't exist."
}

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

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

### Live Activity payload example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Example of building a Live Activity payload using the fluent setters. It sets the event to 'update', content state with a score, timestamp, stale date, attributes type, and an attribute.

```php
$payload = Payload::create()
    ->setEvent('update')
    ->setContentState(['score' => 10])
    ->setTimestamp(time())
    ->setStaleDate(time() + 3600)
    ->setAttributesType('ActivityAttributes')
    ->addAttribute('team', 'home');
```

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

### setMaxConcurrentConnections usage example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Client.md

Example of setting the maximum concurrent connections to 5.

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

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

### 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);

...
```

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

### Usage example: creating a notification with collapse ID and high priority

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Notification.md

Example of creating a Notification, setting the collapse ID to 'sports', setting high priority, and adding it to the client for pushing.

```php
use Pushok\Notification;

$notification = new Notification($payload, $deviceToken);
$notification->setCollapseId('sports');
$notification->setHighPriority();

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

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

### Fluent Payload build with Alert

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Fluent example showing how to build a Payload with an Alert, sound, badge, and custom value. Requires the Pushok\Payload and Pushok\Payload\Alert classes.

```php
use Pushok\Payload;
use Pushok\Payload\Alert;

$payload = Payload::create()
    ->setAlert(Alert::create()->setTitle('Hello!')->setBody('First push notification'))
    ->setSound('default')
    ->setBadge(3)
    ->setCustomValue('key', 'value');
```

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

### notExistingCustomValue() usage example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/InvalidPayloadException.md

Example of catching the InvalidPayloadException thrown by getCustomValue() when the key is not present.

```php
$payload = Payload::create()->setCustomValue('user_id', 7);

try {
    $payload->getCustomValue('unknown');
} catch (InvalidPayloadException $e) {
    echo $e->getMessage(); // Custom value with key 'unknown' doesn't exist.
}
```

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

### Full usage - push with a freshly generated JWT

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Token.md

Complete example of creating a Token auth provider, building a payload, and sending notifications via the Pushok client.

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

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

$payload = Payload::create()->setAlert('Hello')->setSound('default');
$client  = new Client($authProvider, false);

foreach ($deviceTokens as $token) {
    $client->addNotification(new Notification($payload, $token));
}

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

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

### setNbConcurrentRequests usage example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Client.md

Example of setting the number of concurrent requests to 40.

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

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

### reservedKey() usage example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/InvalidPayloadException.md

Example of catching the InvalidPayloadException thrown by setCustomValue() when using the reserved 'aps' key.

```php
use Pushok\InvalidPayloadException;
use Pushok\Payload;

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

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

### jsonSerialize() usage example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Shows how to use json_encode() on a Payload object, which invokes jsonSerialize(). The example output demonstrates the resulting JSON structure with an 'aps' key and custom values.

```php
json_encode($payload); // invokes jsonSerialize(); e.g. {"aps":{"alert":"Hi","badge":3},"key":"value"}
```

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

### get() method signature

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Token.md

Declares the public method signature for get(), which returns the current JWT token string.

```php
public function get(): string
```

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

### Full push workflow with certificate

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Certificate.md

Complete example of sending a push notification using the Certificate provider. It creates the provider, builds a payload, creates a client, adds notifications for each device token, and pushes.

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

$options = [
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/certificate.pem',
    'certificate_secret' => null,
];

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

$payload = Payload::create()->setAlert('Hello')->setSound('default');
$client  = new Client($authProvider, $production = false);

foreach ($deviceTokens as $deviceToken) {
    $client->addNotification(new Notification($payload, $deviceToken));
}

$responses = $client->push(); // AuthProviderInterface[] results
```

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

### setAutoCloseConnections usage example

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Client.md

Example of disabling auto-close to keep the connection open for reuse. Subsequent push() calls reuse the connection.

```php
$client->setAutoCloseConnections(false);
$responses = $client->push();
// handle stays open — subsequent push() reuses the connection
```

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

### setVolume / getVolume

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Sound.md

Sets or gets the sound volume. The setter is fluent and returns the `Sound` instance for chaining.

```APIDOC
## `setVolume(float $value): Sound` / `getVolume()`

### Description
Sets or gets the sound volume. The setter is fluent and returns the `Sound` instance for chaining.

### Method
`setVolume(float $value): Sound`
`getVolume()`

### Parameters
- `$value` (float) - Required - The volume value.

### Return
- `setVolume` returns `Sound` for chaining.
- `getVolume` returns the current volume.

### JSON Key
`volume` (when `is_float`)

### Source
`src/Payload/Sound.php:109-116` / `:121-124`
```

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

### 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();
}
```

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

### Custom AuthProviderInterface implementation

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/AuthProviderInterface.md

Demonstrates implementing the interface directly with a custom provider. The example adds the apns-topic header conditionally based on the push type and a custom Authorization header.

```php
use Pushok\AuthProviderInterface;
use Pushok\Request;

class MyProvider implements AuthProviderInterface
{
    public function authenticateClient(Request $request)
    {
        $request->addHeaders([
            'apns-topic' => $request->getHeaders()['apns-push-type'] === 'voip'
                ? 'com.app.Test.voip'
                : 'com.app.Test',
            'Authorization' => 'bearer my-custom-token',
        ]);
    }
}

$client = new Client(new MyProvider(), false);
```

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

### Client::__construct

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

Creates a new Client instance with the specified authentication provider, environment, and optional curl options.

```APIDOC
## Client::__construct

### Description
Creates a new Client instance with the specified authentication provider, environment, and optional curl options.

### Method
Constructor

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

### Parameters
- **$authProvider** (AuthProviderInterface) - Required - Authentication provider; use `AuthProvider\Token` or `AuthProvider\Certificate`.
- **$isProductionEnv** (bool) - Optional - Default `false` - `false` targets `https://api.development.push.apple.com` (sandbox), `true` targets `https://api.push.apple.com` (production).
- **$curlOptions** (array) - Optional - Default `[]` - Extra curl options merged over the Request's defaults. Entries here override Request defaults for the same option keys (e.g. `[CURLOPT_SSL_VERIFYPEER => false]` to disable SSL verification).
```

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

### Create Token with Basic Options

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Token.md

Creates a Token instance using the static create method with required and optional options, then outputs the generated JWT.

```php
use Pushok\AuthProvider;

$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,
]);

echo $authProvider->get(); // the JWT
```

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

### Token::create() options array

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

Options for creating a Token authentication provider. The array is passed to Token::create() and read directly in the constructor.

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

### Description
Options for creating a Token authentication provider. The array is passed to Token::create() and read directly in the constructor.

### Parameters

| Key | Type | Required | Description |
|---|---|---|---|
| `key_id` | string | yes | Key ID obtained from the Apple developer account; used as the JWT `kid` header and the generated JWK. Missing keys raise an `Undefined array key` error. |
| `team_id` | string | yes | Team ID obtained from the Apple developer account; used as the JWT `iss` claim. |
| `app_bundle_id` | string | yes | App bundle ID, used to derive the `apns-topic` header. |
| `private_key_path` | string \| null | no (`?? null`) | Path to the `.p8` private key file. |
| `private_key_content` | string \| null | no (`?? null`) | Raw private key content; takes precedence over `private_key_path` in `generatePrivateECKey()`. |
| `private_key_secret` | string \| null | no (`?? null`) | Passphrase for the private key. |

### Errors
- If neither `private_key_content` nor `private_key_path` resolves, `Token::create()` throws `\InvalidArgumentException('Unable to find private key.')`.
```

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

### Sound::create()

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Sound.md

Creates a new empty `Sound` instance. The constructor is protected, so this static factory method is the only way to instantiate the class.

```APIDOC
## `create()`

### Description
Creates a new empty `Sound` instance.

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

### Return
A new empty `Sound`.

### Source
`src/Payload/Sound.php:52-54`
```

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

### 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() and getExpirationAt() method signatures

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Notification.md

Sets or gets the expiration date/time for the notification. The value is stored as a clone and sent as the apns-expiration Unix timestamp header. The setter is fluent; the getter returns ?DateTime. Defined in src/Notification.php:134-141 (set) and 126-129 (get).

```php
public function setExpirationAt(DateTime $expirationAt): Notification
public function getExpirationAt(): ?DateTime
```

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

### Basic sandbox client construction with Token auth

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Client.md

Basic construction of a Pushok\Client for the APNs sandbox environment using a token-based authentication provider. The second argument 'false' selects the sandbox 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',
]);

$client = new Client($authProvider, false); // sandbox environment
```

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

### new Client(AuthProviderInterface $authProvider, bool $isProductionEnv = false, array $curlOptions = array())

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Client.md

Constructs a new Pushok\Client instance. The client queues notifications and sends them to APNs using the provided authentication provider and environment settings.

```APIDOC
## Constructor

### Description
Creates a new Pushok\Client instance for sending push notifications to Apple Push Notification service (APNs). The client uses the provided authentication provider to sign requests and connects to either the sandbox or production APNs environment based on the `$isProductionEnv` flag.

### Method
Constructor

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

### Parameters
#### `$authProvider` (AuthProviderInterface) - Required
Authentication provider. Pass a `Pushok\AuthProvider\Token` or `Pushok\AuthProvider\Certificate` instance. Used to authenticate every request.

#### `$isProductionEnv` (bool) - Optional (default: `false`)
Environment flag. `false` uses the APNs sandbox server, `true` uses the production server.

#### `$curlOptions` (array) - Optional (default: `[]`)
Extra curl options. Merged with `+` with request options, so entries override Request defaults. For example, `[CURLOPT_SSL_VERIFYPEER => false]` disables SSL verification.

### Return Value
Returns the constructed `Client` instance.

### Throws
None at construction.

### Example (Sandbox)
```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',
]);

$client = new Client($authProvider, false); // sandbox environment
```

### Example (Production with custom options)
```php
use Pushok\AuthProvider;
use Pushok\Client;

$authProvider = AuthProvider\Certificate::create([
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/cert.pem',
    'certificate_secret' => null,
]);

// Production env, override SSL verification + bump connect timeout
$client = new Client($authProvider, true, [
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_CONNECTTIMEOUT => 15,
]);
```
```

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

### setId() and getId() method signatures

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Notification.md

Sets or gets the canonical UUID identifying the notification. The ID is sent as the apns-id header, and APNs echoes it in the response. The setter is fluent; the getter returns string|null. Defined in src/Notification.php:112-118 (set) and 103-106 (get).

```php
public function setId(string $id): Notification
public function getId()
```

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

### Example APNs payload JSON

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

Example JSON payload sent as the request body. Contains the 'aps' dictionary with alert, sound, and badge, plus custom key-value pairs. Size limits are enforced client-side: 4096 bytes regular, 5120 bytes for voip push type.

```json
{
  "aps": {
    "alert": { "title": "Hello!", "body": "First push notification" },
    "sound": "default",
    "badge": 5
  },
  "key": "value"
}
```

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

### Sound::create() method signature

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Sound.md

The public static factory method to create a new Sound instance. The constructor is protected, so this is the only way to instantiate.

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

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

### setUrlArgs and getUrlArgs signatures

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Methods to set and get the url-args array for Safari notifications.

```php
public function setUrlArgs(array $value): Payload
public function getUrlArgs()
```

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

### Create Token with Raw Key Content and Error Handling

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Token.md

Creates a Token instance using private_key_content instead of a file path, and catches InvalidArgumentException when the private key is missing.

```php
use Pushok\AuthProvider;

try {
    $authProvider = AuthProvider\Token::create([
        'key_id' => 'AAAABBBBCC',
        'team_id' => 'DDDDEEEEFF',
        'app_bundle_id' => 'com.app.Test',
        'private_key_content' => file_get_contents(__DIR__ . '/private_key.p8'),
    ]);
} catch (\InvalidArgumentException $e) {
    // "Unable to find private key." — both key sources were missing
    exit('Fix the token configuration: ' . $e->getMessage());
}
```

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

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

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Sets or gets the URL arguments for Safari notifications.

```APIDOC
## setUrlArgs(array $value): Payload / getUrlArgs()

### Description
Sets or gets the URL arguments for Safari notifications.

### Method
setUrlArgs / getUrlArgs

### Parameters
#### Method Parameters
- **$value** (array) - Required - `url-args` values for Safari notifications.

### Request Example
```php
$payload->setUrlArgs(['arg1', 'arg2']);
```

### Response
#### Return Value
- **Payload** - Returns the current Payload instance for method chaining (setter).
- **array** - Returns the current URL arguments (getter).
```

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

### Certificate::create() options array

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

Options for creating a Certificate authentication provider. The array is passed to Certificate::create() and read directly in the constructor.

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

### Description
Options for creating a Certificate authentication provider. The array is passed to Certificate::create() and read directly in the constructor.

### Parameters

| Key | Type | Required | Description |
|---|---|---|---|
| `certificate_path` | string | yes | Path to the certificate (`.pem`, `.p12`, or `.der`). |
| `certificate_secret` | string | no | Certificate passphrase (passed to `CURLOPT_SSLCERTPASSWD`). |
| `app_bundle_id` | string \| null | no (`?? null`) | App bundle ID used to derive the `apns-topic` header. |
```

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

### setThreadId and getThreadId signatures

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Methods to set and get the thread-id for grouping notifications into conversation threads.

```php
public function setThreadId(string $value): Payload
public function getThreadId()
```

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

### Create Certificate provider with .pem

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Certificate.md

Initializes a Certificate auth provider using a .pem certificate. The certificate_secret is set to null. The certificate_path is required and the app_bundle_id is used for APNs topic generation.

```php
use Pushok\AuthProvider;

$authProvider = AuthProvider\Certificate::create([
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/certificate.pem',
    'certificate_secret' => null,
]);
```

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

### Plain string sound alternative

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Sound.md

Shows that setSound() also accepts a plain string, which serializes as {"sound":"default"}. This is a simpler alternative when critical/volume settings are not needed.

```php
// setSound also accepts a plain string, which serializes as {"sound":"default"}
$payload = Payload::create()->setAlert('Hi')->setSound('default');
```

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

### setHighPriority(), setLowPriority(), and getPriority() method signatures

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Notification.md

Sets or gets the notification priority. setHighPriority() stores PRIORITY_HIGH (10); setLowPriority() stores PRIORITY_LOW (5). If no priority is set and the payload is content-available (silent), the apns-priority header defaults to PRIORITY_LOW. The setters are fluent; getPriority() returns int|null. Defined in src/Notification.php:159-165 (high), 171-177 (low), and 149-152 (get).

```php
public function setHighPriority(): Notification
public function setLowPriority(): Notification
public function getPriority()
```

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

### create(array $options): Certificate

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Certificate.md

Static factory method to create a Certificate authentication provider instance.

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

### Description
Creates a new Certificate authentication provider instance. This is the only way to instantiate the class since the constructor is private.

### Method
`create`

### Parameters
- **$options** (array) - Required - Options array with keys: `certificate_path` (required), `certificate_secret`, `app_bundle_id` (optional).

### Return
`Certificate`

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

$authProvider = AuthProvider\Certificate::create([
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/certificate.pem',
    'certificate_secret' => null,
]);
```
```

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

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

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Sets or gets the category for the notification, which identifies the action to be performed.

```APIDOC
## setCategory(string $value): Payload / getCategory()

### Description
Sets or gets the category for the notification, which identifies the action to be performed.

### Method
setCategory / getCategory

### Parameters
#### Method Parameters
- **$value** (string) - Required - Notification type string (registered action identifiers).

### Request Example
```php
$payload->setCategory('NEW_MESSAGE');
```

### Response
#### Return Value
- **Payload** - Returns the current Payload instance for method chaining (setter).
- **string** - Returns the current category (getter).
```

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

### setName / getName

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Sound.md

Sets or gets the sound name. The setter is fluent and returns the `Sound` instance for chaining.

```APIDOC
## `setName(string $value): Sound` / `getName()`

### Description
Sets or gets the sound name. The setter is fluent and returns the `Sound` instance for chaining.

### Method
`setName(string $value): Sound`
`getName()`

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

### Return
- `setName` returns `Sound` for chaining.
- `getName` returns the current name.

### JSON Key
`name` (when `is_string`)

### Source
`src/Payload/Sound.php:86-93` / `:98-101`
```

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

### Iterating Client::push() results with success and failure branches

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Response.md

Use this loop to process each response from `Client::push()`. It checks for `Response::APNS_SUCCESS` to print the device token and APNs ID, and for `Response::APNS_NOT_ACTIVE_DEVICE_TOKEN_` to remove the token from the database, using `get410Timestamp()` to show when the device was last registered. Other statuses print the HTTP status, error reason, and error description.

```php
use Pushok\Response;

foreach ($client->push() as $response) {
    if ($response->getStatusCode() === Response::APNS_SUCCESS) {
        echo "OK " . $response->getDeviceToken() . " apns-id=" . $response->getApnsId() . "\n";
        continue;
    }

    if ($response->getStatusCode() === Response::APNS_NOT_ACTIVE_DEVICE_TOKEN_) {
        // Device token permanently invalid — remove from database
        echo "Remove token " . $response->getDeviceToken()
             . " (unregistered since " . $response->get410Timestamp() . ")\n";
        continue;
    }

    echo "HTTP " . $response->getStatusCode() . " "
         . $response->getErrorReason() . " — "
         . $response->getErrorDescription() . "\n";
}
```

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

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

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Sets or gets the thread identifier for grouping notifications into conversation threads.

```APIDOC
## setThreadId(string $value): Payload / getThreadId()

### Description
Sets or gets the thread identifier for grouping notifications into conversation threads.

### Method
setThreadId / getThreadId

### Parameters
#### Method Parameters
- **$value** (string) - Required - App-specific identifier for grouping notifications (conversation threads).

### Request Example
```php
$payload->setThreadId('THREAD_123');
```

### Response
#### Return Value
- **Payload** - Returns the current Payload instance for method chaining (setter).
- **string** - Returns the current thread identifier (getter).
```

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

### Create Certificate provider with .p12 and passphrase

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Certificate.md

Initializes a Certificate auth provider using a .p12 certificate with a passphrase. The passphrase is used for CURLOPT_SSLCERTPASSWD, and the provider sets CURLOPT_SSLCERTTYPE to 'P12'.

```php
use Pushok\AuthProvider;

$authProvider = AuthProvider\Certificate::create([
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/certificate.p12',
    'certificate_secret' => 'p12-passphrase',
]); // authenticates with CURLOPT_SSLCERTTYPE => 'P12'
```

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

### setCategory and getCategory signatures

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Methods to set and get the notification category string, which identifies registered action identifiers.

```php
public function setCategory(string $value): Payload
public function getCategory()
```

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

### setInterruptionLevel($interruptionLevel): Payload / getInterruptionLevel()

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Sets or gets the interruption level for the notification, controlling how the system presents the alert.

```APIDOC
## setInterruptionLevel($interruptionLevel): Payload / getInterruptionLevel()

### Description
Sets or gets the interruption level for the notification, controlling how the system presents the alert.

### Method
- `setInterruptionLevel($interruptionLevel): Payload`
- `getInterruptionLevel()`

### Parameters
- `$interruptionLevel` (string) - Required - One of APNs' interruption levels — `passive`, `active`, `time-sensitive`, or `critical`. Emitted when `is_string()`.

### Source
- `src/Payload.php:300-305 (set)`
- `src/Payload.php:288-291 (get)`
```

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

### setCritical / getCritical

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Sound.md

Sets or gets the critical alert flag for the sound. The setter is fluent and returns the `Sound` instance for chaining.

```APIDOC
## `setCritical(int $value): Sound` / `getCritical()`

### Description
Sets or gets the critical alert flag for the sound. The setter is fluent and returns the `Sound` instance for chaining.

### Method
`setCritical(int $value): Sound`
`getCritical()`

### Parameters
- `$value` (int) - Required - The critical flag value.

### Return
- `setCritical` returns `Sound` for chaining.
- `getCritical` returns the current critical value.

### JSON Key
`critical` (when `is_integer`)

### Source
`src/Payload/Sound.php:63-70` / `:75-78`
```

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

### Client constructor signature

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

Constructor for the Client class. Requires an AuthProviderInterface instance. The second parameter selects the APNs environment (false for sandbox, true for production). The third parameter provides extra curl options that override Request defaults for the same keys.

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

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

### getDeviceToken(): string

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Notification.md

Returns the device token passed to the constructor.

```APIDOC
## getDeviceToken(): string

### Description
Returns the device token passed to the constructor.

### Method
Method

### Return
`string` - The device token passed to the constructor.

### Example
```php
$token = $notification->getDeviceToken();
```
```

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

### jsonSerialize(): array

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Builds the array representation of the payload, starting with an empty 'aps' object and merging custom values at the top level.

```APIDOC
## jsonSerialize(): array

### Description
Builds the array representation of the payload. Always starts with `['aps' => new \stdClass]` so an empty payload serializes to `{"aps":{}}`. Custom values are merged at the top level.

### Method
`jsonSerialize`

### Signature
```php
public function jsonSerialize(): array
```

### Return Value
- **array** - Structure: `['aps' => \stdClass, ...custom]` where `aps` is a `stdClass` with standard keys.

### Example
```php
json_encode($payload); // invokes jsonSerialize(); e.g. {"aps":{"alert":"Hi","badge":3},"key":"value"}
```
```

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

### setSound($sound): Payload / getSound()

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Payload.md

Sets or gets the sound for the notification payload. The sound can be a string filename or a Sound object for advanced configuration.

```APIDOC
## setSound($sound): Payload / getSound()

### Description
Sets or gets the sound for the notification payload. The sound can be a string filename or a Sound object for advanced configuration.

### Method
- `setSound($sound): Payload`
- `getSound()`

### Parameters
- `$sound` (Sound | string) - Required - Name of a sound file in the app bundle (e.g. `'default'`) or a `Sound` object for name/critical/volume. Anything else is **silently ignored**.

### Source
- `src/Payload.php:274-283 (set)`
- `src/Payload.php:262-265 (get)`
```

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

### Production client construction with Certificate auth and custom curl options

Source: https://github.com/edamov/pushok/blob/master/_autodocs/api-reference/Client.md

Production client construction with certificate-based authentication and custom curl options. The 'true' argument selects the production APNs server, and the provided options disable SSL verification and increase the connect timeout.

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

$authProvider = AuthProvider\Certificate::create([
    'app_bundle_id' => 'com.app.Test',
    'certificate_path' => __DIR__ . '/cert.pem',
    'certificate_secret' => null,
]);

// Production env, override SSL verification + bump connect timeout
$client = new Client($authProvider, true, [
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_CONNECTTIMEOUT => 15,
]);
```