From fe4601bb8baccbe23a05d125b1fadf24646df260 Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Sun, 27 Oct 2024 15:29:49 +0100 Subject: [PATCH] docs: update symfony README.md file --- src/Symfony/README.md | 346 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 330 insertions(+), 16 deletions(-) diff --git a/src/Symfony/README.md b/src/Symfony/README.md index 47aa95a1..c613a521 100644 --- a/src/Symfony/README.md +++ b/src/Symfony/README.md @@ -6,26 +6,340 @@

- - PHPFlasher Logo + + PHPFlasher Logo

-## About PHPFlasher +

+ Author Badge + Source Code Badge + GitHub Release Badge + License Badge + Packagist Downloads Badge + GitHub Stars Badge + Supported PHP Version Badge +

-PHPFlasher is a powerful and easy-to-use package that allows you to quickly and easily add flash messages to your Laravel or Symfony projects. -Whether you need to alert users of a successful form submission, an error, or any other important information, flash messages are a simple and effective solution for providing feedback to your users. +## Table of Contents -With PHPFlasher, you can easily record and store messages within the session, making it simple to retrieve and display them on the current or next page. -This improves user engagement and enhances the overall user experience on your website or application. +- [About PHPFlasher Symfony Adapter](#about-phpflasher-symfony-adapter) +- [Features](#features) +- [Supported Versions](#supported-versions) +- [Installation](#installation) + - [Core Package](#core-package) + - [Adapters](#adapters) +- [Configuration](#configuration) + - [Configuration File](#configuration-file) + - [Configuration Options](#configuration-options) +- [Quick Start](#quick-start) +- [Usage Examples](#usage-examples) +- [Adapters Overview](#adapters-overview) +- [Official Documentation](#official-documentation) +- [Contributors and Sponsors](#contributors-and-sponsors) +- [Contact](#contact) +- [License](#license) -Whether you're a beginner or an experienced developer, PHPFlasher's intuitive and straightforward design makes it easy to integrate into your projects. -So, if you're looking for a reliable, flexible and easy to use flash messages solution, PHPFlasher is the perfect choice. +## 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 + +| PHPFlasher Symfony Adapter Version | PHP Version | Symfony Version | +|------------------------------------|-------------|-----------------| +| **v2.x** | ≥ 8.2 | ≥ 7.0 | +| **v1.x** | ≥ 5.3 | ≥ 2.0 | + +> **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](https://github.com/php-flasher/flasher-symfony/tree/1.x). + +## Installation + +### Core Package + +Install the PHPFlasher Symfony Adapter via Composer: + +```bash +composer require php-flasher/flasher-symfony +``` + +After installation, set up the necessary assets: + +```shell +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](https://github.com/php-flasher/flasher-toastr-symfony) - Symfony Adapter +- [flasher-noty-symfony](https://github.com/php-flasher/flasher-noty-symfony) - Symfony Adapter +- [flasher-notyf-symfony](https://github.com/php-flasher/flasher-notyf-symfony) - Symfony Adapter +- [flasher-sweetalert-symfony](https://github.com/php-flasher/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: + +```bash +php bin/console flasher:install --config +``` + +This will create a file at `config/packages/flasher.yaml` with the following content: + +```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' +``` + +### Configuration Options + +| **Option** | **Description** | +|------------------|---------------------------------------------------------------------------------------------------------------------------| +| `default` | **String**: The default notification library to use (e.g., `'flasher'`, `'toastr'`, `'noty'`, `'notyf'`, `'sweetalert'`). | +| `main_script` | **String**: Path to the main PHPFlasher JavaScript file. | +| `styles` | **Array**: List of CSS files to style your notifications. | +| `options` | **Array** (Optional): Global options for all notifications (e.g., `'timeout'`, `'position'`). | +| `inject_assets` | **Boolean**: Whether to automatically inject JavaScript and CSS assets into your HTML pages. | +| `translate` | **Boolean**: Enable message translation using Symfony’s translation service. | +| `excluded_paths` | **Array**: URL patterns to exclude from asset injection and flash_bag conversion. | +| `flash_bag` | **Array**: Map Symfony flash message keys to notification types. | +| `filter` | **Array** (Optional): Criteria to filter which notifications are displayed (e.g., `'limit'`). | +| `presets` | **Array** (Optional): Define notification presets to simplify notification creation. | + +## 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 +redirectToRoute('book_list'); + } +} +``` + +### Using the `flasher` Service + +```php +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 + +```php +flash()->success('Operation completed successfully!'); +``` + +### Error Message + +```php +flash()->error('An error occurred.'); +``` + +### Info Message + +```php +flash()->info('This is an informational message.'); +``` + +### Warning Message + +```php +flash()->warning('This is a warning message.'); +``` + +### Passing Options + +```php +flash()->success('Custom message with options.', ['timeout' => 3000, 'position' => 'bottom-left']); +``` + +### Using presets + +Define a preset in your `config/packages/flasher.yaml`: + +```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 +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: + +| Adapter Repository | Description | +|-----------------------------------------------------------------------------------------|--------------------------------| +| [flasher-symfony](https://github.com/php-flasher/flasher-symfony) | Symfony framework adapter | +| [flasher-toastr-symfony](https://github.com/php-flasher/flasher-toastr-symfony) | Toastr adapter for Symfony | +| [flasher-noty-symfony](https://github.com/php-flasher/flasher-noty-symfony) | Noty adapter for Symfony | +| [flasher-notyf-symfony](https://github.com/php-flasher/flasher-notyf-symfony) | Notyf adapter for Symfony | +| [flasher-sweetalert-symfony](https://github.com/php-flasher/flasher-sweetalert-symfony) | SweetAlert adapter for Symfony | + +> **Note:** Each adapter has its own repository. For detailed installation and usage instructions, please refer to the [Official Documentation](https://php-flasher.io). ## Official Documentation -Documentation for PHPFlasher can be found on the [https://php-flasher.io](https://php-flasher.io). +Comprehensive documentation for PHPFlasher is available at [https://php-flasher.io](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 @@ -42,7 +356,7 @@ Shining stars of our community: - + @@ -52,7 +366,7 @@ Shining stars of our community: - +
Younes ENNAJI
Younes ENNAJI
💻 📖 🚧		Younes ENNAJI
Younes ENNAJI
💻 📖 🚧		 Salma Mourad
Salma Mourad
💵		 Nashwan Abdullah
Nashwan Abdullah
💵		 Arvid de Jong
Arvid de Jong
💵
Lucas Maciel
Lucas Maciel
🎨		Antoni Siek
Antoni Siek
💻		Ahmed Gamal
Ahmed Gamal
💻 📖
@@ -64,17 +378,17 @@ Shining stars of our community: ## Contact -PHPFlasher is being actively developed by yoeunes. +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](https://github.com/php-flasher/php-flasher/issues) +- [Github Issues](https://github.com/php-flasher/php-flasher/issues) - [Github](https://github.com/yoeunes) - [Twitter](https://twitter.com/yoeunes) -- [Linkedin](https://www.linkedin.com/in/younes--ennaji//) +- [Linkedin](https://www.linkedin.com/in/younes--ennaji/) - [Email me directly](mailto:younes.ennaji.pro@gmail.com) ## License PHPFlasher is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). -

Made with ❤️ by Younes ENNAJI

+

Made with ❤️ by Younes ENNAJI