From 88f7546b50416dee6b47fe5b566d425b1bffaa3b Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Mon, 2 Mar 2026 01:29:04 +0000 Subject: [PATCH] Update documentation for installation and libraries --- docs/pages/installation.md | 238 ++++++++++++++++++++++++++++++- docs/pages/library/noty.md | 4 +- docs/pages/library/notyf.md | 2 +- docs/pages/library/sweetalert.md | 6 +- docs/pages/library/toastr.md | 8 +- docs/pages/themes/amazon.md | 26 ++++ 6 files changed, 273 insertions(+), 11 deletions(-) diff --git a/docs/pages/installation.md b/docs/pages/installation.md index fa9381e6..a6ac2f9b 100644 --- a/docs/pages/installation.md +++ b/docs/pages/installation.md @@ -1,12 +1,20 @@ --- permalink: /installation/ title: Installation -description: Install PHPFlasher in your project easily. It’s modular, so you can install only the parts you need. Just include the library in your composer.json file and run composer install to get started. +description: Install PHPFlasher in your project easily. It's modular, so you can install only the parts you need. Just include the library in your composer.json file and run composer install to get started. --- **PHPFlasher** is modular and consists of multiple libraries, allowing users to install and use only the specific components they need for their project. +## Requirements + +- **PHP 8.2** or higher +- **Composer** +- **Laravel 11+** or **Symfony 7+** + +--- + ## Installation **PHPFlasher** can be installed using composer : @@ -22,6 +30,8 @@ After installation, you need to run another command to set up the necessary asse php artisan flasher:install ``` +This command publishes the required JavaScript and CSS files to your `public/vendor/flasher` directory. These assets are automatically injected into your HTML responses. +
** Symfony**: @@ -35,6 +45,8 @@ After installation, you need to run another command to set up the necessary asse php bin/console flasher:install ``` +This command publishes the required JavaScript and CSS files to your `public/vendor/flasher` directory. These assets are automatically injected into your HTML responses. + --- ## Usage @@ -390,3 +402,227 @@ return [ 'Congratulations!' => 'تهانينا', ]; ``` + +--- + +

Resource Operations

+ +PHPFlasher provides convenient methods for common CRUD operations. These methods automatically generate appropriate success messages with the resource name. + +```php +flash()->created(string|object|null $resource = null): Envelope +flash()->updated(string|object|null $resource = null): Envelope +flash()->saved(string|object|null $resource = null): Envelope +flash()->deleted(string|object|null $resource = null): Envelope +``` + +{% assign id = '#/ usage created' %} +{% assign type = 'success' %} +{% assign message = 'The resource was created' %} +{% assign options = '{}' %} +{% include example.html %} + +```php +{{ id }} + +// Basic usage - displays "The resource was created" +flash()->created(); + +// With a string - displays "The user was created" +flash()->created('user'); + +// With an object - automatically resolves the class name +flash()->created($user); // displays "The User was created" +``` + +{% assign id = '#/ usage updated' %} +{% assign message = 'The post was updated' %} +{% include example.html %} + +```php +{{ id }} + +flash()->updated('post'); +``` + +{% assign id = '#/ usage deleted' %} +{% assign message = 'The comment was deleted' %} +{% include example.html %} + +```php +{{ id }} + +flash()->deleted('comment'); +``` + +| param | description | +|-------------|--------------------------------------------------------------------------------------------| +| `$resource` | A string name, an object (class name will be extracted), or null (defaults to "resource") | + +> If you pass an object that implements a `getFlashIdentifier()` method, that value will be used as the resource name. + +--- + +

Conditional Notifications

+ +Use `when()` and `unless()` to conditionally display notifications without wrapping your code in if statements. + +```php +flash()->when(bool|\Closure $condition): static +flash()->unless(bool|\Closure $condition): static +``` + +{% assign id = '#/ usage when' %} +{% assign type = 'success' %} +{% assign message = 'Profile updated successfully!' %} +{% assign options = '{}' %} +{% include example.html %} + +```php +{{ id }} + +// Only show notification if condition is true +flash() + ->when($user->isVerified()) + ->success('Profile updated successfully!'); + +// Using a closure for more complex conditions +flash() + ->when(fn() => $order->total() > 100) + ->success('You qualify for free shipping!'); +``` + +{% assign id = '#/ usage unless' %} +{% assign type = 'warning' %} +{% assign message = 'Please verify your email address.' %} +{% include example.html %} + +```php +{{ id }} + +// Show notification unless condition is true +flash() + ->unless($user->hasVerifiedEmail()) + ->warning('Please verify your email address.'); +``` + +| param | description | +|--------------|----------------------------------------------------------------| +| `$condition` | A boolean or a Closure that returns a boolean | + +--- + +

keep

+ +The `keep()` method increments the notification's hop count by 1, allowing it to persist through an additional request. This is useful when you need a notification to survive one more redirect. + +```php +flash()->keep(): static +``` + +```php +// Notification will persist through one additional redirect +flash() + ->keep() + ->success('This message will survive one more redirect.'); +``` + +| behavior | description | +|-------------|----------------------------------------------------------------| +| Default | Notifications are shown once and then removed | +| With keep() | Notification persists through one additional request | + +> The `keep()` method is a shorthand for incrementing the current hops by 1. For more control, use the `hops()` method directly. + +--- + +

delay

