Laravel FCM Notification Channel

https://github.com/laravel-notification-channels/fcm
Admin
This package makes it easy to send notifications using Firebase Cloud Messaging (FCM) with Laravel.
Tokens:33,349
Snippets:233
Trust Score:8.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### notification() usage example

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Shows how to create a message with a notification resource using named arguments.

```php
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

$message = FcmMessage::create()->notification(
    new FcmNotification(title: 'Title', body: 'Body', image: 'https://example.com/img.png')
);
```

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

### Install via Composer

Source: https://github.com/laravel-notification-channels/fcm/blob/master/README.md

Use Composer to install the laravel-notification-channels/fcm package. Run this command in your project root.

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

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

### Creating an FcmMessage instance

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Example of creating an FcmMessage with named arguments, including a notification payload.

```php
use NotificationChannels\Fcm\FcmMessage;
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

$message = new FcmMessage(
    name: 'welcome',
    data: ['key' => 'value'],
    notification: new FcmNotification(
        title: 'Welcome',
        body: 'Glad to have you.',
    ),
);
```

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

### ios() usage example

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Shows how to call ios() with an APNs payload to set a custom sound.

```php
$message->ios(['payload' => ['aps' => ['sound' => 'default']]]);
```

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

### android() usage example

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Example of calling android() with a notification channel ID. The options are stored under the 'android' key of the custom property.

```php
$message->android(['notification' => ['channel_id' => 'abc123']]);
```

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

### Example: Creating an FcmNotification instance

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Shows how to instantiate the Notification class with named arguments. The import is aliased to avoid conflict with Illuminate\Notifications\Notification.

```php
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

$notification = new FcmNotification(
    title: 'Account Activated',
    body: 'Your account has been activated.',
    image: 'http://example.com/url-to-image-here.png',
);
```

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

### Example: FcmMessage with Notification and toArray()

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Example usage of FcmMessage::create() with a Notification instance, then calling toArray() to get the payload. The comment shows the expected output array with the notification key.

```php
$message = FcmMessage::create()->notification(
    new Notification(title: 'Title', body: 'Body')
);

$payload = $message->toArray();
// ['notification' => ['title' => 'Title', 'body' => 'Body']]
```

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

### usingClient() usage example

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Shows how to override the Firebase client per message by resolving a custom client and passing it to usingClient().

```php
public function toFcm($notifiable)
{
    $client = app(\Kreait\Firebase\Contract\Messaging::class); // per-message credentials

    return FcmMessage::create()
        ->data(['key' => 'value'])
        ->usingClient($client);
}
```

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

### Using Notification::create() with named arguments

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/FcmResource.md

Example of using the inherited `create()` factory to instantiate a concrete resource with named arguments. This demonstrates how `Notification::create()` returns a `Notification` instance, not an `FcmResource`.

```php
use NotificationChannels\Fcm\Resources\Notification;

$notification = Notification::create(title: 'Hello', body: 'World');
```

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

### Fluent notification creation with title, body, and image

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Fluent usage example that chains title, body, and image setters on a Notification instance.

```php
$notification = Notification::create()
    ->title('Title')
    ->body('Body')
    ->image('https://example.com/image.png');
```

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

### Run tests with composer test

Source: https://github.com/laravel-notification-channels/fcm/blob/master/README.md

Use this command to run the package's test suite. It executes the PHPUnit tests configured for the project. Ensure Composer dependencies are installed before running.

```bash
composer test
```

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

### toArray() usage example

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Shows how to create a message with name, data, and android custom options, then convert to array. The resulting array includes the name, data, and android keys, with the android key coming from the custom array spread.

```php
$payload = FcmMessage::create()
    ->name('welcome')
    ->data(['key' => 'value'])
    ->android(['notification' => ['color' => '#000']])
    ->toArray();

// [
//   'name'         => 'welcome',
//   'data'         => ['key' => 'value'],
//   'android'      => ['notification' => ['color' => '#000']],
// ]
```

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

### custom() usage example

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Example of calling custom() with Android-specific options. The array is spread into the top level of toArray(), so custom keys become top-level Firebase message keys.

```php
$message->custom([
    'android' => [
        'notification' => ['color' => '#0A0A0A'],
        'fcm_options'  => ['analytics_label' => 'analytics'],
    ],
]);
```

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

### Class declaration for FcmResource\Notification

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Declares the Notification class extending FcmResource. This is the starting point for the resource value object.

```php
class Notification extends FcmResource
{
```

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

### Handling NotificationFailed event for FcmTopicChannel

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmTopicChannel.md

Error handling example for FcmTopicChannel. When a MessagingException is caught during send, a NotificationFailed event is dispatched with the exception under the 'exception' data key. This listener checks the channel and retrieves the exception for logging, retrying, or alerting.

