Laravel Expo Channel

https://github.com/laravel-notification-channels/expo
Admin
A Laravel notification channel for sending push notifications to React Native apps using Expo's push...
Tokens:40,870
Snippets:372
Trust Score:8.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Run this command to install the package using Composer.

```bash
composer require laravel-notification-channels/expo
```

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

### Using playSound()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Usage example for playSound().

```php
$message->playSound();
```

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

### title() usage example

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Example usage of title() with a title string.

```php
$message->title('Payment received');
```

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

### Usage example for ExpoEnvelope::make()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoEnvelope.md

Example of creating an envelope with two recipient tokens and a message. Uses ExpoPushToken::make() and ExpoMessage::create().

```php
use NotificationChannels\Expo\ExpoPushToken;
use NotificationChannels\Expo\ExpoMessage;
use NotificationChannels\Expo\Gateway\ExpoEnvelope;

$envelope = ExpoEnvelope::make([
    ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]'),
    ExpoPushToken::make('ExponentPushToken[GuU2eCJd6Xq03IFHvKViM5]'),
], ExpoMessage::create('Hello', 'World'));
```

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

### Using priority()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Usage example for priority() with the value 'high'.

```php
$message->priority('high');
```

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

### subtitle() usage example

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Example usage of subtitle() with a subtitle string.

```php
$message->subtitle('From your security team');
```

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

### Example output of toArray()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoEnvelope.md

Example result of toArray() showing the structure with 'body', 'title', and 'to' keys.

```php
[
    'body' => 'World',
    'title' => 'Hello',
    'to' => [
        'ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]',
        'ExponentPushToken[GuU2eCJd6Xq03IFHvKViM5]',
    ],
]
```

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

### richContent() usage example

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Example usage of richContent() with a publicly accessible image URL.

```php
$message->richContent('https://example.com/hero.png');
```

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

### Conditional message configuration with when() and unless()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Example of using when() and unless() to conditionally apply message settings based on notifiable properties.

```php
return ExpoMessage::create('Suspicious Activity')
    ->when($notifiable->wantsSound(), fn ($msg) => $msg->playSound())
    ->unless($notifiable->isVip(), fn ($msg) => $msg->normal(), fn ($msg) => $msg->high());
```

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

### Usage example for toJson()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoEnvelope.md

Example of calling toJson() with JSON_UNESCAPED_SLASHES and the resulting JSON output.

```php
echo $envelope->toJson(JSON_UNESCAPED_SLASHES);
// {"body":"World","title":"Hello","to":["ExponentPushToken[...]","ExponentPushToken[...]"]}
```

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

### Instantiate ExpoGatewayUsingGuzzle with access token and handler

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/configuration.md

Shows how to construct the gateway directly for custom wiring or tests. The first example uses the `accessToken` named parameter, the second uses a mocked handler stack for testing.

```php
use NotificationChannels\Expo\Gateway\ExpoGatewayUsingGuzzle;

// Production-style wiring mirroring the service provider:
$gateway = new ExpoGatewayUsingGuzzle(accessToken: env('EXPO_ACCESS_TOKEN'));

// Test wiring with a mocked handler stack:
$gateway = new ExpoGatewayUsingGuzzle(handler: HandlerStack::create(new MockHandler([...])));
```

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

### Usage of priority setters

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Usage examples for the priority setters. The high() call sets priority to 'high', and default() sets it to 'default'.

```php
$message->high();  // priority: 'high'
$message->default(); // priority: 'default'
```

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

### Using mutableContent()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Usage examples for mutableContent(). Passing false is filtered out by filled() during serialization, so the payload omits the key.

```php
$message->mutableContent(); // enables interception
$message->mutableContent(false); // back to default (omitted from payload)
```

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

### Using contentAvailable()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Usage example for contentAvailable(). The value is stored in the $_contentAvailable property, and because serialization uses get_object_vars(), the emitted JSON key is _contentAvailable. The app must be configured to support background execution.

```php
$message->contentAvailable();
```

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

### PHP Implementation of getReceipts

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/endpoints.md

Example usage of the ExpoGateway::getReceipts method to retrieve delivery receipts, including error handling for the CouldNotGetReceipts exception.

```php
use NotificationChannels\Expo\Gateway\ExpoGateway;
use NotificationChannels\Expo\Exceptions\CouldNotGetReceipts;

// $gateway is the container-resolved ExpoGateway (send + receipts)
try {
    $receipts = $gateway->getReceipts($persistedTicketIds);
} catch (CouldNotGetReceipts $e) {
    // poll failed at the HTTP layer — retry later
}
```

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

### contentAvailable() method signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Method signature for setting whether the notification causes the iOS app to start in the background. The default value is true.

```php
public function contentAvailable(bool $value = true): self
```

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

### Use ttl() to set one-hour redelivery

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Example usage of the ttl() method to set a TTL of 3600 seconds (one hour) for redelivery.

