Download the PHP package laragear/alerts without Composer

Alerts

Set multiple alerts from your backend, render them in the frontend with any HTML.

Become a sponsor

Your support allows me to keep this package free, up-to-date and maintainable. Alternatively, you can spread the word!

Requirements

• Laravel 10 or later

Installation

You can install the package via composer:

If you don't have anything to start with in your frontend, you can use Laravel Jetstream, or go the classic way and use Bootstrap, Bulma.io, UI kit, TailwindCSS and INK, among many others.

Usage

This package allows you to set a list of Alerts in your application and render them in the frontend in just a few minutes.

The default renderer uses Bootstrap 5 styles to transform each alert into alerts. If you're using Tailwind CSS, you can use the included Tailwind renderer by create your own renderer for your particular framework.

Quickstart

To set an Alert in your frontend, you can use the alert() helper for shorter syntax, or the Alert Facade, whatever is your preference. A good place to use them is before sending a response to the browser, like in your HTTP Controllers.

If you're sending a redirect, the alerts will be magically flashed so the next request can show them.

The alert() helper accepts the text message and the types of the alert. In the above example, we created a simple "success" alert.

To render the alerts in the frontend, use the <x-alerts-container /> Blade component which will take care of the magic, anywhere you want to put it.

If there is at least one Alert to be rendered, the above will be transformed into proper HTML:

Alternatively, you can use the type($message) syntax right from the Alert facade or the alert() helper.

Message

You can use the type($message) syntax, or go for the classic route and add the text inside the Alert using the message() method.

[!IMPORTANT]

By default, the message() method escapes the text. If you want to send a raw message, you should use raw().

Raw message

Since the message() method escapes the text for safety, you can use the raw() method to output a string verbatim. This allows you to use HTML for personalized messages, like adding some style, links, or even scripts.

Warning: Don't use raw() to show user-generated content. YOU HAVE BEEN WARNED.

Alert Type

You can set an alert "type" by its name by just using it as a method name. The types() method is preferred if you need to set more than one.

The types are like keywords that the underlying Renderer will use to transform the alert into proper HTML code.

[!NOTE]

The default Bootstrap Renderer will set each unrecognized type as an additional CSS class.

Localization

To gracefully localize messages on the fly, use the trans() method, which is a mirror of the __() helper.

You can also use transChoice() with the same parameters of trans_choice().

Dismiss

Most of the frontend frameworks have alerts or notifications that can be dismissible, but require adding more than a single class to allow for interactivity.

You can set an alert to be dismissible using dismiss(), signaling the Renderer to make the modification necessary to be dismissible.

If you want to change your mind, you can use dismiss(false):

How the dismissible alert is transformed into code will depend on the renderer itself. The default Bootstrap renderer adds the proper CSS classes and a dismiss button automatically.

Conditional Alerts

You can also push an Alert if a condition evaluates to true or false by using when() and unless(), respectively. Further method calls will be sent to the void.

Persistent Alerts

Alerts only last for the actual response being sent. On redirects, these are flashed into the session so these are available on the next request (the redirection target).

To make any alert persistent you can use the persistAs() method with a key to identify the alert.

[!NOTE]

Setting a persistent alert replaces any previous set with the same key.

Once you're done, you can delete the persistent Alert using abandon() method directly from the helper using the key of the persisted Alert. For example, we can abandon the previous alert if the disk is no longer full.

Links

Setting up links for an alert doesn't have to be cumbersome. You can easily replace a string between curly braces in your message for a link using to(), route(), action(), and away().

Links can also work over translated messages, as long these have a word in curly braces.

If you have more than one link, you can chain multiple links to a message.

[!IMPORTANT]

Links strings are case-sensitive, and replaces all occurrences of the same string. You can create your own Renderer if this is not desired.

Tags

Sometimes you may have more than one place in your site to place Alerts, like one for global alerts and other for small user alerts. Tags can work to filter which Alerts you want to render.

You can set the tags of the Alert using tag().

Using the Alerts directive, you can filter the Alerts to render by the tag names using the :tags slot.

Configuration

