Simplify PHPDoc comments in Noty integration

Remove verbose documentation pattern references and redundant explanations, keeping only essential type annotations.
2026-03-31 15:07:47 +01:00 · 2026-01-15 22:35:01 +01:00
parent 21348f384d
commit 611fda9c61
9 changed files with 24 additions and 407 deletions
@@ -10,29 +10,6 @@ use Flasher\Prime\Stamp\StampInterface;
 use Illuminate\Support\Facades\Facade;

 /**
- * Noty - Laravel facade for Noty notifications.
- *
- * This facade provides a static interface to Noty's functionality within Laravel,
- * following Laravel's facade pattern. It offers comprehensive IDE autocompletion
- * for all Noty builder methods.
- *
- * Design patterns:
- * - Facade: Provides a simplified, static interface to a complex subsystem
- * - Proxy: Acts as a proxy to the underlying Noty service
- *
- * Usage examples:
- * ```php
- * // Simple notification
- * Noty::success('Operation completed successfully');
- *
- * // Chained configuration
- * Noty::layout('topRight')
- *     ->theme('mint')
- *     ->timeout(5000)
- *     ->progressBar(true)
- *     ->success('Record saved');
- * ```
- *
 * @method static NotyBuilder success(string $message, array<string, mixed> $options = array())
 * @method static NotyBuilder error(string $message, array<string, mixed> $options = array())
 * @method static NotyBuilder warning(string $message, array<string, mixed> $options = array())
@@ -71,11 +48,6 @@ use Illuminate\Support\Facades\Facade;
 */
 final class Noty extends Facade
 {
-    /**
-     * Get the registered name of the component.
-     *
-     * @return string The service container binding key for Noty
-     */
    protected static function getFacadeAccessor(): string
    {
        return 'flasher.noty';
@@ -7,24 +7,8 @@ namespace Flasher\Noty\Laravel;
 use Flasher\Laravel\Support\PluginServiceProvider;
 use Flasher\Noty\Prime\NotyPlugin;

-/**
- * FlasherNotyServiceProvider - Laravel service provider for Noty integration.
- *
- * This service provider registers the Noty plugin with Laravel's service container.
- * It extends the base plugin service provider to inherit common registration logic
- * while providing the Noty-specific plugin implementation.
- *
- * Design patterns:
- * - Service Provider: Implements Laravel's service provider pattern
- * - Factory Method: Creates the plugin instance
- */
 final class FlasherNotyServiceProvider extends PluginServiceProvider
 {
-    /**
-     * Creates the Noty plugin instance.
-     *
-     * @return NotyPlugin The Noty plugin instance
-     */
    public function createPlugin(): NotyPlugin
    {
        return new NotyPlugin();
@@ -7,28 +7,10 @@ namespace Flasher\Noty\Prime;
 use Flasher\Prime\Factory\NotificationFactory;

 /**
- * Noty - Factory implementation for Noty.js notifications.
- *
- * This class implements the notification factory for Noty.js, creating
- * specialized notification builders configured for Noty's specific features.
- * It serves as the primary entry point for creating Noty notifications.
- *
- * Design patterns:
- * - Factory: Creates specialized notification builders
- * - Bridge: Connects PHPFlasher's notification system to Noty.js
- * - Composition: Delegates to NotyBuilder for construction details
- *
 * @mixin \Flasher\Noty\Prime\NotyBuilder
 */
 final class Noty extends NotificationFactory implements NotyInterface
 {
-    /**
-     * {@inheritdoc}
-     *
-     * Creates a new Noty-specific notification builder.
-     *
-     * @return NotyBuilder A builder configured for Noty.js notifications
-     */
    public function createNotificationBuilder(): NotyBuilder
    {
        return new NotyBuilder('noty', $this->storageManager);
@@ -8,17 +8,6 @@ use Flasher\Prime\Notification\Envelope;
 use Flasher\Prime\Notification\NotificationBuilder;

 /**
- * NotyBuilder - Builder implementation for Noty.js notifications.
- *
- * This class provides a fluent interface for configuring Noty.js notifications.
- * It extends the core notification builder with Noty-specific options and
- * features, such as layout, theme, animation, and more.
- *
- * 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"|"alert"|"information"
 * @phpstan-type OptionsType array{
 *     layout?: "top"|"topLeft"|"topCenter"|"topRight"|"center"|"centerLeft"|"centerRight"|"bottom"|"bottomLeft"|"bottomCenter"|"bottomRight",
@@ -51,11 +40,7 @@ use Flasher\Prime\Notification\NotificationBuilder;
 final class NotyBuilder extends NotificationBuilder
 {
    /**
-     * Sets the notification type with Noty-specific type checking.
-     *
-     * @phpstan-param NotificationType $type The notification type
-     *
-     * @return static The builder instance
+     * @phpstan-param NotificationType $type
     */
    public function type(string $type): static
    {
@@ -63,13 +48,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Creates a success notification with Noty-specific options.
-     *
-     * @param string      $message The notification message
-     * @param OptionsType $options Noty-specific options
-     * @param string|null $title   The notification title
-     *
-     * @return Envelope The notification envelope
+     * @param OptionsType $options
     */
    public function success(string $message, array $options = [], ?string $title = null): Envelope
    {
@@ -77,13 +56,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Creates an error notification with Noty-specific options.
-     *
-     * @param string      $message The notification message
-     * @param OptionsType $options Noty-specific options
-     * @param string|null $title   The notification title
-     *
-     * @return Envelope The notification envelope
+     * @param OptionsType $options
     */
    public function error(string $message, array $options = [], ?string $title = null): Envelope
    {
@@ -91,13 +64,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Creates an info notification with Noty-specific options.
-     *
-     * @param string      $message The notification message
-     * @param OptionsType $options Noty-specific options
-     * @param string|null $title   The notification title
-     *
-     * @return Envelope The notification envelope
+     * @param OptionsType $options
     */
    public function info(string $message, array $options = [], ?string $title = null): Envelope
    {
@@ -105,13 +72,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Creates a warning notification with Noty-specific options.
-     *
-     * @param string      $message The notification message
-     * @param OptionsType $options Noty-specific options
-     * @param string|null $title   The notification title
-     *
-     * @return Envelope The notification envelope
+     * @param OptionsType $options
     */
    public function warning(string $message, array $options = [], ?string $title = null): Envelope
    {
@@ -119,17 +80,8 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Creates a notification of the specified type with Noty-specific options.
-     *
-     * @param string|null $type    The notification type
-     * @param string|null $message The notification message
-     * @param array       $options Noty-specific options
-     * @param string|null $title   The notification title
-     *
-     * @phpstan-param NotificationType|null $type    The notification type
-     * @phpstan-param OptionsType           $options Noty-specific options
-     *
-     * @return Envelope The notification envelope
+     * @phpstan-param NotificationType|null $type
+     * @phpstan-param OptionsType           $options
     */
    public function flash(?string $type = null, ?string $message = null, array $options = [], ?string $title = null): Envelope
    {
@@ -137,12 +89,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets notification options with Noty-specific type checking.
-     *
-     * @param OptionsType $options The notification options
-     * @param bool        $append  Whether to append or replace existing options
-     *
-     * @return static The builder instance
+     * @param OptionsType $options
     */
    public function options(array $options, bool $append = true): static
    {
@@ -150,46 +97,24 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets a specific notification option with Noty-specific type checking.
-     *
     * @template T of OptionsType
     * @template K of key-of<T>
     *
-     * @param string $name  The option name
-     * @param mixed  $value The option value
-     *
     * @phpstan-param K $name
     * @phpstan-param T[K] $value
-     *
-     * @return static The builder instance
     */
    public function option(string $name, mixed $value): static
    {
        return parent::option($name, $value);
    }

-    /**
-     * Sets the notification text (alias for message).
-     *
-     * This string can contain HTML too. But be careful and don't pass user inputs to this parameter.
-     *
-     * @param string $text The notification text
-     *
-     * @return self The builder instance
-     */
    public function text(string $text): self
    {
        return $this->message($text);
    }

    /**
-     * Creates an alert notification.
-     *
-     * @param string|null $message The notification message
-     * @param string|null $title   The notification title
-     * @param OptionsType $options Noty-specific options
-     *
-     * @return self The builder instance
+     * @param OptionsType $options
     */
    public function alert(?string $message = null, ?string $title = null, array $options = []): self
    {
@@ -211,15 +136,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets the notification layout.
-     *
-     * @param string $layout The layout position
-     *
-     * @phpstan-param OptionsType['layout'] $layout The layout position
-     *
-     * - ClassName generator uses this value → noty_layout__${layout}
-     *
-     * @return self The builder instance
+     * @phpstan-param OptionsType['layout'] $layout
     */
    public function layout(string $layout): self
    {
@@ -229,15 +146,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets the notification theme.
-     *
-     * @param string $theme The theme name
-     *
-     * @phpstan-param OptionsType['theme'] $theme The theme name
-     *
-     * ClassName generator uses this value → noty_theme__${theme}
-     *
-     * @return self The builder instance
+     * @phpstan-param OptionsType['theme'] $theme
     */
    public function theme(string $theme): self
    {
@@ -246,16 +155,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets the notification timeout.
-     *
-     * false, 1000, 3000, 3500, etc. Delay for closing event in milliseconds (ms).
-     * Set 'false' for sticky notifications.
-     *
-     * @param false|int $timeout The timeout in milliseconds or false for sticky
-     *
-     * @return self The builder instance
-     */
    public function timeout(false|int $timeout): self
    {
        $this->option('timeout', $timeout);
@@ -263,15 +162,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets whether to display a progress bar.
-     *
-     * true, false - Displays a progress bar if timeout is not false.
-     *
-     * @param bool $progressBar Whether to display a progress bar
-     *
-     * @return self The builder instance
-     */
    public function progressBar(bool $progressBar = false): self
    {
        $this->option('progressBar', $progressBar);
@@ -280,13 +170,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets how the notification can be closed.
-     *
-     * click, button.
-     *
-     * @param string|string[] $closeWith Close methods
-     *
-     * @return self The builder instance
+     * @param string[] $closeWith
     */
    public function closeWith(string|array $closeWith): self
    {
@@ -296,16 +180,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets animation effects for opening or closing.
-     *
-     * @param "open"|"close"                                  $option Which animation to set
-     * @param "noty_effects_open"|"noty_effects_close"|string $effect The animation effect
-     *
-     * If string, assumed to be CSS class name. If null, no animation at all.
-     * If function, runs the function. (v3.0.1+)
-     * You can use animate.css class names or your custom css animations as well.
-     *
-     * @return self The builder instance
+     * @param "open"|"close" $option
     */
    public function animation(string $option, string $effect): self
    {
@@ -319,18 +194,11 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets sound options for the notification.
-     *
-     * @param string $option The sound option to set
-     * @param mixed  $value  The option value
-     *
-     * @phpstan-param "sources"|"volume"|"conditions" $option The sound option to set
+     * @phpstan-param "sources"|"volume"|"conditions" $option
     * @phpstan-param ($option is "sources" ? string[] :
     *        ($option is "volume" ? int :
     *        ($option is "conditions" ? string[] :
-     *        mixed))) $value The option value
-     *
-     * @return self The builder instance
+     *        mixed))) $value
     */
    public function sounds(string $option, mixed $value): self
    {
@@ -344,15 +212,8 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets document title options for the notification.
-     *
-     * @param string $option The document title option
-     * @param mixed  $value  The option value
-     *
-     * @phpstan-param "conditions"|string $option The document title option
-     * @phpstan-param ($option is "conditions" ? string[] : mixed) $value The option value
-     *
-     * @return self The builder instance
+     * @phpstan-param "conditions"|string $option
+     * @phpstan-param ($option is "conditions" ? string[] : mixed) $value
     */
    public function docTitle(string $option, mixed $value): self
    {
@@ -365,13 +226,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets whether the notification is modal.
-     *
-     * @param bool $modal Whether the notification is modal
-     *
-     * @return self The builder instance
-     */
    public function modal(bool $modal = true): self
    {
        $this->option('modal', $modal);
@@ -379,15 +233,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets the notification ID.
-     *
-     * You can use this id with querySelectors. Generated automatically if false.
-     *
-     * @param bool|string $id The notification ID or false to generate automatically
-     *
-     * @return self The builder instance
-     */
    public function id(bool|string $id): self
    {
        $this->option('id', $id);
@@ -395,15 +240,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets whether to force the notification.
-     *
-     * DOM insert method depends on this parameter. If false uses append, if true uses prepend.
-     *
-     * @param bool $force Whether to force the notification
-     *
-     * @return self The builder instance
-     */
    public function force(bool $force = true): self
    {
        $this->option('force', $force);
@@ -411,13 +247,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets the notification queue.
-     *
-     * @param string $queue The queue name
-     *
-     * @return self The builder instance
-     */
    public function queue(string $queue): self
    {
        $this->option('queue', $queue);
@@ -425,16 +254,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets whether the notification kills other notifications.
-     *
-     * If true closes all visible notifications and shows itself.
-     * If string(queueName) closes all visible notification on this queue and shows itself.
-     *
-     * @param bool|string $killer Whether to kill other notifications
-     *
-     * @return self The builder instance
-     */
    public function killer(bool|string $killer): self
    {
        $this->option('killer', $killer);
@@ -442,16 +261,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets the notification container.
-     *
-     * Custom container selector string. Like '.my-custom-container'.
-     * Layout parameter will be ignored.
-     *
-     * @param false|string $container The container selector or false to use default
-     *
-     * @return self The builder instance
-     */
    public function container(false|string $container): self
    {
        $this->option('container', $container);
@@ -460,13 +269,7 @@ final class NotyBuilder extends NotificationBuilder
    }

    /**
-     * Sets the notification buttons.
-     *
-     * An array of Noty.button, for creating confirmation dialogs.
-     *
-     * @param string[] $buttons The buttons configuration
-     *
-     * @return self The builder instance
+     * @param string[] $buttons
     */
    public function buttons(array $buttons): self
    {
@@ -475,16 +278,6 @@ final class NotyBuilder extends NotificationBuilder
        return $this;
    }

-    /**
-     * Sets whether to use visibility control.
-     *
-     * If true Noty uses PageVisibility API to handle timeout.
-     * To ensure that users do not miss their notifications.
-     *
-     * @param bool $visibilityControl Whether to use visibility control
-     *
-     * @return self The builder instance
-     */
    public function visibilityControl(bool $visibilityControl): self
    {
        $this->option('visibilityControl', $visibilityControl);
@@ -7,17 +7,6 @@ namespace Flasher\Noty\Prime;
 use Flasher\Prime\Factory\NotificationFactoryInterface;

 /**
- * NotyInterface - Contract for Noty notification factories.
- *
- * This interface defines the contract for Noty notification factories.
- * It extends the core notification factory interface to ensure compatibility
- * with PHPFlasher's notification system, while allowing IDE completion for
- * Noty-specific methods through the mixin annotation.
- *
- * Design patterns:
- * - Interface Segregation: Provides a specific interface for Noty functionality
- * - Contract: Defines a contract for creating Noty notifications
- *
 * @mixin \Flasher\Noty\Prime\NotyBuilder
 */
 interface NotyInterface extends NotificationFactoryInterface
@@ -6,56 +6,25 @@ namespace Flasher\Noty\Prime;

 use Flasher\Prime\Plugin\Plugin;

-/**
- * NotyPlugin - Plugin definition for Noty.js integration with PHPFlasher.
- *
- * This class defines the core plugin configuration for the Noty.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 NotyPlugin extends Plugin
 {
-    /**
-     * {@inheritdoc}
-     *
-     * Returns the plugin's unique identifier.
-     */
    public function getAlias(): string
    {
        return 'noty';
    }

-    /**
-     * {@inheritdoc}
-     *
-     * Returns the factory class responsible for creating Noty notifications.
-     */
    public function getFactory(): string
    {
        return Noty::class;
    }

-    /**
-     * {@inheritdoc}
-     *
-     * Returns the service alias for dependency injection containers.
-     */
    public function getServiceAliases(): string
    {
        return NotyInterface::class;
    }

    /**
-     * {@inheritdoc}
-     *
-     * Returns the required JavaScript files for Noty.js integration.
-     *
-     * @return string[] Array of script paths
+     * @return string[]
     */
    public function getScripts(): array
    {
@@ -66,11 +35,7 @@ final class NotyPlugin extends Plugin
    }

    /**
-     * {@inheritdoc}
-     *
-     * Returns the required CSS files for Noty.js styling.
-     *
-     * @return string[] Array of stylesheet paths
+     * @return string[]
     */
    public function getStyles(): array
    {
@@ -8,25 +8,8 @@ use Flasher\Prime\Container\FlasherContainer;
 use Flasher\Prime\Notification\Envelope;
 use Flasher\Prime\Notification\Type;

-/*
- * Namespace-specific helper functions for Noty notifications.
- *
- * This file provides a namespace-specific helper function that simplifies
- * the creation of Noty notifications from code that uses imports.
- *
- * Design pattern: Facade - Provides a simplified interface to a complex subsystem
- */
-
 if (!\function_exists('Flasher\Noty\Prime\noty')) {
    /**
-     * Creates a Noty notification or returns the Noty factory.
-     *
-     * This function simplifies the process of creating Noty notifications.
-     * When called with no arguments, it returns an instance of NotyInterface.
-     * When called with arguments, it creates a Noty notification and returns an Envelope.
-     *
-     * @param string|null                                              $message the message content of the notification
-     * @param "success"|"info"|"warning"|"error"|"alert"|"information" $type    The type of the notification (e.g., success, error, warning, info).
     * @param array{
     *     layout?: "top"|"topLeft"|"topCenter"|"topRight"|"center"|"centerLeft"|"centerRight"|"bottom"|"bottomLeft"|"bottomCenter"|"bottomRight",
     *     theme?: "relax"|"mint"|"metroui",
@@ -53,18 +36,9 @@ if (!\function_exists('Flasher\Noty\Prime\noty')) {
     *     container?: false|string,
     *     buttons?: string[],
     *     visibilityControl?: bool,
-     * } $options additional options for the Noty notification
-     * @param string|null $title the title of the notification
-     *
-     * @return Envelope|NotyInterface Returns an Envelope containing the notification details when arguments are provided.
-     *                                Returns an instance of NotyInterface when no arguments are provided.
+     * } $options
     *
     * @phpstan-return ($message is empty ? NotyInterface : Envelope)
-     *
-     * Usage:
-     * 1. Without arguments - Get the Noty factory: $noty = noty();
-     * 2. With arguments - Create and return a Noty notification:
-     *    noty('Message', Type::SUCCESS, ['option' => 'value'], 'Title');
     */
    function noty(?string $message = null, string $type = Type::SUCCESS, array $options = [], ?string $title = null): Envelope|NotyInterface
    {
@@ -74,6 +48,6 @@ if (!\function_exists('Flasher\Noty\Prime\noty')) {
            return $factory;
        }

-        return $factory->flash($type, $message, $options, $title);
+        return $factory->flash($type, $message, $options, $title); // @phpstan-ignore-line
    }
 }
@@ -7,25 +7,8 @@ use Flasher\Prime\Container\FlasherContainer;
 use Flasher\Prime\Notification\Envelope;
 use Flasher\Prime\Notification\Type;

-/*
- * Global helper functions for Noty notifications.
- *
- * This file provides a global helper function that simplifies
- * the creation of Noty notifications from any PHP code.
- *
- * Design pattern: Facade - Provides a simplified interface to a complex subsystem
- */
-
 if (!function_exists('noty')) {
    /**
-     * Creates a Noty notification or returns the Noty factory.
-     *
-     * This function simplifies the process of creating Noty notifications.
-     * When called with no arguments, it returns an instance of NotyInterface.
-     * When called with arguments, it creates a Noty notification and returns an Envelope.
-     *
-     * @param string|null                                              $message the message content of the notification
-     * @param "success"|"info"|"warning"|"error"|"alert"|"information" $type    The type of the notification (e.g., success, error, warning, info).
     * @param array{
     *     layout?: "top"|"topLeft"|"topCenter"|"topRight"|"center"|"centerLeft"|"centerRight"|"bottom"|"bottomLeft"|"bottomCenter"|"bottomRight",
     *     theme?: "relax"|"mint"|"metroui",
@@ -52,18 +35,9 @@ if (!function_exists('noty')) {
     *     container?: false|string,
     *     buttons?: string[],
     *     visibilityControl?: bool,
-     * } $options additional options for the Noty notification
-     * @param string|null $title the title of the notification
-     *
-     * @return Envelope|NotyInterface Returns an Envelope containing the notification details when arguments are provided.
-     *                                Returns an instance of NotyInterface when no arguments are provided.
+     * } $options
     *
     * @phpstan-return ($message is empty ? NotyInterface : Envelope)
-     *
-     * Usage:
-     * 1. Without arguments - Get the Noty factory: $noty = noty();
-     * 2. With arguments - Create and return a Noty notification:
-     *    noty('Message', Type::SUCCESS, ['option' => 'value'], 'Title');
     */
    function noty(?string $message = null, string $type = Type::SUCCESS, array $options = [], ?string $title = null): Envelope|NotyInterface
    {
@@ -73,6 +47,6 @@ if (!function_exists('noty')) {
            return $factory;
        }

-        return $factory->flash($type, $message, $options, $title);
+        return $factory->flash($type, $message, $options, $title); // @phpstan-ignore-line
    }
 }
@@ -8,24 +8,8 @@ use Flasher\Noty\Prime\NotyPlugin;
 use Flasher\Prime\Plugin\PluginInterface;
 use Flasher\Symfony\Support\PluginBundle;

-/**
- * FlasherNotySymfonyBundle - Symfony bundle for Noty integration.
- *
- * This bundle registers the Noty plugin with Symfony's service container.
- * It extends the base plugin bundle to inherit common registration logic
- * while providing the Noty-specific plugin implementation.
- *
- * Design patterns:
- * - Bundle: Implements Symfony's bundle pattern for packaging functionality
- * - Factory Method: Creates the plugin instance
- */
 final class FlasherNotySymfonyBundle extends PluginBundle // Symfony\Component\HttpKernel\Bundle\Bundle
 {
-    /**
-     * Creates the Noty plugin instance.
-     *
-     * @return PluginInterface The Noty plugin instance
-     */
    public function createPlugin(): PluginInterface
    {
        return new NotyPlugin();