Luminova Framework

PHP Luminova: Notification Service Message Model

Last updated: 2024-08-28 22:36:27

Build Firebase notification message payload configurations using the Luminova Message model.

The notification Message model enables you to build a notification payload efficiently. It provides various methods to add custom fields to the notification payload, to customize your application requirements and platform configuration settings.


  • Class namespace: \Luminova\Notifications\Models\Message
  • This class is marked as final and can't be subclassed
  • This class is a Final class

Constants

This constants represent platform specific notifications configuration.

ConstantVisibilityTypeValue
DEFAULTpublicint1
ANDROIDpublicint2
APNpublicint3
WEBPUSHpublicint4

Methods

Example Usage

$message = new Message();
$message->setPlatform(Message::ANDROID)
  ->setRaw(false)
  ->setToken('your_single_notification_token')
  ->setTopic('your_topic')
  ->setTokens(['token1', 'token2'])
  ->add('foo', 'value', 'android')
  ->addNested('foo.bar.baz', 'baz value')
  ->addData('key', 'value1')
  ->addAndroid('key', 'value')
  ->addApns('key' => 'value')
  ->addWebpush(['key' => 'value'])
  ->setFcmOptions(['key' => 'value'])
  ->setNotification([
      'title' => 'Your Notification Title',
      'body' => 'Your Notification Message',
      'image' => 'https://example.com/image.png'
  ]);

constructor

Initialize new message model, you can optionally pass an array to build your notification payload from.

public __construct(array|null $setter = null): mixed

Parameters:

ParameterTypeDescription
$setterarray|nullAn optional array to initialize model from.

Setter Fields

  • platform (int) Notification specific platform (default: 1).
  • raw bool - Send notification from your build payload or array without modifying.
  • token string - Single notification token, (required) if you are sending notification to a single device.
  • topic string - Single notification topic, (required) if you are sending notification to a topic/channel.
  • tokens array<int,string> - Multiple notification tokens, (required) if you are sending notification to multiple device tokens.
  • data array<string,mixed> - Optional data to send with the notification.
  • android array<string,mixed> - Android specific configuration.
  • apns array<string,mixed> - APNs specific configuration.
  • webpush array<string,mixed> - WebPush specific configuration.
  • fcm_options array<string,mixed> - Optional firebase configurations.
  • notification array<string,mixed> - Notification payload information.
      • title (string) Notification title.
      • body (string) Notification message body.
      • image (string) Notification image URL.

Setter Fields Array Example

<?php 
$setter = [
  'platform' => 1, // Default for all platforms
  'raw' => false, // Default no raw payload
  'token' => 'your_single_notification_token',
  'topic' => 'your_topic',
  'tokens' => ['token1', 'token2'],
  'data' => ['key1' => 'value1', 'key2' => 'value2'],
  'android' => [
    'key' => 'value'
  ],
  'apns' => [
    'key' => 'value'
  ],
  'webpush' => [
    'key' => 'value'
  ],
  'fcm_options' => [
    'key' => 'value'
  ],
  'notification' => [
    'title' => 'Your Notification Title',
    'body' => 'Your Notification Message',
    'image' => 'https://example.com/image.png'
  ]
];

See Also:


add

The add method allows you to add key-value pairs to the notification payload. It supports nested payload structures and can merge values recursively if needed. If the root key is specified, the method ensures that the payload under the root is an array before adding or merging the key-value pair.

public add(string $key, mixed $value, string|null $root = null): self

Parameters:

ParameterTypeDescription
$keystringThe key to add.
$valuemixedThe value to associate with the key.
$rootstring|nullOptional root key for nested payloads, if NUll, the key will be store in payload root instead. and replace any existing key value.

Return Value:

self - Return notification message model instance for method chaining.

Example

<?php
use \Luminova\Notifications\Models\Message;

$message = new Message();

// Add top-level key-value pair
$message->add('title', 'New Message');

// Add nested key-value pair
$message->add('body', 'You have a new message', 'notification');

// Add and merge array values
$message->add('data', ['key1' => 'value1'], 'extra');
$message->add('data', ['key2' => 'value2'], 'extra');

Example payload after additions

[
    'title' => 'New Message',
    'notification' => [
        'body' => 'You have a new message'
    ],
    'extra' => [
        'data' => [
            'key1' => 'value1',
            'key2' => 'value2'
        ]
    ]
]

addNested

Add a nested configuration key-value pair to the payload using dot (.) notation string as a delimiter to represent the nested structure of keys.

The addNested method is designed to enhance the addition of values to deeply nested structures within the payload. It parses a dot notation string to determine the nested keys and sets the provided value at the correct depth in the payload.

public addNested(string $keys, mixed $value): self

Parameters:

ParameterTypeDescription
$keysstringThe dot-separated keys representing the nested structure.
$valuemixedThe value to set at the specified nested location. It can be of any type (string, array, etc.).

Return Value:

self - Return notification message model instance for method chaining. Returns the updated instance of the class, allowing method chaining.

Example

Add a value to a deeply nested structure using dot notation.

<?php
use \Luminova\Notifications\Models\Message;

$message = new Message();
$message->addNested('notification.alerts.urgent', 'Immediate attention required');

Example payload after addition.

[
  'notification' => [
      'alerts' => [
          'urgent' => 'Immediate attention required'
      ]
  ]
];

Chain multiple additions

$message->addNested('notification.alerts.low', 'Routine checkup')
  ->addNested('notification.alerts.medium', 'Scheduled maintenance');

Example payload after chaining additions.

[
  'notification' => [
      'alerts' => [
          'urgent' => 'Immediate attention required',
          'low' => 'Routine checkup',
          'medium' => 'Scheduled maintenance'
      ]
  ]
];

addApns

Add APNs specific configuration key-value pair to notification payload.

public addApns(string $key, mixed $value): self

Parameters:

ParameterTypeDescription
$keystringThe key to add.
$valuemixedThe value to associate with the key.

Return Value:

self - Return notification message model instance for method chaining.


addWebpush

Add WebPush specific configuration key-value pair to the notification payload.

public addWebpush(string $key, mixed $value): self

Parameters:

ParameterTypeDescription
$keystringThe key to add.
$valuemixedThe value to associate with the key.

Return Value:

self - Return notification message model instance for method chaining.


addAndroid

Add Android specific configuration key-value pair to the notification payload.

public addAndroid(string $key, mixed $value): self

Parameters:

ParameterTypeDescription
$keystringThe key to add.
$valuemixedThe value to associate with the key.

Return Value:

self - Return notification message model instance for method chaining.


addData

Add a custom key-value pair to notification data object.

public addData(string $key, string $value): self

Parameters:

ParameterTypeDescription
$keystringThe key to add.
$valuestringThe value to associate with the key.

Return Value:

self - Return notification message model instance for method chaining.


addNotification

Add a key-value pair to the notification object.

public addNotification(string $key, string $value): self

Parameters:

ParameterTypeDescription
$keystringThe key to add.
$valuestringThe value to associate with the key.

Return Value:

self - Return notification message model instance for method chaining.


setNotification

Set array of key-value pair to the notification object.

public setNotification(array&lt;string,mixed&gt; $notification): self

Parameters:

ParameterTypeDescription
$notificationarray<string,mixed>The notification payload object.

Return Value:

self - Return notification message model instance for method chaining.


setFcmOptions

Set FCM options. array of key-value pair to the fcm_options object.

public setFcmOptions(array&lt;string,mixed&gt; $options): self

Parameters:

ParameterTypeDescription
$optionsarray<string,mixed>The FCM options.

Return Value:

self - Return notification message model instance for method chaining.


setTitle

Set the display title for notification.

public setTitle(string $title): self

Parameters:

ParameterTypeDescription
$titlestringThe notification title.

Return Value:

self - Return notification message model instance for method chaining.


setBody

Set the display body for notification.

public setBody(string $body): self

Parameters:

ParameterTypeDescription
$bodystringNotification message body.

Return Value:

self - Return notification message model instance for method chaining.


setImageUrl

Set the image URL for notification.

public setImageUrl(string $url): self

Parameters:

ParameterTypeDescription
$urlstringThe image url to set.

Return Value:

self - Return notification message model instance for method chaining.


setIcon

Set the icon for the notification.

public setIcon(string $icon): self

Parameters:

ParameterTypeDescription
$iconstringThe notification icon.

Return Value:

self - Return notification message model instance for method chaining.


setSound

Set the sound for the notification.

public setSound(string $sound): self

Parameters:

ParameterTypeDescription
$soundstringNotification sound.

Return Value:

self - Return notification message model instance for method chaining.


setVibration

Set the vibration pattern for the notification.

public setVibration(array $vibrate): self

Parameters:

ParameterTypeDescription
$vibratearrayThe vibrate pattern e.g. [200, 100, 200].

Return Value:

self - Return notification message model instance for method chaining.


setTag

Set a tag for the notification.

public setTag(string $tag): self

Parameters:

ParameterTypeDescription
$tagstringThe notification tag.

Return Value:

self - Return notification message model instance for method chaining.


setColor

Set a color for the notification.

public setColor(string $color): self

Parameters:

ParameterTypeDescription
$colorstringThe notification color.

Return Value:

self - Return notification message model instance for method chaining.


setAnalytic

Set the analytic label for the notification.

public setAnalytic(string $analytic): self

Parameters:

ParameterTypeDescription
$analyticstringSet analytic label.

Return Value:

self - Return notification message model instance for method chaining.


setPriority

Set the notification priority.

public setPriority(string $priority): self

Parameters:

ParameterTypeDescription
$prioritystringThe notification priority (e.g normal).

Return Value:

self - Return notification message model instance for method chaining.


setTtl

