diff --git a/docs/_includes/_usage.md b/docs/_includes/_usage.md index aac9755e..3619f5f3 100644 --- a/docs/_includes/_usage.md +++ b/docs/_includes/_usage.md @@ -1,7 +1,6 @@ ## Usage -To display a notification message, you can either use the `flash()` helper method or obtain an instance of `flasher` from the service container. -Then, before returning a view or redirecting, call the `success()` method and pass in the desired message to be displayed. +To show a notification message, you can use the `flash()` helper function or get an instance of `flasher` from the service container. Before you return a view or redirect, call one of the notification methods like `success()` and pass in the message you want to display. {% assign id = '#/ PHPFlasher' %} {% assign type = 'success' %} @@ -24,7 +23,7 @@ class BookController flash('{{ message }}'); - // ... redirect or render the view + // ... redirect or render a view } /** @@ -36,18 +35,16 @@ class BookController $flasher->success('{{ site.data.messages["success"] | sample }}'); - // ... redirect or render the view + // ... redirect or render a view } } ```
-It's important to choose a message that is clear and concise, and that accurately reflects the outcome of the operation.
-In this case, `"Book has been created successfully!"` is already a good message, -but you may want to tailor it to fit the specific context and language of your application. +Choose a message that is clear and tells the user what happened. For example, `"Book has been created successfully!"` is a good message, but you can adjust it to fit your application's context and language. -> Using this package is actually pretty easy. Adding notifications to your application actually require only one line of code. +> Using this package is easy. You can add notifications to your application with just one line of code. {% assign id = '#/ usage success' %} {% assign type = 'success' %} @@ -99,8 +96,7 @@ flash()->{{ type }}('{{ message }}'); --- -These four methods `success()`, `error()`, `warning()`, `info()` are simply convenience shortcuts for the `flash()` method, -allowing you to specify the `type` and `message` in a single method call rather than having to pass both as separate arguments to the `flash()` method. +These four methods — `success()`, `error()`, `warning()`, and `info()` — are shortcuts for the `flash()` method. They let you specify the `type` and `message` in one method call instead of passing them separately to `flash()`. ```php flash()->flash(string $type, string $message, string $title = null, array $options = []) @@ -118,22 +114,19 @@ flash()->flash(string $type, string $message, string $title = null, array $optio flash()->flash('{{ type }}', '{{ message }}'); ``` -| param | description | -|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `$type` | Notification type : success, error, warning, info | -| `$message` | The body of the message you want to deliver to your user. This may contain HTML. If you add links, be sure to add the appropriate classes for the framework you are using. | -| `$title` | The notification title, Can also include HTML | -| `$options` | Custom options for javascript libraries (toastr, noty, notyf ...etc) | +| Parameter | Description | +|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `$type` | Notification type: success, error, warning, info | +| `$message` | The message you want to show to the user. This can include HTML. If you add links, make sure to add the right classes for your framework. | +| `$title` | The notification title. Can also include HTML. | +| `$options` | Custom options for JavaScript libraries (toastr, noty, notyf, etc.). | ---

options

-The `options()` method allows you to set multiple options at once by passing an array of `key-value` pairs, -while the `option()` method allows you to set a single option by specifying its name and value as separate arguments.

-The optional `$append` argument for the `options()` method can be used to specify whether the new options should be appended to any existing options, -or whether they should overwrite them. +The `options()` method lets you set multiple options at once by passing an array of key-value pairs. The `option()` method lets you set a single option by specifying its name and value. The `$append` argument for `options()` decides whether the new options should be added to existing ones (`true`) or replace them (`false`). ```php flash()->options(array $options, bool $append = true); @@ -160,7 +153,7 @@ flash()

option

-Set a single option by specifying its name and value as separate arguments. +To set a single option: ```php flash()->option(string $option, mixed $value); @@ -185,7 +178,7 @@ flash()

priority

-Sets the priority of a flash message, the highest priority will be displayed first. +Set the priority of a flash message. Messages with higher priority appear first. ```php flash()->priority(int $priority); @@ -246,17 +239,17 @@ flash() ->info('{{ infoMessage }}'); ``` -| param | description | -|-------------|--------------------------------------------------------------------------------------------| -| `$priority` | The priority of the notification, the higher the priority, the sooner it will be displayed | +| param | description | +|-------------|-------------------------------------------------------------------| +| `$priority` | The priority of the notification. Higher numbers are shown first. | ---

hops

