php-flasher/docs/pages/symfony.md

permalink, title, description, framework

permalink	title	description	framework
/symfony/	Symfony	Integrate PHPFlasher in your Symfony application to enhance user experience with flash notifications. This open-source package simplifies the addition of engaging messages following user actions.	symfony

Requirements

PHPFlasher offers a seamless way to incorporate flash notifications in Symfony projects, enhancing user feedback with minimal setup.

Requirements for using PHPFlasher with Symfony:

PHP v8.2 or higher Symfony v7.0 or higher

---

Installation

PHPFlasher's modular design lets you select and install only the components your project needs.

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

---

{% include _usage.md %}

---

Configuration

As optional, if you want to modify the default configuration, you can publish the configuration file:

php bin/console flasher:install --config

The configuration file will be located at config/packages/flasher.yaml and will have the following content:

# config/packages/flasher.yaml

flasher:
    # Default notification library (e.g., 'flasher', 'toastr', 'noty', etc.)
    default: flasher

    # Path to the main JavaScript file of PHPFlasher
    main_script: '/vendor/flasher/flasher.min.js'

    # Path to the stylesheets for PHPFlasher notifications
    styles:
        - '/vendor/flasher/flasher.min.css'

    # Enable translation of PHPFlasher messages using Symfony's translator service
    translate: true

    # Automatically inject PHPFlasher assets in HTML response
    inject_assets: true

    # Map Symfony session keys to PHPFlasher notification types
    flash_bag:
        success: ['success']
        error: ['error', 'danger']
        warning: ['warning', 'alarm']
        info: ['info', 'notice', 'alert']

    # Criteria to filter displayed notifications (limit, types)
    filter:
        # Limit number of displayed notifications
        limit: 5

---

Presets

You can create a preset for a custom notification that you want to reuse in multiple places by adding a presets entry in the configuration file.

You can think of a preset as a pre-defined message that you can use in multiple locations.

For example, you can create a preset named entity_saved in the configuration file and then use

{% assign id = '#/ symfony preset' %} {% assign type = 'success' %} {% assign message = 'Entity saved successfully' %} {% assign title = 'Entity saved' %} {% assign options = '{}' %} {% include example.html %}

# config/packages/flasher.yaml

flasher:
    presets:
        entity_saved:
            type: '{{ type }}'
            message: '{{ message }}'
            title: '{{ title }}'

To use the preset, you can call the preset() method and pass the name of the preset as the first argument:

{{ id }}

class BookController
{
    public function save()
    {
        flash()->preset('entity_saved');

This is equivalent to:

class BookController
{
    public function save()
    {
        flash()->{{ type }}('{{ message }}', '{{ title }}');

Variables

Presets can also contain variables that can be substituted by using the translation system. Take the following example where you have a preset showing a personalised welcome message to the user.

# config/packages/flasher.yaml

flasher:
    presets:
        hello_user:
            type: {{ type }}
            message: welcome_back_user

In the translations file you can define welcome_back_user with the message containing the variable :username.

# translations/flasher.en.yaml

welcome_back_user: Welcome back :username

If you want to substitute the :username in the above translation with a username in the controller, you can achieve this by passing an array of values to be substituted as the second argument.

class BookController
{
    public function save()
    {
        $username = 'John Doe';

        flash()->preset('hello_user', ['username' => $username]);

---

---

RTL support

PHPFlasher makes it easy to incorporate right-to-left languages like Arabic or Hebrew. it automatically detects the text direction and handles the necessary adjustments for you.

Simply make sure the translation service is enabled and let PHPFlasher handle the rest.

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

{{ id }}

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

---

Translation

PHPFlasher allows you to translate your notification messages and presets, it comes with Arabic, English, French, German, Spanish, Portuguese, Russian, and Chinese translations out of the box. but you can easily add your own translations.

For example, to override the English translation strings for PHPFlasher, you can create a language file at the following location: translations/flasher.en.yaml.

In this file, you should only define the translation strings you want to override. Any translation strings that you don't override will still be loaded from PHPFlasher's original language files.

Here are examples of the default translation keys for Arabic, English, and French in PHPFlasher:

# translations/flasher.ar.yaml

success: 'نجاح'
error: 'خطأ'
warning: 'تحذير'
info: 'معلومة'

The resource was created: 'تم إنشاء :resource'
The resource was updated: 'تم تعديل :resource'
The resource was saved: 'تم حفظ :resource'
The resource was deleted: 'تم حذف :resource'

resource: 'الملف'

# translations/flasher.en.yaml

success: 'Success'
error: 'Error'
warning: 'Warning'
info: 'Info'

The resource was created: 'The :resource was created'
The resource was updated: 'The :resource was updated'
The resource was saved: 'The :resource was saved'
The resource was deleted: 'The :resource was deleted'

resource: 'resource'

# translations/flasher.fr.yaml

success: 'Succès'
error: 'Erreur'
warning: 'Avertissement'
info: 'Information'

The resource was created: 'La ressource :resource a été ajoutée'
The resource was updated: 'La ressource :resource a été mise à jour'
The resource was saved: 'La ressource :resource a été enregistrée'
The resource was deleted: 'La ressource :resource a été supprimée'

resource: ''

These translation files facilitate localizing notifications to match user preferences and ensure that your applications can communicate effectively across different linguistic contexts.

{% assign id = '#/ symfony arabic translations' %} {% assign successMessage = 'تم إنشاء الملف' %} {% assign errorMessage = 'حدث خطأ أثناء إرسال طلبك.' %} {% assign warningMessage = 'يجب إكمال جميع الحقول الإلزامية قبل إرسال النموذج' %} {% assign infoMessage = 'سيتم تحديث هذه الصفحة في غضون 10 دقائق.' %}

<script type="text/javascript"> messages['{{ id }}'] = [ { handler: 'flasher', type: 'success', message: '{{ successMessage }}', title: 'نجاح', options: {}, }, { handler: 'flasher', type: 'error', message: '{{ errorMessage }}', title: 'خطأ', options: {}, }, { handler: 'flasher', type: 'warning', message: '{{ warningMessage }}', title: 'تحذير', options: {}, }, { handler: 'flasher', type: 'info', message: '{{ infoMessage }}', title: 'معلومة', options: {}, }, ]; </script>

{{ id }}

// Translate the flash message using the PHPFlasher translation files
flash()->success('The resource was created');

flash()->error('{{ errorMessage }}');
flash()->warning('{{ warningMessage }}');
flash()->info('{{ infoMessage }}');

{% assign id = '#/ symfony french translations' %} {% assign successMessage = "La ressource a été ajoutée" %} {% assign errorMessage = "Une erreur s’est produite lors de l’envoi de votre demande." %} {% assign warningMessage = "Vous devez remplir tous les champs obligatoires avant de soumettre le formulaire." %} {% assign infoMessage = "Cette page sera mise à jour dans 10 minutes."%}

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

{{ id }}

// Translate the flash message using the PHPFlasher translation files
flash()->success('The resource was created');

flash()->error('{{ errorMessage }}');
flash()->warning('{{ warningMessage }}');
flash()->info('{{ infoMessage }}');