php-flasher/docs/pages/symfony.md

permalink, title, description, framework

permalink	title	description	framework
/symfony/	Symfony	Integrate PHPFlasher into your Symfony application to enhance user experience with flash notifications. This guide shows you how to add engaging messages after user actions using PHPFlasher in Symfony.	symfony

Requirements

PHPFlasher helps you easily add flash notifications to your Symfony projects, improving user feedback with minimal setup.

To use PHPFlasher with Symfony, you need:

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

---

Installation

PHPFlasher is modular. You can install only the parts you need.

Run this command to install it:

composer require php-flasher/flasher-symfony

After installing, run this command to set up the required assets:

php bin/console flasher:install

---

{% include _usage.md %}

---

Configuration

If you want to change the default settings, you can publish the configuration file:

php bin/console flasher:install --config

This will create a file at config/packages/flasher.yaml with the following content:

# config/packages/flasher.yaml

flasher:
    # Default notification library (e.g., 'flasher', 'toastr', 'noty', 'notyf', 'sweetalert')
    default: flasher
  
    # Path to the main PHPFlasher JavaScript file
    main_script: '/vendor/flasher/flasher.min.js'
  
    # List of CSS files to style your notifications
    styles:
        - '/vendor/flasher/flasher.min.css'
  
    # Set global options for all notifications (optional)
    # options:
    #     # Time in milliseconds before the notification disappears
    #     timeout: 5000
    #     # Where the notification appears on the screen
    #     position: 'top-right'
  
    # Automatically inject JavaScript and CSS assets into your HTML pages
    inject_assets: true
  
    # Enable message translation using Symfony's translation service
    translate: true
  
    # URL patterns to exclude from asset injection and flash_bag conversion
    excluded_paths:
        - '/^\/_profiler/'
        - '/^\/_fragment/'
  
    # Map Symfony flash message keys to notification types
    flash_bag:
      success: ['success']
      error: ['error', 'danger']
      warning: ['warning', 'alarm']
      info: ['info', 'notice', 'alert']
  
    # Set criteria to filter which notifications are displayed (optional)
    # filter:
    #     # Maximum number of notifications to show at once
    #     limit: 5
  
    # Define notification presets to simplify notification creation (optional)
    # presets:
    #     # Example preset:
    #     entity_saved:
    #         type: 'success'
    #         title: 'Entity saved'
    #         message: 'Entity saved successfully'

---

Presets

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

A preset is like a pre-defined message you can use in many places.

For example, create a preset named entity_saved:

{% 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, call the preset() method and pass the name of the preset:

{{ id }}

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

This is the same as:

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

Variables

Presets can also have variables that you can replace using the translation system. For example, you can have a preset that shows a personalized welcome message.

# config/packages/flasher.yaml

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

In your translation file, define welcome_back_user with a message containing the variable :username.

# translations/flasher.en.yaml

welcome_back_user: Welcome back :username

To replace :username with the actual username in your controller, pass an array with the values to substitute 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 use right-to-left languages like Arabic or Hebrew. It automatically detects the text direction and adjusts accordingly.

Just make sure the translation service is enabled, and PHPFlasher will 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 lets you translate your notification messages and presets. It comes with translations for Arabic, English, French, German, Spanish, Portuguese, Russian, and Chinese. You can also add your own translations.

To override the English translations for PHPFlasher, create a file at translations/flasher.en.yaml.

In this file, define only the translation strings you want to change. Any strings you don't override will use PHPFlasher's default translations.

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

# 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 help you localize notifications to match user preferences, so your application can communicate effectively in different languages.

{% 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 }}');