Introduction

A package that allows you to manage different types of alerts throughout your application.

The package requires PHP 8.3+ and follows the FIG standard PSR-4 to ensure a high level of interoperability between shared PHP code and is fully unit-tested.

Have a read through the Installation Guide and on how to Integrate it with Laravel 12.

Installation

The best and easiest way to install the Alerts package is with Composer.

Preparation

Open your composer.json file and add the following to the require array:

"cartalyst/alerts": "^9.0"

Note: Make sure that after the required changes your composer.json file is valid by running composer validate.

Install the dependencies

Run Composer to install or update the new requirement.

php composer install

or

php composer update

Now you are able to require the vendor/autoload.php file to autoload the package.

Integration

Cartalyst packages are framework agnostic and as such can be integrated easily natively or with your favorite framework.

Laravel

The Alerts package has optional support for Laravel 12 and it comes bundled with a Service Provider and a Facade for easy integration.

After installing the package, open your Laravel config file located at config/app.php and add the following lines.

In the $providers array add the following service provider for this package.

'Cartalyst\Alerts\Laravel\AlertsServiceProvider',

In the $aliases array add the following facades for this package.

'Alert' => 'Cartalyst\Alerts\Laravel\Facades\Alert',

Configuration

After installing, you can publish the package configuration file into your application by running the following command on your terminal:

php artisan vendor:publish

This will publish the config file to config/cartalyst.alerts.php where you can modify the package configuration.

Native

Alerts ships with a native facade that makes using it as simple as follows:

// Import the necessary classes
use Cartalyst\Alerts\Native\Facades\Alert;

// Include the composer autoload file
require 'vendor/autoload.php';

// Start using alerts
Alert::error(['foo', 'bar']);

Usage

In this section we'll show how you can make use of the alerts package.

Alert Types

Types can be decided by the user, the type is defined by the method name you call on the facade.

error type

Alert::error('error message');

warning type

Alert::warning('warning message');

foo type

Alert::foo('foo message');

Notifiers

Notifiers are responsible for storing the alerts across your application.

Alerts ships with two notifiers.

Default

The default notifier is used without having to call an additional method that returns the desired notifier.

• Laravel

The default notifier is set to flash.

• Native

The default notifier can be set using Alert::setDefaultNotifier($notifier)

Retrieve a notifier

Sending alerts using a different notifier requires retrieving the notifier first.

Usage

Assuming we have a view notifier we can do the following.

// Call the notifier `key` on the facade to retrieve the notifier.
Alert::view()->error('foo');

// Call the `notifier` method and pass in the notifier key.
Alert::notifier('view')->error('foo');

Flash Notifier (notifies on redirections)

The flash notifier requires illuminate/session and illuminate/filesystem in order to add flashing notifications capability.

The flash notifier will persist the alert for one request.

Usage

Alert::error('Error message');

Note The flash notifier is the default notifier, therefore, all alerts that are directly called on the facade will be handled by the flash notifier.

Notifier (notifies on the same request)

The notifier will persist the alerts during the current request only.

Usage

Alert::view()->error('Error message');

Alert Areas

In addition to a message, the various notifiers accept an optional second argument, which is an area name. Areas are useful for displaying messages in specific places within the rendered response output.

When an area is not specfied, the default area is used, which may not be ideal in all scenarios.

For example, your layout might normally output alerts at the top of the page, but perhaps you would like to display alerts that are specific to a particular area of the layout in context, and not at the top of the page.

You can achieve this by specifying an area:

Alert::error('Error message', 'right-sidebar');

Now, this error message will be returned only when you retrieve alerts that include the right-sidebar area, as explained below.

Retrieving alerts

The methods below will apply the desired filters to the list of alerts, afterwards, get can be called in order to retrieve the alerts.

The methods below can be chained to filter down alerts more than once.

Alert::whereType('foo')->whereArea('bar')->get();

Alert::whereType($type|$types)

This method will filter down alerts based on the given type(s).

Usage

// Returns all alerts of type `foo`
Alert::whereType('foo')->get();

// Returns all alerts of type `foo` and `bar`
Alert::whereType([ 'foo', 'bar' ])->get();

Alert::whereArea($area|$areas)

This method will filter down alerts based on the given area(s).

Usage

// Returns all alerts of area `foo`
Alert::whereArea('foo')->get();

// Returns all alerts of area `foo` and `bar`
Alert::whereArea([ 'foo', 'bar' ])->get();

Alert::whereNotType($type|$types)

This method will filter down alerts excluding the given type(s).

Usage

// Returns all alerts excluding type `foo`
Alert::whereNotType('foo')->get();

// Returns all alerts excluding type `foo` and `bar`
Alert::whereNotType([ 'foo', 'bar' ])->get();

Alert::whereNotArea($type|$types)

This method will filter down alerts excluding the given area(s).

Usage

// Returns all alerts excluding area `foo`
Alert::whereNotArea('foo')->get();

// Returns all alerts excluding area `foo` and `bar`
Alert::whereNotArea([ 'foo', 'bar' ])->get();

Alert::get()

You can retrieve all or the filtered list of alerts using the get method. Calling this method will return a list of alerts and reset any applied filters afterwards.

// All alerts
$alerts = Alert::get();

Generating the alerts view

@foreach (Alert::get() as $alert)

<div class="alert">

    <p>{{ $alert->message }}</p>

</div>

@endforeach

Note The example above uses Laravel's blade syntax for readability.

Class

Alert classes can be useful when it comes to adding classes to HTML elements, let's take an error alert as an example.

The class property on every alert defaults to the alert type, in our case error.

Alert

Alert::error('Error');

View

The following view will output the class alert-error on the div tag.

@foreach (Alert::get() as $alert)

<div class="alert alert-{{ $alert->class }}">

    <p>{{ $alert->message }}</p>

</div>

@endforeach

Changing that class to alert-danger can be achieved by:

• Native

Calling the setConfig method on the AlertsBootstrapper and passing in the $config array.

$config = [

    'error' => 'danger',

];

Cartalyst\Alerts\Native\AlertsBootstrapper::setConfig($config);

• Laravel

Updating the config file and providing a key/value array that defines the classes to rewrite.

return [

    'error' => 'danger',

];