Set TTL for the notification.

public setTtl(string $ttl): self

Parameters:

ParameterTypeDescription
$ttlstringThe ttl (e.g. 3600s).

Return Value:

self - Return notification message model instance for method chaining.


Set a link to open when notification is clicked.

public setLink(string $url): self

Parameters:

ParameterTypeDescription
$urlstringThe notification action url.

Return Value:

self - Return notification message model instance for method chaining.


setClickAction

Set click action, an activity with a matching intent filter is launched when a user clicks on the notification.

public setClickAction(string $action): self

Parameters:

ParameterTypeDescription
$actionstringThe notification intent action.

Return Value:

self - Return notification message model instance for method chaining.


setBadgeCount

Sets the number of badge count this notification will add.

public setBadgeCount(int $count): self

This may be displayed as a badge count for launchers that support badging.

Parameters:

ParameterTypeDescription
$countintThe number of badge to add for this notification.

Return Value:

self - Return notification message model instance for method chaining.


setPackage

Sets package restriction, the package name of your application where the registration token must match in order to receive the message.

public setPackage(string $package): self

Parameters:

ParameterTypeDescription
$packagestringThe notification package restriction (e.g: com.app.name.foo).

Return Value:

self - Return notification message model instance for method chaining.


isRaw

Determine if notification should be sent raw from payload array.

public isRaw(): bool

Return Value:

bool - Return true if should send notification as raw, otherwise false.


setRaw

Set raw flag, to send notification raw from payload array, instead of building notification.

public setRaw(bool $raw): self

Parameters:

ParameterTypeDescription
$rawboolShould send notification as raw, otherwise false.

Return Value:

self - Return notification message model instance for method chaining.


setTopic

Set the notification topic to use when called channel method.

public setTopic(string $topic): self

Parameters:

ParameterTypeDescription
$topicstringThe notification topic name.

Return Value:

self - Return notification message model instance for method chaining.


setConditions

Set the notification topic conditional expression to use when called condition method.

public setConditions(string $conditions): self

Parameters:

ParameterTypeDescription
$conditionsstringThe conditional expression.

Return Value:

self - Return notification message model instance for method chaining.


setTokens

Set the notification device tokens to use when called broadcast method.

public setTokens(array&lt;int,string&gt; $tokens): self

Parameters:

ParameterTypeDescription
$tokensarray<int,string>The device notification tokens.

Return Value:

self - Return notification message model instance for method chaining.


setToken

Set the notification device token to use when called send method.

public setToken(string $token): self

Parameters:

ParameterTypeDescription
$tokenstringThe notification device token.

Return Value:

self - Return notification message model instance for method chaining.


setPlatform

Set the notification platform type.

public setPlatform(int $platform): self

Parameters:

ParameterTypeDescription
$platformintThe notification platform.

Expected Platforms

  • Message::DEFAULT 1 - Default notification without platform specific.
  • Message::ANDROID 2 - Android platform.
  • Message::APN 3 - APNs platform.
  • Message::WEBPUSH 4 - WebPush platform.

Return Value:

self - Return notification message model instance for method chaining.


getTokens

Get the array of notification device tokens.

public getTokens(): array

Return Value:

array - Return the array of notification device tokens.


getConditions

Get notification topic conditional expression.

public getConditions(): string

Return Value:

string - Return notification topic expression.


getToken

Get notification token.

public getToken(): string

Return Value:

string - Return notification token.


getPlatform

Get notification platform id.

public getPlatform(): int

Return Value:

int - Returns the notification platform id.


getPriority

Get notification priority.

public getPriority(): string

Return Value:

string - Return notification priority.


getTitle

Get notification title.

public getTitle(): string

Return Value:

string - Return notification title.


getBody

Get notification body.

public getBody(): string

Return Value:

string - Return notification body.


getData

Get notification custom data.

public getData(): array&lt;string,mixed&gt;

Return Value:

array&lt;string,mixed&gt; - Returns the notification data.


getImageUrl

Get notification image url.

public getImageUrl(): string

Return Value:

string - Return notification image url.


getTopic

Get notification channel topic.

public getTopic(): string

Return Value:

string - Returns notification channel topic.


getAnalytic

Get notification analytic label.

public getAnalytic(): string

Return Value:

string - Return notification analytics label.


get

Get key from notification object.

public get( $key,  $default = null): mixed

Parameters:

ParameterTypeDescription
$key****Key to retrieve.
$default****Default value.

Return Value:

mixed - Return notification key value.


getPayload

Get notification payload or a specific key from payload.

public getPayload(string $key = null): mixed

Parameters:

ParameterTypeDescription
$keystringOptional key to retrieve from payload.

Return Value:

mixed - Return array of notification payload or value from passed key.


fromArray

Process notification payload and return an array representing full notification configurations.

public fromArray(): array&lt;string,mixed&gt;

Return Value:

array&lt;string,mixed&gt; - Return notification payload.