If you find PHPFlasher useful, please consider giving it a ⭐ star on GitHub 😊. If you spot any typos or have suggestions, feel free to contribute to the documentation 📝. Your feedback helps keep the project up-to-date and well-maintained. Thank you

PHPFlasher is modular and consists of multiple libraries, allowing users to install and use only the specific components they need for their project.

Installation

PHPFlasher can be installed using composer :

Laravel:

composer require php-flasher/flasher-laravel

After installation, you need to run another command to set up the necessary assets for PHPFlasher:

php artisan flasher:install

Symfony:

composer require php-flasher/flasher-symfony

After installation, you need to run another command to set up the necessary assets for PHPFlasher:

php bin/console flasher:install

Usage

To display a notification message, you can either use the flash() helper method or obtain an instance of flasher from the service container. Then, before returning a view or redirecting, call the success() method and pass in the desired message to be displayed.

#/ PHPFlasher

use Flasher\Prime\FlasherInterface;

class BookController
{
    public function saveBook()
    {
        // ...

        flash('Your contact has been added.');
        
        flash()->success('Operation completed successfully.');
            
        app('flasher')->success('Your account has been re-activated.');

        // ... redirect or render the view
    }
    
    /**
     * if you prefer to use dependency injection 
     */
    public function register(FlasherInterface $flasher)
    {
        // ...
        
        $flasher->success('Operation completed successfully.');
        
        // ... redirect or render the view
    }
}

It’s important to choose a message that is clear and concise, and that accurately reflects the outcome of the operation.
In this case, "Book has been created successfully!" is already a good message, but you may want to tailor it to fit the specific context and language of your application.

Using this package is actually pretty easy. Adding notifications to your application actually require only one line of code.

#/ usage success

flash()->success('Your password has been reset.');

#/ usage error

flash()->error('There was an issue confirming your reservation.');

#/ usage warning

flash()->warning('Your information may not have been saved.');

#/ usage info

flash()->info('Your review has been submitted and is being reviewed.');

These four methods (success, error, warning, info) are simply convenience shortcuts for the flash method, allowing you to specify the type and message in a single method call rather than having to pass both as separate arguments to the flash method.

flash()->flash(string $type, string $message, string $title = null, array $options = [])

#/ usage flash

flash()->flash('error', 'There was an issue restoring your account.');

options

You can specify custom options for the flash messages when using a JavaScript library like toastr, noty, or notyf.

The options() method allows you to set multiple options at once by passing an array of key-value pairs, while the option() method allows you to set a single option by specifying its name and value as separate arguments.

The optional $merge argument for the options() method can be used to specify whether the new options should be merged with any existing options, or whether they should overwrite them.

flash()->options(array $options, bool $merge = true);

Refer to the documentation for your chosen JavaScript library to see which options are available and how they should be formatted.

#/ usage options

flash()
    ->options([
        'timeout' => 3000, // 3 seconds
        'position' => 'top-center',
    ])
    ->warning('Your password may be at risk.');

option

Set a single option by specifying its name and value as separate arguments.

flash()->option(string $option, mixed $value);

#/ usage option

flash()
    ->option('position', 'top-center')
    ->option('timeout', 3000)
    ->error('There was an issue un-linking your account.');

priority

Sets the priority of a flash message, the highest priority will be displayed first.

flash()->priority(int $priority);

#/ usage priority

flash()
    ->priority(3)
    ->success('Priority 3 → Your account has been re-verified.');

flash()
    ->priority(1)
    ->error('Priority 1 → We’re sorry, but an error occurred.');

flash()
    ->priority(4)
    ->warning('Priority 4 → Your contact may not have been added.');

flash()
    ->priority(2)
    ->info('Priority 2 → Your message has been received and is being processed.');

hops

This method sets the number of requests that the flash message should persist for. By default, flash messages are only displayed for a single request and are then discarded. By setting the number of hops, the flash message will be persisted for multiple requests.

As an example, with a multi-page form, you may want to store messages until all pages have been filled.

flash()->hops(int $hops);

flash()
    ->hops(2)
    ->info('Your application has been received and is being reviewed.');

translate

This method sets the locale to be used for the translation of the flash message. If a non-null value is provided, the flash message will be translated into the specified language. If null is provided, the default locale will be used.

flash()->translate(string $locale = null);

#/ usage translate

flash()
    ->translate('ar')
    ->success('Your request was processed successfully.', 'Congratulations!');

#/ usage translate with position

flash()
    ->translate('ar')
    ->option('position', 'top-left')
    ->success('Your request was processed successfully.', 'Congratulations!');

It is important to note that the translate() method only sets the locale to be used for the translation of the flash message. It does not actually perform the translation itself.

In order to translate the flash message, you will need to provide the appropriate translation keys in your translation files.

In the above example, to translate the flash message into Arabic, If you are using Laravel you will need to add the following keys to the resources/lang/ar/messages.php file:

return [
    'Your request was processed successfully.' => 'تمت العملية بنجاح.',
    'Congratulations!' => 'تهانينا',
];