From 3f920f2c01455c3b618654a5081e60d4a0b7a475 Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Fri, 16 Jan 2026 00:07:42 +0100 Subject: [PATCH] Simplify PHPDoc comments in Plugin, HTTP, Stamp, and Test constraint classes Removes verbose documentation while preserving type annotations. --- .../Http/Csp/ContentSecurityPolicyHandler.php | 116 ++---------------- src/Prime/Http/RequestExtension.php | 42 +------ src/Prime/Http/ResponseExtension.php | 53 +------- src/Prime/Plugin/FlasherPlugin.php | 88 ++----------- src/Prime/Plugin/Plugin.php | 61 --------- .../Response/Presenter/ArrayPresenter.php | 20 --- .../Response/Presenter/HtmlPresenter.php | 45 +------ .../Response/Resource/ResourceManager.php | 44 +------ src/Prime/Response/Response.php | 74 ++--------- src/Prime/Response/ResponseManager.php | 61 ++------- src/Prime/Stamp/HtmlStamp.php | 27 +--- src/Prime/Stamp/PluginStamp.php | 27 +--- src/Prime/Stamp/PresenterStamp.php | 23 +--- src/Prime/Template/PHPTemplateEngine.php | 26 +--- src/Prime/Test/Constraint/Notification.php | 54 +------- .../Test/Constraint/NotificationCount.php | 41 +------ .../Test/Constraint/NotificationMessage.php | 39 +----- .../Test/Constraint/NotificationOption.php | 49 -------- .../Test/Constraint/NotificationOptions.php | 40 +----- .../Test/Constraint/NotificationTitle.php | 41 ------- .../Test/Constraint/NotificationType.php | 38 +----- src/Prime/Translation/EchoTranslator.php | 20 +-- 22 files changed, 56 insertions(+), 973 deletions(-) diff --git a/src/Prime/Http/Csp/ContentSecurityPolicyHandler.php b/src/Prime/Http/Csp/ContentSecurityPolicyHandler.php index 6907fa8a..37374538 100644 --- a/src/Prime/Http/Csp/ContentSecurityPolicyHandler.php +++ b/src/Prime/Http/Csp/ContentSecurityPolicyHandler.php @@ -7,40 +7,13 @@ namespace Flasher\Prime\Http\Csp; use Flasher\Prime\Http\RequestInterface; use Flasher\Prime\Http\ResponseInterface; -/** - * ContentSecurityPolicyHandler - Manages Content Security Policy for PHPFlasher. - * - * This class handles the complex task of managing Content Security Policy (CSP) headers - * to allow PHPFlasher's JavaScript and CSS to run securely. It generates nonces for - * scripts and styles, modifies CSP headers to include these nonces, and ensures that - * inline code can execute without being blocked by CSP. - * - * Design patterns: - * - Strategy: Implements a specific approach to CSP handling - * - Adapter: Works with different request and response implementations - */ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandlerInterface { - /** - * Header for passing script nonce between components. - */ private const SCRIPT_NONCE_HEADER = 'X-PHPFlasher-Script-Nonce'; - - /** - * Header for passing style nonce between components. - */ private const STYLE_NONCE_HEADER = 'X-PHPFlasher-Style-Nonce'; - /** - * Whether CSP handling is disabled. - */ private bool $cspDisabled = false; - /** - * Creates a new ContentSecurityPolicyHandler instance. - * - * @param NonceGeneratorInterface $nonceGenerator The generator for creating secure nonces - */ public function __construct(private readonly NonceGeneratorInterface $nonceGenerator) { } @@ -87,14 +60,7 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler } /** - * Returns nonces from headers if existing, otherwise null. - * - * This method checks if the necessary nonce headers are present in the provided - * request or response object and returns their values if found. - * - * @param RequestInterface|ResponseInterface $object The object to check for nonce headers - * - * @return array{csp_script_nonce: ?string, csp_style_nonce: ?string}|null Nonce values or null if not found + * @return array{csp_script_nonce: ?string, csp_style_nonce: ?string}|null */ private function getHeaderNonces(RequestInterface|ResponseInterface $object): ?array { @@ -108,27 +74,12 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler return null; } - /** - * Removes temporary nonce headers from the response. - * - * These headers are used internally to pass nonces between components but - * should not be sent to the client. - * - * @param ResponseInterface $response The response to clean - */ private function cleanHeaders(ResponseInterface $response): void { $response->removeHeader(self::SCRIPT_NONCE_HEADER); $response->removeHeader(self::STYLE_NONCE_HEADER); } - /** - * Removes all CSP headers from the response. - * - * This is used when CSP handling is disabled to ensure no CSP restrictions are applied. - * - * @param ResponseInterface $response The response to modify - */ private function removeCspHeaders(ResponseInterface $response): void { $response->removeHeader('X-Content-Security-Policy'); @@ -137,15 +88,9 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler } /** - * Updates Content-Security-Policy headers in a response. + * @param array{csp_script_nonce?: ?string, csp_style_nonce?: ?string} $nonces * - * This method modifies existing CSP headers to include nonces for PHPFlasher's - * JavaScript and CSS, allowing them to execute without being blocked by CSP. - * - * @param ResponseInterface $response The response to modify - * @param array{csp_script_nonce?: ?string, csp_style_nonce?: ?string} $nonces The nonces to add to CSP - * - * @return array{csp_script_nonce?: ?string, csp_style_nonce?: ?string} The nonces used + * @return array{csp_script_nonce?: ?string, csp_style_nonce?: ?string} */ private function updateCspHeaders(ResponseInterface $response, array $nonces = []): array { @@ -202,22 +147,13 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler return $nonces; } - /** - * Generates a valid Content-Security-Policy nonce. - * - * @return string The generated nonce - */ private function generateNonce(): string { return $this->nonceGenerator->generate(); } /** - * Converts a directive set array into Content-Security-Policy header value. - * - * @param array $directives The CSP directives to convert - * - * @return string The formatted CSP header value + * @param array $directives */ private function generateCspHeader(array $directives): string { @@ -225,11 +161,7 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler } /** - * Converts a Content-Security-Policy header value into a directive set array. - * - * @param string|null $header The CSP header value to parse - * - * @return array The parsed directive set + * @return array */ private function parseDirectives(?string $header): array { @@ -248,15 +180,7 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler } /** - * Detects if the 'unsafe-inline' is permitted for a directive within the directive set. - * - * This method checks if a specific CSP directive allows inline scripts or styles, - * taking into account CSP level 2+ hash and nonce exceptions. - * - * @param array $directivesSet The directives to check - * @param string $type The directive type to check - * - * @return bool True if inline content is permitted + * @param array $directivesSet */ private function authorizesInline(array $directivesSet, string $type): bool { @@ -270,14 +194,7 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler } /** - * Checks if a directive list contains hash or nonce restrictions. - * - * This is important for CSP processing because in CSP Level 2+, the presence of a - * hash or nonce invalidates 'unsafe-inline' even if it's present. - * - * @param string[] $directives The CSP directive values to check - * - * @return bool True if the directive list contains a hash or nonce restriction + * @param string[] $directives */ private function hasHashOrNonce(array $directives): bool { @@ -297,15 +214,9 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler } /** - * Finds the fallback directive for a specific directive type. + * @param array $directiveSet * - * In CSP, if a specific directive isn't defined, browsers fall back to default-src. - * This method implements that behavior for the PHPFlasher CSP handler. - * - * @param array $directiveSet The complete directive set - * @param string $type The directive type to find a fallback for - * - * @return string[]|null The fallback directive values, or null if no fallback exists + * @return string[]|null */ private function getDirectiveFallback(array $directiveSet, string $type): ?array { @@ -318,18 +229,11 @@ final class ContentSecurityPolicyHandler implements ContentSecurityPolicyHandler } /** - * Retrieves the Content-Security-Policy headers from a response. - * - * This method extracts all CSP-related headers from the response - * and parses their values into directive sets. - * - * @param ResponseInterface $response The response to extract CSP headers from - * * @return array{ * Content-Security-Policy?: array, * Content-Security-Policy-Report-Only?: array, * X-Content-Security-Policy?: array, - * } Mapped CSP headers and their parsed directive sets + * } */ private function getCspHeaders(ResponseInterface $response): array { diff --git a/src/Prime/Http/RequestExtension.php b/src/Prime/Http/RequestExtension.php index 7d7c80e6..0ed3e6db 100644 --- a/src/Prime/Http/RequestExtension.php +++ b/src/Prime/Http/RequestExtension.php @@ -6,44 +6,21 @@ namespace Flasher\Prime\Http; use Flasher\Prime\FlasherInterface; -/** - * RequestExtension - Converts framework flash messages to PHPFlasher notifications. - * - * This class is responsible for extracting flash messages from request objects - * (typically stored in the session) and converting them to PHPFlasher notifications. - * It provides a bridge between framework-specific flash messaging systems and - * PHPFlasher's notification system. - * - * Design patterns: - * - Adapter: Adapts framework flash message systems to PHPFlasher - * - Mediator: Coordinates the interaction between framework and PHPFlasher - */ final readonly class RequestExtension implements RequestExtensionInterface { /** - * Flattened mapping from flash message keys to notification types. - * * @var array */ private array $mapping; /** - * Creates a new RequestExtension instance. - * - * @param FlasherInterface $flasher The flasher service for creating notifications - * @param array $mapping Mapping from framework flash types to PHPFlasher types + * @param array $mapping */ public function __construct(private FlasherInterface $flasher, array $mapping = []) { $this->mapping = $this->flatMapping($mapping); } - /** - * {@inheritdoc} - * - * This method processes the request to extract flash messages and convert them - * to PHPFlasher notifications. It only processes requests with active sessions. - */ public function flash(RequestInterface $request, ResponseInterface $response): ResponseInterface { if (!$request->hasSession()) { @@ -56,14 +33,9 @@ final readonly class RequestExtension implements RequestExtensionInterface } /** - * Flattens a nested mapping array to a simple key-value mapping. + * @param array $mapping * - * Converts a mapping like ['success' => ['success', 'ok']] to - * ['success' => 'success', 'ok' => 'success']. - * - * @param array $mapping The nested mapping array - * - * @return array The flattened mapping + * @return array */ private function flatMapping(array $mapping): array { @@ -78,14 +50,6 @@ final readonly class RequestExtension implements RequestExtensionInterface return $flatMapping; } - /** - * Processes the request and converts flash messages to notifications. - * - * This method checks for each flash message type in the request and creates - * corresponding PHPFlasher notifications for any that are found. - * - * @param RequestInterface $request The request to process - */ private function processRequest(RequestInterface $request): void { foreach ($this->mapping as $alias => $type) { diff --git a/src/Prime/Http/ResponseExtension.php b/src/Prime/Http/ResponseExtension.php index e7536e65..8c61572a 100644 --- a/src/Prime/Http/ResponseExtension.php +++ b/src/Prime/Http/ResponseExtension.php @@ -8,26 +8,10 @@ use Flasher\Prime\FlasherInterface; use Flasher\Prime\Http\Csp\ContentSecurityPolicyHandlerInterface; use Flasher\Prime\Response\Presenter\HtmlPresenter; -/** - * ResponseExtension - Injects notification HTML into HTTP responses. - * - * This class is responsible for injecting the HTML for notifications into HTTP responses. - * It handles the placement of notification code at appropriate injection points in HTML - * responses, manages Content Security Policy headers, and ensures that notifications are - * only injected in suitable responses. - * - * Design patterns: - * - Decorator: Enhances HTTP responses by adding notification HTML - * - Chain of Responsibility: Determines whether each response is suitable for modification - */ final readonly class ResponseExtension implements ResponseExtensionInterface { /** - * Creates a new ResponseExtension instance. - * - * @param FlasherInterface $flasher The flasher service for rendering notifications - * @param ContentSecurityPolicyHandlerInterface $cspHandler The CSP handler for managing security headers - * @param list $excludedPaths Regex patterns for paths where notifications shouldn't be rendered + * @param list $excludedPaths */ public function __construct( private FlasherInterface $flasher, @@ -36,16 +20,6 @@ final readonly class ResponseExtension implements ResponseExtensionInterface ) { } - /** - * {@inheritdoc} - * - * This method: - * 1. Checks if the response is eligible for notification injection - * 2. Finds an appropriate insertion point in the HTML - * 3. Updates CSP headers if needed - * 4. Renders the notification HTML - * 5. Injects the rendered HTML into the response - */ public function render(RequestInterface $request, ResponseInterface $response): ResponseInterface { if (!$this->isRenderable($request, $response)) { @@ -99,24 +73,6 @@ final readonly class ResponseExtension implements ResponseExtensionInterface return $response; } - /** - * Determines if a response is eligible for notification rendering. - * - * A response is renderable if: - * - The request path is not excluded - * - It's not an AJAX request - * - It's an HTML request format - * - The response is HTML - * - The response is successful (2XX) - * - It's not a redirection - * - It's not an attachment - * - It's not JSON - * - * @param RequestInterface $request The request - * @param ResponseInterface $response The response - * - * @return bool True if notifications should be rendered in this response - */ private function isRenderable(RequestInterface $request, ResponseInterface $response): bool { return !$this->isPathExcluded($request) @@ -129,13 +85,6 @@ final readonly class ResponseExtension implements ResponseExtensionInterface && !$response->isJson(); } - /** - * Checks if the current request path is excluded from notification rendering. - * - * @param RequestInterface $request The request - * - * @return bool True if the path is excluded - */ private function isPathExcluded(RequestInterface $request): bool { if (!method_exists($request, 'getUri')) { // @phpstan-ignore-line diff --git a/src/Prime/Plugin/FlasherPlugin.php b/src/Prime/Plugin/FlasherPlugin.php index 3a4b9aed..f0a56d49 100644 --- a/src/Prime/Plugin/FlasherPlugin.php +++ b/src/Prime/Plugin/FlasherPlugin.php @@ -9,16 +9,6 @@ use Flasher\Prime\FlasherInterface; use Flasher\Prime\Notification\Type; /** - * FlasherPlugin - Core plugin for PHPFlasher. - * - * This class represents the core PHPFlasher plugin, which provides the basic - * notification functionality. It serves as the default plugin and the foundation - * for other plugins to build upon. - * - * Design patterns: - * - Core Plugin: Provides essential functionality that other plugins extend - * - Configuration Management: Handles normalization and defaults for system config - * * @phpstan-type ConfigType array{ * default: string, * main_script: string, @@ -70,21 +60,11 @@ final class FlasherPlugin extends Plugin return FlasherInterface::class; } - /** - * Gets the default plugin name. - * - * @return string The default plugin name - */ public function getDefault(): string { return 'flasher'; } - /** - * Gets the path to the main PHPFlasher script. - * - * @return string The script path - */ public function getRootScript(): string { return '/vendor/flasher/flasher.min.js'; @@ -103,17 +83,6 @@ final class FlasherPlugin extends Plugin return '/vendor/flasher/flasher.min.css'; } - /** - * {@inheritdoc} - * - * This overridden method extends the parent's normalization process with - * additional steps specific to the core plugin: - * - Normalizing plugin configurations - * - Normalizing preset configurations - * - Adding default configuration values - * - Normalizing flash bag mappings - * - Setting preset defaults - */ public function normalizeConfig(array $config = []): array { $config = parent::normalizeConfig($config); @@ -129,11 +98,6 @@ final class FlasherPlugin extends Plugin } /** - * Normalizes the plugins configuration. - * - * This method ensures the core plugin is properly configured, merges global options - * with plugin-specific options, and normalizes array formats for scripts and styles. - * * @param array{ * scripts: string[], * styles: string[], @@ -143,14 +107,14 @@ final class FlasherPlugin extends Plugin * styles?: string[], * options?: array, * }>, - * } $config The raw configuration + * } $config * * @return array{ * scripts: string[], * styles: string[], * options: array, * plugins: array, - * } The normalized configuration + * } */ private function normalizePlugins(array $config): array { @@ -191,11 +155,6 @@ final class FlasherPlugin extends Plugin } /** - * Normalizes the themes configuration. - * - * This method ensures that the themes configuration has the correct structure - * and includes default themes unless explicitly disabled. - * * @param array{ * scripts: string[], * styles: string[], @@ -206,7 +165,7 @@ final class FlasherPlugin extends Plugin * styles?: string[], * options?: array, * }>, - * } $config The raw configuration + * } $config * * @return array{ * scripts: string[], @@ -214,7 +173,7 @@ final class FlasherPlugin extends Plugin * options: array, * plugins: array, * themes: array, - * } The normalized configuration + * } */ private function normalizeThemes(array $config): array { @@ -261,18 +220,13 @@ final class FlasherPlugin extends Plugin } /** - * Normalizes the presets configuration. - * - * This method ensures that string-only preset definitions are expanded to full arrays - * with the string value as the message. - * * @param array{ * scripts: string[], * styles: string[], * options: array, * presets?: array>, * plugins: array, - * } $config The raw configuration + * } $config * * @return array{ * scripts: string[], @@ -280,7 +234,7 @@ final class FlasherPlugin extends Plugin * options: array, * presets?: array>, * plugins: array, - * } The normalized configuration + * } */ private function normalizePresets(array $config): array { @@ -296,11 +250,6 @@ final class FlasherPlugin extends Plugin } /** - * Adds default configuration values. - * - * This method ensures that all required configuration keys have values, - * providing defaults for any that are missing. - * * @param array{ * default?: string|null, * main_script?: string|null, @@ -313,7 +262,7 @@ final class FlasherPlugin extends Plugin * options: array, * presets?: array>, * plugins: array, - * } $config The raw configuration + * } $config * * @return array{ * default: string|null, @@ -327,7 +276,7 @@ final class FlasherPlugin extends Plugin * options: array, * presets: array>, * plugins: array, - * } The configuration with defaults added + * } */ private function addDefaultConfig(array $config): array { @@ -349,11 +298,6 @@ final class FlasherPlugin extends Plugin } /** - * Normalizes the flash bag configuration. - * - * This method ensures that the flash bag mapping has the correct structure - * and includes default mappings unless explicitly disabled. - * * @param array{ * default: string|null, * main_script: string|null, @@ -367,7 +311,7 @@ final class FlasherPlugin extends Plugin * presets: array>, * plugins: array, * flash_bag?: bool|array, - * } $config The raw configuration + * } $config * * @return array{ * default: string|null, @@ -382,7 +326,7 @@ final class FlasherPlugin extends Plugin * presets: array>, * plugins: array, * flash_bag: false|array, - * } The normalized configuration + * } */ private function normalizeFlashBag(array $config): array { @@ -407,10 +351,6 @@ final class FlasherPlugin extends Plugin } /** - * Sets default values for presets. - * - * This method ensures that all presets have required fields with default values. - * * @param array{ * default: string|null, * main_script: string|null, @@ -424,7 +364,7 @@ final class FlasherPlugin extends Plugin * presets: array>, * plugins: array, * flash_bag: false|array, - * } $config The raw configuration + * } $config * * @return array{ * default: string|null, @@ -439,7 +379,7 @@ final class FlasherPlugin extends Plugin * presets: array>, * plugins: array, * flash_bag: false|array, - * } The normalized configuration + * } */ private function setPresetsDefaults(array $config): array { @@ -452,13 +392,11 @@ final class FlasherPlugin extends Plugin } /** - * Returns the default themes configuration. - * * @return array - * }> The default themes configuration + * }> */ private function getDefaultThemes(): array { diff --git a/src/Prime/Plugin/Plugin.php b/src/Prime/Plugin/Plugin.php index 7ee7ac66..16c12942 100644 --- a/src/Prime/Plugin/Plugin.php +++ b/src/Prime/Plugin/Plugin.php @@ -4,85 +4,38 @@ declare(strict_types=1); namespace Flasher\Prime\Plugin; -/** - * Plugin - Base class for PHPFlasher plugins. - * - * This abstract class provides a common foundation for PHPFlasher plugins, - * implementing standard behaviors and conventions. Plugin implementations - * should extend this class and customize the specific aspects they need to change. - * - * Design patterns: - * - Template Method: Defines standard algorithms with customizable steps - * - Convention over Configuration: Provides sensible defaults based on naming conventions - */ abstract class Plugin implements PluginInterface { - /** - * {@inheritdoc} - * - * By default, derives the plugin name from its alias with a "flasher_" prefix. - */ public function getName(): string { return 'flasher_'.$this->getAlias(); } - /** - * {@inheritdoc} - * - * By default, derives the service ID from the plugin alias with a "flasher." prefix. - */ public function getServiceId(): string { return 'flasher.'.$this->getAlias(); } - /** - * {@inheritdoc} - * - * By default, returns an empty array, meaning no service aliases are registered. - */ public function getServiceAliases(): string|array { return []; } - /** - * {@inheritdoc} - * - * By default, returns an empty array, meaning no scripts are included. - */ public function getScripts(): string|array { return []; } - /** - * {@inheritdoc} - * - * By default, returns an empty array, meaning no styles are included. - */ public function getStyles(): string|array { return []; } - /** - * {@inheritdoc} - * - * By default, returns an empty array, meaning no options are configured. - */ public function getOptions(): array { return []; } - /** - * {@inheritdoc} - * - * By default, locates the assets directory by convention based on the plugin's - * class location. - */ public function getAssetsDir(): string { $resourcesDir = $this->getResourcesDir(); @@ -91,13 +44,6 @@ abstract class Plugin implements PluginInterface return realpath($assetsDir) ?: ''; } - /** - * {@inheritdoc} - * - * By default, locates the resources directory by convention based on the plugin's - * class location. Looks first for a Resources subdirectory in the same directory, - * then falls back to a Resources directory one level up. - */ public function getResourcesDir(): string { $reflection = new \ReflectionClass($this); @@ -109,13 +55,6 @@ abstract class Plugin implements PluginInterface return realpath($resourcesDir) ?: ''; } - /** - * {@inheritdoc} - * - * This implementation merges the provided config with defaults from the plugin's - * getScripts(), getStyles(), and getOptions() methods and ensures arrays are properly - * normalized. - */ public function normalizeConfig(array $config): array { $config = [ diff --git a/src/Prime/Response/Presenter/ArrayPresenter.php b/src/Prime/Response/Presenter/ArrayPresenter.php index 99abd92c..ac8011f0 100644 --- a/src/Prime/Response/Presenter/ArrayPresenter.php +++ b/src/Prime/Response/Presenter/ArrayPresenter.php @@ -7,17 +7,6 @@ namespace Flasher\Prime\Response\Presenter; use Flasher\Prime\Response\Response; /** - * ArrayPresenter - Presents notifications as a PHP array structure. - * - * This presenter converts a Response object into a PHP array structure that can - * be used for further processing, serialization, or API responses. It's particularly - * useful as a base for other presenters that need structured data rather than - * rendered output. - * - * Design patterns: - * - Presenter: Transforms domain objects (Notifications) into a presentation format - * - Adapter: Converts internal representation to a format suitable for external use - * * @phpstan-type ArrayPresenterType array{ * envelopes: arraymainScript) { @@ -85,15 +61,6 @@ final readonly class ResourceManager implements ResourceManagerInterface return $response; } - /** - * Adds an HTML stamp to a notification envelope. - * - * This method renders a template for the notification and attaches the - * rendered HTML as a stamp on the envelope. - * - * @param string $view The template view name - * @param Envelope $envelope The notification envelope - */ private function addHtmlStamp(string $view, Envelope $envelope): void { $compiled = $this->templateEngine->render($view, ['envelope' => $envelope]); @@ -101,15 +68,6 @@ final readonly class ResourceManager implements ResourceManagerInterface $envelope->withStamp(new HtmlStamp($compiled)); } - /** - * Adds resources for a plugin to a response. - * - * This method retrieves the resource configuration for a plugin and adds - * its scripts, styles, and options to the response. - * - * @param Response $response The response to populate - * @param string $plugin The plugin alias - */ private function addResources(Response $response, string $plugin): void { $resource = $this->resources[$plugin] ?? []; diff --git a/src/Prime/Response/Response.php b/src/Prime/Response/Response.php index 468ca007..873fc992 100644 --- a/src/Prime/Response/Response.php +++ b/src/Prime/Response/Response.php @@ -6,62 +6,35 @@ namespace Flasher\Prime\Response; use Flasher\Prime\Notification\Envelope; -/** - * Response - Container for notification data ready for presentation. - * - * This class encapsulates all the data needed to render notifications in a response, - * including the notification envelopes themselves, scripts, styles, options, and context. - * It serves as a data transfer object between the notification storage and presenters. - * - * Design patterns: - * - Data Transfer Object (DTO): Aggregates all data needed for notification rendering - * - Immutable Collection: Core envelopes and context are immutable while allowing - * controlled mutation of presentation resources - */ final class Response { - /** - * The main script to be included in the response. - */ private string $mainScript = ''; /** - * Additional JavaScript files to be included in the response. - * * @var string[] */ private array $scripts = []; /** - * CSS stylesheets to be included in the response. - * * @var string[] */ private array $styles = []; /** - * Plugin-specific options organized by plugin alias. - * * @var array> */ private array $options = []; /** - * Creates a new Response instance. - * - * @param Envelope[] $envelopes The notification envelopes to present - * @param array $context Additional context for the presentation (e.g., CSP nonces) + * @param Envelope[] $envelopes + * @param array $context */ public function __construct(private readonly array $envelopes, private readonly array $context) { } /** - * Adds JavaScript scripts to the response. - * - * This method appends new scripts to the existing list, ensuring uniqueness. - * - * @param string[] $scripts The scripts to add + * @param string[] $scripts */ public function addScripts(array $scripts): void { @@ -69,11 +42,7 @@ final class Response } /** - * Adds CSS stylesheets to the response. - * - * This method appends new styles to the existing list, ensuring uniqueness. - * - * @param string[] $styles The styles to add + * @param string[] $styles */ public function addStyles(array $styles): void { @@ -81,13 +50,7 @@ final class Response } /** - * Adds or merges options for a specific plugin. - * - * This method merges new options with existing ones for the specified alias, - * creating the entry if it doesn't exist. - * - * @param string $alias The plugin alias - * @param array $options The options to add or merge + * @param array $options */ public function addOptions(string $alias, array $options): void { @@ -96,34 +59,24 @@ final class Response } /** - * Gets the notification envelopes to be presented. - * - * @return Envelope[] The notification envelopes + * @return Envelope[] */ public function getEnvelopes(): array { return $this->envelopes; } - /** - * Gets the main script path. - */ public function getMainScript(): string { return $this->mainScript; } - /** - * Sets the main script path. - */ public function setMainScript(string $mainScript): void { $this->mainScript = $mainScript; } /** - * Gets the CSS stylesheets. - * * @return string[] */ public function getStyles(): array @@ -132,8 +85,6 @@ final class Response } /** - * Gets the JavaScript scripts. - * * @return string[] */ public function getScripts(): array @@ -142,9 +93,7 @@ final class Response } /** - * Gets the plugin-specific options. - * - * @return array> The options organized by plugin alias + * @return array> */ public function getOptions(): array { @@ -152,9 +101,7 @@ final class Response } /** - * Gets the presentation context. - * - * @return array The context data + * @return array */ public function getContext(): array { @@ -162,11 +109,6 @@ final class Response } /** - * Converts the response to an array representation. - * - * This method transforms all data in the response, including converting notification - * envelopes to arrays, into a format suitable for serialization or rendering. - * * @return array{ * envelopes: array $criteria + * @param array $context * - * This implementation follows a multi-step process: - * 1. Filters notifications from storage based on criteria - * 2. Removes rendered notifications from storage - * 3. Dispatches a PresentationEvent to allow listeners to modify notifications - * 4. Creates a Response object with notifications and context - * 5. Uses the appropriate presenter to render the response - * 6. Dispatches a ResponseEvent to allow final modifications + * @phpstan-return ($presenter is 'html' ? string : + * ($presenter is 'array' ? ArrayPresenterType : + * ($presenter is 'json' ? ArrayPresenterType : + * mixed))) */ public function render(string $presenter = 'html', array $criteria = [], array $context = []): mixed { @@ -87,16 +67,7 @@ final class ResponseManager implements ResponseManagerInterface } /** - * Creates a presenter instance for the specified format. - * - * This method retrieves a presenter by alias from the registry and instantiates - * it if it's a factory closure. - * - * @param string $alias The presenter alias - * - * @return PresenterInterface The presenter instance - * - * @throws PresenterNotFoundException If no presenter is registered with the given alias + * @throws PresenterNotFoundException */ private function createPresenter(string $alias): PresenterInterface { @@ -110,11 +81,6 @@ final class ResponseManager implements ResponseManagerInterface } /** - * Creates a Response object with notifications and context. - * - * This method creates a Response object and populates it with resources - * (scripts, styles, options) using the ResourceManager. - * * @param Envelope[] $envelopes * @param array $context */ @@ -125,17 +91,6 @@ final class ResponseManager implements ResponseManagerInterface return $this->resourceManager->populateResponse($response); } - /** - * Uses a presenter to render a response. - * - * This method selects the appropriate presenter based on the requested format - * and uses it to render the response. - * - * @param Response $response The response to render - * @param string $presenter The presenter format to use - * - * @return mixed The rendered result - */ private function presentResponse(Response $response, string $presenter): mixed { $presenter = $this->createPresenter($presenter); diff --git a/src/Prime/Stamp/HtmlStamp.php b/src/Prime/Stamp/HtmlStamp.php index 865d1f7b..0454b103 100644 --- a/src/Prime/Stamp/HtmlStamp.php +++ b/src/Prime/Stamp/HtmlStamp.php @@ -4,44 +4,19 @@ declare(strict_types=1); namespace Flasher\Prime\Stamp; -/** - * HtmlStamp - Contains prerendered HTML content for a notification. - * - * This stamp stores HTML content that should be rendered directly in the page - * instead of being processed by the JavaScript notification library. It's useful - * for complex notifications that require custom markup or server-rendered content. - * - * Design patterns: - * - Value Object: Immutable object representing a specific concept - * - Memento: Captures and externalizes an object's internal state - */ final readonly class HtmlStamp implements StampInterface, PresentableStampInterface { - /** - * Creates a new HtmlStamp instance. - * - * @param string $html The prerendered HTML content - */ public function __construct(private string $html) { } - /** - * Gets the HTML content. - * - * @return string The prerendered HTML content - */ public function getHtml(): string { return $this->html; } /** - * Converts the stamp to an array representation. - * - * This method implements the serialization logic required by PresentableStampInterface. - * - * @return array{html: string} The array representation + * @return array{html: string} */ public function toArray(): array { diff --git a/src/Prime/Stamp/PluginStamp.php b/src/Prime/Stamp/PluginStamp.php index b16e0c05..f5262cdd 100644 --- a/src/Prime/Stamp/PluginStamp.php +++ b/src/Prime/Stamp/PluginStamp.php @@ -4,44 +4,19 @@ declare(strict_types=1); namespace Flasher\Prime\Stamp; -/** - * PluginStamp - Associates a notification with a specific plugin. - * - * This stamp identifies which plugin should handle a notification. It ensures - * that notifications are rendered with the correct plugin's resources and options. - * This information is also serialized into the notification's metadata. - * - * Design patterns: - * - Value Object: Immutable object representing a specific concept - * - Strategy Identifier: Identifies which rendering strategy to use - */ final readonly class PluginStamp implements PresentableStampInterface, StampInterface { - /** - * Creates a new PluginStamp instance. - * - * @param string $plugin The plugin alias (e.g., 'toastr', 'sweetalert') - */ public function __construct(private string $plugin) { } - /** - * Gets the plugin alias. - * - * @return string The plugin alias - */ public function getPlugin(): string { return $this->plugin; } /** - * Converts the stamp to an array representation. - * - * This method implements the serialization logic required by PresentableStampInterface. - * - * @return array{plugin: string} The array representation + * @return array{plugin: string} */ public function toArray(): array { diff --git a/src/Prime/Stamp/PresenterStamp.php b/src/Prime/Stamp/PresenterStamp.php index 148c8139..d521a651 100644 --- a/src/Prime/Stamp/PresenterStamp.php +++ b/src/Prime/Stamp/PresenterStamp.php @@ -4,26 +4,10 @@ declare(strict_types=1); namespace Flasher\Prime\Stamp; -/** - * PresenterStamp - Controls which presenters can render a notification. - * - * This stamp restricts which presenters can render a notification by specifying - * a regex pattern. Only presenters whose names match the pattern will be allowed - * to render the notification. This is useful for creating notifications that - * are only meant for specific presentation formats. - * - * Design patterns: - * - Value Object: Immutable object representing a specific concept - * - Filter: Restricts which presenters can render a notification - */ final readonly class PresenterStamp implements StampInterface { /** - * Creates a new PresenterStamp instance. - * - * @param string $pattern A regex pattern that presenter names must match - * - * @throws \InvalidArgumentException If the provided pattern is not a valid regex + * @throws \InvalidArgumentException */ public function __construct(private string $pattern) { @@ -32,11 +16,6 @@ final readonly class PresenterStamp implements StampInterface } } - /** - * Gets the pattern value. - * - * @return string The regex pattern - */ public function getPattern(): string { return $this->pattern; diff --git a/src/Prime/Template/PHPTemplateEngine.php b/src/Prime/Template/PHPTemplateEngine.php index 566c5da9..66b872e5 100644 --- a/src/Prime/Template/PHPTemplateEngine.php +++ b/src/Prime/Template/PHPTemplateEngine.php @@ -4,34 +4,10 @@ declare(strict_types=1); namespace Flasher\Prime\Template; -/** - * PHPTemplateEngine - Simple PHP-based template rendering engine. - * - * This implementation provides a straightforward template rendering mechanism using - * native PHP as the template language. It works by including PHP files and extracting - * context variables into the template's scope. - * - * Design patterns: - * - Strategy: Implements a specific template rendering strategy - * - Output Capture: Uses output buffering to capture rendered content - * - * Security considerations: - * - Context variables are extracted with EXTR_SKIP flag to prevent variable overwriting - * - Template files must exist and be readable - */ final class PHPTemplateEngine implements TemplateEngineInterface { /** - * {@inheritdoc} - * - * This implementation: - * 1. Verifies the template file exists and is readable - * 2. Starts output buffering - * 3. Extracts context variables into the current scope - * 4. Includes the template file - * 5. Captures and returns the output - * - * @throws \InvalidArgumentException If the template file doesn't exist or isn't readable + * @throws \InvalidArgumentException */ public function render(string $name, array $context = []): string { diff --git a/src/Prime/Test/Constraint/Notification.php b/src/Prime/Test/Constraint/Notification.php index 4a2a623c..9e183052 100644 --- a/src/Prime/Test/Constraint/Notification.php +++ b/src/Prime/Test/Constraint/Notification.php @@ -8,27 +8,10 @@ use Flasher\Prime\EventDispatcher\Event\NotificationEvents; use Flasher\Prime\Notification\NotificationInterface; use PHPUnit\Framework\Constraint\Constraint; -/** - * Notification - PHPUnit constraint for asserting complete notification properties. - * - * This constraint verifies that a NotificationEvents collection contains at least - * one notification matching a combination of type, message, title, and options. - * It allows for comprehensive notification assertions by checking multiple properties. - * - * Design patterns: - * - Composite: Part of PHPUnit's constraint composition system - * - Strategy: Implements a specific assertion strategy - * - Specification: Represents a specification that notifications can satisfy - */ final class Notification extends Constraint { /** - * Creates a new Notification constraint. - * - * @param string $expectedType Expected notification type (e.g., 'success', 'error') - * @param string|null $expectedMessage Expected message content (null to ignore) - * @param array $expectedOptions Expected options as an associative array - * @param string|null $expectedTitle Expected title content (null to ignore) + * @param array $expectedOptions */ public function __construct( private readonly string $expectedType, @@ -38,11 +21,6 @@ final class Notification extends Constraint ) { } - /** - * Returns a string representation of the constraint. - * - * @return string The constraint description - */ public function toString(): string { $details = [ @@ -64,14 +42,6 @@ final class Notification extends Constraint return 'contains a notification with '.implode(', ', $details); } - /** - * Evaluates if the given NotificationEvents object contains at least one notification - * matching all the expected properties. - * - * @param NotificationEvents|mixed $other An instance of NotificationEvents to evaluate - * - * @return bool True if a matching notification is found - */ protected function matches(mixed $other): bool { if (!$other instanceof NotificationEvents) { @@ -87,19 +57,6 @@ final class Notification extends Constraint return false; } - /** - * Checks if a specific notification matches all expected properties. - * - * A notification matches if: - * - Its type equals the expected type AND - * - Its message equals the expected message (if provided) AND - * - Its title equals the expected title (if provided) AND - * - Its options contain all expected option key-value pairs (if provided) - * - * @param NotificationInterface $notification The notification to check - * - * @return bool True if the notification matches all criteria - */ private function isNotificationMatching(NotificationInterface $notification): bool { return $notification->getType() === $this->expectedType @@ -109,14 +66,7 @@ final class Notification extends Constraint } /** - * Provides a detailed failure description when the constraint fails. - * - * This method lists all actual notifications with their properties, - * making test failures easier to diagnose. - * - * @param NotificationEvents $other The evaluated NotificationEvents instance - * - * @return string A detailed failure description + * @param NotificationEvents $other */ protected function failureDescription(mixed $other): string { diff --git a/src/Prime/Test/Constraint/NotificationCount.php b/src/Prime/Test/Constraint/NotificationCount.php index e0e132b8..d3f640fe 100644 --- a/src/Prime/Test/Constraint/NotificationCount.php +++ b/src/Prime/Test/Constraint/NotificationCount.php @@ -7,45 +7,17 @@ namespace Flasher\Prime\Test\Constraint; use Flasher\Prime\EventDispatcher\Event\NotificationEvents; use PHPUnit\Framework\Constraint\Constraint; -/** - * NotificationCount - PHPUnit constraint for asserting notification count. - * - * This constraint verifies that a NotificationEvents collection contains - * exactly the expected number of notifications. It's used by the FlasherAssert - * class for count-related assertions. - * - * Design patterns: - * - Composite: Part of PHPUnit's constraint composition system - * - Strategy: Implements a specific assertion strategy - */ final class NotificationCount extends Constraint { - /** - * Creates a new NotificationCount constraint. - * - * @param int $expectedValue The expected number of notifications - */ public function __construct(private readonly int $expectedValue) { } - /** - * Returns a string representation of the constraint. - * - * @return string The constraint description - */ public function toString(): string { return \sprintf('matches the expected notification count of %d.', $this->expectedValue); } - /** - * Evaluates if the given NotificationEvents object matches the expected notification count. - * - * @param NotificationEvents|mixed $other An instance of NotificationEvents to evaluate - * - * @return bool True if the actual count matches the expected count - */ protected function matches(mixed $other): bool { if (!$other instanceof NotificationEvents) { @@ -56,11 +28,7 @@ final class NotificationCount extends Constraint } /** - * Provides a detailed failure description when the constraint fails. - * - * @param NotificationEvents $other The evaluated NotificationEvents instance - * - * @return string A detailed failure description + * @param NotificationEvents $other */ protected function failureDescription(mixed $other): string { @@ -69,13 +37,6 @@ final class NotificationCount extends Constraint return \sprintf('Expected the notification count to be %d, but got %d instead.', $this->expectedValue, $actualCount); } - /** - * Counts the notifications in the given NotificationEvents object. - * - * @param NotificationEvents $events The NotificationEvents instance - * - * @return int The number of notifications - */ private function countNotifications(NotificationEvents $events): int { return \count($events->getEnvelopes()); diff --git a/src/Prime/Test/Constraint/NotificationMessage.php b/src/Prime/Test/Constraint/NotificationMessage.php index 2e2810d5..a54d91f5 100644 --- a/src/Prime/Test/Constraint/NotificationMessage.php +++ b/src/Prime/Test/Constraint/NotificationMessage.php @@ -8,47 +8,17 @@ use Flasher\Prime\EventDispatcher\Event\NotificationEvents; use Flasher\Prime\Notification\NotificationInterface; use PHPUnit\Framework\Constraint\Constraint; -/** - * NotificationMessage - PHPUnit constraint for asserting notification message presence. - * - * This constraint verifies that a NotificationEvents collection contains at least - * one notification with a message containing the expected text. It's used by the - * FlasherAssert class for message-related assertions. - * - * Design patterns: - * - Composite: Part of PHPUnit's constraint composition system - * - Strategy: Implements a specific assertion strategy - * - String Matcher: Performs string matching on notification messages - */ final class NotificationMessage extends Constraint { - /** - * Creates a new NotificationMessage constraint. - * - * @param string $expectedMessage The expected message text (or substring) - */ public function __construct(private readonly string $expectedMessage) { } - /** - * Returns a string representation of the constraint. - * - * @return string The constraint description - */ public function toString(): string { return \sprintf('contains a notification with message "%s"', $this->expectedMessage); } - /** - * Evaluates if the given NotificationEvents object contains at least one notification - * with a message containing the expected text. - * - * @param NotificationEvents|mixed $other An instance of NotificationEvents to evaluate - * - * @return bool True if a notification with the expected message text is found - */ protected function matches(mixed $other): bool { if (!$other instanceof NotificationEvents) { @@ -65,14 +35,7 @@ final class NotificationMessage extends Constraint } /** - * Provides a detailed failure description when the constraint fails. - * - * This method lists all actual notification messages found, making - * test failures easier to diagnose. - * - * @param NotificationEvents $other The evaluated NotificationEvents instance - * - * @return string A detailed failure description + * @param NotificationEvents $other */ protected function failureDescription(mixed $other): string { diff --git a/src/Prime/Test/Constraint/NotificationOption.php b/src/Prime/Test/Constraint/NotificationOption.php index 568343cf..786641b9 100644 --- a/src/Prime/Test/Constraint/NotificationOption.php +++ b/src/Prime/Test/Constraint/NotificationOption.php @@ -8,35 +8,12 @@ use Flasher\Prime\EventDispatcher\Event\NotificationEvents; use Flasher\Prime\Notification\NotificationInterface; use PHPUnit\Framework\Constraint\Constraint; -/** - * NotificationOption - PHPUnit constraint for asserting a specific notification option. - * - * This constraint verifies that a NotificationEvents collection contains at least - * one notification with a specific option key and optionally a specific value. It's - * used by the FlasherAssert class for option-specific assertions. - * - * Design patterns: - * - Composite: Part of PHPUnit's constraint composition system - * - Strategy: Implements a specific assertion strategy - * - Key-Value Matcher: Performs key-value matching on notification options - */ final class NotificationOption extends Constraint { - /** - * Creates a new NotificationOption constraint. - * - * @param string $expectedKey The expected option key - * @param mixed $expectedValue The expected option value (null to check only key existence) - */ public function __construct(private readonly string $expectedKey, private readonly mixed $expectedValue = null) { } - /** - * Returns a string representation of the constraint. - * - * @return string The constraint description - */ public function toString(): string { $description = \sprintf('contains a notification with an option "%s"', $this->expectedKey); @@ -48,14 +25,6 @@ final class NotificationOption extends Constraint return $description; } - /** - * Evaluates if the given NotificationEvents object contains at least one notification - * with the expected option key and value. - * - * @param NotificationEvents|mixed $other An instance of NotificationEvents to evaluate - * - * @return bool True if a notification with the expected option is found - */ protected function matches(mixed $other): bool { if (!$other instanceof NotificationEvents) { @@ -71,13 +40,6 @@ final class NotificationOption extends Constraint return false; } - /** - * Checks if a specific notification has the expected option key and value. - * - * @param NotificationInterface $notification The notification to check - * - * @return bool True if the notification has the expected option - */ private function isOptionMatching(NotificationInterface $notification): bool { $options = $notification->getOptions(); @@ -85,21 +47,10 @@ final class NotificationOption extends Constraint return isset($options[$this->expectedKey]) && $options[$this->expectedKey] === $this->expectedValue; } - /** - * Provides a detailed failure description when the constraint fails. - * - * This method lists all actual notification options found, making - * test failures easier to diagnose. - * - * @param NotificationEvents $other The evaluated NotificationEvents instance - * - * @return string A detailed failure description - */ protected function failureDescription(mixed $other): string { $actualOptions = []; - // @phpstan-ignore-next-line if ($other instanceof NotificationEvents) { foreach ($other->getEnvelopes() as $notification) { $actualOptions[] = json_encode($notification->getOptions()); diff --git a/src/Prime/Test/Constraint/NotificationOptions.php b/src/Prime/Test/Constraint/NotificationOptions.php index a7c2cdf8..cc4c2b30 100644 --- a/src/Prime/Test/Constraint/NotificationOptions.php +++ b/src/Prime/Test/Constraint/NotificationOptions.php @@ -7,47 +7,20 @@ namespace Flasher\Prime\Test\Constraint; use Flasher\Prime\EventDispatcher\Event\NotificationEvents; use PHPUnit\Framework\Constraint\Constraint; -/** - * NotificationOptions - PHPUnit constraint for asserting notification options. - * - * This constraint verifies that a NotificationEvents collection contains at least - * one notification with options matching all the expected key-value pairs. It's used - * by the FlasherAssert class for options-related assertions. - * - * Design patterns: - * - Composite: Part of PHPUnit's constraint composition system - * - Strategy: Implements a specific assertion strategy - * - Key-Value Matcher: Performs associative array matching on notification options - */ final class NotificationOptions extends Constraint { /** - * Creates a new NotificationOptions constraint. - * - * @param array $expectedOptions The expected option key-value pairs + * @param array $expectedOptions */ public function __construct(private readonly array $expectedOptions) { } - /** - * Returns a string representation of the constraint. - * - * @return string The constraint description - */ public function toString(): string { return 'contains a notification with options matching '.json_encode($this->expectedOptions, \JSON_PRETTY_PRINT); } - /** - * Evaluates if the given NotificationEvents object contains at least one notification - * with options containing all the expected key-value pairs. - * - * @param NotificationEvents|mixed $other An instance of NotificationEvents to evaluate - * - * @return bool True if a notification with matching options is found - */ protected function matches(mixed $other): bool { if (!$other instanceof NotificationEvents) { @@ -63,21 +36,10 @@ final class NotificationOptions extends Constraint return false; } - /** - * Provides a detailed failure description when the constraint fails. - * - * This method lists all actual notification options found, making - * test failures easier to diagnose. - * - * @param NotificationEvents $other The evaluated NotificationEvents instance - * - * @return string A detailed failure description - */ protected function failureDescription(mixed $other): string { $actualOptions = []; - // @phpstan-ignore-next-line if ($other instanceof NotificationEvents) { foreach ($other->getEnvelopes() as $notification) { $actualOptions[] = json_encode($notification->getOptions()); diff --git a/src/Prime/Test/Constraint/NotificationTitle.php b/src/Prime/Test/Constraint/NotificationTitle.php index 470c389a..cbce9489 100644 --- a/src/Prime/Test/Constraint/NotificationTitle.php +++ b/src/Prime/Test/Constraint/NotificationTitle.php @@ -8,47 +8,17 @@ use Flasher\Prime\EventDispatcher\Event\NotificationEvents; use Flasher\Prime\Notification\NotificationInterface; use PHPUnit\Framework\Constraint\Constraint; -/** - * NotificationTitle - PHPUnit constraint for asserting notification title presence. - * - * This constraint verifies that a NotificationEvents collection contains at least - * one notification with a title containing the expected text. It's used by the - * FlasherAssert class for title-related assertions. - * - * Design patterns: - * - Composite: Part of PHPUnit's constraint composition system - * - Strategy: Implements a specific assertion strategy - * - String Matcher: Performs string matching on notification titles - */ final class NotificationTitle extends Constraint { - /** - * Creates a new NotificationTitle constraint. - * - * @param string $expectedTitle The expected title text (or substring) - */ public function __construct(private readonly string $expectedTitle) { } - /** - * Returns a string representation of the constraint. - * - * @return string The constraint description - */ public function toString(): string { return \sprintf('contains a notification with a title containing "%s"', $this->expectedTitle); } - /** - * Evaluates if the given NotificationEvents object contains at least one notification - * with a title containing the expected text. - * - * @param NotificationEvents|mixed $other An instance of NotificationEvents to evaluate - * - * @return bool True if a notification with the expected title text is found - */ protected function matches(mixed $other): bool { if (!$other instanceof NotificationEvents) { @@ -64,19 +34,8 @@ final class NotificationTitle extends Constraint return false; } - /** - * Provides a detailed failure description when the constraint fails. - * - * This method lists all actual notification titles found, making - * test failures easier to diagnose. - * - * @param NotificationEvents $other The evaluated NotificationEvents instance - * - * @return string A detailed failure description - */ protected function failureDescription(mixed $other): string { - // @phpstan-ignore-next-line if (!$other instanceof NotificationEvents) { return 'Expected an instance of NotificationEvents but received a different type.'; } diff --git a/src/Prime/Test/Constraint/NotificationType.php b/src/Prime/Test/Constraint/NotificationType.php index dbcc4554..00ef4a81 100644 --- a/src/Prime/Test/Constraint/NotificationType.php +++ b/src/Prime/Test/Constraint/NotificationType.php @@ -8,46 +8,17 @@ use Flasher\Prime\EventDispatcher\Event\NotificationEvents; use Flasher\Prime\Notification\NotificationInterface; use PHPUnit\Framework\Constraint\Constraint; -/** - * NotificationType - PHPUnit constraint for asserting notification type presence. - * - * This constraint verifies that a NotificationEvents collection contains at least - * one notification of the specified type. It's used by the FlasherAssert class - * for type-related assertions. - * - * Design patterns: - * - Composite: Part of PHPUnit's constraint composition system - * - Strategy: Implements a specific assertion strategy - */ final class NotificationType extends Constraint { - /** - * Creates a new NotificationType constraint. - * - * @param string $expectedType The expected notification type (e.g., 'success', 'error') - */ public function __construct(private readonly string $expectedType) { } - /** - * Returns a string representation of the constraint. - * - * @return string The constraint description - */ public function toString(): string { return \sprintf('contains a notification of type "%s".', $this->expectedType); } - /** - * Evaluates if the given NotificationEvents object contains at least one notification - * of the expected type. - * - * @param NotificationEvents|mixed $other An instance of NotificationEvents to evaluate - * - * @return bool True if a notification of the expected type is found - */ protected function matches(mixed $other): bool { if (!$other instanceof NotificationEvents) { @@ -64,14 +35,7 @@ final class NotificationType extends Constraint } /** - * Provides a detailed failure description when the constraint fails. - * - * This method provides context about what types were found instead of - * the expected type, making test failures easier to diagnose. - * - * @param NotificationEvents $other The evaluated NotificationEvents instance - * - * @return string A detailed failure description + * @param NotificationEvents $other */ protected function failureDescription(mixed $other): string { diff --git a/src/Prime/Translation/EchoTranslator.php b/src/Prime/Translation/EchoTranslator.php index eba05440..d5974c3a 100644 --- a/src/Prime/Translation/EchoTranslator.php +++ b/src/Prime/Translation/EchoTranslator.php @@ -4,34 +4,16 @@ declare(strict_types=1); namespace Flasher\Prime\Translation; -/** - * EchoTranslator - Minimal translator implementation that returns message IDs unchanged. - * - * This implementation simply returns the message identifiers as-is, without - * performing any actual translation. It serves as a fallback translator when - * no real translation service is available. - * - * Design patterns: - * - Null Object: Provides a do-nothing implementation that maintains API compatibility - * - Fallback: Serves as a default implementation when no specific translator is provided - */ final readonly class EchoTranslator implements TranslatorInterface { /** - * {@inheritdoc} - * - * This implementation simply returns the message identifier unchanged. + * @param array $parameters */ public function translate(string $id, array $parameters = [], ?string $locale = null): string { return $id; } - /** - * {@inheritdoc} - * - * This implementation always returns 'en' as the default locale. - */ public function getLocale(): string { return 'en';