```php
$message->ttl(3600); // redeliver for at most one hour
```

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

### Send push notification and handle errors

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoGateway.md

Example of sending a push notification and handling per-token failures. The response's isFailure() method indicates whether any errors occurred; errors() returns an array of ExpoError objects.

```php
$response = $gateway->sendPushNotifications($envelope);

if ($response->isFailure()) {
    foreach ($response->errors() as $error) {
        // handle per-token failure
    }
}
```

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

### AsExpoPushToken::set() method signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Casts-and-Validation.md

Signature of the set() method in AsExpoPushToken. It validates via get() and returns the token string for persistence.

```php
/**
 * Transform the attribute to its underlying model values from an ExpoPushToken.
 *
 * @param  array<string, mixed>  $attributes
 */
public function set($model, string $key, $value, array $attributes): ?string
```

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

### Check for MessageRateExceeded Error

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/types.md

Example usage of the isMessageRateExceeded method to handle rate limiting by implementing backoff logic.

```php
if ($error->type->isMessageRateExceeded()) {
    // back off and retry later
}
```

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

### Serialize ExpoMessage with json_encode

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Example of serializing an ExpoMessage with json_encode, showing the resulting JSON with title, body, and badge fields.

```php
json_encode(ExpoMessage::create('Hi', 'There')->badge(3));
// {"title":"Hi","body":"There","badge":3}
```

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

### contentAvailable()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Sets whether the notification causes the iOS app to start in the background. Accepts an optional boolean parameter, defaults to true. Returns the message instance for chaining.

```APIDOC
## contentAvailable()

### Description
Sets whether the notification causes the iOS app to start in the background.

### Method
contentAvailable

### Signature
public function contentAvailable(bool $value = true): self

### Parameters
- **$value** (bool) - Optional - Default: `true` - Whether the notification causes the iOS app to start in the background.

### Return Value
- **self** - Returns the message instance for method chaining.

### Exceptions
- Does not throw.

### Notes
- Stored in the `$_contentAvailable` property; because serialization uses `get_object_vars()`, the emitted JSON key is `_contentAvailable`.
- The app must be configured to support background execution.

### Example
```php
$message->contentAvailable();
```
```

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

### Handling failed Expo notifications

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/types.md

Example of using the ExpoError object within an event listener to handle failed notifications, specifically checking for unregistered devices.

```php
use NotificationChannels\Expo\Events\ExpoNotificationFailed;

class HandleFailedExpoNotifications
{
    public function handle(ExpoNotificationFailed $event): void
    {
        $error = $event->error;

        if ($error->type->isDeviceNotRegistered()) {
            $event->notifiable->update(['expo_token' => null]);
        }
    }
}
```

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

### AsExpoPushToken::get() method signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Casts-and-Validation.md

Signature of the get() method in AsExpoPushToken. It converts a raw attribute value to an ExpoPushToken or null, throwing InvalidArgumentException for malformed tokens or unsupported types.

```php
/**
 * Transform the attribute from the underlying model values to an ExpoPushToken.
 *
 * @param  array<string, mixed>  $attributes
 */
public function get($model, string $key, $value, array $attributes): ?ExpoPushToken
```

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

### register() method

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoServiceProvider.md

Binds the gateway, registers the channel as a singleton, and extends the ChannelManager.

```php
public function register(): void
{
    $this->app->bind(ExpoGateway::class, $this->createExpoGateway(...));
    $this->app->singleton(ExpoChannel::class);

    $this->callAfterResolving(ChannelManager::class, $this->extendManager(...));
}
```

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

### createExpoGateway() private method

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoServiceProvider.md

Creates an ExpoGatewayUsingGuzzle instance, reading the access token from config and validating it.

```php
private function createExpoGateway(Application $app): ExpoGatewayUsingGuzzle
{
    /** @var Repository $config */
    $config = $app->make(Repository::class);

    $accessToken = $config->get('services.expo.access_token');

    if (! is_null($accessToken) && ! is_string($accessToken)) {
        throw new InvalidArgumentException('The provided access token is not a valid Expo Access Token.');
    }

    return new ExpoGatewayUsingGuzzle($accessToken);
}
```

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

### Run tests with Composer

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Use this command to run the package's test suite. It executes the tests defined in the project using Composer.

```bash
composer test
```

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

### Create an ExpoPushToken instance with make()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

The make() method is the static factory used to create a validated ExpoPushToken instance from a raw string.

```php
use NotificationChannels\Expo\ExpoPushToken;

$token = ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]');
```

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

### ExpoEnvelope::make()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoEnvelope.md

Static factory method to create a new ExpoEnvelope instance. The constructor is private, so this is the only way to instantiate the class.

