darkghosthunter / laralerts
Quickly create one or multiple Alerts from your backend
Fund package maintenance!
Ko Fi
paypal.me/darkghosthunter
Requires
- php: ^7.2
- ext-json: *
- illuminate/routing: ^6.0||^7.0
- illuminate/session: ^6.0||^7.0
- illuminate/support: ^6.0||^7.0
- illuminate/view: ^6.0||^7.0
Requires (Dev)
- orchestra/testbench: ^4.1||^5.0
README
Laralerts
Quickly set one or multiple Alerts in your backend, and render them in the frontend.
Laralerts is compatible with any frontend framework to better suit your app, not the other way around.
Requirements
- Laravel 6 or Laravel 7
Installation
You can install the package via composer:
composer require darkghosthunter/laralerts
You can quick start your frontend scaffolding installing Laravel UI, specially if you don't have anything to start with.
Good alternatives to Bootstrap are Bulma.io, Materialize, Semantic UI, Material UI, UI kit and INK.
And that's it. Everything works out of the box.
Usage
Creating an Alert
To set an Alert in your frontend, you can use the alert()
helper, or the Alert
Facade. A good place to use them is before sending a View or Redirect response to the browser, like in your HTTP Controllers.
<?php namespace App\Http\Controllers; use Illuminate\Http\Request; use App\Article; class ArticleController extends Controller { /** * Update the Article * * @param \Illuminate\Http\Request $request * @param \App\Article $article * @return \Illuminate\Http\Response */ public function update(Request $request, Article $article) { $request->validate([ 'title' => 'required|string|max:255', 'body' => 'required|string' ]); $article->fill($request)->save(); alert('Your article has been updated!', 'success', true); return redirect()->action('ArticleController@edit', $article); } // ... }
The alert()
helper accepts the text message, the type of the alert, and if it should be dismissible, making your alerts into expressive one-liners.
To render them in the frontend, use the @alerts
Blade directive which will take care of the magic, anywhere you want.
<div class="header"> <h1>Welcome to my site</h1> @alerts </div>
And if there is no Alerts to show, don't worry, no HTML will be rendered.
Conditional Alerts
You can also push an Alert if a condition evaluates to true or false. Just use the alert_if
and alert_unless
, respectively.
<?php alert_if(true, 'You should see this alert'); alert_unless(false, 'And this too since the condition is false!'); alert_if(false)->message('No problem with chaining methods!');
When alert_if
and alert_unless
evaluate to false, you will still receive an Alert instance, but this won't be persisted into the session or response, avoiding unwanted errors in your backend.
Message
Add the text inside the Alert using the message()
method. Yeah, that's it.
<?php use DarkGhostHunter\Laralerts\Facades\Alert; alert()->message('Your message was sent!') ->success(); Alert::message('We will email you a copy!') ->info();
<div class="alert alert-success" role="alert"> Your message was sent! </div> <div class="alert alert-info" role="alert"> We will email you a copy! </div>
By default, the
message()
method escapes the text. If you want to send a raw message, you should useraw()
.
Raw message
Since the message()
method escapes the text for safety, you can use the raw()
method to do output the raw string you set. This allows you to use HTML for personalized messages, like adding some style or emojis like 😍.
<?php alert()->message('This is <strong>FUBAR</strong>.') ->warning(); alert()->raw('But this is <strong>important</strong>.') ->warning();
<div class="alert alert-warning" role="alert"> This is <strong>FUBAR</strong>. </div> <div class="alert alert-warning" role="alert"> But this is <strong>important</strong>. </div>
Warning: Don't use raw()
to show user-generated content. You have been warned.
Using Localization
To gracefully localize messages on the fly, use the lang()
method, which is a mirror to the @lang
Blade directive.
<?php alert()->lang('email.sent', ['email' => $email], 'es')->success();
<div class="alert alert-success" role="alert">> ¡Tu email ha sido cambiado a "margarita@madrid.cl" con éxito! </div>
Alert Type
You're probably using Bootstrap 4, so in that case you can use multiple fluent methods that mirror the Alert class from Bootstrap 4, right out of the box.
Method | Class |
---|---|
primary() |
alert-primary |
secondary() |
alert-secondary |
success() |
alert-success |
danger() |
alert-danger |
warning() |
alert-warning |
info() |
alert-info |
light() |
alert-light |
dark() |
alert-dark |
<?php alert()->message('Your message was sent!') ->primary();
<div class="alert alert-primary" role="alert"> Your message was sent! </div>
If you're not using Bootstrap 4, you can change this list with your own.
By default, Alerts don't have any default type, so when they're rendered they will be transparent (without style or color). Don't worry, you can easily set a default.
Adding your own fluid classes
If you need to modify the Alert types, you can use the static method Alert::setTypes()
with an array of accepted types of Alerts. You can do this on the boot method or register method of your AppServiceProvider
.
The alert classes must must be keyed by the name of the fluent method, and the underlying class to attach to the alert.
<?php /** * Bootstrap any application services. * * @return void */ public function boot() { // ... \DarkGhostHunter\Laralerts\Alert::setTypes([ 'gradient' => 'gradient', 'popping' => 'bg-pop-color', ]); }
<?php alert()->message('Popping colors!')->popping();
<div class="alert bg-pop-color" role="alert"> Popping colors! </div>
The array you supply is not added, but replaced entirely. If you want to just add some types, use the addTypes()
static method.
<?php \DarkGhostHunter\Laralerts\Alert::addTypes([ 'these' => 'class-these', 'are' => 'class-are', 'added' => 'class-added', ]);
Dismiss
To make an Alert dismissible, use the dismiss()
method. This will change the Blade view used to render the Alert in HTML to make it dismissible.
By contrast, if you have set dismissible Alerts by default, using the fixed()
method will make a particular Alert non-dismissible by using the default Blade view.
<?php alert()->message('Your message was sent!') ->success() ->dismiss();
<div class="alert alert-info alert-dismissible fade show" role="alert"> Your message was sent! <button type="button" class="close" data-dismiss="alert" aria-label="Close"> <span aria-hidden="true">×</span> </button> </div>
By using two different Blade views for dismissable and non-dismissable alerts, there is more flexibility on how to render them.
Additional Classes
You can issue additional classes to your Alert by seamlessly using the classes()
method, which accepts a list of classes to be added into the HTML code.
<?php alert()->message('Your message was sent!') ->success() ->classes('message-sent', 'global-alert');
<div class="alert alert-success message-sent global-alert" role="alert"> Your message was sent! </div>
Persisting the Alerts
By default, in every request lifecycle (except on Redirects) you will start with an empty Alert Bag.
You can rescue the old Alerts using the reflash()
method. This will take the old alerts and put them into the Alert Bag, merging with any other alert you have set previously, but with the new ones taking precedence.
Once you create a new alert, it will be appended to the existing bag of alerts from the request or redirect made before.
<?php alert() ->reflash() ->message('Be sure to check the other alerts.') ->warning();
<div class="alert alert-success message-sent global-alert" role="alert"> Your message was sent! </div> <div class="alert alert-warning" role="alert"> Be sure to check the other alerts. </div>
Adding Alerts to a JSON Response
This library has a convenient way to add Alerts into your JSON Responses. Just simply add the alert.json
middleware into your routes or api
routes, as the documentation says.
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. Here is an example:
<?php use Illuminate\Support\Facades\Route; use DarkGhostHunter\Laralerts\Http\Middleware\AppendAlertsToJsonResponse; Route::group('api', function () { Route::post('create')->uses('UserController@create'); Route::post('update')->uses('UserController@update'); })->middleware('alert.json:_status.alerts');
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:
{ "resource": "users", "url": "/v1/users", "_status": { "timestamp": "2019-06-05T03:47:24Z", "action" : "created", "id": 648, "alerts": [ { "message": "The user has been created!", "type" : "success", "dismiss": true, "classes": null } ] } }
To keep good performance, the Alerts will be injected into the Session only if it has started. For example, api
routes are stateless and do not have exceptions, so there is no need to explicitly disable sessions in these places.
Configuration
Laralerts works 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.
php artisan vendor:publish --provider="DarkGhostHunter\Laralerts\LaralertsServiceProvider"
Let's examine the configuration array, which is quite simple:
<?php return [ 'directive' => 'alerts', 'key' => '_alerts', 'type' => null, 'dismiss' => false, ];
Directive
This library registers the @alerts
blade component, that has the container where all the Alerts will be rendered.
If you're using a directive with the same name, you may want to change it so it doesn't collide. I totally recommend you to use @laralerts
as a safe bet.
<?php return [ 'directive' => 'laralerts', ];
When changing this parameter, you may want to use
php artisan view:clear
to rebuild your compiled views with the new directive.
Session Key
The Alert Bag is registered into the Session by a given key, which is _alerts
by default. If you're using this key name for other things in your session, you should change the key name.
<?php return [ 'key' => '_alerts', ];
For ease of mind, the Alerts serialize and unserialize as
array
, so you don't have to worry about storage concerns.
Default Type
The default type of the Alerts in the Application. You can use any of the included type names, like success
or info
, or your own as long is registered properly. You can override the default type anytime when you create an Alert manually.
<?php return [ 'type' => 'primary', ];
Modifying the HTML
You may be using another frontend framework different from Bootstrap 4, 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/laralerts
:
alert.blade.php
: The HTML for a single Alert.alert-dismiss.blade.php
: Same as above, but for a dismissible Alert.alerts.blade.php
: The HTML that contains all the Alerts
The Alert view receives:
$message
: The message to show inside the Alert.$type
: The type name.$typeClass
: The type CSS class.$classes
: The additional classes to add to the HTML block.
You can change the HTML to whatever you want, like adapting the Alert to be used with Bulma.io Notifications.
/resources/views/vendor/laralerts/alert-dismiss.blde.php
<div class="notification is-{{ $typeClass }} {{ $classes }}"> <button class="delete"></button> {!! $message !!} </div>
Adding an Alert from JSON
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 addFromJson()
method.
<?php $json = '"{"message":"Email delivered"}"'; alert()->addFromJson($json)->success()->dismiss();
This will work as long the JSON has the message
key with the text to include inside the Alert. Additionally, you can add the type
, dismiss
and classes
keys to add an Alert, with the possibility of override them afterwards.
If you need to add many alerts from a JSON string, use the addManyFromJson()
method and (optionally) issue the key where they are using dot notation.
When doing this, the alerts will be created using the message
, type
, dismiss
and classes
respectively.
<?php $json = '"{ "content": { "alerts": { "message": "I like trains!" }, { "message": "Me too!" }, } }"'; alert()->addManyFromJson($json, 'content.alerts');
Macros
This package is totally compatible with Macros. You can add your own macros to the AlertManager
class, which has access to the Session Store and the Alert Bag.
You can add your own macros the usual way, preferably directly through the class itself.
<?php use DarkGhostHunter\Laralerts\AlertManager; AlertManager::macro('countAlerts', function () { return $this->alertBag->count(); });
Security
If you discover any security related issues, please email darkghosthunter@gmail.com instead of using the issue tracker.
License
The MIT License (MIT). Please see License File for more information.