From 548044bd7f3c0745137317721fa93e9bb800756d Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Fri, 16 Jan 2026 00:17:52 +0100 Subject: [PATCH] Simplify PHPDoc comments in Notification builder classes Removes verbose documentation while preserving type annotations for array parameters. --- .../NotificationBuilderMethods.php | 150 +----------------- .../NotificationMethodAliases.php | 92 +---------- 2 files changed, 10 insertions(+), 232 deletions(-) diff --git a/src/Prime/Notification/NotificationBuilderMethods.php b/src/Prime/Notification/NotificationBuilderMethods.php index 97955c8a..9da666f5 100644 --- a/src/Prime/Notification/NotificationBuilderMethods.php +++ b/src/Prime/Notification/NotificationBuilderMethods.php @@ -14,26 +14,10 @@ use Flasher\Prime\Stamp\TranslationStamp; use Flasher\Prime\Stamp\UnlessStamp; use Flasher\Prime\Stamp\WhenStamp; -/** - * Core notification builder methods. - * - * This trait implements the core builder methods for configuring notifications. - * It provides the fluent API for setting notification properties and attaching stamps. - */ trait NotificationBuilderMethods { - /** - * The notification envelope being built. - */ protected readonly Envelope $envelope; - /** - * Sets the notification title. - * - * @param string $title The title to set - * - * @return static The builder instance for method chaining - */ public function title(string $title): static { $this->envelope->setTitle($title); @@ -41,13 +25,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Sets the notification message. - * - * @param string $message The message to set - * - * @return static The builder instance for method chaining - */ public function message(string $message): static { $this->envelope->setMessage($message); @@ -55,13 +32,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Sets the notification type. - * - * @param string $type The type to set (e.g., "success", "error", "info", "warning") - * - * @return static The builder instance for method chaining - */ public function type(string $type): static { $this->envelope->setType($type); @@ -70,12 +40,7 @@ trait NotificationBuilderMethods } /** - * Sets multiple options for the notification. - * - * @param array $options The options to set - * @param bool $append Whether to merge with existing options (true) or replace them (false) - * - * @return static The builder instance for method chaining + * @param array $options */ public function options(array $options, bool $append = true): static { @@ -88,14 +53,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Sets a single option for the notification. - * - * @param string $name The option name - * @param mixed $value The option value - * - * @return static The builder instance for method chaining - */ public function option(string $name, mixed $value): static { $this->envelope->setOption($name, $value); @@ -103,15 +60,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Sets the notification priority. - * - * Higher priority notifications are typically displayed before lower priority ones. - * - * @param int $priority The priority value (higher values indicate higher priority) - * - * @return static The builder instance for method chaining - */ public function priority(int $priority): static { $this->envelope->withStamp(new PriorityStamp($priority)); @@ -119,15 +67,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Increases the number of request hops the notification will persist. - * - * This method is useful for keeping a notification across multiple redirects. - * It increments the current hop count by 1, ensuring the notification persists - * for one additional request. - * - * @return static The builder instance for method chaining - */ public function keep(): static { $stamp = $this->envelope->get(HopsStamp::class); @@ -136,17 +75,6 @@ trait NotificationBuilderMethods return $this->hops(1 + $amount); } - /** - * Sets the exact number of request hops the notification will persist. - * - * This determines how many redirects/page loads a notification will survive. - * For example, a value of 2 means the notification will be shown on the current - * request and the next request, then be removed. - * - * @param int $amount The number of hops to keep the notification - * - * @return static The builder instance for method chaining - */ public function hops(int $amount): static { $this->envelope->withStamp(new HopsStamp($amount)); @@ -154,13 +82,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Sets a delay before showing the notification. - * - * @param int $delay The delay in milliseconds - * - * @return static The builder instance for method chaining - */ public function delay(int $delay): static { $this->envelope->withStamp(new DelayStamp($delay)); @@ -169,15 +90,7 @@ trait NotificationBuilderMethods } /** - * Configures translation parameters for the notification. - * - * This allows the message and title to be translated according to the current locale. - * Parameters can be used for variable substitution in translation strings. - * - * @param array $parameters Translation parameters - * @param string|null $locale Specific locale to use, or null for default - * - * @return static The builder instance for method chaining + * @param array $parameters */ public function translate(array $parameters = [], ?string $locale = null): static { @@ -186,16 +99,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Sets the handler (plugin) that should process the notification. - * - * This specifies which adapter (e.g., 'toastr', 'sweetalert') should be used - * to render the notification. - * - * @param string $handler The handler/plugin name - * - * @return static The builder instance for method chaining - */ public function handler(string $handler): static { $this->envelope->withStamp(new PluginStamp($handler)); @@ -204,14 +107,7 @@ trait NotificationBuilderMethods } /** - * Sets additional context data for the notification. - * - * Context data can be used for customizing the rendering of notifications - * or providing additional information to handlers. - * - * @param array $context The context data - * - * @return static The builder instance for method chaining + * @param array $context */ public function context(array $context): static { @@ -220,15 +116,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Adds a condition that must be true for the notification to be displayed. - * - * When multiple when() conditions are used, all must be true (AND logic). - * - * @param bool|\Closure $condition A boolean or closure returning a boolean - * - * @return static The builder instance for method chaining - */ public function when(bool|\Closure $condition): static { $condition = $this->validateCallableCondition($condition); @@ -243,15 +130,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Adds a condition that must be false for the notification to be displayed. - * - * When multiple unless() conditions are used, all must be false (OR logic for the negation). - * - * @param bool|\Closure $condition A boolean or closure returning a boolean - * - * @return static The builder instance for method chaining - */ public function unless(bool|\Closure $condition): static { $condition = $this->validateCallableCondition($condition); @@ -266,13 +144,6 @@ trait NotificationBuilderMethods return $this; } - /** - * Adds one or more stamps to the notification envelope. - * - * @param StampInterface[]|StampInterface $stamps The stamps to add - * - * @return static The builder instance for method chaining - */ public function with(array|StampInterface $stamps): static { if ($stamps instanceof StampInterface) { @@ -284,26 +155,13 @@ trait NotificationBuilderMethods return $this; } - /** - * Gets the current notification envelope. - * - * @return Envelope The notification envelope - */ public function getEnvelope(): Envelope { return $this->envelope; } /** - * Validates that a condition is either a boolean or a closure returning a boolean. - * - * If the condition is a closure, it is evaluated with the current envelope as parameter. - * - * @param bool|\Closure $condition The condition to validate - * - * @return bool The evaluated boolean condition - * - * @throws \InvalidArgumentException If the condition is not a boolean or doesn't return a boolean + * @throws \InvalidArgumentException */ protected function validateCallableCondition(bool|\Closure $condition): bool { diff --git a/src/Prime/Notification/NotificationMethodAliases.php b/src/Prime/Notification/NotificationMethodAliases.php index d8df0405..df273625 100644 --- a/src/Prime/Notification/NotificationMethodAliases.php +++ b/src/Prime/Notification/NotificationMethodAliases.php @@ -4,24 +4,10 @@ declare(strict_types=1); namespace Flasher\Prime\Notification; -/** - * Provides alternative method names for notification creation. - * - * This trait implements aliases for the standard notification methods, offering - * alternative naming conventions with 'add' prefix. These aliases improve API - * usability by providing familiar method names for developers coming from different - * frameworks. - */ trait NotificationMethodAliases { /** - * Alias for success() method. - * - * @param string $message The notification message - * @param array $options Optional configuration for the notification - * @param string|null $title Optional title for the notification - * - * @return Envelope The created notification envelope + * @param array $options */ public function addSuccess(string $message, array $options = [], ?string $title = null): Envelope { @@ -29,13 +15,7 @@ trait NotificationMethodAliases } /** - * Alias for error() method. - * - * @param string $message The notification message - * @param array $options Optional configuration for the notification - * @param string|null $title Optional title for the notification - * - * @return Envelope The created notification envelope + * @param array $options */ public function addError(string $message, array $options = [], ?string $title = null): Envelope { @@ -43,13 +23,7 @@ trait NotificationMethodAliases } /** - * Alias for info() method. - * - * @param string $message The notification message - * @param array $options Optional configuration for the notification - * @param string|null $title Optional title for the notification - * - * @return Envelope The created notification envelope + * @param array $options */ public function addInfo(string $message, array $options = [], ?string $title = null): Envelope { @@ -57,13 +31,7 @@ trait NotificationMethodAliases } /** - * Alias for warning() method. - * - * @param string $message The notification message - * @param array $options Optional configuration for the notification - * @param string|null $title Optional title for the notification - * - * @return Envelope The created notification envelope + * @param array $options */ public function addWarning(string $message, array $options = [], ?string $title = null): Envelope { @@ -71,14 +39,7 @@ trait NotificationMethodAliases } /** - * Alias for flash() method. - * - * @param string|null $type The notification type - * @param string|null $message The notification message - * @param array $options Optional configuration for the notification - * @param string|null $title Optional title for the notification - * - * @return Envelope The created notification envelope + * @param array $options */ public function addFlash(?string $type = null, ?string $message = null, array $options = [], ?string $title = null): Envelope { @@ -86,74 +47,33 @@ trait NotificationMethodAliases } /** - * Alias for preset() method. - * - * @param string $preset The preset name - * @param array $parameters Template parameters - * - * @return Envelope The created notification envelope + * @param array $parameters */ public function addPreset(string $preset, array $parameters = []): Envelope { return $this->preset($preset, $parameters); } - /** - * Alias for created() method. - * - * @param string|object|null $resource The resource that was created - * - * @return Envelope The created notification envelope - */ public function addCreated(string|object|null $resource = null): Envelope { return $this->created($resource); } - /** - * Alias for updated() method. - * - * @param string|object|null $resource The resource that was updated - * - * @return Envelope The created notification envelope - */ public function addUpdated(string|object|null $resource = null): Envelope { return $this->updated($resource); } - /** - * Alias for saved() method. - * - * @param string|object|null $resource The resource that was saved - * - * @return Envelope The created notification envelope - */ public function addSaved(string|object|null $resource = null): Envelope { return $this->saved($resource); } - /** - * Alias for deleted() method. - * - * @param string|object|null $resource The resource that was deleted - * - * @return Envelope The created notification envelope - */ public function addDeleted(string|object|null $resource = null): Envelope { return $this->deleted($resource); } - /** - * Alias for operation() method. - * - * @param string $operation The operation name - * @param string|object|null $resource The resource that was operated on - * - * @return Envelope The created notification envelope - */ public function addOperation(string $operation, string|object|null $resource = null): Envelope { return $this->operation($operation, $resource);