From 1c5fbbba9a9abd4dddb759ba84af0cb4b7b64270 Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Sat, 10 Jan 2026 02:15:51 +0100 Subject: [PATCH] Refactors and improves documentation clarity --- docs/_includes/_usage.md | 4 +- docs/pages/installation.md | 3 +- docs/pages/javascript.md | 4 +- docs/pages/themes.md | 2 +- src/Laravel/Resources/config.php | 26 +++--- src/Prime/EventDispatcher/EventDispatcher.php | 7 +- src/Prime/Notification/FlasherBuilder.php | 89 +++++++++---------- src/Prime/Notification/Notification.php | 46 +++++----- src/Prime/Response/Response.php | 8 +- src/Prime/Response/ResponseManager.php | 10 +-- src/Prime/Storage/StorageManager.php | 28 +++--- 11 files changed, 108 insertions(+), 119 deletions(-) diff --git a/docs/_includes/_usage.md b/docs/_includes/_usage.md index b0aa1673..8177de79 100644 --- a/docs/_includes/_usage.md +++ b/docs/_includes/_usage.md @@ -31,9 +31,9 @@ class BookController
-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. +Choose a clear message that 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 easy. You can add notifications to your application with just one line of code. +> This package is easy to use. You can add notifications to your application with just one line of code. {% assign id = '#/ usage success' %} {% assign type = 'success' %} diff --git a/docs/pages/installation.md b/docs/pages/installation.md index 62a38f5d..fa9381e6 100644 --- a/docs/pages/installation.md +++ b/docs/pages/installation.md @@ -378,8 +378,7 @@ flash() |-----------|------------------------------------------------------------------------------| | `$locale` | The locale to be used for the translation, or null to use the default locale | -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 that the `translate()` method only sets the locale; it does not perform the translation itself. In order to translate the flash message, you will need to provide the appropriate translation keys in your translation files. diff --git a/docs/pages/javascript.md b/docs/pages/javascript.md index 487715c8..1b0680e2 100644 --- a/docs/pages/javascript.md +++ b/docs/pages/javascript.md @@ -5,7 +5,7 @@ title: JavaScript description: Easily add flash notification messages to your JavaScript application with PHPFlasher. Follow our step-by-step guide to install the library using npm or include it in your project using CDN links, and start engaging and informing your users with powerful flash messages. --- -PHPFlasher assets can be installed from a cdn or using npm +PHPFlasher assets can be installed from a CDN or using npm ## Installation Quick start guide for installing the PHPFlasher from cdn or npm. @@ -68,7 +68,7 @@ or if you are using a cdn like this: ### Other adapters -First grad the cdn for any js library adapter supported by PHPFlasher or install it with npm +First grab the CDN for any js library adapter supported by PHPFlasher or install it with npm and then call the `create()` method on flasher object : ```html diff --git a/docs/pages/themes.md b/docs/pages/themes.md index fd4eda6e..87ec7a40 100644 --- a/docs/pages/themes.md +++ b/docs/pages/themes.md @@ -2,7 +2,7 @@ ## Overview -The PHPFlasher theme system allows for consistent, customizable notification designs across your application. Themes define both the visual appearance (using CSS/SCSS) and the HTML structure (using template functions) of notifications. +The PHPFlasher theme system allows for consistent, customizable notification designs across your application. Themes define both the visual appearance (CSS/SCSS) and HTML structure of notifications. ## Core Concepts diff --git a/src/Laravel/Resources/config.php b/src/Laravel/Resources/config.php index c32fe53f..6460d986 100644 --- a/src/Laravel/Resources/config.php +++ b/src/Laravel/Resources/config.php @@ -14,33 +14,33 @@ use Flasher\Prime\Configuration; * @return array PHPFlasher configuration */ return Configuration::from([ - // Default notification library (e.g., 'flasher', 'toastr', 'noty', 'notyf', 'sweetalert') + // Default notification adapter 'default' => 'flasher', - // Path to the main PHPFlasher JavaScript file + // Main script path 'main_script' => '/vendor/flasher/flasher.min.js', - // List of CSS files to style your notifications + // Stylesheet files 'styles' => [ '/vendor/flasher/flasher.min.css', ], - // Set global options for all notifications (optional) + // Global notification options // 'options' => [ - // 'timeout' => 5000, // Time in milliseconds before the notification disappears - // 'position' => 'top-right', // Where the notification appears on the screen + // 'timeout' => 5000, + // 'position' => 'top-right', // ], - // Automatically inject JavaScript and CSS assets into your HTML pages + // Auto-inject assets into responses 'inject_assets' => true, - // Enable message translation using Laravel's translation service + // Enable automatic message translation 'translate' => true, - // URL patterns to exclude from asset injection and flash_bag conversion + // URL patterns to exclude from asset injection and flash bag conversion 'excluded_paths' => [], - // Map Laravel flash message keys to notification types + // Map Laravel session flash keys to notification types 'flash_bag' => [ 'success' => ['success'], 'error' => ['error', 'danger'], @@ -48,12 +48,12 @@ return Configuration::from([ 'info' => ['info', 'notice', 'alert'], ], - // Set criteria to filter which notifications are displayed (optional) + // Filter criteria for notifications // 'filter' => [ - // 'limit' => 5, // Maximum number of notifications to show at once + // 'limit' => 5, // ], - // Define notification presets to simplify notification creation (optional) + // Predefined notification configurations // 'presets' => [ // 'entity_saved' => [ // 'type' => 'success', diff --git a/src/Prime/EventDispatcher/EventDispatcher.php b/src/Prime/EventDispatcher/EventDispatcher.php index 3f8d7613..6027b832 100644 --- a/src/Prime/EventDispatcher/EventDispatcher.php +++ b/src/Prime/EventDispatcher/EventDispatcher.php @@ -25,7 +25,7 @@ use Flasher\Prime\EventDispatcher\EventListener\EventListenerInterface; final class EventDispatcher implements EventDispatcherInterface { /** - * Mapping of event names to their registered listeners. + * Mapping of event names to listeners. * * @var array */ @@ -54,7 +54,7 @@ final class EventDispatcher implements EventDispatcherInterface * that implement StoppableEventInterface. It calls each listener in * registration order until all listeners are called or propagation is stopped. * - * @throws \InvalidArgumentException If a listener is not callable + * @throws \InvalidArgumentException */ public function dispatch(object $event): object { @@ -77,9 +77,6 @@ final class EventDispatcher implements EventDispatcherInterface /** * {@inheritdoc} - * - * This implementation registers a listener for all events it declares - * interest in through its getSubscribedEvents() method. */ public function addListener(EventListenerInterface $listener): void { diff --git a/src/Prime/Notification/FlasherBuilder.php b/src/Prime/Notification/FlasherBuilder.php index 2ccd1ac6..093fcee7 100644 --- a/src/Prime/Notification/FlasherBuilder.php +++ b/src/Prime/Notification/FlasherBuilder.php @@ -28,11 +28,11 @@ namespace Flasher\Prime\Notification; final class FlasherBuilder extends NotificationBuilder { /** - * Sets the notification type with type-safety. + * Sets the notification type. * - * @phpstan-param NotificationType $type The notification type (success, info, warning, error) + * @phpstan-param NotificationType $type * - * @return static The builder instance for method chaining + * @return static */ public function type(string $type): static { @@ -42,11 +42,11 @@ final class FlasherBuilder extends NotificationBuilder /** * Creates and stores a success notification. * - * @param string $message The notification message - * @param OptionsType $options Optional configuration for the notification - * @param string|null $title Optional title for the notification + * @param string $message + * @param OptionsType $options + * @param string|null $title * - * @return Envelope The created and stored notification envelope + * @return Envelope */ public function success(string $message, array $options = [], ?string $title = null): Envelope { @@ -56,11 +56,11 @@ final class FlasherBuilder extends NotificationBuilder /** * Creates and stores an error notification. * - * @param string $message The notification message - * @param OptionsType $options Optional configuration for the notification - * @param string|null $title Optional title for the notification + * @param string $message + * @param OptionsType $options + * @param string|null $title * - * @return Envelope The created and stored notification envelope + * @return Envelope */ public function error(string $message, array $options = [], ?string $title = null): Envelope { @@ -70,11 +70,11 @@ final class FlasherBuilder extends NotificationBuilder /** * Creates and stores an info notification. * - * @param string $message The notification message - * @param OptionsType $options Optional configuration for the notification - * @param string|null $title Optional title for the notification + * @param string $message + * @param OptionsType $options + * @param string|null $title * - * @return Envelope The created and stored notification envelope + * @return Envelope */ public function info(string $message, array $options = [], ?string $title = null): Envelope { @@ -84,11 +84,11 @@ final class FlasherBuilder extends NotificationBuilder /** * Creates and stores a warning notification. * - * @param string $message The notification message - * @param OptionsType $options Optional configuration for the notification - * @param string|null $title Optional title for the notification + * @param string $message + * @param OptionsType $options + * @param string|null $title * - * @return Envelope The created and stored notification envelope + * @return Envelope */ public function warning(string $message, array $options = [], ?string $title = null): Envelope { @@ -98,16 +98,13 @@ final class FlasherBuilder extends NotificationBuilder /** * Creates and stores a notification with specified type. * - * This is a general-purpose method that can be used to create notifications - * of any type, with complete control over all parameters. + * @phpstan-param NotificationType|null $type + * @phpstan-param OptionsType $options * - * @phpstan-param NotificationType|null $type The notification type - * @phpstan-param OptionsType $options Optional configuration for the notification + * @param string|null $message + * @param string|null $title * - * @param string|null $message The notification message - * @param string|null $title Optional title for the notification - * - * @return Envelope The created and stored notification envelope + * @return Envelope */ public function flash(?string $type = null, ?string $message = null, array $options = [], ?string $title = null): Envelope { @@ -115,12 +112,12 @@ final class FlasherBuilder extends NotificationBuilder } /** - * Sets multiple options for the notification. + * Sets multiple options. * - * @param OptionsType $options Configuration options for the notification - * @param bool $append Whether to merge with existing options (true) or replace them (false) + * @param OptionsType $options + * @param bool $append * - * @return static The builder instance for method chaining + * @return static */ public function options(array $options, bool $append = true): static { @@ -128,15 +125,15 @@ final class FlasherBuilder extends NotificationBuilder } /** - * Sets a single option for the notification. + * Sets a single option. * * @template T of OptionsType * @template K of key-of * - * @phpstan-param K $name The option name - * @phpstan-param T[K] $value The option value + * @phpstan-param K $name + * @phpstan-param T[K] $value * - * @return static The builder instance for method chaining + * @return static */ public function option(string $name, mixed $value): static { @@ -144,11 +141,11 @@ final class FlasherBuilder extends NotificationBuilder } /** - * Sets the display timeout for the notification. + * Sets the display timeout. * - * @param int $milliseconds The timeout duration in milliseconds (0 for no timeout) + * @param int $milliseconds * - * @return self The builder instance for method chaining + * @return self */ public function timeout(int $milliseconds): self { @@ -158,13 +155,11 @@ final class FlasherBuilder extends NotificationBuilder } /** - * Sets the stacking direction for notifications. + * Sets the stacking direction. * - * @param "top"|"bottom" $direction The direction in which notifications should stack - * - 'top': newer notifications appear above older ones - * - 'bottom': newer notifications appear below older ones + * @param "top"|"bottom" $direction * - * @return self The builder instance for method chaining + * @return self */ public function direction(string $direction): self { @@ -174,13 +169,11 @@ final class FlasherBuilder extends NotificationBuilder } /** - * Sets the display position for notifications. + * Sets the display position. * - * @phpstan-param OptionsType['position'] $position The position on screen - * (top-right, top-left, top-center, - * bottom-right, bottom-left, bottom-center) + * @phpstan-param OptionsType['position'] $position * - * @return self The builder instance for method chaining + * @return self */ public function position(string $position): self { diff --git a/src/Prime/Notification/Notification.php b/src/Prime/Notification/Notification.php index e8a0be5d..85174ed0 100644 --- a/src/Prime/Notification/Notification.php +++ b/src/Prime/Notification/Notification.php @@ -39,9 +39,9 @@ final class Notification implements NotificationInterface private array $options = []; /** - * Gets the title of the notification. + * Gets the title. * - * @return string The notification title + * @return string */ public function getTitle(): string { @@ -49,9 +49,9 @@ final class Notification implements NotificationInterface } /** - * Sets the title of the notification. + * Sets the title. * - * @param string $title The title to set + * @param string $title */ public function setTitle(string $title): void { @@ -59,9 +59,9 @@ final class Notification implements NotificationInterface } /** - * Gets the message of the notification. + * Gets the message. * - * @return string The notification message + * @return string */ public function getMessage(): string { @@ -69,9 +69,9 @@ final class Notification implements NotificationInterface } /** - * Sets the message of the notification. + * Sets the message. * - * @param string $message The message to set + * @param string $message */ public function setMessage(string $message): void { @@ -79,9 +79,9 @@ final class Notification implements NotificationInterface } /** - * Gets the type of the notification. + * Gets the type. * - * @return string The notification type + * @return string */ public function getType(): string { @@ -89,9 +89,9 @@ final class Notification implements NotificationInterface } /** - * Sets the type of the notification. + * Sets the type. * - * @param string $type The type to set + * @param string $type */ public function setType(string $type): void { @@ -99,9 +99,9 @@ final class Notification implements NotificationInterface } /** - * Gets all options of the notification. + * Gets all options. * - * @return array The notification options + * @return array */ public function getOptions(): array { @@ -122,12 +122,12 @@ final class Notification implements NotificationInterface } /** - * Gets a specific option of the notification with a default fallback. + * Gets a specific option with a default fallback. * - * @param string $name The name of the option - * @param mixed $default The default value to return if the option is not set + * @param string $name + * @param mixed $default * - * @return mixed The option value or the default value + * @return mixed */ public function getOption(string $name, mixed $default = null): mixed { @@ -137,10 +137,10 @@ final class Notification implements NotificationInterface } /** - * Sets a specific option for the notification. + * Sets a specific option. * - * @param string $name The name of the option - * @param mixed $value The value of the option + * @param string $name + * @param mixed $value */ public function setOption(string $name, mixed $value): void { @@ -148,9 +148,9 @@ final class Notification implements NotificationInterface } /** - * Unsets a specific option of the notification. + * Unsets a specific option. * - * @param string $name The name of the option to unset + * @param string $name */ public function unsetOption(string $name): void { diff --git a/src/Prime/Response/Response.php b/src/Prime/Response/Response.php index 5273c077..7f8af2bc 100644 --- a/src/Prime/Response/Response.php +++ b/src/Prime/Response/Response.php @@ -108,7 +108,7 @@ final class Response /** * Gets the main script path. * - * @return string The path to the main JavaScript file + * @return string */ public function getMainScript(): string { @@ -118,7 +118,7 @@ final class Response /** * Sets the main script path. * - * @param string $mainScript The path to the main JavaScript file + * @param string $mainScript */ public function setMainScript(string $mainScript): void { @@ -128,7 +128,7 @@ final class Response /** * Gets the CSS stylesheets. * - * @return string[] The stylesheet paths + * @return string[] */ public function getStyles(): array { @@ -138,7 +138,7 @@ final class Response /** * Gets the JavaScript scripts. * - * @return string[] The script paths + * @return string[] */ public function getScripts(): array { diff --git a/src/Prime/Response/ResponseManager.php b/src/Prime/Response/ResponseManager.php index a34fc1af..d5e03f23 100644 --- a/src/Prime/Response/ResponseManager.php +++ b/src/Prime/Response/ResponseManager.php @@ -112,13 +112,13 @@ final class ResponseManager implements ResponseManagerInterface /** * Creates a Response object with notifications and context. * - * This method creates a basic Response object and then populates it with - * resources (scripts, styles, options) using the ResourceManager. + * This method creates a Response object and populates it with resources + * (scripts, styles, options) using the ResourceManager. * - * @param Envelope[] $envelopes The notification envelopes - * @param array $context Additional context for the presentation + * @param Envelope[] $envelopes + * @param array $context * - * @return Response The populated response object + * @return Response */ private function createResponse(array $envelopes, array $context): Response { diff --git a/src/Prime/Storage/StorageManager.php b/src/Prime/Storage/StorageManager.php index f1482394..3b1b6fd1 100644 --- a/src/Prime/Storage/StorageManager.php +++ b/src/Prime/Storage/StorageManager.php @@ -46,9 +46,9 @@ final readonly class StorageManager implements StorageManagerInterface } /** - * Retrieves all stored notification envelopes. + * Retrieves all stored envelopes. * - * @return Envelope[] Array of notification envelopes + * @return Envelope[] */ public function all(): array { @@ -56,17 +56,17 @@ final readonly class StorageManager implements StorageManagerInterface } /** - * Filters notifications based on provided criteria. + * Filters notifications by criteria. * - * This method combines default criteria with the provided criteria, - * creates a filter using the filter factory, and applies it to the envelopes. + * This method combines default criteria with provided criteria, + * creates a filter using the filter factory, and applies it to envelopes. * Before applying the filter, it dispatches a FilterEvent to allow modification. * - * @param array $criteria Filtering criteria + * @param array $criteria * - * @return Envelope[] Array of filtered notification envelopes + * @return Envelope[] * - * @throws CriteriaNotRegisteredException If a requested filter criterion doesn't exist + * @throws CriteriaNotRegisteredException */ public function filter(array $criteria = []): array { @@ -80,12 +80,12 @@ final readonly class StorageManager implements StorageManagerInterface } /** - * Adds one or more notification envelopes to storage. + * Adds notification envelopes to storage. * * Before adding envelopes, it dispatches a PersistEvent to allow modification * of the envelopes. After storage, it dispatches a PostPersistEvent. * - * @param Envelope ...$envelopes One or more notification envelopes to store + * @param Envelope ...$envelopes */ public function add(Envelope ...$envelopes): void { @@ -99,12 +99,12 @@ final readonly class StorageManager implements StorageManagerInterface } /** - * Updates one or more notification envelopes in storage. + * Updates notification envelopes in storage. * * Before updating envelopes, it dispatches an UpdateEvent to allow modification * of the envelopes. After update, it dispatches a PostUpdateEvent. * - * @param Envelope ...$envelopes One or more notification envelopes to update + * @param Envelope ...$envelopes */ public function update(Envelope ...$envelopes): void { @@ -118,13 +118,13 @@ final readonly class StorageManager implements StorageManagerInterface } /** - * Removes one or more notification envelopes from storage. + * Removes notification envelopes from storage. * * Before removal, it dispatches a RemoveEvent to allow listeners to modify * which envelopes should be removed or kept. After removal, it dispatches * a PostRemoveEvent. * - * @param Envelope ...$envelopes One or more notification envelopes to remove + * @param Envelope ...$envelopes */ public function remove(Envelope ...$envelopes): void {