```APIDOC
## `make()`

### Description
Creates a new `ExpoEnvelope` instance with the given recipients and message.

### Method
`public static function make(array $recipients, ExpoMessage $message): self`

### Parameters
- **$recipients** (`array<int, ExpoPushToken>`) - Required - Push tokens to deliver to; must be non-empty.
- **$message** (`ExpoMessage`) - Required - The message to send to every recipient.

### Returns
A new `ExpoEnvelope` instance.

### Exceptions
- `InvalidArgumentException` if `$recipients` is empty.

### Example
```php
use NotificationChannels\Expo\ExpoPushToken;
use NotificationChannels\Expo\ExpoMessage;
use NotificationChannels\Expo\Gateway\ExpoEnvelope;

$envelope = ExpoEnvelope::make([
    ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]'),
    ExpoPushToken::make('ExponentPushToken[GuU2eCJd6Xq03IFHvKViM5]'),
], ExpoMessage::create('Hello', 'World'));
```
```

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

### extendManager() private method

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoServiceProvider.md

Extends the ChannelManager with the 'expo' driver.

```php
private function extendManager(ChannelManager $manager): void
{
    $manager->extend(
        ExpoChannel::NAME,
        fn (Application $app) => $app->make(ExpoChannel::class)
    );
}
```

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

### Expo Push Notification Request Body

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/endpoints.md

Example JSON payload for the push notification request, including message content, metadata, and recipient tokens.

```json
{
  "title": "Suspicious Activity",
  "body": "Someone tried logging in to your account!",
  "data": "{\"email\":\"user@example.com\"}",
  "ttl": 3600,
  "expiration": 1767225600,
  "priority": "high",
  "subtitle": "From your security team",
  "sound": "default",
  "badge": 3,
  "channelId": "chat-messages",
  "categoryId": "new-message",
  "mutableContent": true,
  "_contentAvailable": true,
  "richContent": {"image": "https://example.com/hero.png"},
  "to": [
    "ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]",
    "ExpoPushToken[Wi54gvIrap4SDW4Dsh6b0h]"
  ]
}
```

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

### Using AsExpoPushToken cast in a model

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Casts-and-Validation.md

Example of using the AsExpoPushToken cast on an Eloquent model. The 'expo_token' attribute is cast to ExpoPushToken::class, which resolves to AsExpoPushToken.

```php
use NotificationChannels\Expo\ExpoPushToken;

class User extends Authenticatable
{
    protected function casts(): array
    {
        return [
            'expo_token' => ExpoPushToken::class, // resolves to AsExpoPushToken
        ];
    }
}
```

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

### __construct()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoChannel.md

Constructor for ExpoChannel. Injects the gateway and event dispatcher. Normally instantiated by the container, not directly by users.

```APIDOC
## __construct(ExpoGateway $gateway, Dispatcher $events)

### Description
Creates a new ExpoChannel instance with the given gateway and event dispatcher. This constructor is typically called by the Laravel container.

### Method
__construct

### Signature
```php
public function __construct(private ExpoGateway $gateway, private Dispatcher $events)
```

### Parameters
- **$gateway** (ExpoGateway) - Required - Transport that performs the HTTP calls to Expo.
- **$events** (Dispatcher) - Required - Laravel event dispatcher used to emit sent/failed events.

### Return Type
void
```

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

### Implement __toString()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

Returns the raw token string, enabling string interpolation and usage in string contexts.

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

```php
"token: {$token}";
$notifiable->routeNotificationForExpo()
```

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

### Instantiate ExpoGatewayUsingGuzzle with access token

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoGateway.md

Instantiates the gateway with an access token from the Laravel config. The token is optional; when provided, requests carry Authorization: Bearer {accessToken}.

```php
use NotificationChannels\Expo\Gateway\ExpoGatewayUsingGuzzle;

$gateway = new ExpoGatewayUsingGuzzle(accessToken: config('services.expo.access_token'));
```

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

### Expo Push Notification Response Body

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/endpoints.md

Example JSON response body received when the request returns a 200 status, containing a list of ticket statuses.

```json
{
  "data": [
    {"status": "ok", "id": "ticket-uuid-1"},
    {"status": "error", "message": "DeviceNotRegistered: ...", "details": {"error": "DeviceNotRegistered"}}
  ]
}
```

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

### Using ExpoPushToken::rule() in a FormRequest

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Casts-and-Validation.md

Example of using ExpoPushToken::rule() in a FormRequest validation rules array. The 'token' field is required and must be a valid Expo push token.

```php
use Illuminate\Foundation\Http\FormRequest;
use NotificationChannels\Expo\ExpoPushToken;

class StoreDeviceRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'device_id' => ['required', 'string', 'min:2', 'max:255'],
            'token' => ['required', ExpoPushToken::rule()],
        ];
    }
}
```

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

### Round-trip token with AsExpoPushToken

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Casts-and-Validation.md

Demonstrates round-tripping a token through the cast: assigning a token string, saving, refreshing, and reading back the ExpoPushToken instance and its string form.

