php-flasher/flasher-symfony

Integrate flash notifications into Symfony projects effortlessly with PHPFlasher. Improve user experience and application feedback loops easily.

v2.1.1 2024-10-20 14:11 UTC

Requires

• php: >=8.2
• php-flasher/flasher: ^2.1.1
• symfony/config: ^7.0
• symfony/console: ^7.0
• symfony/dependency-injection: ^7.0
• symfony/http-kernel: ^7.0

Suggests

• symfony/translation: To translate flash messages, title and presets
• symfony/ux-twig-component: To utilize and interact with flash messages components in Twig templates

MIT

• Younes ENNAJI

• symfony
• php
• open-source
• flash-notifications
• user-feedback
• phpflasher

README

Table of Contents

• About PHPFlasher Symfony Adapter
• Features
• Supported Versions
• Installation
  • Core Package
  • Adapters
• Configuration
  • Configuration File
  • Configuration Options
• Quick Start
• Usage Examples
• Adapters Overview
• Official Documentation
• Contributors and Sponsors
• Contact
• License

About PHPFlasher Symfony Adapter

PHPFlasher Symfony Adapter is an open-source package that seamlessly integrates PHPFlasher’s robust flash messaging capabilities into your Symfony applications. It streamlines the process of adding flash messages, offering an intuitive API to enhance user experience with minimal configuration.

With PHPFlasher Symfony Adapter, you can effortlessly display success, error, warning, and informational messages to your users, ensuring clear communication of application states and actions.

Features

• Seamless Symfony Integration: Designed specifically for Symfony, ensuring compatibility and ease of use.
• Multiple Notification Libraries: Supports various frontend libraries like Toastr, Noty, SweetAlert, and Notyf.
• Flexible Configuration: Customize the appearance and behavior of flash messages to fit your application's needs.
• Intuitive API: Simple methods to create and manage flash messages without boilerplate code.
• Extensible: Easily add or create new adapters for different frontend libraries.

Supported Versions

Note: Ensure your project meets the PHP and Symfony version requirements for the PHPFlasher Symfony Adapter version you intend to use. For older PHP or Symfony versions, refer to PHPFlasher v1.x.

Installation

Core Package

Install the PHPFlasher Symfony Adapter via Composer:

composer require php-flasher/flasher-symfony

After installation, set up the necessary assets:

php bin/console flasher:install

Note: PHPFlasher automatically injects the necessary JavaScript and CSS assets into your Blade templates. No additional steps are required for asset injection.

Adapters

PHPFlasher provides various adapters for different notification libraries. Below is an overview of available adapters for Symfony:

• flasher-toastr-symfony - Symfony Adapter
• flasher-noty-symfony - Symfony Adapter
• flasher-notyf-symfony - Symfony Adapter
• flasher-sweetalert-symfony - Symfony Adapter

For detailed installation and usage instructions for each adapter, refer to their respective README.md.

Configuration

After installing the PHPFlasher Symfony Adapter, you can configure it by publishing the configuration file or by modifying it directly.

Configuration File

If you need to customize the default settings, publish the configuration file using the following command:

php bin/console flasher:install --config

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

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'

Configuration Options

Quick Start

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

Using the flash() Helper

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\RedirectResponse;

class BookController extends AbstractController
{
    public function saveBook(): RedirectResponse
    {
        // Your logic here

        flash('Your changes have been saved!');

        return $this->redirectToRoute('book_list');
    }
}

Using the flasher Service

<?php

namespace App\Controller;

use Flasher\Prime\FlasherInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\RedirectResponse;

class AnotherController extends AbstractController
{
    private FlasherInterface $flasher;

    public function __construct(FlasherInterface $flasher)
    {
        $this->flasher = $flasher;
    }

    public function register(): RedirectResponse
    {
        // Your logic here
        
        $this->flasher->success('Your changes have been saved!');

        // ... redirect or render the view
        return $this->redirectToRoute('home');
    }

    public function update(): RedirectResponse
    {
        // Your logic here

        $this->flasher->error('An error occurred while updating.');

        return $this->redirectToRoute('update_page');
    }
}

Usage Examples

Success Message

flash()->success('Operation completed successfully!');

Error Message

flash()->error('An error occurred.');

Info Message

flash()->info('This is an informational message.');

Warning Message

flash()->warning('This is a warning message.');

Passing Options

flash()->success('Custom message with options.', ['timeout' => 3000, 'position' => 'bottom-left']);

Using presets

Define a preset in your config/packages/flasher.yaml:

flasher:
    # ... other configurations

    presets:
        entity_saved:
            type: 'success'
            title: 'Entity Saved'
            message: 'The entity has been saved successfully.'
        entity_deleted:
            type: 'warning'
            title: 'Entity Deleted'
            message: 'The entity has been deleted.'

Use the preset in your controller:

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\RedirectResponse;

class BookController extends AbstractController
{
    public function save(): RedirectResponse
    {
        // Your saving logic

        flash()->preset('entity_saved');

        return $this->redirectToRoute('books.index');
    }

    public function delete(): RedirectResponse
    {
        // Your deletion logic

        flash()->preset('entity_deleted');

        return $this->redirectToRoute('books.index');
    }
}

Adapters Overview

PHPFlasher supports various adapters to integrate seamlessly with different frontend libraries. Below is an overview of available adapters for Symfony:

Note: Each adapter has its own repository. For detailed installation and usage instructions, please refer to the Official Documentation.

Official Documentation

Comprehensive documentation for PHPFlasher is available at https://php-flasher.io. Here you will find detailed guides, API references, and advanced usage examples to help you get the most out of PHPFlasher.

Contributors and sponsors

Join our team of contributors and make a lasting impact on our project!

We are always looking for passionate individuals who want to contribute their skills and ideas. Whether you're a developer, designer, or simply have a great idea, we welcome your participation and collaboration.

Shining stars of our community:

Contact

PHPFlasher is being actively developed by yoeunes. You can reach out with questions, bug reports, or feature requests on any of the following:

• Github Issues
• Github
• Twitter
• Linkedin
• Email me directly

License

PHPFlasher is open-sourced software licensed under the MIT license.

Made with ❤️ by Younes ENNAJI