php-flasher/docs/_includes/_usage.md

Usage

PHPFlasher provides a simple and intuitive way to add notifications to your application. You can use either the flash() helper function or inject the FlasherInterface through dependency injection.

{% assign id = '#/ PHPFlasher' %} {% assign type = 'success' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} {% include example.html %}

{{ id }}

// Using the helper function
flash()->success('{{ site.data.messages["success"] | sample }}');

// Or using dependency injection
use Flasher\Prime\FlasherInterface;

class BookController
{
    public function store(FlasherInterface $flasher)
    {
        // Save the book...
        $flasher->success('{{ message }}');
        
        return redirect()->back();
    }
}

Choose a message that is clear and tells the user what happened. For example, "Book has been created successfully!" is a good message, but you can adjust it to fit your application's context and language.

Using this package is easy. You can add notifications to your application with just one line of code.

{% assign id = '#/ usage success' %} {% assign type = 'success' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} {% include example.html %}

{{ id }}

flash()->{{ type }}('{{ message }}');

{% assign id = '#/ usage error' %} {% assign type = 'error' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} {% include example.html %}

{{ id }}

flash()->{{ type }}('{{ message }}');

{% assign id = '#/ usage warning' %} {% assign type = 'warning' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} {% include example.html %}

{{ id }}

flash()->{{ type }}('{{ message }}');

{% assign id = '#/ usage info' %} {% assign type = 'info' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} {% include example.html %}

{{ id }}

flash()->{{ type }}('{{ message }}');

---

These four methods — success(), error(), warning(), and info() — are shortcuts for the flash() method. They let you specify the type and message in one method call instead of passing them separately to flash().

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

{% assign id = '#/ usage flash' %} {% assign type = site.data.messages.types | sample %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} {% include example.html %}

{{ id }}

flash()->flash('{{ type }}', '{{ message }}');

Parameter	Description
$type	Notification type: success, error, warning, info
$message	The message you want to show to the user. This can include HTML. If you add links, make sure to add the right classes for your framework.
$title	The notification title. Can also include HTML.
$options	Custom options for JavaScript libraries (toastr, noty, notyf, etc.).

---

options

The options() method lets you set multiple options at once by passing an array of key-value pairs. The option() method lets you set a single option by specifying its name and value. The $append argument for options() decides whether the new options should be added to existing ones (true) or replace them (false).

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

{% assign id = '#/ usage options' %} {% assign type = site.data.messages.types | sample %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{"timeout": 3000, "position": "top-center"}' %} {% include example.html %}

{{ id }}

flash()
    ->options([
        'timeout' => 3000, // 3 seconds
        'position' => 'top-center',
    ])
    ->{{ type }}('{{ message }}');

---

option

To set a single option:

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

{% assign id = '#/ usage option' %} {% assign type = site.data.messages.types | sample %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{"timeout": 3000, "position": "bottom-right"}' %} {% include example.html %}

{{ id }}

flash()
    ->option('position', 'bottom-right')
    ->option('timeout', 3000)
    ->{{ type }}('{{ message }}');

---

priority

Control the order of multiple notifications, messages with higher priority appear first.

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

{% assign id = '#/ usage priority' %} {% assign successMessage = site.data.messages['success'] | sample | prepend: 'Priority 3 → ' %} {% assign errorMessage = site.data.messages['error'] | sample | prepend: 'Priority 1 → ' %} {% assign warningMessage = site.data.messages['warning'] | sample | prepend: 'Priority 4 → ' %} {% assign infoMessage = site.data.messages['info'] | sample | prepend: 'Priority 2 → ' %}

<script type="text/javascript"> messages['{{ id }}'] = [ { handler: 'flasher', type: 'warning', message: '{{ warningMessage }}', options: {}, }, { handler: 'flasher', type: 'success', message: '{{ successMessage }}', options: {}, }, { handler: 'flasher', type: 'info', message: '{{ infoMessage }}', options: {}, }, { handler: 'flasher', type: 'error', message: '{{ errorMessage }}', options: {}, }, ]; </script>

{{ id }}

flash()
    ->priority(3)
    ->success('{{ successMessage }}');

flash()
    ->priority(1)
    ->error('{{ errorMessage }}');

flash()
    ->priority(4)
    ->warning('{{ warningMessage }}');

flash()
    ->priority(2)
    ->info('{{ infoMessage }}');

param	description
$priority	The priority of the notification. Higher numbers are shown first.

---

hops

The hops() method sets how many requests the flash message should last for. By default, flash messages show for one request. Setting the number of hops makes the message stay for multiple requests.

For example, in a multi-page form, you might want to keep messages until all pages are completed.

{% assign id = '#/ usage hops' %} {% assign type = site.data.messages.types | sample %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} {% include example.html %}

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

flash()
    ->hops(2)
    ->{{ type }}('{{ message }}');

param	description
$hops	Number of requests the flash message will persist for

---

translate

The translate() method sets the locale for translating the flash message. If you provide a locale, the message will be translated to that language. If you pass null, it uses the default locale.

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

{% assign id = '#/ usage translate' %} {% assign type = 'success' %} {% assign message = 'تمت العملية بنجاح.' %} {% assign title = 'تهانينا' %} {% assign options = '{"rtl": true, "position": "top-right"}' %} {% include example.html %}

{{ id }}

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

{% assign id = '#/ usage translate with position' %} {% assign type = 'success' %} {% assign message = 'تمت العملية بنجاح.' %} {% assign title = 'تهانينا' %} {% assign options = '{"rtl": true, "position": "top-left"}' %} {% include example.html %}

{{ id }}

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

param	description
$locale	The locale to use for translation, or null for the default

Note: The translate() method only sets the locale. It doesn't translate the message by itself.

To translate the message, you need to add the translation keys in your translation files.

{% if page.framework == 'laravel' %}

For example, to translate the message into Arabic, add these keys to resources/lang/ar/messages.php:

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

{% elsif page.framework == 'symfony' %}

For example, to translate the message into Arabic, add these keys to translations/messages.ar.yaml:

Your request was processed successfully.: 'تمت العملية بنجاح.'
Congratulations!: 'تهانينا'

{% endif %}