```php
$user->expo_token = ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]');
$user->save();

$user->refresh()->expo_token; // ExpoPushToken instance
$user->expo_token->asString(); // "ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]"
```

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

### Static make() factory method

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoEnvelope.md

Static factory method that creates a new ExpoEnvelope instance. The constructor is private, so this is the only way to instantiate.

```php
/**
 * @see __construct()
 *
 * @param  array<int, ExpoPushToken>  $recipients
 */
public static function make(array $recipients, ExpoMessage $message): self
```

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

### Create an ExpoMessage with title and body

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Creates a new ExpoMessage with a title and body. The title and body parameters are optional and default to empty strings.

```php
use NotificationChannels\Expo\ExpoMessage;

$message = ExpoMessage::create('Suspicious Activity', 'Someone tried logging in to your account!');
```

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

### asString()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

Instance method that returns the raw token string value.

```APIDOC
## `asString()`

### Description
Returns the raw token string. Because the class is `readonly`, `value` is only accessible through this method (or magic accessors).

### Method
`asString`

### Signature
```php
public function asString(): string
```

### Parameters
None

### Return Value
- `string` - The raw token string

### Example
```php
$token->asString(); // "ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]"
```
```

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

### Composer package discovery configuration

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoServiceProvider.md

Declares the provider in composer.json under extra.laravel.providers for auto-discovery.

```json
"extra": {
    "laravel": {
        "providers": [
          "NotificationChannels\\Expo\\ExpoServiceProvider"
        ]
    }
}
```

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

### ExpoResponse::message() method

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoResponse.md

Returns the fatal message string when the response is fatal; returns an empty string otherwise. When the gateway gets a non-200 HTTP status, this holds the raw response body, which ExpoChannel::send() embeds in CouldNotSendNotification.

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

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

### Apply Conditionals to ExpoMessage

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Shows how to use the when and unless methods on ExpoMessage to conditionally apply methods without breaking the chain.

```php
use NotificationChannels\Expo\ExpoMessage;

public function toExpo($notifiable): ExpoMessage
{
    return ExpoMessage::create('Suspicious Activity')
        ->body('Someone tried logging in to your account!')
        ->when($notifiable->wantsSound(), fn ($msg) => $msg->playSound())
        ->unless($notifiable->isVip(), fn ($msg) => $msg->normal(), fn ($msg) => $msg->high());
}
```

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

### Persist Expo tickets listener

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Events.md

Example listener that persists the ticket IDs from the ExpoNotificationSent event. It iterates over the $tickets map and updates the Device model's last_ticket_id for each token. Ticket UUIDs can be persisted and polled later with ExpoGateway::getReceipts().

```php
use NotificationChannels\Expo\Events\ExpoNotificationSent;

class PersistExpoTickets
{
    public function handle(ExpoNotificationSent $event): void
    {
        foreach ($event->tickets as $token => $ticketId) {
            Device::where('expo_token', $token)->update([
                'last_ticket_id' => $ticketId,
            ]);
        }
    }
}
```

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

### ExpoChannel constructor

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoChannel.md

Constructor that injects an ExpoGateway and an event Dispatcher. Instances are normally created by the container, not manually.

```php
public function __construct(private ExpoGateway $gateway, private Dispatcher $events)
```

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

### Multicast to Multiple Devices with Collection

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Shows a User model with a routeNotificationForExpo method that returns a Collection of ExpoPushToken instances for multicasting. No notifications are sent if the collection is empty.

```php
use Illuminate\Database\Eloquent\Collection;

class User extends Authenticatable
{
    use Notifiable;

    /**
    * @return Collection<int, ExpoPushToken>
    */
    public function routeNotificationForExpo(): Collection
    {
        return $this->devices->pluck('expo_token');
    }
}
```

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

### equals()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

Instance method that compares this token with another token or raw string, returning true if they are equal.

```APIDOC
## `equals()`

### Description
Returns `true` when the other token's string representation equals this token's string representation.

### Method
`equals`

### Signature
```php
public function equals(self|string $other): bool
```

### Parameters
- **$other** (`self` | `string`) - Required - Another `ExpoPushToken` or a raw token string

### Return Value
- `bool` - `true` if the tokens are equal, `false` otherwise

### Example
```php
$a = ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]');
$b = ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]');

$a->equals($b);     // true
$a->equals('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]'); // true
$a->equals('ExponentPushToken[SomethingElse]');           // false
```
```

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

### getReceipts() usage with exception handling

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoGateway.md

Shows how to call getReceipts() with an array of ticket UUIDs and handle the CouldNotGetReceipts exception. The method returns an array keyed by ticket UUID; an empty input array returns [] immediately.

```php
use NotificationChannels\Expo\Exceptions\CouldNotGetReceipts;

try {
    $receipts = $gateway->getReceipts(['ticket-uuid-1', 'ticket-uuid-2']);
} catch (CouldNotGetReceipts $e) {
    report($e);
}
```

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

### __toString()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