```php
use Illuminate\Notifications\Events\NotificationFailed;
use Illuminate\Support\Arr;
use Kreait\Firebase\Exception\MessagingException;

class HandleTopicFailure
{
    public function handle(NotificationFailed $event): void
    {
        if ($event->channel == FcmTopicChannel::class) {
            $exception = Arr::get($event->data, 'exception');

            if ($exception instanceof MessagingException) {
                // e.g. log, retry, alert
            }
        }
    }
}

```

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

### Basic FCM notification example

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmChannel.md

Basic usage of the FCM channel: define a notification with `via` returning `FcmChannel::class` and a `toFcm` method that returns an `FcmMessage`. The notifiable model must implement `routeNotificationForFcm` to return a token string or an array of tokens for multicast. Sending is done via `$user->notify(new AccountActivated)`.

```php
use Illuminate\Notifications\Notification;
use NotificationChannels\Fcm\FcmChannel;
use NotificationChannels\Fcm\FcmMessage;

class AccountActivated extends Notification
{
    public function via($notifiable)
    {
        return [FcmChannel::class];
    }

    public function toFcm($notifiable): FcmMessage
    {
        return FcmMessage::create()->data(['type' => 'account-activated']);
    }
}

// Notifiable model:
class User
{
    use Notifiable;

    // Returns a single token string or an array of token strings (multicast).
    public function routeNotificationForFcm($notification)
    {
        return $this->getDeviceTokens();
    }
}

// Send:
$user->notify(new AccountActivated);
```

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

### Handle NotificationFailed event to delete expired tokens

Source: https://github.com/laravel-notification-channels/fcm/blob/master/README.md

Listen for the Illuminate\Notifications\Events\NotificationFailed event to handle failures. The example deletes expired notification tokens from the database when the failure is for FcmChannel.

```php
<?php

namespace App\Listeners;

use Illuminate\Notifications\Events\NotificationFailed;
use Illuminate\Support\Arr;

class DeleteExpiredNotificationTokens
{
    /**
     * Handle the event.
     */
    public function handle(NotificationFailed $event): void
    {
        if ($event->channel == FcmChannel::class) {

            $report = Arr::get($event->data, 'report');

            $target = $report->target();

            $event->notifiable->notificationTokens()
                ->where('push_token', $target->value())
                ->delete();
        }
    }
}
```

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

### Resources\Notification::__construct()

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/configuration.md

Creates a new Resources\Notification instance. All constructor arguments are optional and default to null. Fluent setters are also available for each option.

```APIDOC
## Resources\Notification::__construct()

### Description
Creates a new Resources\Notification instance. All constructor arguments are optional and default to null. Fluent setters are also available for each option.

### Method
CONSTRUCTOR

### Endpoint
Resources\Notification::__construct()

### Parameters
#### Constructor Parameters (all optional)
- **title** (?string) - Optional - Notification title
- **body** (?string) - Optional - Notification body text
- **image** (?string) - Optional - Notification image URL

### Fluent Equivalents
- title()
- body()
- image()

### Request Example
```php
$notification = new Resources\Notification(
    title: 'Hello',
    body: 'World',
    image: 'https://example.com/image.png'
);
```

### Response
#### Success Response
Returns a new Resources\Notification instance.

#### Response Example
```php
Resources\Notification { ... }
```
```

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

### FcmResource::create

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/FcmResource.md

Static factory method for creating resource instances.

```APIDOC
## `create` (static)

### Description
Static factory method that creates a new instance of the concrete subclass. It forwards the provided arguments to the subclass constructor.

### Method
`create` (static method)

### Signature
```php
public static function create(...$args): static
```

### Parameters
- `$args` (variadic) - Optional - Forwarded to the concrete subclass constructor (named arguments).

### Return Type
`static` - A new instance of the concrete subclass, late-bound.

### Example
```php
use NotificationChannels\Fcm\Resources\Notification;

$notification = Notification::create(title: 'Hello', body: 'World');
```
```

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

### usingClient() method definition

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Defines the usingClient() method that accepts a Messaging client and returns self.

```php
    /**
     * Set the client to use for the message.
     */
    public function usingClient(Messaging $client): self
```

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

### FcmTopicChannel

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmTopicChannel.md

Documentation for the FcmTopicChannel class, including its constructor and parameters.