+ +The `delay()` method sets a delay (in milliseconds) before the notification is displayed. This is useful for staggered notifications or giving users time to focus on content before showing a message. + +```php +flash()->delay(int $delay): static +``` + +{% assign id = '#/ usage delay' %} +{% assign type = 'info' %} +{% assign message = 'Check out our new features!' %} +{% assign options = '{"delay": 2000}' %} +{% include example.html %} + +```php +{{ id }} + +// Notification appears after 2 seconds +flash() + ->delay(2000) // 2000 milliseconds = 2 seconds + ->info('Check out our new features!'); +``` + +| param | description | +|----------|--------------------------------------------------| +| `$delay` | Delay in milliseconds before showing the notification | + +--- + +

preset

+ +Presets allow you to define reusable notification configurations in your config file, then reference them by name in your code. + +```php +flash()->preset(string $preset, array $parameters = []): Envelope +``` + +First, define presets in your configuration file: + +** Laravel** - `config/flasher.php`: + +```php +return [ + 'presets' => [ + 'entity_saved' => [ + 'type' => 'success', + 'title' => 'Saved', + 'message' => 'The :entity has been saved successfully.', + ], + 'welcome' => [ + 'type' => 'info', + 'message' => 'Welcome back, :name!', + 'options' => [ + 'timeout' => 3000, + ], + ], + ], +]; +``` + +** Symfony** - `config/packages/flasher.yaml`: + +```yaml +flasher: + presets: + entity_saved: + type: success + title: Saved + message: 'The :entity has been saved successfully.' + welcome: + type: info + message: 'Welcome back, :name!' + options: + timeout: 3000 +``` + +Then use the preset in your code: + +```php +// Use a preset with parameter substitution +flash()->preset('entity_saved', [':entity' => 'product']); + +// Another example +flash()->preset('welcome', [':name' => $user->name]); +``` + +| param | description | +|---------------|------------------------------------------------------------| +| `$preset` | The name of the preset as defined in your configuration | +| `$parameters` | Key-value pairs for placeholder substitution in the message | diff --git a/docs/pages/library/noty.md b/docs/pages/library/noty.md index 597e1012..d2f071df 100644 --- a/docs/pages/library/noty.md +++ b/docs/pages/library/noty.md @@ -89,7 +89,7 @@ flasher: --- -> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `notyf` adapter. +> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `noty` adapter. --- @@ -182,7 +182,7 @@ For more information on Noty options and usage, please refer to the original doc --- -> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `notyf` adapter. +> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `noty` adapter. --- diff --git a/docs/pages/library/notyf.md b/docs/pages/library/notyf.md index 5bc576e4..1fdf7341 100644 --- a/docs/pages/library/notyf.md +++ b/docs/pages/library/notyf.md @@ -94,7 +94,7 @@ Then, before returning a view or redirecting, call the `success()` method and pa

success

-{% assign id = '#/ noty' %} +{% assign id = '#/ notyf' %} {% assign type = 'success' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} diff --git a/docs/pages/library/sweetalert.md b/docs/pages/library/sweetalert.md index fbb7e4c6..359b341b 100644 --- a/docs/pages/library/sweetalert.md +++ b/docs/pages/library/sweetalert.md @@ -87,7 +87,7 @@ flasher: --- -> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `notyf` adapter. +> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `sweetalert` adapter. --- @@ -96,7 +96,7 @@ Then, before returning a view or redirecting, call the `success()` method and pa

success

-{% assign id = '#/ noty' %} +{% assign id = '#/ sweetalert' %} {% assign type = 'success' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} @@ -180,7 +180,7 @@ For more information on Sweetalert2 alert options and usage, please refer to th --- -> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `notyf` adapter. +> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `sweetalert` adapter. --- diff --git a/docs/pages/library/toastr.md b/docs/pages/library/toastr.md index 692d6fbc..2af1050b 100644 --- a/docs/pages/library/toastr.md +++ b/docs/pages/library/toastr.md @@ -72,7 +72,7 @@ php bin/console flasher:install flasher: plugins: - noty: + toastr: scripts: - '/vendor/flasher/jquery.min.js' - '/vendor/flasher/toastr.min.js' @@ -90,7 +90,7 @@ flasher: --- -> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `notyf` adapter. +> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `toastr` adapter. --- @@ -99,7 +99,7 @@ Then, before returning a view or redirecting, call the `success()` method and pa

success

-{% assign id = '#/ noty' %} +{% assign id = '#/ toastr' %} {% assign type = 'success' %} {% assign message = site.data.messages[type] | sample %} {% assign options = '{}' %} @@ -183,7 +183,7 @@ For more information on Toastr options and usage, please refer to the original d --- -> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `notyf` adapter. +> The methods described in the **[Usage](/installation/#-usage)** section can also be used with the `toastr` adapter. --- diff --git a/docs/pages/themes/amazon.md b/docs/pages/themes/amazon.md index 0a830e91..0b89328b 100644 --- a/docs/pages/themes/amazon.md +++ b/docs/pages/themes/amazon.md @@ -74,3 +74,29 @@ html_structure: | --- + +## Usage + +To use the Amazon theme, specify it in your flash notification: + +```php +flash()->use('theme.amazon')->success('Your order has been placed successfully!'); +flash()->use('theme.amazon')->error('Unable to process your payment.'); +flash()->use('theme.amazon')->warning('This item is almost out of stock.'); +flash()->use('theme.amazon')->info('Free shipping on orders over $25.'); +``` + +Or set it as the default theme in your configuration: + +**Laravel** - `config/flasher.php`: +```php +return [ + 'default' => 'theme.amazon', +]; +``` + +**Symfony** - `config/packages/flasher.yaml`: +```yaml +flasher: + default: theme.amazon +```