Returns the raw token string, enabling string interpolation and string-context use.

```APIDOC
## `__toString()`

### Description
Returns the raw token string; enables string interpolation and string-context use.

### Method
`__toString`

### Parameters
None.

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

### Example
```php
public function __toString(): string
{
    return $this->asString();
}
```
```

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

### ExpoMessage::create()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Static factory method that creates a new ExpoMessage instance. This is the entry point for building a message, as the constructor is private.

```APIDOC
## `create()`

### Description
Creates a new `ExpoMessage` instance. This is the entry point for building a message; the constructor is private.

### Method
`public static function create(string $title = '', string $body = ''): self`

### Parameters
- **$title** (string) - Optional - Default: `''` - Title to display in the notification
- **$body** (string) - Optional - Default: `''` - Message body to display

### Returns
A new `ExpoMessage` instance.

### Example
```php
use NotificationChannels\Expo\ExpoMessage;

$message = ExpoMessage::create('Suspicious Activity', 'Someone tried logging in to your account!');
```
```

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

### Set message body

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Sets the message body to 'Your order has shipped'. The body must not be empty.

```php
$message->body('Your order has shipped');
```

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

### Implement jsonSerialize()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

Returns the raw token string, allowing json_encode($token) to produce a JSON string.

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

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

### Body - body() and text()

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Sets the message body to display in the notification. The value must not be empty.

```php
body(string $value)
text(string $value)
```

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

### Title - title()

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Set the title to display in the notification. The value must not be empty.

```php
title(string $value)
```

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

### ExpoResponse::isFatal(), isFailure(), isOk() methods

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoResponse.md

Each returns whether the response is of the corresponding type. Exactly one of the three returns true.

```php
public function isFatal(): bool
public function isFailure(): bool
public function isOk(): bool
```

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

### Custom gateway usage of ExpoResponse factories

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoResponse.md

Used directly when implementing a custom gateway or testing one. Shows how to create each type of response: ok with tickets, failed with an ExpoError, and fatal with a message.

```php
use NotificationChannels\Expo\Gateway\ExpoResponse;
use NotificationChannels\Expo\ExpoError;
use NotificationChannels\Expo\ExpoErrorType;
use NotificationChannels\Expo\ExpoPushToken;

// Accepted pushes
return ExpoResponse::ok(['0' => 'ticket-uuid-1']);

// Refused tokens
return ExpoResponse::failed([
    ExpoError::make(
        ExpoErrorType::DeviceNotRegistered,
        ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]'),
        'Device not registered'
    ),
]);

// Transport failure
return ExpoResponse::fatal('Upstream unavailable');
```

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

### Priority - priority(), default(), normal(), high()

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Sets the delivery priority of the message. The value must be 'default', 'normal', or 'high'.

```php
priority(string $value)
default()
normal()
high()
```

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

### ExpoGatewayUsingGuzzle class declaration

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoGateway.md

Declares the default Guzzle-backed gateway implementation. It is final and readonly, and implements the ExpoGateway interface.

```php
/** @internal */
final readonly class ExpoGatewayUsingGuzzle implements ExpoGateway
```

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

### priority()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Sets the delivery priority of the notification. Accepts a required string parameter and returns the message instance for chaining.

```APIDOC
## priority()

### Description
Sets the delivery priority of the notification.

### Method
priority

### Signature
public function priority(string $value): self

### Parameters
- **$value** (string) - Required - Delivery priority: `default`, `normal`, or `high`.

### Return Value
- **self** - Returns the message instance for method chaining.

### Exceptions
- Throws `InvalidArgumentException` with message "The priority must be default, normal or high." when the value is not in `PRIORITIES` (`['default', 'normal', 'high']`).

### Notes
- The value is lowercased before validation.

### Example
```php
$message->priority('high');
```
```

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

### Create a Notification with ExpoMessage

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Defines a notification class with a toExpo method that returns an ExpoMessage with body, data, expiration, priority, and sound. The via method returns the 'expo' channel.

```php
use NotificationChannels\Expo\ExpoMessage;

class SuspiciousActivityDetected extends Notification
{
    public function toExpo($notifiable): ExpoMessage
    {
        return ExpoMessage::create('Suspicious Activity')
            ->body('Someone tried logging in to your account!')
            ->data($notifiable->only('email', 'id'))
            ->expiresAt(now()->addHour())
            ->priority('high')
            ->playSound();
    }

    public function via($notifiable): array
    {
        return ['expo'];
    }
}
```

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

### data(Arrayable|Jsonable|JsonSerializable|array $value): self

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Sets arbitrary JSON data to be delivered to the app. Converts various input types to a JSON string and stores it. Throws JsonException on encoding failure.

