From ea164fde17310adf1fb794b697869c72f820ad06 Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Thu, 15 Jan 2026 22:51:25 +0100 Subject: [PATCH] Simplify PHPDoc comments in Notyf integration Remove verbose documentation pattern references and redundant explanations, keeping only essential type annotations. --- src/Noty/Prime/functions.php | 3 +- src/Noty/Prime/helpers.php | 3 +- src/Notyf/Laravel/Facade/Notyf.php | 28 ---------- .../Laravel/FlasherNotyfServiceProvider.php | 16 ------ src/Notyf/Prime/Notyf.php | 18 ------ src/Notyf/Prime/NotyfBuilder.php | 55 ------------------- src/Notyf/Prime/NotyfInterface.php | 11 ---- src/Notyf/Prime/NotyfPlugin.php | 41 +------------- src/Notyf/Prime/functions.php | 28 +--------- src/Notyf/Prime/helpers.php | 28 +--------- .../Symfony/FlasherNotyfSymfonyBundle.php | 16 ------ 11 files changed, 8 insertions(+), 239 deletions(-) diff --git a/src/Noty/Prime/functions.php b/src/Noty/Prime/functions.php index 34d74193..3e94c267 100644 --- a/src/Noty/Prime/functions.php +++ b/src/Noty/Prime/functions.php @@ -37,6 +37,7 @@ if (!\function_exists('Flasher\Noty\Prime\noty')) { * buttons?: string[], * visibilityControl?: bool, * } $options + * @param 'success'|'info'|'warning'|'error'|'alert'|'information' $type * * @phpstan-return ($message is empty ? NotyInterface : Envelope) */ @@ -48,6 +49,6 @@ if (!\function_exists('Flasher\Noty\Prime\noty')) { return $factory; } - return $factory->flash($type, $message, $options, $title); // @phpstan-ignore-line + return $factory->flash($type, $message, $options, $title); } } diff --git a/src/Noty/Prime/helpers.php b/src/Noty/Prime/helpers.php index a715f6b7..068f3e83 100644 --- a/src/Noty/Prime/helpers.php +++ b/src/Noty/Prime/helpers.php @@ -36,6 +36,7 @@ if (!function_exists('noty')) { * buttons?: string[], * visibilityControl?: bool, * } $options + * @param 'success'|'info'|'warning'|'error'|'alert'|'information' $type * * @phpstan-return ($message is empty ? NotyInterface : Envelope) */ @@ -47,6 +48,6 @@ if (!function_exists('noty')) { return $factory; } - return $factory->flash($type, $message, $options, $title); // @phpstan-ignore-line + return $factory->flash($type, $message, $options, $title); } } diff --git a/src/Notyf/Laravel/Facade/Notyf.php b/src/Notyf/Laravel/Facade/Notyf.php index 90a4e5a4..c12a9260 100644 --- a/src/Notyf/Laravel/Facade/Notyf.php +++ b/src/Notyf/Laravel/Facade/Notyf.php @@ -10,29 +10,6 @@ use Flasher\Prime\Stamp\StampInterface; use Illuminate\Support\Facades\Facade; /** - * Notyf - Laravel facade for Notyf notifications. - * - * This facade provides a static interface to Notyf's functionality within Laravel, - * following Laravel's facade pattern. It offers comprehensive IDE autocompletion - * for all Notyf builder methods. - * - * Design patterns: - * - Facade: Provides a simplified, static interface to a complex subsystem - * - Proxy: Acts as a proxy to the underlying Notyf service - * - * Usage examples: - * ```php - * // Simple notification - * Notyf::success('Operation completed successfully'); - * - * // Chained configuration - * Notyf::duration(3000) - * ->dismissible(true) - * ->position('x', 'right') - * ->position('y', 'top') - * ->success('Record saved'); - * ``` - * * @method static NotyfBuilder success(string $message, array $options = array()) * @method static NotyfBuilder error(string $message, array $options = array()) * @method static NotyfBuilder warning(string $message, array $options = array()) @@ -57,11 +34,6 @@ use Illuminate\Support\Facades\Facade; */ final class Notyf extends Facade { - /** - * Get the registered name of the component. - * - * @return string The service container binding key for Notyf - */ protected static function getFacadeAccessor(): string { return 'flasher.notyf'; diff --git a/src/Notyf/Laravel/FlasherNotyfServiceProvider.php b/src/Notyf/Laravel/FlasherNotyfServiceProvider.php index aa80d9ea..d43ca3a4 100644 --- a/src/Notyf/Laravel/FlasherNotyfServiceProvider.php +++ b/src/Notyf/Laravel/FlasherNotyfServiceProvider.php @@ -7,24 +7,8 @@ namespace Flasher\Notyf\Laravel; use Flasher\Laravel\Support\PluginServiceProvider; use Flasher\Notyf\Prime\NotyfPlugin; -/** - * FlasherNotyfServiceProvider - Laravel service provider for Notyf integration. - * - * This service provider registers the Notyf plugin with Laravel's service container. - * It extends the base plugin service provider to inherit common registration logic - * while providing the Notyf-specific plugin implementation. - * - * Design patterns: - * - Service Provider: Implements Laravel's service provider pattern - * - Factory Method: Creates the plugin instance - */ final class FlasherNotyfServiceProvider extends PluginServiceProvider { - /** - * Creates the Notyf plugin instance. - * - * @return NotyfPlugin The Notyf plugin instance - */ public function createPlugin(): NotyfPlugin { return new NotyfPlugin(); diff --git a/src/Notyf/Prime/Notyf.php b/src/Notyf/Prime/Notyf.php index a3375ff5..66d5faf7 100644 --- a/src/Notyf/Prime/Notyf.php +++ b/src/Notyf/Prime/Notyf.php @@ -7,28 +7,10 @@ namespace Flasher\Notyf\Prime; use Flasher\Prime\Factory\NotificationFactory; /** - * Notyf - Factory implementation for Notyf.js notifications. - * - * This class implements the notification factory for Notyf.js, creating - * specialized notification builders configured for Notyf's specific features. - * It serves as the primary entry point for creating Notyf notifications. - * - * Design patterns: - * - Factory: Creates specialized notification builders - * - Bridge: Connects PHPFlasher's notification system to Notyf.js - * - Composition: Delegates to NotyfBuilder for construction details - * * @mixin \Flasher\Notyf\Prime\NotyfBuilder */ final class Notyf extends NotificationFactory implements NotyfInterface { - /** - * {@inheritdoc} - * - * Creates a new Notyf-specific notification builder. - * - * @return NotyfBuilder A builder configured for Notyf.js notifications - */ public function createNotificationBuilder(): NotyfBuilder { return new NotyfBuilder('notyf', $this->storageManager); diff --git a/src/Notyf/Prime/NotyfBuilder.php b/src/Notyf/Prime/NotyfBuilder.php index 46f23f2a..7e7f1b1d 100644 --- a/src/Notyf/Prime/NotyfBuilder.php +++ b/src/Notyf/Prime/NotyfBuilder.php @@ -7,18 +7,6 @@ namespace Flasher\Notyf\Prime; use Flasher\Prime\Notification\NotificationBuilder; /** - * NotyfBuilder - Builder implementation for Notyf.js notifications. - * - * This class provides a fluent interface for configuring Notyf.js notifications. - * It extends the core notification builder with Notyf-specific options and - * features, focusing on Notyf's minimalist approach with fewer options than other - * notification libraries. - * - * Design patterns: - * - Builder: Provides a fluent interface for constructing complex objects - * - Fluent Interface: Methods return $this for method chaining - * - Type Safety: Uses PHPStan annotations for compile-time type checking - * * @phpstan-type NotificationType "success"|"info"|"warning"|"error" * @phpstan-type OptionsType array{ * duration?: int, @@ -33,15 +21,6 @@ use Flasher\Prime\Notification\NotificationBuilder; */ final class NotyfBuilder extends NotificationBuilder { - /** - * Sets the notification display duration. - * - * Number of milliseconds before hiding the notification. Use 0 for infinite duration. - * - * @param int $duration Duration in milliseconds - * - * @return self The builder instance - */ public function duration(int $duration): self { $this->option('duration', $duration); @@ -49,13 +28,6 @@ final class NotyfBuilder extends NotificationBuilder return $this; } - /** - * Sets whether to show the notification with a ripple effect. - * - * @param bool $ripple Whether to enable ripple effect - * - * @return self The builder instance - */ public function ripple(bool $ripple = true): self { $this->option('ripple', $ripple); @@ -64,18 +36,7 @@ final class NotyfBuilder extends NotificationBuilder } /** - * Sets the notification position in the viewport. - * - * Viewport location where notifications are rendered. - * - * @param "x"|"y" $position Specifies the axis: 'x' for horizontal, 'y' for vertical - * @param "left"|"center"|"right"|"top"|"bottom" $value Position value, dependent on the axis: - * - If $position is 'x', $value must be 'left', 'center' or 'right' - * - If $position is 'y', $value must be 'top', 'center' or 'bottom' - * * @phpstan-param ($position is 'x' ? "left"|"center"|"right" : "top"|"center"|"bottom") $value - * - * @return self The builder instance */ public function position(string $position, string $value): self { @@ -87,15 +48,6 @@ final class NotyfBuilder extends NotificationBuilder return $this; } - /** - * Sets whether to allow users to dismiss the notification. - * - * Whether to allow users to dismiss the notification with a button. - * - * @param bool $dismissible Whether to make the notification dismissible - * - * @return self The builder instance - */ public function dismissible(bool $dismissible): self { $this->option('dismissible', $dismissible); @@ -103,13 +55,6 @@ final class NotyfBuilder extends NotificationBuilder return $this; } - /** - * Sets the background color of the notification. - * - * @param string $background CSS color value for the notification background - * - * @return self The builder instance - */ public function background(string $background): self { $this->option('background', $background); diff --git a/src/Notyf/Prime/NotyfInterface.php b/src/Notyf/Prime/NotyfInterface.php index 73829ca7..b638e7d4 100644 --- a/src/Notyf/Prime/NotyfInterface.php +++ b/src/Notyf/Prime/NotyfInterface.php @@ -7,17 +7,6 @@ namespace Flasher\Notyf\Prime; use Flasher\Prime\Factory\NotificationFactoryInterface; /** - * NotyfInterface - Contract for Notyf notification factories. - * - * This interface defines the contract for Notyf notification factories. - * It extends the core notification factory interface to ensure compatibility - * with PHPFlasher's notification system, while allowing IDE completion for - * Notyf-specific methods through the mixin annotation. - * - * Design patterns: - * - Interface Segregation: Provides a specific interface for Notyf functionality - * - Contract: Defines a contract for creating Notyf notifications - * * @mixin \Flasher\Notyf\Prime\NotyfBuilder */ interface NotyfInterface extends NotificationFactoryInterface diff --git a/src/Notyf/Prime/NotyfPlugin.php b/src/Notyf/Prime/NotyfPlugin.php index 042e991c..1e8e8c3e 100644 --- a/src/Notyf/Prime/NotyfPlugin.php +++ b/src/Notyf/Prime/NotyfPlugin.php @@ -6,57 +6,25 @@ namespace Flasher\Notyf\Prime; use Flasher\Prime\Plugin\Plugin; -/** - * NotyfPlugin - Plugin definition for Notyf.js integration with PHPFlasher. - * - * This class defines the core plugin configuration for the Notyf.js notification - * library integration. It specifies the required JavaScript and CSS assets, - * factory class, and service identifiers for dependency injection containers. - * - * Design patterns: - * - Plugin: Implements the plugin pattern for extending core functionality - * - Registry: Registers the plugin's assets and identifiers with the core system - * - Metadata: Provides metadata about the plugin's requirements - */ final class NotyfPlugin extends Plugin { - /** - * {@inheritdoc} - * - * Returns the plugin's unique identifier. - */ public function getAlias(): string { return 'notyf'; } - /** - * {@inheritdoc} - * - * Returns the factory class responsible for creating Notyf notifications. - */ public function getFactory(): string { return Notyf::class; } - /** - * {@inheritdoc} - * - * Returns the service alias for dependency injection containers. - */ public function getServiceAliases(): string { return NotyfInterface::class; } /** - * {@inheritdoc} - * - * Returns the required JavaScript files for Notyf.js integration. - * Compared to other libraries, Notyf has a minimal footprint with just one script. - * - * @return string[] Array of script paths + * @return string[] */ public function getScripts(): array { @@ -66,12 +34,7 @@ final class NotyfPlugin extends Plugin } /** - * {@inheritdoc} - * - * Returns the required CSS files for Notyf.js styling. - * Notyf has a minimal footprint with just one stylesheet. - * - * @return string[] Array of stylesheet paths + * @return string[] */ public function getStyles(): array { diff --git a/src/Notyf/Prime/functions.php b/src/Notyf/Prime/functions.php index 2d5d06d0..3f944df6 100644 --- a/src/Notyf/Prime/functions.php +++ b/src/Notyf/Prime/functions.php @@ -8,25 +8,8 @@ use Flasher\Prime\Container\FlasherContainer; use Flasher\Prime\Notification\Envelope; use Flasher\Prime\Notification\Type; -/* - * Namespace-specific helper functions for Notyf notifications. - * - * This file provides a namespace-specific helper function that simplifies - * the creation of Notyf notifications from code that uses imports. - * - * Design pattern: Facade - Provides a simplified interface to a complex subsystem - */ - if (!\function_exists('Flasher\Notyf\Prime\notyf')) { /** - * Creates a Notyf notification or returns the Notyf factory. - * - * This function simplifies the process of creating Notyf notifications. - * When called with no arguments, it returns an instance of NotyfInterface. - * When called with arguments, it creates a Notyf notification and returns an Envelope. - * - * @param string|null $message the message content of the notification - * @param "success"|"info"|"warning"|"error" $type The type of the notification (e.g., success, error, warning, info). * @param array{ * duration?: int, * ripple?: bool, @@ -36,18 +19,9 @@ if (!\function_exists('Flasher\Notyf\Prime\notyf')) { * }, * dismissible?: bool, * background?: string, - * } $options additional options for the Notyf notification - * @param string|null $title the title of the notification - * - * @return Envelope|NotyfInterface Returns an Envelope containing the notification details when arguments are provided. - * Returns an instance of NotyfInterface when no arguments are provided. + * } $options * * @phpstan-return ($message is empty ? NotyfInterface : Envelope) - * - * Usage: - * 1. Without arguments - Get the Notyf factory: $notyf = notyf(); - * 2. With arguments - Create and return a Notyf notification: - * notyf('Message', Type::SUCCESS, ['option' => 'value'], 'Title'); */ function notyf(?string $message = null, string $type = Type::SUCCESS, array $options = [], ?string $title = null): Envelope|NotyfInterface { diff --git a/src/Notyf/Prime/helpers.php b/src/Notyf/Prime/helpers.php index e3af9a19..456a6331 100644 --- a/src/Notyf/Prime/helpers.php +++ b/src/Notyf/Prime/helpers.php @@ -7,25 +7,8 @@ use Flasher\Prime\Container\FlasherContainer; use Flasher\Prime\Notification\Envelope; use Flasher\Prime\Notification\Type; -/* - * Global helper functions for Notyf notifications. - * - * This file provides a global helper function that simplifies - * the creation of Notyf notifications from any PHP code. - * - * Design pattern: Facade - Provides a simplified interface to a complex subsystem - */ - if (!function_exists('notyf')) { /** - * Creates a Notyf notification or returns the Notyf factory. - * - * This function simplifies the process of creating Notyf notifications. - * When called with no arguments, it returns an instance of NotyfInterface. - * When called with arguments, it creates a Notyf notification and returns an Envelope. - * - * @param string|null $message the message content of the notification - * @param "success"|"info"|"warning"|"error" $type The type of the notification (e.g., success, error, warning, info). * @param array{ * duration?: int, * ripple?: bool, @@ -35,18 +18,9 @@ if (!function_exists('notyf')) { * }, * dismissible?: bool, * background?: string, - * } $options additional options for the Notyf notification - * @param string|null $title the title of the notification - * - * @return Envelope|NotyfInterface Returns an Envelope containing the notification details when arguments are provided. - * Returns an instance of NotyfInterface when no arguments are provided. + * } $options * * @phpstan-return ($message is empty ? NotyfInterface : Envelope) - * - * Usage: - * 1. Without arguments - Get the Notyf factory: $notyf = notyf(); - * 2. With arguments - Create and return a Notyf notification: - * notyf('Message', Type::SUCCESS, ['option' => 'value'], 'Title'); */ function notyf(?string $message = null, string $type = Type::SUCCESS, array $options = [], ?string $title = null): Envelope|NotyfInterface { diff --git a/src/Notyf/Symfony/FlasherNotyfSymfonyBundle.php b/src/Notyf/Symfony/FlasherNotyfSymfonyBundle.php index 3f0b19e3..549ffff0 100644 --- a/src/Notyf/Symfony/FlasherNotyfSymfonyBundle.php +++ b/src/Notyf/Symfony/FlasherNotyfSymfonyBundle.php @@ -8,24 +8,8 @@ use Flasher\Notyf\Prime\NotyfPlugin; use Flasher\Prime\Plugin\PluginInterface; use Flasher\Symfony\Support\PluginBundle; -/** - * FlasherNotyfSymfonyBundle - Symfony bundle for Notyf integration. - * - * This bundle registers the Notyf plugin with Symfony's service container. - * It extends the base plugin bundle to inherit common registration logic - * while providing the Notyf-specific plugin implementation. - * - * Design patterns: - * - Bundle: Implements Symfony's bundle pattern for packaging functionality - * - Factory Method: Creates the plugin instance - */ final class FlasherNotyfSymfonyBundle extends PluginBundle // Symfony\Component\HttpKernel\Bundle\Bundle { - /** - * Creates the Notyf plugin instance. - * - * @return PluginInterface The Notyf plugin instance - */ public function createPlugin(): PluginInterface { return new NotyfPlugin();