```APIDOC
## FcmTopicChannel

### Description
Topic-based Firebase Cloud Messaging channel. Sends a notification to a Firebase topic (subscribe/publish style) instead of individual device tokens. If the Firebase client raises a `Kreait\Firebase\Exception\MessagingException`, it is caught and converted into a dispatched `Illuminate\Notifications\Events\NotificationFailed` event.

### Import Path
`use NotificationChannels\Fcm\FcmTopicChannel;` (file `src/FcmTopicChannel.php`)

### Namespace
`NotificationChannels\Fcm`

### Pattern
Instantiated by the `Illuminate\Notifications` framework via container dependency injection.

### Channel Name
`fcm-topic` (resolved through `$notifiable->routeNotificationFor('fcm-topic')` on `AnonymousNotifiable` instances).

### Class Declaration
```php
class FcmTopicChannel
{
```

### Constructor
```php
/**
 * Create a new channel instance.
 */
public function __construct(protected Dispatcher $events, protected Messaging $client)
{
    //
}
```

#### Parameters
- **$events** (`Illuminate\Contracts\Events\Dispatcher`) - Required - Event dispatcher used to emit `NotificationFailed` events
- **$client** (`Kreait\Firebase\Contract\Messaging`) - Required - Firebase Messaging client used for the topic `send` (overridable per message via `FcmMessage::usingClient()`)

Both parameters are constructor-promoted to protected properties `$this->events` and `$this->client`.
```

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

### FcmMessage constructor

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Constructor with optional named arguments, each promoted to a public property. All parameters default to null or empty arrays.

```php
    /**
     * Create a new message instance.
     */
    public function __construct(
        public ?string $name = null,
        public ?string $token = null,
        public ?string $topic = null,
        public ?string $condition = null,
        public ?array $data = [],
        public ?array $custom = [],
        public ?Notification $notification = null,
        public ?Messaging $client = null,
    ) {
        //
    }
```

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

### Catching InvalidArgumentException in toFcm()

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/errors.md

Shows how to catch the InvalidArgumentException thrown by FcmMessage::data() when a non-string value is passed. The exception is thrown before $this->data is mutated, so a failed call leaves the message unchanged. The example coerces a numeric value to a string inside the catch block.

```php
use Illuminate\Notifications\Notification;
use NotificationChannels\Fcm\FcmMessage;

class CurrencyAlert extends Notification
{
    public function toFcm($notifiable)
    {
        $message = FcmMessage::create();

        try {
            $message->data(['rate' => number_to_string($this->rate)]); // numeric → must be converted
        } catch (InvalidArgumentException $e) {
            // 'Data values must be strings.' — coerce instead
            $message->data(['rate' => (string) $this->rate]);
        }

        return $message;
    }
}
```

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

### FcmMessage::create()

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/configuration.md

Creates a new FcmMessage instance. All constructor arguments are optional and default to null or empty arrays. Fluent setters are also available for each option.

```APIDOC
## FcmMessage::create()

### Description
Creates a new FcmMessage instance. All constructor arguments are optional and default to null or empty arrays. Fluent setters are also available for each option.

### Method
CONSTRUCTOR

### Endpoint
FcmMessage::__construct()

### Parameters
#### Constructor Parameters (all optional)
- **name** (?string) - Optional - Message name
- **token** (?string) - Optional - Device registration token
- **topic** (?string) - Optional - Topic for topic sends
- **condition** (?string) - Optional - Targeting condition for topic messages
- **data** (?array) - Optional - String-valued key/value data (non-string values rejected)
- **custom** (?array) - Optional - Arbitrary options spread at the top level of the payload
- **notification** (?Notification) - Optional - Notification resource (title/body/image payload)
- **client** (?Messaging) - Optional - Per-message Firebase client override

### Fluent Equivalents
- name()
- token()
- topic()
- condition()
- data()
- custom()
- android()
- ios()
- notification()
- usingClient()

### Request Example
```php
$message = FcmMessage::create();
// or with arguments
$message = FcmMessage::create(
    name: 'My Message',
    token: 'device-token',
    data: ['key' => 'value']
);
```

### Response
#### Success Response
Returns a new FcmMessage instance.

#### Response Example
```php
FcmMessage { ... }
```
```

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

### Notification::create

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Creates a new Notification instance using named arguments forwarded to the constructor.

```APIDOC
## `create` (static, inherited from `FcmResource`)

```php
    public static function create(...$args): static
```

Source: `src/Resources/FcmResource.php:7-11` (inherited)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$args` | variadic | no | — | Forwarded to the `Notification` constructor (named arguments) |

**Return type:** `static` — a new `Notification` instance.

**Example:**

```php
$notification = Notification::create(title: 'Title', body: 'Body');
```
```

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

### Create a new FcmMessage instance

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Static factory method that returns a new FcmMessage instance. Accepts variadic arguments forwarded to the constructor. Returns a late-bound static instance.

```php
    /**
     * Create a new message instance.
     */
    public static function create(...$args): static
    {
        return new static(...$args);
    }
```

```php
$message = FcmMessage::create(name: 'welcome');
```

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

### FcmMessage

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Documentation for the FcmMessage class, including its constructor and parameters.

```APIDOC
## FcmMessage

### Description
Message value object for Firebase Cloud Messaging. Implements `Kreait\Firebase\Messaging\Message` and is the object the framework passes to the Firebase client (`sendMulticast` / `send`). All state is held in public promoted properties; fluent setters mutate and return `self`.

### Import Path
`use NotificationChannels\Fcm\FcmMessage;` (file `src/FcmMessage.php`)

### Namespace
`NotificationChannels\Fcm`

### Trait
`use Macroable;` (`Illuminate\Support\Traits\Macroable`)

### Implements
`Kreait\Firebase\Messaging\Message`

### Class Declaration
```php
class FcmMessage implements Message
{
    use Macroable;
```

### Constructor
```php
public function __construct(
    public ?string $name = null,
    public ?string $token = null,
    public ?string $topic = null,
    public ?string $condition = null,
    public ?array $data = [],
    public ?array $custom = [],
    public ?Notification $notification = null,
    public ?Messaging $client = null,
) {}
```

### Parameters
- **$name** (`?string`) - Optional - Message name
- **$token** (`?string`) - Optional - Single device registration token
- **$topic** (`?string`) - Optional - Topic name the message is published to
- **$condition** (`?string`) - Optional - Notifications to topics/segments condition
- **$data** (`?array`) - Optional - Custom key/value data payload (all values must be strings)
- **$custom** (`?array`) - Optional - Arbitrary platform-specific options; spread at the top level of `toArray()`
- **$notification** (`?Notification`) - Optional - `Resources\Notification` payload rendered under the `notification` key
- **$client** (`?Messaging`) - Optional - Firebase client override; when set, channels use it in place of their injected client

### Example
```php
use NotificationChannels\Fcm\FcmMessage;
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

$message = new FcmMessage(
    name: 'welcome',
    data: ['key' => 'value'],
    notification: new FcmNotification(
        title: 'Welcome',
        body: 'Glad to have you.',
    ),
);
```
```

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

### ios() method definition

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Defines the ios() method that merges APNs options into the custom array under the 'apns' key. Returns self for fluent chaining.

```php
    /**
     * Set APNs-specific custom options.
     */
    public function ios(?array $options = []): self
    {
        $this->custom([...$this->custom, 'apns' => $options]);

        return $this;
    }
```

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

### Create notification with title and body

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Creates a Notification instance using named arguments for title and body.

```php
$notification = Notification::create(title: 'Title', body: 'Body');
```

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

### Notification image method

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Fluent setter for the notification image URL. Accepts a nullable string and returns self for chaining.

```php
    /**
     * Set the notification image.
     */
    public function image(?string $image): self
```

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

### FcmMessage available methods

Source: https://github.com/laravel-notification-channels/fcm/blob/master/README.md

Shows the chainable methods available on FcmMessage for customizing a message: name, token, topic, condition, data, and custom. The complete list of options is in the FcmMessage source.

```php
FcmMessage::create()
    ->name('name')
    ->token('token')
    ->topic('topic')
    ->condition('condition')
    ->data(['a' => 'b'])
    ->custom(['notification' => []]);
```

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

### custom

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Documentation for the `custom` method of the FcmMessage class, which sets custom options for the Firebase message.

```APIDOC
## `custom`

### Description
Sets the message custom options. The provided array is spread into the top level of `toArray()`, so custom keys become top-level Firebase message keys.

### Method
`custom`

### Signature
`public function custom(?array $custom = []): self`

### Parameters
- `$custom` (`?array`, optional, default `[]`) - Arbitrary nested options, e.g. `['android' => [...], 'apns' => [...], 'notification' => [...]]`; replaces the whole `custom` property when called with a value.

### Return Type
`self` - fluent.

### Example
```php
$message->custom([
    'android' => [
        'notification' => ['color' => '#0A0A0A'],
        'fcm_options'  => ['analytics_label' => 'analytics'],
    ],
]);
```
```

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

### Constructor for FcmResource\Notification

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Defines the constructor with optional named parameters for title, body, and image, each promoted to public properties.

```php
    /**
     * Create a new notification instance.
     */
    public function __construct(
        public ?string $title = null,
        public ?string $body = null,
        public ?string $image = null
    ) {
        //
    }
```

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

### Set the message token

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Fluent setter for the device registration token. Accepts a nullable string and returns the same instance for chaining.

```php
    /**
     * Set the message token.
     */
    public function token(?string $token): self
```

```php
FcmMessage::create()->token('device-registration-token-xyz');
```

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

### android() method signature and body

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Signature and body of the android() method, which merges Android-specific options into the existing custom array using a spread merge, preserving previously set custom keys.

```php
    /**
     * Set Aandroid specific custom options.
     */
    public function android(?array $options = []): self
    {
        $this->custom([...$this->custom, 'android' => $options]);

        return $this;
    }
```

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

### notification() method definition

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Defines the notification() method that accepts a Notification resource and returns self.

```php
    /**
     * Set the message notification.
     */
    public function notification(Notification $notification): self
```

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

### Notification::title

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Sets the notification title. Returns the instance for fluent chaining.

```APIDOC
## `title`

```php
    /**
     * Set the notification title.
     */
    public function title(?string $title): self
```

Source: `src/Resources/Notification.php:21-29`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$title` | `?string` | yes | — | Notification title |

**Return type:** `self` — fluent.
```

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

### FcmMessage::token

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the message token. Returns the same instance for fluent chaining.

```APIDOC
## `FcmMessage::token`

### Description
Sets the message token.

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

### Parameters
- `$token` (`?string`) - Required - Single device registration token.

### Return Type
`self` - The same FcmMessage instance (fluent).

### Example
```php
FcmMessage::create()->token('device-registration-token-xyz');
```
```

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

### Notification::body

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Sets the notification body text. Returns the instance for fluent chaining.

```APIDOC
## `body`

```php
    /**
     * Set the notification body.
     */
    public function body(?string $body): self
```

Source: `src/Resources/Notification.php:31-39`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$body` | `?string` | yes | — | Notification body text |

**Return type:** `self` — fluent.
```

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

### Notification::image

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Sets the notification image URL. Returns the instance for fluent chaining.

```APIDOC
## `image`

```php
    /**
     * Set the notification image.
     */
    public function image(?string $image): self
```

Source: `src/Resources/Notification.php:41-49`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$image` | `?string` | yes | — | Notification image URL |

**Return type:** `self` — fluent.

**Example (fluent usage):**

```php
$notification = Notification::create()
    ->title('Title')
    ->body('Body')
    ->image('https://example.com/image.png');
```
```

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

### FcmMessage::name

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the message name. Returns the same instance for fluent chaining.

```APIDOC
## `FcmMessage::name`

### Description
Sets the message name.

### Method
`public function name(?string $name): self`

### Parameters
- `$name` (`?string`) - Required - Message name.

### Return Type
`self` - The same FcmMessage instance (fluent).

### Example
```php
$message = FcmMessage::create()->name('promo');
```
```

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

### Basic on-demand routing with FcmTopicChannel

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmTopicChannel.md

Basic usage of FcmTopicChannel with on-demand routing. The notification's toFcm method returns an FcmMessage without a topic; the topic is supplied via Notification::route(FcmTopicChannel::class, 'news') using an anonymous notifiable.

```php
use Illuminate\Notifications\Notification;
use NotificationChannels\Fcm\FcmMessage;
use NotificationChannels\Fcm\FcmTopicChannel;

class BlogCreated extends Notification
{
    public function toFcm($notifiable)
    {
        return FcmMessage::create()->data(['blog_id' => $this->blog->id]);
    }
}

// Route to the 'news' topic via an anonymous notifiable:
Notification::route(FcmTopicChannel::class, 'news')
    ->notify(new BlogCreated($blog));
```

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

### FcmTopicChannel constructor

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmTopicChannel.md

Constructor that injects the event dispatcher and Firebase Messaging client. Both parameters are constructor-promoted to protected properties. The client can be overridden per message via FcmMessage::usingClient().

```php
    /**
     * Create a new channel instance.
     */
    public function __construct(protected Dispatcher $events, protected Messaging $client)
    {
        //
    }
```

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

### usingClient

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the Firebase Messaging client to use for the message.

```APIDOC
## `usingClient`

### Description
Sets the Firebase Messaging client to use for the message.

### Method
`usingClient`

### Signature
`public function usingClient(Messaging $client): self`

### Parameters
- **$client** (`Kreait\Firebase\Contract\Messaging`) - Required - Firebase Messaging client override.

### Return Type
`self` — fluent.

### Behavior
Stores the client in `$this->client`. Both channels resolve their outbound client as `$message->client ?? $this->client`, so this message-scoped client always wins over the channel's injected client. Useful to switch Firebase credentials per notification.

### Example
```php
public function toFcm($notifiable)
{
    $client = app(\Kreait\Firebase\Contract\Messaging::class); // per-message credentials

    return FcmMessage::create()
        ->data(['key' => 'value'])
        ->usingClient($client);
}
```
```

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

### notification

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the message notification resource.

```APIDOC
## `notification`

### Description
Sets the message notification resource.

### Method
`notification`

### Signature
`public function notification(Notification $notification): self`

### Parameters
- **$notification** (`NotificationChannels\Fcm\Resources\Notification`) - Required - The notification resource rendered under the `notification` key of `toArray()`.

### Return Type
`self` — fluent.

### Example
```php
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

$message = FcmMessage::create()->notification(
    new FcmNotification(title: 'Title', body: 'Body', image: 'https://example.com/img.png')
);
```
```

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

### topic

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the message topic for the FCM message.

```APIDOC
## `topic`

### Description
Sets the message topic for the FCM message.

### Method
`topic`

### Signature
`public function topic(?string $topic): self`

### Parameters
- **$topic** (`?string`) - Required - Topic name

### Return Type
`self` - fluent

### Example
```php
FcmMessage::create()->topic('news');
```
```

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

### Notification Constructor

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Documentation for the Notification resource value object constructor, which creates a Firebase push notification's human-readable content.

```APIDOC
## Notification Constructor

### Description
Creates a new Firebase notification resource value object with optional title, body, and image fields. This object is embedded in an FcmMessage and serialized under the `notification` key of the message payload.

### Method
Constructor

### Endpoint
`new Notification(?string $title = null, ?string $body = null, ?string $image = null)`

### Parameters
- **$title** (?string) - Optional - Notification title
- **$body** (?string) - Optional - Notification body text
- **$image** (?string) - Optional - Notification image URL

### Request Example
```php
use NotificationChannels\Fcm\Resources\Notification as FcmNotification;

$notification = new FcmNotification(
    title: 'Account Activated',
    body: 'Your account has been activated.',
    image: 'http://example.com/url-to-image-here.png',
);
```

### Response
No return value. The constructor initializes the object's public properties.
```

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

### Notification body method

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Fluent setter for the notification body text. Accepts a nullable string and returns self for chaining.

```php
    /**
     * Set the notification body.
     */
    public function body(?string $body): self
```

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

### FcmChannel constructor with injected dependencies

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmChannel.md

Constructor that injects the event dispatcher and Firebase Messaging client. Both dependencies are provided by the container; the client is normally the laravel-firebase-bound implementation for the FIREBASE_CREDENTIALS configuration.

```php
    public function __construct(protected Dispatcher $events, protected Messaging $client)
    {
        //
    }
```

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

### android

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Documentation for the `android` method of the FcmMessage class, which sets Android-specific custom options for the Firebase message.

```APIDOC
## `android`

### Description
Sets Android-specific custom options. The provided options are stored under the `android` key of the `custom` property, merging with any previously set custom keys.

### Method
`android`

### Signature
`public function android(?array $options = []): self`

### Parameters
- `$options` (`?array`, optional, default `[]`) - Android-specific options stored under the `android` key of `custom`.

### Return Type
`self` - fluent.

### Behavior
Merges `['android' => $options]` into the existing `custom` array (spread merge), preserving any previously set custom keys such as `apns` or `meta`.

### Example
```php
$message->android(['notification' => ['channel_id' => 'abc123']]);
```
```

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

### Notification title method

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Fluent setter for the notification title. Accepts a nullable string and returns self for chaining.

```php
    /**
     * Set the notification title.
     */
    public function title(?string $title): self
```

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

### FcmMessage::android()

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/types.md

Sets the android custom options for the message payload. Merges the provided options into the custom array under the 'android' key.

```APIDOC
## FcmMessage::android()

### Description
Sets the android custom options for the message payload. Merges the provided options into the custom array under the 'android' key.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (array) - Required - Nested options such as ['notification' => ['color' => '#0A0A0A', 'channel_id' => …], 'fcm_options' => ['analytics_label' => 'analytics']]

### Request Example
{
  "android": {
    "notification": {
      "color": "#0A0A0A",
      "channel_id": "string"
    },
    "fcm_options": {
      "analytics_label": "analytics"
    }
  }
}

### Response
#### Success Response (200)
- **android** (array) - The android options set

#### Response Example
{
  "android": {
    "notification": {
      "color": "#0A0A0A",
      "channel_id": "string"
    },
    "fcm_options": {
      "analytics_label": "analytics"
    }
  }
}
```

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

### Notification::create static method signature

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Static factory method inherited from FcmResource that forwards variadic arguments to the Notification constructor. Returns a new Notification instance.

```php
public static function create(...$args): static
```

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

### Notification via() method returning FcmChannel

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/configuration.md

Defines the via() method on a notification to return the FCM channel class. Use this to bind a notification to the FCM channel, either FcmChannel or FcmTopicChannel.

```php
public function via($notifiable)
{
    return [FcmChannel::class]; // or [FcmTopicChannel::class]
}
```

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

### routeNotificationForFcm returning multiple tokens

Source: https://github.com/laravel-notification-channels/fcm/blob/master/README.md

Defines the routeNotificationForFcm method to return an array of tokens for multicast notifications to different user devices. The method returns the result of getDeviceTokens().

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