```APIDOC
## data(Arrayable|Jsonable|JsonSerializable|array $value): self

### Description
Sets arbitrary JSON data to be delivered to the app. Converts various input types to a JSON string and stores it. Throws JsonException on encoding failure.

### Method
data

### Signature
public function data(Arrayable|Jsonable|JsonSerializable|array $value): self

### Parameters
- **$value** (Arrayable|Jsonable|JsonSerializable|array) - Required - Arbitrary JSON data delivered to your app. Conversion logic: an Arrayable is converted via toArray(), a Jsonable via toJson(JSON_THROW_ON_ERROR), and anything else via json_encode($value, JSON_THROW_ON_ERROR). The encoded string is stored in $data.

### Exceptions
- **JsonException** - Thrown when JSON encoding fails (JSON_THROW_ON_ERROR), e.g. on invalid UTF-8 or infinite recursion.

### Examples
```php
$message->data(['email' => 'user@example.com', 'id' => 42]);
```

```php
try {
    $message->data($invalidUtf8Payload); // throws JsonException
} catch (JsonException $e) {
    Log::error('Could not encode message data', ['exception' => $e]);
}
```
```

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

### Retrieve token string with asString

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

The asString method returns the raw token string from the readonly class.

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

```php
$token->asString(); // "ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]"
```

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

### POST https://exp.host/--/api/v2/push/getReceipts

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoGateway.md

HTTP endpoint for retrieving receipts for push notifications, as used by the default Guzzle-backed gateway.

```APIDOC
## [POST] https://exp.host/--/api/v2/push/getReceipts

### Description
Retrieves receipts for previously sent push notifications. This is the transport method used by the `ExpoGatewayUsingGuzzle` implementation.

### Method
POST

### Endpoint
https://exp.host/--/api/v2/push/getReceipts

### Parameters
#### Request Body
- **ticketIds** (array) - Required - Array of up to 1000 ticket UUIDs per call.

### Request Example
```json
{
  "ids": ["ticket-uuid-1", "ticket-uuid-2"]
}
```

### Response
#### Success Response (200)
- **data** (object) - Object keyed by ticket UUID, each value containing `status`, optional `message`, and optional `details`.

#### Response Example
```json
{
  "data": {
    "ticket-uuid-1": {
      "status": "ok"
    }
  }
}
```
```

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

### ExpoPushTokenRule::make() method signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Casts-and-Validation.md

Signature of the make() factory method for ExpoPushTokenRule. It takes no parameters and returns a new rule instance.

```php
public static function make(): self
```

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

### POST https://exp.host/--/api/v2/push/send

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoGateway.md

HTTP endpoint for sending push notifications, as used by the default Guzzle-backed gateway.

```APIDOC
## [POST] https://exp.host/--/api/v2/push/send

### Description
Sends push notifications to the Expo push service. This is the transport method used by the `ExpoGatewayUsingGuzzle` implementation.

### Method
POST

### Endpoint
https://exp.host/--/api/v2/push/send

### Parameters
#### Request Body
- **envelope** (ExpoEnvelope) - Required - The envelope containing recipients and message to deliver.

### Request Example
```json
{
  "to": ["ExponentPushToken[xxxxxxxxxxxxxxxxxxxxx]"],
  "title": "Hello",
  "body": "World"
}
```

### Response
#### Success Response (200)
- **data** (array) - Array of ticket objects, each with a `status` field.

#### Response Example
```json
{
  "data": [
    {
      "status": "ok",
      "id": "ticket-uuid"
    }
  ]
}
```

### Error Handling
- Non-200 status: returns `ExpoResponse::fatal((string) $response->getBody())`.
- Tickets with `status === 'error'`: builds an `ExpoError` from `details.error`, the token at the same index, and the ticket's `message`.
- If any errors: returns `ExpoResponse::failed($errors)`.
- Otherwise: returns `ExpoResponse::ok($ticketIds)` where `$ticketIds` maps recipient index to ticket UUID for tickets with `status === 'ok'` and a string `id`.
```

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

### Set badge value to 5

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Sets the badge value to 5 on the app icon. The value must be non-negative.

```php
$message->badge(5); // badge with "5" on the app icon
```

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

### Set Expo Access Token in config/services.php

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/configuration.md

Add this to your `config/services.php` to configure the optional Expo Access Token. The token is read from the `EXPO_ACCESS_TOKEN` environment variable and sent as `Authorization: Bearer {token}` on every request.

```php
'expo' => [
    'access_token' => env('EXPO_ACCESS_TOKEN'),
],
```

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

### playSound()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Sets the sound to the default device notification sound (iOS only). Takes no parameters and returns the message instance for chaining.

```APIDOC
## playSound()

### Description
Sets the sound to the default device notification sound (iOS only).

### Method
playSound

### Signature
public function playSound(): self

### Parameters
- None

### Return Value
- **self** - Returns the message instance for method chaining.

### Exceptions
- Does not throw.

### Notes
- Sets `$sound` to the string `'default'`.
- Custom sounds are not supported.

### Example
```php
$message->playSound();
```
```

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

