docs: enhance code documentation with comprehensive PHPDoc comments

Author: yoeunes

.github/FUNDING.yml

@@ -1,2 +1 @@
 github: yoeunes
-custom: https://www.paypal.com/paypalme/yoeunes

.phpstorm.meta.php

@@ -1,13 +1,36 @@
 <?php
 
+/**
+ * PhpStorm Meta File - IDE Enhancement for PHPFlasher.
+ *
+ * This file provides PhpStorm with additional type information and method completion
+ * capabilities for the PHPFlasher library. It's not loaded during runtime but is used
+ * exclusively by the IDE to improve developer experience.
+ *
+ * The file enhances code intelligence in several ways:
+ * 1. Adds type inference for Envelope::get() method
+ * 2. Provides completion for factory methods in FlasherInterface
+ * 3. Registers expected argument sets for notification types
+ * 4. Defines expected arguments for various builder methods
+ *
+ * Design patterns:
+ * - Metadata: Provides additional information about code that's only used by tools
+ * - IDE Integration: Bridges the gap between dynamic PHP code and static analysis tools
+ *
+ * Note: This file is part of the development tooling and has no effect on runtime behavior.
+ */
+
 namespace PHPSTORM_META;
 
+// Infer the correct type when Envelope::get() is called with a class name
 override(Envelope::get(0), type(0));
 
+// Map factory methods to their return types for better autocompletion
 override(\Flasher\Prime\FlasherInterface::create(), map(['flasher' => \Flasher\Prime\Factory\FlasherFactory::class, 'theme.' => \Flasher\Prime\Factory\FlasherFactory::class]));
 override(\Flasher\Prime\Container\FlasherContainer::create(), map(['flasher' => \Flasher\Prime\Factory\FlasherFactory::class, 'theme.' => \Flasher\Prime\Factory\FlasherFactory::class]));
 override(\Flasher\Prime\FlasherInterface::use(), map(['flasher' => \Flasher\Prime\Factory\FlasherFactory::class, 'theme.' => \Flasher\Prime\Factory\FlasherFactory::class]));
 
+// Register and utilize notification type constants for better code completion
 registerArgumentsSet('types', 'success', 'error', 'warning', 'info');
 expectedArguments(\Flasher\Prime\Notification\NotificationBuilderInterface::type(), 0, argumentsSet('types'));
 expectedArguments(\Flasher\Prime\Notification\NotificationBuilderInterface::addFlash(), 0, argumentsSet('types'));
@@ -17,7 +40,11 @@
 expectedArguments(\Flasher\Prime\flash(), 1, argumentsSet('types'));
 expectedReturnValues(\Flasher\Prime\Notification\NotificationInterface::getType(), argumentsSet('types'));
 
+// Define expected arguments for handlers
 expectedArguments(\Flasher\Prime\Notification\NotificationBuilderInterface::handler(), 0, 'flasher', 'toastr', 'noty', 'notyf', 'sweetalert');
 
+// Define expected arguments for render formats
 expectedArguments(\Flasher\Prime\FlasherInterface::render(), 0, 'html', 'json', 'array');
+
+// Define expected arguments for common option keys
 expectedArguments(\Flasher\Prime\Notification\FlasherBuilder::option(), 0, 'timeout', 'timeouts', 'fps', 'position', 'direction', 'rtl', 'style', 'escapeHtml');

Asset/AssetManager.php

@@ -4,17 +4,45 @@
 
 namespace Flasher\Prime\Asset;
 