    ...

    /**
     * Specifies the user's FCM tokens
     *
     * @return string|array
     */
    public function routeNotificationForFcm()
    {
        return $this->getDeviceTokens();
    }
}
```

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

### Use a custom Firebase Messaging client with FcmMessage::usingClient

Source: https://github.com/laravel-notification-channels/fcm/blob/master/README.md

Provide a custom Kreait\Firebase\Contract\Messaging instance to the FCM message to override the default client. Useful when you need different Firebase configurations per notification.

```php
public function toFcm(mixed $notifiable): FcmMessage
{
    $client = app(\Kreait\Firebase\Contract\Messaging::class);

    return FcmMessage::create()->usingClient($client);
}
```

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

### Send FCM notification to a topic using FcmTopicChannel

Source: https://github.com/laravel-notification-channels/fcm/blob/master/README.md

Use an on-demand notification to route to a topic by passing the topic name as the route parameter. The notification's toFcm method will be used to build the message.

```php
use NotificationChannels\Fcm\FcmTopicChannel;

Notification::route(FcmTopicChannel::class, 'news')
    ->notify(new BlogCreated($blog));
```

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

### data

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the message data as an associative array where every value must be a string.

```APIDOC
## `data`

### Description
Sets the message data as an associative array where every value must be a string.