### Priority setters: default(), normal(), high()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Convenience setters that assign 'default', 'normal', and 'high' respectively to $priority, returning $this.

```php
public function default(): self
public function normal(): self
public function high(): self
```

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

### AsExpoPushToken::get()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Casts-and-Validation.md

Transforms the attribute from the underlying model values to an ExpoPushToken instance.

```APIDOC
## AsExpoPushToken::get()

### Description
Transforms the attribute from the underlying model values to an ExpoPushToken instance.

### Method
`get`

### Signature
```php
public function get($model, string $key, $value, array $attributes): ?ExpoPushToken
```

### Parameters
- **$model** (mixed) - Required - The model instance (per CastsAttributes)
- **$key** (string) - Required - The attribute name being cast
- **$value** (mixed) - Required - The raw (string/null/ExpoPushToken) attribute value
- **$attributes** (array<string, mixed>) - Required - The model's raw attributes

### Return Value
`?ExpoPushToken` - The converted ExpoPushToken instance, or null if the value is null.

### Behavior
- If `$value` is a string, it is converted via `ExpoPushToken::make($value)`, which throws `InvalidArgumentException` on malformed tokens.
- If `$value` is null or an existing `ExpoPushToken`, it is returned unchanged.
- Any other type throws `InvalidArgumentException` with message "The given value cannot be cast to an instance of ExpoPushToken."
```

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

### default() / normal() / high()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Convenience setters that assign priority values 'default', 'normal', or 'high' to the message and return the instance for chaining.

```APIDOC
## `default()` / `normal()` / `high()`

### Description
Convenience setters with no parameters. They assign `'default'`, `'normal'`, and `'high'` respectively to `$priority`, returning `$this`.

### Method
`public function default(): self`
`public function normal(): self`
`public function high(): self`

### Parameters
None.

### Return Value
Returns `$this` for method chaining.

### Usage Example
```php
$message->high();  // priority: 'high'
$message->default(); // priority: 'default'
```
```

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

### Define notification with Expo channel and toExpo()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoChannel.md

Shows a notification class using the 'expo' channel in via() and returning an ExpoMessage from toExpo(). The message is created with a title and body.

```php
use Illuminate\Notifications\Notification;
use NotificationChannels\Expo\ExpoMessage;

class SuspiciousActivityDetected extends Notification
{
    public function via($notifiable): array
    {
        return ['expo']; // ExpoChannel::NAME
    }

    public function toExpo($notifiable): ExpoMessage
    {
        return ExpoMessage::create('Suspicious Activity')
            ->body('Someone tried logging in to your account!');
    }
}
```

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

### JSON data - data()

Source: https://github.com/laravel-notification-channels/expo/blob/main/README.md

Sets the JSON data for the message. JSON payloads exceeding 1 KiB are compressed using Gzip if ext-zlib is available; sending more than 4 KiB is not recommended.

```php
data(Arrayable|Jsonable|JsonSerializable|array $value)
```

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

### Catch both exceptions with multi-catch

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Exceptions.md

Catches both `CouldNotGetReceipts` and `CouldNotSendNotification` in a single catch block, reporting the exception.

```php
use NotificationChannels\Expo\Exceptions\CouldNotGetReceipts;
use NotificationChannels\Expo\Exceptions\CouldNotSendNotification;

try {
    $gateway->getReceipts($ticketIds);
} catch (CouldNotGetReceipts | CouldNotSendNotification $e) {
    report($e);
}
```

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

### playSound() method signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Method signature for playSound(). It takes no parameters and sets $sound to the string 'default', which tells Expo to play the device's default notification sound (iOS only). Custom sounds are not supported.

```php
public function playSound(): self
```

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

### when() and unless()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Conditional helpers from the Conditionable trait that conditionally apply callbacks to the message based on a given value.

```APIDOC
## Conditional helpers (`Conditionable`)

### Description
Provides `when()` and `unless()` methods to conditionally modify the message based on a runtime condition.

### Methods

#### `when(mixed $value, callable $callback, ?callable $default = null)`
- Returns `$this` unless the callback returns a non-null value.
- The callback receives `($this, $value)`.

#### `unless(mixed $value, callable $callback, ?callable $default = null)`
- Returns `$this` unless the callback returns a non-null value.
- The callback receives `($this, $value)`.

### Example
```php
return ExpoMessage::create('Suspicious Activity')
    ->when($notifiable->wantsSound(), fn ($msg) => $msg->playSound())
    ->unless($notifiable->isVip(), fn ($msg) => $msg->normal(), fn ($msg) => $msg->high());
```
```

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

### richContent() method signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Method signature for setting rich content with an image URL. Stores ['image' => $imageUrl] in $richContent. Throws InvalidArgumentException when the URL is empty. On iOS, displaying the image requires a Notification Service Extension.

```php
public function richContent(string $imageUrl): self
```

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

### Implement routeNotificationForExpo() on notifiable

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoChannel.md

