Alert API

The API provides the ability to create alerts (message boxes) with custom messages.

This extension is NOT included by default in the boson-php/runtime and must be installed separately.

Linux is currently not supported and will throw an exception.

#Installation

Via Composer:

composer require boson-php/app-ext-alert

After that, add the extension to the config:

new Boson\ApplicationCreateInfo(
    extensions: [
        ...Boson\ApplicationCreateInfo::DEFAULT_APPLICATION_EXTENSIONS,
        // ...
        new Boson\Api\Alert\AlertExtension(),
    ],
);

#Usage

You can access the subsystem using Application::$alert property.

$app = new Boson\Application();

$app->alert; // Access to Alert API

#Creating

To create an alert, you should use the create() method, passing there a configuration DTO Boson\Api\Alert\AlertCreateInfo with a title and a message.

use Boson\Application;
use Boson\Api\Alert\AlertCreateInfo;

$app = new Application();

$app->alert->create(new AlertCreateInfo(
    title: 'Title',
    text: 'Message',
));

After the call, you will receive a corresponding message box.

On Windows:

On macOS:

The alert call is blocking and stops the application until the user makes a choice (clicks on the button).

#Buttons

The alert invocation returns the clicked button as a result. By default, there is only one button, like Boson\Api\Alert\AlertButton::Ok.

$button = $app->alert->create(new AlertCreateInfo( 
    // ...
));

if ($button === Boson\Api\Alert\AlertButton::Ok) {
    echo 'OK button clicked!';
}

The execution result may return null. This indicates an unexpected or abnormal termination of the alert. In most cases, this should not happen.

#Cancellation

You can add a second "Cancel" button using the cancel: true configuration option.

$button = $app->alert->create(new AlertCreateInfo(
    // ...
    cancel: true,
));

if ($button === Boson\Api\Alert\AlertButton::Ok) {
    echo 'OK button clicked!';
}

if ($button === Boson\Api\Alert\AlertButton::Cancel) {
    echo 'Cancel button clicked!';
}

#Icons

By default, no icon is used when displaying an alert (or the system icon is used). To specify a custom icon, use the icon configuration field.

The icon can contain one of the following possible values:

• null – Default value (No Icon)

• Boson\Api\Alert\AlertIcon::Info – Information system icon.

• Boson\Api\Alert\AlertIcon::Warning – Warning system icon

• Boson\Api\Alert\AlertIcon::Error – Error system icon