### Method
`data`

### Signature
`public function data(?array $data): self`

### Parameters
- **$data** (`?array`) - Required - Associative array; every value must be a string

### Return Type
`self` - fluent

### Throws
- `InvalidArgumentException` with message `Data values must be strings.` when any value in `$data` is not a string (keys are not validated, only values).

### Examples
```php
$message = FcmMessage::create()->data(['data1' => 'value', 'data2' => 'value2']);
```

```php
try {
    $message->data(['bad' => 12345]); // non-string value
} catch (InvalidArgumentException $e) {
    // $e->getMessage() === 'Data values must be strings.'
}
```
```

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

### FcmResource::create() static factory method

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/FcmResource.md

The static factory method that constructs a new instance of the concrete subclass using late static binding. It forwards any arguments to the subclass constructor, allowing named arguments. This method is inherited by all subclasses.

```php
    public static function create(...$args): static
    {
        return new static(...$args);
    }
```

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

### Define routeNotificationForFcm for fcm channel

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/types.md

Defines the token route for the 'fcm' channel. Return a single token string or an array of token strings for multicast. The result is wrapped with Arr::wrap(), so both forms are accepted; empty collections cause send() to return null without calling Firebase.

```php
public function routeNotificationForFcm($notification)
{
    return $this->fcm_token;         // single string
    // or
    return $this->getDeviceTokens(); // array of strings → multicast
}
```

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

### Set the message name

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Fluent setter for the message name. Accepts a nullable string and returns the same instance for chaining.

```php
    /**
     * Set the message name.
     */
    public function name(?string $name): self