-This method sets the number of requests that the flash message should persist for. By default, flash messages are only displayed for a single request and are then discarded. By setting the number of hops, the flash message will be persisted for multiple requests. +The `hops()` method sets how many requests the flash message should last for. By default, flash messages show for one request. Setting the number of hops makes the message stay for multiple requests. -As an example, with a multi-page form, you may want to store messages until all pages have been filled. +For example, in a multi-page form, you might want to keep messages until all pages are completed. {% assign id = '#/ usage hops' %} {% assign type = site.data.messages.types | sample %} @@ -274,16 +267,15 @@ flash() ->{{ type }}('{{ message }}'); ``` -| param | description | -|---------|---------------------------------------------------------------| -| `$hops` | indicate how many requests the flash message will persist for | +| param | description | +|---------|-------------------------------------------------------| +| `$hops` | Number of requests the flash message will persist for | ---

translate

-This method sets the `locale` to be used for the translation of the flash message. If a non-null value is provided, -the flash message will be translated into the specified language. If null is provided, the **default** `locale` will be used. +The `translate()` method sets the `locale` for translating the flash message. If you provide a locale, the message will be translated to that language. If you pass `null`, it uses the default locale. ```php flash()->translate(string $locale = null); @@ -320,18 +312,17 @@ flash() ->{{ type }}('Your request was processed successfully.', 'Congratulations!'); ``` -| param | description | -|-----------|------------------------------------------------------------------------------| -| `$locale` | The locale to be used for the translation, or null to use the default locale | +| param | description | +|-----------|--------------------------------------------------------------| +| `$locale` | The locale to use for translation, or `null` for the default | -It is **important** to note that the `translate()` method only sets the locale to be used for the translation of the flash message. -It does not actually perform the translation itself. +**Note:** The `translate()` method only sets the locale. It doesn't translate the message by itself. -In order to translate the flash message, you will need to provide the appropriate translation keys in your translation files. +To translate the message, you need to add the translation keys in your translation files. {% if page.framework == 'laravel' %} -In the above example, to translate the flash message into `Arabic`, you will need to add the following keys to the `resources/lang/ar/messages.php` file: +For example, to translate the message into Arabic, add these keys to `resources/lang/ar/messages.php`: ```php return [ @@ -342,7 +333,7 @@ return [ {% elsif page.framework == 'symfony' %} -In the above example, to translate the flash message into `Arabic`, you will need to add the following keys to the `translations/messages.ar.yaml` file: +For example, to translate the message into Arabic, add these keys to `translations/messages.ar.yaml`: ```yaml Your request was processed successfully.: 'تمت العملية بنجاح.' diff --git a/docs/pages/symfony.md b/docs/pages/symfony.md index 25cf559b..ad199dd9 100644 --- a/docs/pages/symfony.md +++ b/docs/pages/symfony.md @@ -7,9 +7,9 @@ framework: symfony ## Requirements -PHPFlasher offers a seamless way to incorporate flash notifications in Symfony projects, enhancing user feedback with minimal setup. +**PHPFlasher** helps you easily add flash notifications to your ** Symfony** projects, improving user feedback with minimal setup. -Requirements for using PHPFlasher with Symfony: +To use **PHPFlasher** with Symfony, you need: > **PHP** v8.2 or higher > **Symfony** v7.0 or higher @@ -18,13 +18,15 @@ Requirements for using PHP Installation -PHPFlasher's modular design lets you select and install only the components your project needs. +**PHPFlasher** is modular. You can install only the parts you need. + +Run this command to install it: ```shell composer require php-flasher/flasher-symfony ``` -After installation, you need to run another command to set up the necessary assets for PHPFlasher: +After installing, run this command to set up the required assets: ```shell php bin/console flasher:install @@ -38,13 +40,13 @@ php bin/console flasher:install ## Configuration -As optional, if you want to modify the default configuration, you can publish the configuration file: +If you want to change the default settings, you can publish the configuration file: ```bash php bin/console flasher:install --config ``` -The configuration file will be located at `config/packages/flasher.yaml` and will have the following content: +This will create a file at `config/packages/flasher.yaml` with the following content: ```yaml # config/packages/flasher.yaml @@ -71,6 +73,7 @@ flasher: # timeout in milliseconds timeout: 5000 position: 'top-right' + escapeHtml: false # Map Symfony session keys to PHPFlasher notification types flash_bag: @@ -89,11 +92,11 @@ flasher: ## 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 create a preset for a custom notification that you want to reuse in multiple places. Add 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.
+> A preset is like a pre-defined message you can use in many places. -For example, you can create a preset named `entity_saved` in the configuration file and then use +For example, create a preset named `entity_saved`: {% assign id = '#/ symfony preset' %} {% assign type = 'success' %} @@ -113,7 +116,7 @@ flasher: title: '{{ title }}' ``` -To use the preset, you can call the `preset()` method and pass the name of the preset as the first argument: +To use the preset, call the `preset()` method and pass the name of the preset: ```php {{ id }} @@ -125,7 +128,7 @@ class BookController flash()->preset('entity_saved'); ``` -This is equivalent to: +This is the same as: ```php class BookController @@ -137,7 +140,7 @@ class BookController

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. +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. ```yaml # config/packages/flasher.yaml @@ -149,7 +152,7 @@ flasher: message: welcome_back_user ``` -In the translations file you can define `welcome_back_user` with the message containing the variable `:username`. +In your translation file, define `welcome_back_user` with a message containing the variable `:username`. ```yaml # translations/flasher.en.yaml @@ -157,7 +160,7 @@ In the translations file you can define `welcome_back_user` with the message con 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. +To replace `:username` with the actual username in your controller, pass an array with the values to substitute as the second argument: ```php class BookController @@ -175,10 +178,9 @@ class BookController ## 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. +**PHPFlasher** makes it easy to use **right-to-left** languages like `Arabic` or `Hebrew`. It automatically detects the text direction and adjusts accordingly. -Simply make sure the translation service is enabled and let PHPFlasher handle the rest. +Just make sure the translation service is enabled, and **PHPFlasher** will handle the rest. {% assign id = '#/ phpflasher rtl' %} {% assign type = 'success' %} @@ -199,14 +201,13 @@ flash() ## 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. +**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. -For example, to override the `English` translation strings for PHPFlasher, you can create a language file at the following location: -**`translations/flasher.en.yaml`**. +To override the `English` translations for PHPFlasher, create a file at `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. +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` in PHPFlasher: +Here are examples of the default translation keys for `Arabic`, `English`, and `French`: ```yaml # translations/flasher.ar.yaml @@ -256,7 +257,7 @@ 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. +> 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 = 'تم إنشاء الملف' %}