+/**
+ * AssetManager - Manages asset files and their versioning via a manifest file.
+ *
+ * This class provides functionality for handling asset versioning through a manifest
+ * file that maps original asset paths to versioned paths with hash parameters.
+ * The asset versioning helps with cache busting by appending a content hash to the URL.
+ *
+ * Design patterns:
+ * - Resource Manager: Centralized management of web asset resources
+ * - Cache Buster: Handles versioning of assets to ensure browser cache invalidation
+ */
 final class AssetManager implements AssetManagerInterface
 {
     /**
+     * Cached manifest entries mapping original paths to versioned paths.
+     *
      * @var array<string, string>
      */
     private array $entries = [];
 
-    public function __construct(private readonly string $publicDir, private readonly string $manifestPath)
-    {
+    /**
+     * Creates a new AssetManager instance.
+     *
+     * @param string $publicDir    The public directory where assets are located
+     * @param string $manifestPath The path to the manifest file
+     */
+    public function __construct(
+        private readonly string $publicDir,
+        private readonly string $manifestPath,
+    ) {
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * This implementation first checks for an exact match in the manifest,
+     * then tries with directory separators normalized, and falls back to the
+     * original path if no match is found.
+     */
     public function getPath(string $path): string
     {
         $entriesData = $this->getEntriesData();
@@ -27,6 +55,16 @@ public function getPaths(array $paths): array
         return array_map(fn (string $path) => $this->getPath($path), $paths);
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * This method:
+     * 1. Processes each file to calculate its content hash
+     * 2. Creates a mapping from relative paths to versioned paths
+     * 3. Writes the mapping to the manifest file as JSON
+     *
+     * @throws \RuntimeException If unable to write to the manifest file
+     */
     public function createManifest(array $files): void
     {
         foreach ($files as $file) {
@@ -51,7 +89,12 @@ public function createManifest(array $files): void
     /**
      * Loads and returns the entries from the manifest file.
      *
-     * @return array<string, string> the manifest entries
+     * This method lazily loads the manifest data and caches it for subsequent calls.
+     * If no manifest file exists or it cannot be parsed, an empty array is returned.
+     *
+     * @return array<string, string> The manifest entries mapping original to versioned paths
+     *
+     * @throws \InvalidArgumentException If the manifest file contains invalid JSON
      */
     private function getEntriesData(): array
     {
@@ -73,6 +116,16 @@ private function getEntriesData(): array
         return $this->entries = $entries; // @phpstan-ignore-line
     }
 
+    /**
+     * Computes a hash for a file based on its contents.
+     *
+     * This method normalizes line endings to ensure consistent hashing
+     * across different platforms.
+     *
+     * @param string $path The path to the file
+     *
+     * @return string The MD5 hash of the file contents or empty string if file cannot be read
+     */
     private function computeHash(string $path): string
     {
         $contents = file_get_contents($path);

Asset/AssetManagerInterface.php

@@ -4,28 +4,49 @@
 
 namespace Flasher\Prime\Asset;
 
+/**
+ * AssetManagerInterface - Contract for asset management services.
+ *
+ * This interface defines the essential operations for managing web assets,
+ * particularly focusing on path resolution and manifest generation for versioning.
+ *
+ * Design pattern: Strategy - Defines a common interface for different asset
+ * management strategies that can be used interchangeably.
+ */
 interface AssetManagerInterface
 {
     /**
      * Resolves the given path to its hashed version if available in the manifest.
      *
-     * @param string $path the original file path
+     * This method should look up the original path in a manifest of versioned assets
+     * and return the versioned path if found. Otherwise, it should return the original path.
      *
-     * @return string the resolved file path or the original path if not found in the manifest
+     * @param string $path The original file path
+     *
+     * @return string The resolved file path with version hash or the original path if not found
      */
     public function getPath(string $path): string;
 
     /**
-     * @param string[] $paths
+     * Resolves multiple paths to their hashed versions if available.
+     *
+     * This is a batch version of getPath() that processes multiple paths at once.
+     *
+     * @param string[] $paths Array of original file paths
      *
-     * @return string[]
+     * @return string[] Array of resolved file paths in the same order
      */
     public function getPaths(array $paths): array;
 
     /**
-     * Generates a json manifest from given files.
+     * Generates a JSON manifest from given files.
+     *
+     * This method should create a mapping between original file paths and
+     * versioned paths (typically with content hashes) and save it to a manifest file.
+     *
+     * @param string[] $files Array of file paths to include in the manifest
      *
-     * @param string[] $files array of file paths
+     * @throws \RuntimeException If the manifest cannot be created
      */
     public function createManifest(array $files): void;
 }

Configuration.php

@@ -5,6 +5,29 @@
 namespace Flasher\Prime;
 
 /**
+ * Configuration for PHPFlasher.
+ *
+ * This class provides type-safe access to PHPFlasher's configuration structure.
+ * It uses PHPStan annotations to define the complex nested configuration schema,
+ * ensuring configuration consistency and enabling IDE autocompletion.
+ *
+ * Design pattern: Type-safe Configuration - Uses PHP's type system to validate
+ * and document complex configuration structures.
+ *
+ * The configuration array structure contains:
+ * - default: The default notification adapter to use
+ * - main_script: Main JavaScript file path
+ * - scripts: Additional JavaScript files to include
+ * - styles: CSS stylesheets to include
+ * - inject_assets: Whether to auto-inject assets in responses
+ * - translate: Whether to translate notifications
+ * - excluded_paths: Paths where notifications shouldn't be displayed
+ * - options: Global notification options
+ * - filter: Default filtering criteria
+ * - flash_bag: Flash bag configuration for framework integration
+ * - presets: Notification templates/presets with type, title, message and options
+ * - plugins: Plugin-specific configuration with scripts, styles and options
+ *
  * @phpstan-type ConfigType array{
  *     default: string,
  *     main_script?: string,
@@ -20,45 +43,26 @@
  *         type: string,
  *         title: string,
  *         message: string,
- *         options: array<string, mixed>,
+ *         options: array<string, mixed>
  *     }>,
  *     plugins?: array<string, array{
  *         scripts?: string[],
  *         styles?: string[],
- *         options?: array<string, mixed>,
- *     }>,
+ *         options?: array<string, mixed>
+ *     }>
  * }
  */
 final class Configuration
 {
     /**
-     * @param array{
-     *      default: string,
-     *      main_script?: string,
-     *      scripts?: string[],
-     *      styles?: string[],
-     *      inject_assets?: bool,
-     *      translate?: bool,
-     *      excluded_paths?: list<non-empty-string>,
-     *      options?: array<string, mixed>,
-     *      filter?: array<string, mixed>,
-     *      flash_bag?: false|array<string, string[]>,
-     *      presets?: array<string, array{
-     *          type: string,
-     *          title: string,
-     *          message: string,
-     *          options: array<string, mixed>,
-     *      }>,
-     *      plugins?: array<string, array{
-     *          scripts?: string[],
-     *          styles?: string[],
-     *          options?: array<string, mixed>,
-     *      }>,
-     *  } $config
+     * Validates and returns the configuration array.
+     *
+     * This method serves as a type-safe wrapper around configuration arrays,
+     * ensuring that they match the expected schema defined in the PHPStan annotations.
      *
      * @phpstan-param ConfigType $config
      *
-     * @return ConfigType
+     * @phpstan-return ConfigType
      */
     public static function from(array $config): array
     {