Alerts will work out-of-the-box with some common defaults, but if you need a better approach for your particular application, you can configure some parameters. First, publish the configuration file.

Let's examine the configuration array, which is quite simple:

Renderer

This picks the Renderer to use when transforming Alerts metadata into HTML.

This package ships with Bootstrap 5 and Tailwind CSS renderers, but you can INK, or even your own custom frontend framework.

Session Key

When alerts are flashed or persisted, these are stored in the Session by a given key, which is _alerts by default. If you're using this key name for other things, you may want to change it.

This key is also used when sending JSON alerts.

Default tag list

This holds the default tag list to inject to all Alerts when created. You can leave this alone if you're not using tags.

Renderers

A Renderer takes a collection of Alerts and transforms each into an HTML string. This makes swapping a frontend framework easier, and allows greater flexibility when rendering HTML.

Creating a custom renderer

You can create your own using the Renderer contract, and registering it into the RendererManager in your AppServiceProvider. You can use the BootstrapRenderer as a starting point to create your own.

Then, in your config file, set the renderer to the one you have registered.

When you issue an alert, the alert will be rendered using your own custom renderer.

Alerts Container HTML

When the Renderer receives Alerts to render, it will call a "container" view which will render all the Alerts by using a loop.

For example, the included BootstrapRenderer calls the laralerts::bootstrap.container.

You may be using another frontend framework different from Bootstrap 5, or you may want to change the HTML to better suit your application design. In any case, you can override the View files in views/vendor/alerts:

• container.blade.php: The HTML that contains all the Alerts.
• alert.blade.php: The HTML for a single Alert.

The variables the alert.blade.php view receives are set from by Renderer. For the case of the included Bootstrap renderer, these are:

• $alert->message: The message to show inside the Alert.
• $alert->classes: The CSS classes to incorporate into the Alert.
• $alert->dismissible: A boolean that sets the alert as dismissible or not.

As you're suspecting, you can publish the views and override them to suit your needs.

JSON Alerts

Receiving JSON Alerts

Sometimes your application may receive a JSON Alert from an external service using this package. You can quickly add this JSON as an Alert to your application using the fromJson() method.

This will work as long the JSON has the message key with the text to include inside the Alert. Additionally, you can add the types and dismiss keys to add an Alert, with the possibility of override them afterward.

[!WARNING]

The message from JSON is set raw.

Sending JSON Alerts

This library has a convenient way to add Alerts into your JSON Responses. This can be very useful to add your alerts to each response being sent to the browser, like combining this package with Laravel Jetstream.

Just simply add the alerts.json middleware into your api routes or, if you're using Laravel Jetstream or similar, as a global middleware.

When you return a JsonResponse to the browser, the middleware will append the alert as JSON using the same session key defined in the configuration, which is _alerts by default. It also accepts the key parameter to use as an alternative, compatible with dot notation.

When you receive a JSON Response, you will see the alerts appended to whichever key you issued. Using the above example, we should see the alerts key under the _status key:

[!WARNING]

If your key is already present in the JSON response, the key will be overwritten.

Testing

To test if alerts were generated, you can use Alert::fake(), which works like any other faked services. It returns a fake Alert Bag that holds a copy of all alerts generated, which exposes some convenient assertion methods.

The following assertions are available:

Asserting specific alerts

The fake Alert bag allows building conditions for the existence (or nonexistence) of alerts with specific properties, by using assertAlert().

Once you build your conditions, you can use exists() to check if any alert matches, or missing() to check if no alert should match.

Alternatively, you can use count() if you expect a specific number of alerts to match the given conditions, or unique() for matching only one alert.

The following conditions are available:

Laravel Octane compatibility

• The Renderer-related classes are registered as singletons.
• It's safe to extend the RendererManager at boot time.
• The Bag is registered as singleton. You shouldn't resolve it at boot time.
• The Bag contains a stale version of the app config. You shouldn't change the config.
• There are no static properties written during a request.

There should be no problems using this package with Laravel Octane if you use this package as intended.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

This specific package version is licensed under the terms of the MIT License, at time of publishing.

Laravel is a Trademark of Taylor Otwell. Copyright © 2011-2024 Laravel LLC.