```

```php
$message = FcmMessage::create()->name('promo');
```

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

### FcmMessage::ios()

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/types.md

Sets the iOS custom options for the message payload. Merges the provided options into the custom array under the 'apns' key.

```APIDOC
## FcmMessage::ios()

### Description
Sets the iOS custom options for the message payload. Merges the provided options into the custom array under the 'apns' key.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (array) - Required - Nested options such as ['payload' => ['aps' => ['sound' => 'default']], 'fcm_options' => ['analytics_label' => 'analytics']]

### Request Example
{
  "apns": {
    "payload": {
      "aps": {
        "sound": "default"
      }
    },
    "fcm_options": {
      "analytics_label": "analytics"
    }
  }
}

### Response
#### Success Response (200)
- **apns** (array) - The iOS options set

#### Response Example
{
  "apns": {
    "payload": {
      "aps": {
        "sound": "default"
      }
    },
    "fcm_options": {
      "analytics_label": "analytics"
    }
  }
}
```

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

### jsonSerialize() method implementation

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Returns the result of toArray() for JSON serialization. Annotated with #\ReturnTypeWillChange to suppress deprecation warnings.

```php
    /**
     * @return mixed
     */
    #\ReturnTypeWillChange
    public function jsonSerialize()
    {
        return $this->toArray();
    }