Shows the notifiable model must expose routeNotificationForExpo() returning an ExpoPushToken. This is required for the channel to deliver notifications.

```php
class User extends Authenticatable
{
    use Notifiable;

    public function routeNotificationForExpo(): ?ExpoPushToken
    {
        return $this->expo_token;
    }
}
```

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

### Handle invalid token exceptions

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

The make() method throws an InvalidArgumentException if the provided string does not meet the required validation rules.

```php
try {
    ExpoPushToken::make('not-a-token');
} catch (InvalidArgumentException $e) {
    // "not-a-token is not a valid push token."
}
```

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

### Send notification

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoChannel.md

Sends the notification using the notify() method on the user instance.

```php
$user->notify(new SuspiciousActivityDetected());
```

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

### castUsing()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

Static method that returns the fully qualified class name of the AsExpoPushToken cast, enabling the class to be used as an Eloquent custom cast.

```APIDOC
## `castUsing()`

### Description
Returns the FQCN `NotificationChannels\Expo\Casts\AsExpoPushToken`, making the class usable as an Eloquent custom cast.

### Method
`castUsing`

### Signature
```php
public static function castUsing(array $arguments): string
```

### Parameters
- **$arguments** (`array<int, string>`) - Required - Cast constructor arguments (unused by the caster)

### Return Value
- `string` - The fully qualified class name `NotificationChannels\Expo\Casts\AsExpoPushToken`

### Example
```php
protected function casts(): array
{
    return [
        'expo_token' => ExpoPushToken::class,
    ];
}
```
```

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

### ExpoPushToken::make()

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoPushToken.md

Creates a validated ExpoPushToken instance from a raw push token string. Throws InvalidArgumentException if the token is invalid.

```APIDOC
## `make()`

### Description
Creates a validated `ExpoPushToken` instance from a raw push token string. Throws `InvalidArgumentException` if the token fails validation.

### Method
`public static function make(string $token): self`

### Parameters
- **$token** (string) - Required - The raw push token string to validate and wrap.

### Returns
- **ExpoPushToken** - A validated `ExpoPushToken` instance.

### Throws
- **InvalidArgumentException** - If the token fails any of the validation rules.

### Validation Rules
1. The token must be at least 16 characters long.
2. The token must start with `ExponentPushToken[` or `ExpoPushToken[`.
3. The token must end with `]`.

### Request Example
```php
use NotificationChannels\Expo\ExpoPushToken;

$token = ExpoPushToken::make('ExponentPushToken[FtT1dBIc5Wp92HEGuJUhL4]');
```

### Error Example
```php
try {
    ExpoPushToken::make('not-a-token');
} catch (InvalidArgumentException $e) {
    // "not-a-token is not a valid push token."
}
```
```

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

### title() method signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Method signature for setting a title. Throws InvalidArgumentException when the value is empty.

```php
public function title(string $value): self
```

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

### toJson() method implementation

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoEnvelope.md

Serializes the envelope to a JSON string using json_encode with the given options. Returns empty string on failure.

```php
public function toJson($options = 0): string
{
    return json_encode($this->toArray(), $options) ?: '';
}
```

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

### ExpoMessage::create() signature

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Signature of the static factory method that returns a new ExpoMessage. The constructor is private, so this is the entry point for building a message.

```php
public static function create(string $title = '', string $body = ''): self
```

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

### Set data payload and handle JsonException

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoMessage.md

Sets arbitrary JSON data delivered to the app. Converts Arrayable via toArray(), Jsonable via toJson(JSON_THROW_ON_ERROR), and other values via json_encode with JSON_THROW_ON_ERROR. Throws JsonException on encoding failure, e.g. invalid UTF-8 or infinite recursion.

```php
public function data(Arrayable|Jsonable|JsonSerializable|array $value): self
```

```php
$message->data(['email' => 'user@example.com', 'id' => 42]);
```

```php
try {
    $message->data($invalidUtf8Payload); // throws JsonException
} catch (JsonException $e) {
    Log::error('Could not encode message data', ['exception' => $e]);
}
```

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

### Catch CouldNotGetReceipts and log warning

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/Exceptions.md

Catches the exception thrown when the receipts endpoint fails, logs a warning, and suggests retrying later.

```php
use NotificationChannels\Expo\Exceptions\CouldNotGetReceipts;

try {
    $receipts = $gateway->getReceipts($ticketIds);
} catch (CouldNotGetReceipts $e) {
    Log::warning('Receipt polling failed', ['message' => $e->getMessage()]);
    // retry later; receipts for still-pending tickets come back eventually
}
```

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

### Class declaration for ExpoServiceProvider

Source: https://github.com/laravel-notification-channels/expo/blob/main/_autodocs/api-reference/ExpoServiceProvider.md

Declares the final class ExpoServiceProvider extending ServiceProvider.

```php
final class ExpoServiceProvider extends ServiceProvider
```
Tokens:
Raw