```

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

### condition

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the message condition for targeting notification groups or topics.

```APIDOC
## `condition`

### Description
Sets the message condition for targeting notification groups or topics.

### Method
`condition`

### Signature
`public function condition(?string $condition): self`

### Parameters
- **$condition** (`?string`) - Required - Condition expression for targeting notification groups/topics

### Return Type
`self` - fluent

### Example
```php
FcmMessage::create()->topic('news')->condition("'TopicA' in topics || 'TopicB' in topics");
```
```

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

### FcmResource abstract class declaration

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/FcmResource.md

The abstract base class for all FCM resource value objects. It provides the static factory method `create()` and enforces the `toArray()` contract on subclasses. This class is not meant to be instantiated directly.

```php
abstract class FcmResource
{
    public static function create(...$args): static
    {
        return new static(...$args);
    }

    /**
     * Map the resource to an array.
     */
    abstract public function toArray(): array;
}
```

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

### custom() method signature

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Signature of the custom() method, which sets custom message options. Accepts an optional array and returns $this for fluent chaining.

```php
    /**
     * Set the message custom options.
     */
    public function custom(?array $custom = []): self
```

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

### ios

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets APNs-specific custom options on the FCM message.

```APIDOC
## `ios`

### Description
Sets APNs-specific custom options on the FCM message.

### Method
`ios`

### Signature
`public function ios(?array $options = []): self`

### Parameters
- **$options** (`?array`) - Optional - Default: `[]` - APNs-specific options stored under the `apns` key of `custom`.

### Return Type
`self` — fluent.

### Behavior
Merges `['apns' => $options]` into the existing `custom` array, preserving other custom keys.

### Example
```php
$message->ios(['payload' => ['aps' => ['sound' => 'default']]]);
```
```

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

### FcmResource::toArray() abstract method

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/FcmResource.md

The abstract method that every concrete subclass must implement to serialize its fields into an array. For `Notification`, this produces the `title`/`body`/`image` payload consumed by `FcmMessage::toArray()` under the `notification` key.

```php
    /**
     * Map the resource to an array.
     */
    abstract public function toArray(): array;
```

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

### FcmChannel class declaration with TOKENS_PER_REQUEST constant

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmChannel.md

Declares the FcmChannel class with a constant defining the maximum number of device tokens per Firebase multicast request. Token lists are chunked by this amount before dispatch.

```php
class FcmChannel
{
    /**
     * The maximum number of tokens we can use in a single request.
     */
    const int TOKENS_PER_REQUEST = 500;
```

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

### Set message topic

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmMessage.md

Sets the message topic. The topic is read by FcmTopicChannel::send() and overwritten with the routed topic. Returns $this for fluent chaining.

```php
    /**
     * Set the message topic.
     */
    public function topic(?string $topic): self
```

```php
FcmMessage::create()->topic('news');
```

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

### Notification::toArray() implementation

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/Notification.md

Implementation of the toArray() method on the Notification resource. It returns an array with 'title', 'body', and 'image' keys, filtering out null values with array_filter. This method is called by FcmMessage::toArray() and the result is placed under the 'notification' key.

```php
    /**
     * Map the resource to an array.
     */
    public function toArray(): array
    {
        return array_filter([
            'title' => $this->title,
            'body' => $this->body,
            'image' => $this->image,
        ]);
    }
```

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

### FcmChannel::send() - Send FCM notification

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmChannel.md

The `send` method of `FcmChannel` collects device tokens from the notifiable, builds the FCM message, and sends it in chunks of 500 tokens via `sendMulticast`. It returns a collection of `MulticastSendReport` objects or `null` if no tokens are provided. Exceptions from `sendMulticast` propagate to the caller; only per-token failures become `NotificationFailed` events.

```php
    /**
     * Send the given notification.
     */
    public function send(mixed $notifiable, Notification $notification): ?Collection
    {
        $tokens = Arr::wrap($notifiable->routeNotificationFor('fcm', $notification));

        if (empty($tokens)) {
            return null;
        }

        $message = $notification->toFcm($notifiable);

        $client = $message->client ?? $this->client;

        return Collection::make($tokens)
            ->chunk(self::TOKENS_PER_REQUEST)
            ->map(fn ($tokens) => $client->sendMulticast($message, $tokens->all()))
            ->map(fn (MulticastSendReport $report) => $this->checkReportForFailures($notifiable, $notification, $report));
    }
```

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

### FcmResource::toArray

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/Resources/FcmResource.md

Abstract method that subclasses must implement to serialize the resource to an array.

```APIDOC
## `toArray` (abstract)

### Description
Abstract method that maps the resource to an array. Every concrete subclass must implement this method to serialize its fields.

### Method
`toArray` (abstract method)

### Signature
```php
abstract public function toArray(): array;
```

### Return Type
`array` - The serialized resource payload.

### Behavior
Contract method. Every concrete subclass must implement the mapping of its fields to an array. For `Notification` this produces the `title`/`body`/`image` payload consumed by `FcmMessage::toArray()` under the `notification` key.
```

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

### Setting topic on FcmMessage for model-based notifiable

Source: https://github.com/laravel-notification-channels/fcm/blob/master/_autodocs/api-reference/FcmTopicChannel.md

Usage of FcmTopicChannel with a model-based notifiable. The topic is set directly on the FcmMessage via the topic('news') method inside toFcm.

```php
class BlogCreated extends Notification
{
    public function toFcm($notifiable)
    {
        return FcmMessage::create()
            ->topic('news')
            ->data(['blog_id' => $this->blog->id]);
    }
}

```
Tokens:
Raw