From 21348f384d5a69df61fe9c649e4ebf8d1743606e Mon Sep 17 00:00:00 2001 From: Younes ENNAJI Date: Thu, 15 Jan 2026 22:22:20 +0100 Subject: [PATCH] Simplify PHPDoc comments in Laravel and Symfony integrations Remove verbose documentation pattern references and redundant explanations, keeping only essential type annotations. --- src/Laravel/Command/InstallCommand.php | 48 +------ src/Laravel/Component/FlasherComponent.php | 26 +--- .../EventListener/LivewireListener.php | 56 +------- src/Laravel/EventListener/OctaneListener.php | 17 +-- src/Laravel/Facade/Flasher.php | 28 +--- src/Laravel/FlasherServiceProvider.php | 126 +----------------- src/Laravel/Http/Request.php | 21 +-- src/Laravel/Http/Response.php | 22 +-- src/Laravel/Middleware/FlasherMiddleware.php | 27 +--- src/Laravel/Middleware/SessionMiddleware.php | 27 +--- src/Laravel/Storage/SessionBag.php | 31 +---- src/Laravel/Support/PluginServiceProvider.php | 77 +---------- src/Laravel/Template/BladeTemplateEngine.php | 25 +--- src/Laravel/Translation/Translator.php | 46 +------ src/Symfony/Attribute/AsFlasherFactory.php | 24 +--- src/Symfony/Attribute/AsFlasherPresenter.php | 25 +--- src/Symfony/Command/InstallCommand.php | 86 +----------- src/Symfony/Component/FlasherComponent.php | 33 +---- .../Compiler/EventListenerCompilerPass.php | 16 +-- .../Compiler/PresenterCompilerPass.php | 16 +-- src/Symfony/EventListener/FlasherListener.php | 32 +---- src/Symfony/EventListener/SessionListener.php | 31 +---- .../Factory/NotificationFactoryLocator.php | 33 +---- src/Symfony/FlasherSymfonyBundle.php | 31 +---- src/Symfony/Http/Request.php | 21 +-- src/Symfony/Http/Response.php | 16 +-- src/Symfony/Profiler/FlasherDataCollector.php | 61 +-------- src/Symfony/Storage/FallbackSession.php | 17 +-- .../Storage/FallbackSessionInterface.php | 25 +--- src/Symfony/Storage/SessionBag.php | 46 +------ src/Symfony/Support/PluginBundle.php | 55 +------- src/Symfony/Support/PluginBundleInterface.php | 23 +--- src/Symfony/Template/TwigTemplateEngine.php | 25 +--- src/Symfony/Translation/Translator.php | 37 +---- src/Symfony/Twig/FlasherTwigExtension.php | 30 +---- 35 files changed, 51 insertions(+), 1209 deletions(-) diff --git a/src/Laravel/Command/InstallCommand.php b/src/Laravel/Command/InstallCommand.php index 18f1e968..8ccc1dc1 100644 --- a/src/Laravel/Command/InstallCommand.php +++ b/src/Laravel/Command/InstallCommand.php @@ -16,15 +16,7 @@ use Symfony\Component\Console\Output\OutputInterface; use Symfony\Component\Finder\Finder; /** - * InstallCommand - Artisan command for installing PHPFlasher resources. - * - * This command provides a CLI interface for installing PHPFlasher resources - * including assets (JS and CSS files) and configuration files. It discovers - * all registered PHPFlasher plugins and installs their resources. - * - * Design patterns: - * - Command: Implements the command pattern for Artisan CLI integration - * - Discovery: Automatically discovers and processes registered plugins + * Artisan command for installing PHPFlasher resources. */ final class InstallCommand extends Command { @@ -35,21 +27,11 @@ final class InstallCommand extends Command */ protected $description = 'Installs all PHPFlasher resources to the public and config directories.'; - /** - * Creates a new InstallCommand instance. - * - * @param AssetManagerInterface $assetManager Manager for handling PHPFlasher assets - */ public function __construct(private readonly AssetManagerInterface $assetManager) { parent::__construct(); } - /** - * Configure the command. - * - * Sets the command name, description, help text, and options. - */ protected function configure(): void { $this @@ -60,20 +42,6 @@ final class InstallCommand extends Command ->addOption('symlink', 's', InputOption::VALUE_NONE, 'Symlink PHPFlasher assets instead of copying them.'); } - /** - * Execute the command. - * - * Installs PHPFlasher resources by: - * 1. Displaying a fancy banner - * 2. Processing each registered plugin - * 3. Publishing assets and config files - * 4. Creating a manifest file - * - * @param InputInterface $input Command input - * @param OutputInterface $output Command output - * - * @return int Command exit code (0 for success, non-zero for failure) - */ protected function execute(InputInterface $input, OutputInterface $output): int { $output->writeln(''); @@ -162,13 +130,7 @@ final class InstallCommand extends Command } /** - * Publish assets from a plugin to the public directory. - * - * @param PluginInterface $plugin The plugin to publish assets from - * @param string $publicDir The target public directory - * @param bool $useSymlinks Whether to symlink or copy assets - * - * @return string[] Array of published file paths + * @return string[] */ private function publishAssets(PluginInterface $plugin, string $publicDir, bool $useSymlinks): array { @@ -202,12 +164,6 @@ final class InstallCommand extends Command return $files; } - /** - * Publish a plugin's configuration file. - * - * @param PluginInterface $plugin The plugin to publish configuration for - * @param string $configFile The source configuration file path - */ private function publishConfig(PluginInterface $plugin, string $configFile): void { if (!file_exists($configFile)) { diff --git a/src/Laravel/Component/FlasherComponent.php b/src/Laravel/Component/FlasherComponent.php index 7454fd48..a703236f 100644 --- a/src/Laravel/Component/FlasherComponent.php +++ b/src/Laravel/Component/FlasherComponent.php @@ -7,38 +7,14 @@ namespace Flasher\Laravel\Component; use Illuminate\View\Component; /** - * FlasherComponent - Blade component for rendering notifications. - * - * This class provides a Blade component interface for rendering PHPFlasher - * notifications in Laravel views. It can be used with Laravel's component syntax: - * - * - * Design patterns: - * - View Component: Implements Laravel's view component pattern - * - Adapter: Adapts the Flasher render method to Laravel's component interface + * Blade component for rendering PHPFlasher notifications. */ final class FlasherComponent extends Component { - /** - * Creates a new FlasherComponent instance. - * - * @param string $criteria JSON-encoded filtering criteria for notifications - * @param string $context JSON-encoded rendering context - */ public function __construct(public string $criteria = '', public string $context = '') { } - /** - * Renders the component. - * - * This method decodes the JSON criteria and context, then delegates to - * the Flasher service to render the notifications as HTML. - * - * @return string Rendered HTML content - * - * @throws \JsonException If JSON decoding fails - */ public function render(): string { /** @var array $criteria */ diff --git a/src/Laravel/EventListener/LivewireListener.php b/src/Laravel/EventListener/LivewireListener.php index 4dca259b..ad129d72 100644 --- a/src/Laravel/EventListener/LivewireListener.php +++ b/src/Laravel/EventListener/LivewireListener.php @@ -14,27 +14,10 @@ use Livewire\LivewireManager; use Livewire\Mechanisms\HandleComponents\ComponentContext; /** - * LivewireListener - Integrates PHPFlasher with Livewire component lifecycle. - * - * This listener ensures that PHPFlasher notifications can be displayed during - * Livewire component updates without requiring a full page load. It dispatches - * notifications as Livewire events that are handled by the front-end JavaScript. - * - * Design patterns: - * - Observer: Listens to Livewire component lifecycle events - * - Adapter: Adapts PHPFlasher notifications to Livewire's event system - * - Security-aware: Ensures CSP compliance with proper nonce handling + * Integrates PHPFlasher with Livewire component lifecycle. */ final readonly class LivewireListener { - /** - * Creates a new LivewireListener instance. - * - * @param LivewireManager $livewire The Livewire manager - * @param FlasherInterface $flasher The PHPFlasher service - * @param ContentSecurityPolicyHandlerInterface $cspHandler The CSP handler for security - * @param \Closure $request Closure to get the current request - */ public function __construct( private LivewireManager $livewire, private FlasherInterface $flasher, @@ -43,15 +26,6 @@ final readonly class LivewireListener ) { } - /** - * Handle a Livewire component dehydration event. - * - * This method is invoked during Livewire's component rendering process - * and dispatches any pending notifications as Livewire events. - * - * @param Component $component The Livewire component being rendered - * @param ComponentContext $context The Livewire component context - */ public function __invoke(Component $component, ComponentContext $context): void { if ($this->shouldSkip($context)) { @@ -67,14 +41,7 @@ final readonly class LivewireListener } /** - * Dispatches notifications as Livewire events. - * - * This method adds the notifications data to the Livewire component's - * dispatched events, which will be processed by the front-end. - * - * @param Component $component The Livewire component - * @param ComponentContext $context The Livewire component context - * @param array{envelopes: Envelope[]} $data The notification data + * @param array{envelopes: Envelope[]} $data */ private function dispatchNotifications(Component $component, ComponentContext $context, array $data): void { @@ -89,30 +56,13 @@ final readonly class LivewireListener $context->addEffect('dispatches', $dispatches); } - /** - * Determines if notification processing should be skipped. - * - * Skips processing in the following cases: - * - Not a Livewire request - * - During component mounting (initial render) - * - When a redirect is in progress - * - * @param ComponentContext $context The Livewire component context - * - * @return bool True if notification processing should be skipped - */ private function shouldSkip(ComponentContext $context): bool { return !$this->livewire->isLivewireRequest() || $context->mounting || isset($context->effects['redirect']); } /** - * Creates the security context for rendering notifications. - * - * This method generates CSP nonces to ensure scripts loaded by PHPFlasher - * comply with Content Security Policy. - * - * @return array The context with CSP nonces + * @return array */ private function createContext(): array { diff --git a/src/Laravel/EventListener/OctaneListener.php b/src/Laravel/EventListener/OctaneListener.php index 6216815e..00030b87 100644 --- a/src/Laravel/EventListener/OctaneListener.php +++ b/src/Laravel/EventListener/OctaneListener.php @@ -8,25 +8,10 @@ use Flasher\Prime\EventDispatcher\EventListener\NotificationLoggerListener; use Laravel\Octane\Events\RequestReceived; /** - * OctaneListener - Resets notification logger between Octane requests. - * - * This listener ensures that notifications from previous requests don't - * leak into new requests when running Laravel Octane, which keeps workers - * alive between requests. - * - * Design patterns: - * - Observer: Observes Octane request events - * - State Reset: Cleans up state between stateful worker requests + * Resets notification logger between Octane requests. */ final readonly class OctaneListener { - /** - * Handle the Octane RequestReceived event. - * - * Resets the notification logger to ensure clean state for the new request. - * - * @param RequestReceived $event The Octane request received event - */ public function handle(RequestReceived $event): void { /** @var NotificationLoggerListener $listener */ diff --git a/src/Laravel/Facade/Flasher.php b/src/Laravel/Facade/Flasher.php index c90c2f8b..5aea254c 100644 --- a/src/Laravel/Facade/Flasher.php +++ b/src/Laravel/Facade/Flasher.php @@ -10,28 +10,7 @@ use Flasher\Prime\Stamp\StampInterface; use Illuminate\Support\Facades\Facade; /** - * Flasher - Laravel Facade for the PHPFlasher service. - * - * This facade provides a static interface to PHPFlasher's functionality within Laravel, - * following Laravel's facade pattern. It offers comprehensive IDE autocompletion for all - * PHPFlasher methods by providing method signatures in PHPDoc comments. - * - * Design patterns: - * - Facade: Provides a simplified, static interface to a complex subsystem - * - Proxy: Acts as a proxy to the underlying PHPFlasher service - * - * Usage examples: - * ```php - * // Simple notification - * Flasher::success('Operation completed successfully'); - * - * // Chained configuration - * Flasher::type('success') - * ->title('Success') - * ->message('Record saved') - * ->option('timeout', 5000) - * ->push(); - * ``` + * Laravel facade for PHPFlasher with IDE autocompletion support. * * @method static NotificationBuilder title(string $message) * @method static NotificationBuilder message(string $message) @@ -71,11 +50,6 @@ use Illuminate\Support\Facades\Facade; */ final class Flasher extends Facade { - /** - * Get the registered name of the component. - * - * @return string The name of the facade's service binding ('flasher') - */ protected static function getFacadeAccessor(): string { return 'flasher'; diff --git a/src/Laravel/FlasherServiceProvider.php b/src/Laravel/FlasherServiceProvider.php index 33d948dd..2d14c556 100644 --- a/src/Laravel/FlasherServiceProvider.php +++ b/src/Laravel/FlasherServiceProvider.php @@ -43,27 +43,10 @@ use Laravel\Octane\Events\RequestReceived; use Livewire\LivewireManager; /** - * FlasherServiceProvider - Main service provider for Laravel integration. - * - * This class serves as the entry point for integrating PHPFlasher with Laravel. - * It registers all necessary services, components, commands, and middleware - * to provide a seamless Laravel experience. - * - * Design patterns: - * - Service Provider: Implements Laravel's service provider pattern for registration - * - Adapter: Adapts Laravel-specific components to PHPFlasher interfaces - * - Bridge: Connects the framework-agnostic PHPFlasher core to Laravel + * Main service provider for Laravel integration. */ final class FlasherServiceProvider extends PluginServiceProvider { - /** - * Register PHPFlasher services with the Laravel container. - * - * This method follows Laravel's service provider registration phase by: - * 1. Creating the core plugin - * 2. Registering configuration - * 3. Registering core services and adapters - */ public function register(): void { $this->plugin = $this->createPlugin(); @@ -80,17 +63,6 @@ final class FlasherServiceProvider extends PluginServiceProvider $this->registerAssetManager(); } - /** - * Boot PHPFlasher services after all providers are registered. - * - * This method follows Laravel's service provider boot phase by: - * 1. Setting up the service container bridge - * 2. Registering commands - * 3. Loading translations - * 4. Registering middleware - * 5. Registering Blade directives and components - * 6. Setting up Livewire integration - */ public function boot(): void { FlasherContainer::from(static fn () => Container::getInstance()); @@ -102,22 +74,11 @@ final class FlasherServiceProvider extends PluginServiceProvider $this->registerLivewire(); } - /** - * Create the PHPFlasher core plugin instance. - * - * @return FlasherPlugin The core PHPFlasher plugin - */ public function createPlugin(): FlasherPlugin { return new FlasherPlugin(); } - /** - * Register the main Flasher service with Laravel's container. - * - * This service is the main entry point for all PHPFlasher functionality - * and is made available via the 'flasher' service binding. - */ private function registerFlasher(): void { $this->app->singleton('flasher', static function (Application $app) { @@ -135,12 +96,6 @@ final class FlasherServiceProvider extends PluginServiceProvider $this->app->bind(FlasherInterface::class, 'flasher'); } - /** - * Register the factory locator service. - * - * The factory locator is responsible for locating and providing - * notification factory instances. - */ private function registerFactoryLocator(): void { $this->app->singleton('flasher.factory_locator', static function () { @@ -148,12 +103,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the response manager service. - * - * The response manager is responsible for rendering notifications - * into different formats (HTML, JSON, etc.). - */ private function registerResponseManager(): void { $this->app->singleton('flasher.response_manager', static function (Application $app) { @@ -165,11 +114,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the template engine adapter for Blade. - * - * This adapter allows PHPFlasher to render templates using Laravel's Blade engine. - */ private function registerTemplateEngine(): void { $this->app->singleton('flasher.template_engine', static function (Application $app) { @@ -179,12 +123,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the resource manager service. - * - * The resource manager is responsible for managing assets (JS, CSS) - * needed by notifications. - */ private function registerResourceManager(): void { $this->app->singleton('flasher.resource_manager', static function (Application $app) { @@ -208,12 +146,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the storage manager service. - * - * The storage manager is responsible for storing and retrieving - * notifications from storage (session in Laravel's case). - */ private function registerStorageManager(): void { $this->app->singleton('flasher.storage_manager', static function (Application $app) { @@ -228,12 +160,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the event dispatcher and event listeners. - * - * The event dispatcher is responsible for dispatching events during - * the notification lifecycle. - */ private function registerEventDispatcher(): void { $this->app->singleton('flasher.notification_logger_listener', fn () => new NotificationLoggerListener()); @@ -259,11 +185,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the Artisan commands for PHPFlasher. - * - * Commands are only registered when running in console mode. - */ private function registerCommands(): void { if (!$this->app->runningInConsole()) { @@ -281,11 +202,6 @@ final class FlasherServiceProvider extends PluginServiceProvider $this->commands(InstallCommand::class); } - /** - * Register PHPFlasher information with Laravel's about command. - * - * This adds PHPFlasher information to the output of the `php artisan about` command. - */ private function registerAboutCommand(): void { if (!class_exists(AboutCommand::class)) { @@ -310,22 +226,12 @@ final class FlasherServiceProvider extends PluginServiceProvider ]); } - /** - * Register PHPFlasher middleware with Laravel. - * - * Middleware includes session processing and response modification. - */ private function registerMiddlewares(): void { $this->registerSessionMiddleware(); $this->registerFlasherMiddleware(); } - /** - * Register the response middleware. - * - * This middleware injects notification assets into responses. - */ private function registerFlasherMiddleware(): void { if (!$this->getConfig('inject_assets')) { @@ -345,11 +251,6 @@ final class FlasherServiceProvider extends PluginServiceProvider $this->pushMiddlewareToGroup(FlasherMiddleware::class); } - /** - * Register the session middleware. - * - * This middleware processes flash messages from the session. - */ private function registerSessionMiddleware(): void { if (!$this->getConfig('flash_bag')) { @@ -368,11 +269,6 @@ final class FlasherServiceProvider extends PluginServiceProvider $this->pushMiddlewareToGroup(SessionMiddleware::class); } - /** - * Push middleware to the web middleware group. - * - * @param string $middleware The middleware class name - */ private function pushMiddlewareToGroup(string $middleware): void { $this->callAfterResolving(HttpKernel::class, function (HttpKernel $kernel) use ($middleware) { @@ -380,11 +276,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the Content Security Policy handler. - * - * This service handles CSP headers when injecting assets. - */ private function registerCspHandler(): void { $this->app->singleton('flasher.csp_handler', static function () { @@ -392,11 +283,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register the asset manager service. - * - * The asset manager is responsible for managing asset paths and manifests. - */ private function registerAssetManager(): void { $this->app->singleton('flasher.asset_manager', static function () { @@ -407,11 +293,6 @@ final class FlasherServiceProvider extends PluginServiceProvider }); } - /** - * Register Blade directives and components. - * - * @param BladeCompiler $blade The Blade compiler instance - */ private function registerBladeDirectives(BladeCompiler $blade): void { $blade->directive('flasher_render', function (string $expression = '') { @@ -425,11 +306,6 @@ final class FlasherServiceProvider extends PluginServiceProvider $blade->component(FlasherComponent::class, 'flasher'); } - /** - * Register Livewire integration. - * - * This sets up listeners for Livewire component lifecycle events. - */ private function registerLivewire(): void { if (class_exists(LivewireManager::class) && !$this->app->bound('livewire')) { diff --git a/src/Laravel/Http/Request.php b/src/Laravel/Http/Request.php index c205a620..a36760fa 100644 --- a/src/Laravel/Http/Request.php +++ b/src/Laravel/Http/Request.php @@ -9,24 +9,10 @@ use Illuminate\Contracts\Session\Session; use Illuminate\Http\Request as LaravelRequest; /** - * Request - Adapter for Laravel HTTP requests. - * - * This adapter implements PHPFlasher's RequestInterface for Laravel HTTP requests, - * providing a consistent interface for request inspection and session interaction - * regardless of the underlying framework. - * - * Design patterns: - * - Adapter: Adapts framework-specific request objects to PHPFlasher's interface - * - Decorator: Adds PHPFlasher-specific functionality to request objects - * - Composition: Uses composition to delegate to the underlying request object + * Adapter for Laravel HTTP requests. */ final readonly class Request implements RequestInterface { - /** - * Creates a new Request adapter. - * - * @param LaravelRequest $request The underlying Laravel request object - */ public function __construct(private LaravelRequest $request) { } @@ -90,11 +76,6 @@ final readonly class Request implements RequestInterface $session?->forget($type); } - /** - * Gets the session from the request, with graceful handling of missing sessions. - * - * @return Session|null The session or null if not available - */ private function getSession(): ?Session { try { diff --git a/src/Laravel/Http/Response.php b/src/Laravel/Http/Response.php index c24717e7..c7ca1388 100644 --- a/src/Laravel/Http/Response.php +++ b/src/Laravel/Http/Response.php @@ -10,24 +10,10 @@ use Symfony\Component\HttpFoundation\JsonResponse as SymfonyJsonResponse; use Symfony\Component\HttpFoundation\Response as SymfonyResponse; /** - * Response - Adapter for Laravel/Symfony HTTP responses. - * - * This adapter implements PHPFlasher's ResponseInterface for Laravel and Symfony - * HTTP responses, providing a consistent interface for response manipulation - * regardless of the underlying framework. - * - * Design patterns: - * - Adapter: Adapts framework-specific response objects to PHPFlasher's interface - * - Decorator: Adds PHPFlasher-specific functionality to response objects - * - Composition: Uses composition to delegate to the underlying response object + * Adapter for Laravel/Symfony HTTP responses. */ final readonly class Response implements ResponseInterface { - /** - * Creates a new Response adapter. - * - * @param SymfonyResponse $response The underlying Symfony/Laravel response object - */ public function __construct(private SymfonyResponse $response) { } @@ -74,12 +60,6 @@ final readonly class Response implements ResponseInterface return $this->response->getContent() ?: ''; } - /** - * {@inheritdoc} - * - * This implementation preserves the original content in Laravel responses, - * ensuring compatibility with Laravel's view system and JSON responses. - */ public function setContent(string $content): void { $original = null; diff --git a/src/Laravel/Middleware/FlasherMiddleware.php b/src/Laravel/Middleware/FlasherMiddleware.php index b1ac7277..174cfbd0 100644 --- a/src/Laravel/Middleware/FlasherMiddleware.php +++ b/src/Laravel/Middleware/FlasherMiddleware.php @@ -11,39 +11,14 @@ use Illuminate\Http\Request as LaravelRequest; use Symfony\Component\HttpFoundation\Response as SymfonyResponse; /** - * FlasherMiddleware - Middleware for injecting PHPFlasher assets into responses. - * - * This middleware processes outgoing HTTP responses to inject PHPFlasher's - * JavaScript and CSS assets when needed. It's typically added to Laravel's - * web middleware group. - * - * Design patterns: - * - Pipeline: Participates in Laravel's middleware pipeline - * - Decorator: Decorates HTTP responses with PHPFlasher assets - * - Adapter: Adapts Laravel requests/responses to PHPFlasher interfaces + * Middleware for injecting PHPFlasher assets into responses. */ final readonly class FlasherMiddleware { - /** - * Creates a new FlasherMiddleware instance. - * - * @param ResponseExtensionInterface $responseExtension Service for extending responses with notifications - */ public function __construct(private ResponseExtensionInterface $responseExtension) { } - /** - * Handle an incoming request. - * - * Processes the response after the application has generated it, - * injecting PHPFlasher assets and notifications as needed. - * - * @param LaravelRequest $request The incoming request - * @param \Closure $next The next middleware handler - * - * @return mixed The processed response - */ public function handle(LaravelRequest $request, \Closure $next): mixed { $response = $next($request); diff --git a/src/Laravel/Middleware/SessionMiddleware.php b/src/Laravel/Middleware/SessionMiddleware.php index 366cddc8..9f1c4f5e 100644 --- a/src/Laravel/Middleware/SessionMiddleware.php +++ b/src/Laravel/Middleware/SessionMiddleware.php @@ -11,39 +11,14 @@ use Illuminate\Http\Request as LaravelRequest; use Symfony\Component\HttpFoundation\Response as SymfonyResponse; /** - * SessionMiddleware - Middleware for processing session flash messages. - * - * This middleware processes Laravel's session flash messages and converts them - * to PHPFlasher notifications, allowing seamless integration with existing code - * that uses Laravel's built-in flash messaging. - * - * Design patterns: - * - Pipeline: Participates in Laravel's middleware pipeline - * - Adapter: Adapts Laravel flash messages to PHPFlasher notifications - * - Transformer: Transforms one message format to another + * Middleware for processing session flash messages. */ final readonly class SessionMiddleware { - /** - * Creates a new SessionMiddleware instance. - * - * @param RequestExtensionInterface $requestExtension Service for processing request flash messages - */ public function __construct(private RequestExtensionInterface $requestExtension) { } - /** - * Handle an incoming request. - * - * Processes the request and response to convert Laravel flash messages - * to PHPFlasher notifications. - * - * @param LaravelRequest $request The incoming request - * @param \Closure $next The next middleware handler - * - * @return mixed The processed response - */ public function handle(LaravelRequest $request, \Closure $next): mixed { $response = $next($request); diff --git a/src/Laravel/Storage/SessionBag.php b/src/Laravel/Storage/SessionBag.php index 9aed595d..bec02643 100644 --- a/src/Laravel/Storage/SessionBag.php +++ b/src/Laravel/Storage/SessionBag.php @@ -9,38 +9,16 @@ use Flasher\Prime\Storage\Bag\BagInterface; use Illuminate\Session\SessionManager; /** - * SessionBag - Laravel session storage for PHPFlasher notifications. - * - * This class implements PHPFlasher's storage interface using Laravel's session - * system, providing persistence for notifications across requests. - * - * Design patterns: - * - Adapter: Adapts Laravel's session system to PHPFlasher's storage interface - * - Repository: Provides CRUD operations for notification storage + * Laravel session storage for PHPFlasher notifications. */ final readonly class SessionBag implements BagInterface { - /** - * Session key for storing notification envelopes. - */ public const ENVELOPES_NAMESPACE = 'flasher::envelopes'; - /** - * Creates a new SessionBag instance. - * - * @param SessionManager $session Laravel's session manager - */ public function __construct(private SessionManager $session) { } - /** - * {@inheritdoc} - * - * Retrieves all stored notification envelopes from the session. - * - * @return Envelope[] The stored notification envelopes - */ public function get(): array { /** @var Envelope[] $envelopes */ @@ -49,13 +27,6 @@ final readonly class SessionBag implements BagInterface return $envelopes; } - /** - * {@inheritdoc} - * - * Stores notification envelopes in the session. - * - * @param Envelope[] $envelopes The notification envelopes to store - */ public function set(array $envelopes): void { $this->session->put(self::ENVELOPES_NAMESPACE, $envelopes); diff --git a/src/Laravel/Support/PluginServiceProvider.php b/src/Laravel/Support/PluginServiceProvider.php index e5b987f0..228e55a9 100644 --- a/src/Laravel/Support/PluginServiceProvider.php +++ b/src/Laravel/Support/PluginServiceProvider.php @@ -12,18 +12,7 @@ use Illuminate\Contracts\Foundation\CachesConfiguration; use Illuminate\Support\ServiceProvider; /** - * PluginServiceProvider - Base service provider for PHPFlasher plugins. - * - * This abstract class provides the foundation for all PHPFlasher plugin - * service providers in Laravel. It handles the registration of plugin - * configuration, factories, and services. - * - * Design patterns: - * - Template Method: Defines the skeleton of registration process with customizable steps - * - Factory: Creates plugin instances via createPlugin method - * - Service Provider: Implements Laravel's service provider pattern - * - * Plugin providers should extend this class and implement the createPlugin method. + * Base service provider for PHPFlasher plugins in Laravel. */ abstract class PluginServiceProvider extends ServiceProvider { @@ -32,23 +21,8 @@ abstract class PluginServiceProvider extends ServiceProvider */ protected PluginInterface $plugin; - /** - * Create the plugin instance. - * - * Child classes must implement this method to provide their specific plugin. - * - * @return PluginInterface The plugin instance - */ abstract public function createPlugin(): PluginInterface; - /** - * Register services with the Laravel container. - * - * This method: - * 1. Creates the plugin instance - * 2. Registers plugin configuration - * 3. Calls the afterRegister hook for customization - */ public function register(): void { $this->plugin = $this->createPlugin(); @@ -57,37 +31,17 @@ abstract class PluginServiceProvider extends ServiceProvider $this->afterRegister(); } - /** - * Bootstrap services after all providers are registered. - * - * This method: - * 1. Registers the plugin factory - * 2. Calls the afterBoot hook for customization - */ public function boot(): void { $this->registerFactory(); $this->afterBoot(); } - /** - * Get the plugin's configuration file path. - * - * @return string The absolute path to the configuration file - */ public function getConfigurationFile(): string { return rtrim($this->getResourcesDir(), '/').'/config.php'; } - /** - * Get a configuration value with optional default. - * - * @param string|null $key The configuration key to retrieve, or null for all config - * @param mixed $default The default value to return if the key doesn't exist - * - * @return mixed The configuration value - */ protected function getConfig(?string $key = null, mixed $default = null): mixed { /** @var Repository $config */ @@ -96,11 +50,6 @@ abstract class PluginServiceProvider extends ServiceProvider return $key ? $config->get('flasher.'.$key, $default) : $config->get('flasher'); } - /** - * Get the plugin's resources directory path. - * - * @return string The absolute path to the resources directory - */ protected function getResourcesDir(): string { $r = new \ReflectionClass($this); @@ -108,12 +57,6 @@ abstract class PluginServiceProvider extends ServiceProvider return pathinfo($r->getFileName() ?: '', \PATHINFO_DIRNAME).'/Resources/'; } - /** - * Register the plugin's configuration. - * - * This method merges the plugin's default configuration with any user-defined - * configuration and registers it with Laravel's config repository. - */ protected function registerConfiguration(): void { if ($this->app instanceof CachesConfiguration && $this->app->configurationIsCached()) { @@ -136,32 +79,14 @@ abstract class PluginServiceProvider extends ServiceProvider $config->set($key, $this->plugin->normalizeConfig($current)); } - /** - * Hook method executed after registration. - * - * Child classes can override this method to add custom registration logic. - */ protected function afterRegister(): void { } - /** - * Hook method executed after boot. - * - * Child classes can override this method to add custom boot logic. - */ protected function afterBoot(): void { } - /** - * Register the plugin's notification factory. - * - * This method: - * 1. Registers the factory as a singleton - * 2. Registers any aliases for the factory - * 3. Adds the factory to the factory locator - */ protected function registerFactory(): void { $this->app->singleton($this->plugin->getServiceId(), function (Application $app) { diff --git a/src/Laravel/Template/BladeTemplateEngine.php b/src/Laravel/Template/BladeTemplateEngine.php index 5dc6f178..8e9c1033 100644 --- a/src/Laravel/Template/BladeTemplateEngine.php +++ b/src/Laravel/Template/BladeTemplateEngine.php @@ -8,37 +8,14 @@ use Flasher\Prime\Template\TemplateEngineInterface; use Illuminate\View\Factory; /** - * BladeTemplateEngine - Laravel Blade adapter for PHPFlasher templates. - * - * This class provides an implementation of PHPFlasher's template engine interface - * using Laravel's Blade templating system. It allows PHPFlasher to render templates - * using all of Blade's features. - * - * Design patterns: - * - Adapter: Adapts Laravel's Blade engine to PHPFlasher's template interface - * - Bridge: Connects PHPFlasher's templating needs with Laravel's templating system + * Laravel Blade adapter for PHPFlasher templates. */ final readonly class BladeTemplateEngine implements TemplateEngineInterface { - /** - * Creates a new BladeTemplateEngine instance. - * - * @param Factory $blade Laravel's view factory - */ public function __construct(private Factory $blade) { } - /** - * {@inheritdoc} - * - * Renders a template using Laravel's Blade engine. - * - * @param string $name The template name or path - * @param array $context The template variables - * - * @return string The rendered template - */ public function render(string $name, array $context = []): string { return $this->blade->make($name, $context)->render(); diff --git a/src/Laravel/Translation/Translator.php b/src/Laravel/Translation/Translator.php index 4c758271..aff1e7c1 100644 --- a/src/Laravel/Translation/Translator.php +++ b/src/Laravel/Translation/Translator.php @@ -8,42 +8,14 @@ use Flasher\Prime\Translation\TranslatorInterface; use Illuminate\Translation\Translator as LaravelTranslator; /** - * Translator - Laravel adapter for PHPFlasher translations. - * - * This class provides an implementation of PHPFlasher's translator interface - * using Laravel's translation system. It enables PHPFlasher notifications - * to be localized using Laravel's language files and translation workflow. - * - * Design patterns: - * - Adapter: Adapts Laravel's translator to PHPFlasher's interface - * - Decorator: Adds PHPFlasher-specific behavior to Laravel's translator + * Laravel adapter for PHPFlasher translations. */ final readonly class Translator implements TranslatorInterface { - /** - * Creates a new Translator instance. - * - * @param LaravelTranslator $translator Laravel's translator service - */ public function __construct(private LaravelTranslator $translator) { } - /** - * {@inheritdoc} - * - * Translates a message using Laravel's translation system. - * Tries multiple namespaces in this order: - * 1. flasher::messages.{id} - * 2. messages.{id} - * 3. {id} directly - * - * @param string $id The translation key - * @param array $parameters The parameters for variable substitution - * @param string|null $locale The locale to use, or null for default - * - * @return string The translated string - */ public function translate(string $id, array $parameters = [], ?string $locale = null): string { $parameters = $this->formatParameters($parameters); @@ -61,27 +33,15 @@ final readonly class Translator implements TranslatorInterface return $translation; } - /** - * {@inheritdoc} - * - * Gets the current locale from Laravel's translator. - * - * @return string The current locale code - */ public function getLocale(): string { return $this->translator->getLocale(); } /** - * Formats the parameters by stripping the colon prefix from keys for Laravel's translator. + * @param array $parameters * - * This ensures compatibility between PHPFlasher's parameter format (:parameter) - * and Laravel's parameter format (parameter). - * - * @param array $parameters The parameters with potential colon prefixes - * - * @return array The formatted parameters + * @return array */ private function formatParameters(array $parameters): array { diff --git a/src/Symfony/Attribute/AsFlasherFactory.php b/src/Symfony/Attribute/AsFlasherFactory.php index e05e0cb8..54ff1170 100644 --- a/src/Symfony/Attribute/AsFlasherFactory.php +++ b/src/Symfony/Attribute/AsFlasherFactory.php @@ -5,33 +5,11 @@ declare(strict_types=1); namespace Flasher\Symfony\Attribute; /** - * AsFlasherFactory - Attribute for tagging notification factories. - * - * This attribute enables auto-configuration of notification factory services in Symfony. - * When applied to a factory class, it automatically registers the class with the container - * using the specified alias, making it available to the PHPFlasher system. - * - * Design patterns: - * - Attribute-based Configuration: Uses PHP 8 attributes for declarative service configuration - * - Service Tagging: Implements Symfony's tag-based service discovery mechanism - * - * Usage: - * ```php - * #[AsFlasherFactory('toastr')] - * class ToastrFactory implements NotificationFactoryInterface - * { - * // ... - * } - * ``` + * Attribute for tagging notification factories. */ #[\Attribute(\Attribute::TARGET_CLASS)] final readonly class AsFlasherFactory { - /** - * Creates a new AsFlasherFactory attribute. - * - * @param string $alias The unique alias for the notification factory (e.g., 'toastr', 'noty') - */ public function __construct(public string $alias) { } diff --git a/src/Symfony/Attribute/AsFlasherPresenter.php b/src/Symfony/Attribute/AsFlasherPresenter.php index 20e8a02e..c09b076d 100644 --- a/src/Symfony/Attribute/AsFlasherPresenter.php +++ b/src/Symfony/Attribute/AsFlasherPresenter.php @@ -5,34 +5,11 @@ declare(strict_types=1); namespace Flasher\Symfony\Attribute; /** - * AsFlasherPresenter - Attribute for tagging response presenters. - * - * This attribute enables auto-configuration of response presenter services in Symfony. - * When applied to a presenter class, it automatically registers the class with the - * container using the specified alias, making it available to PHPFlasher's response system. - * - * Design patterns: - * - Attribute-based Configuration: Uses PHP 8 attributes for declarative service configuration - * - Service Tagging: Implements Symfony's tag-based service discovery mechanism - * - Strategy Pattern: Supports pluggable response formatting strategies - * - * Usage: - * ```php - * #[AsFlasherPresenter('html')] - * class HtmlPresenter implements PresenterInterface - * { - * // ... - * } - * ``` + * Attribute for tagging response presenters. */ #[\Attribute(\Attribute::TARGET_CLASS)] final readonly class AsFlasherPresenter { - /** - * Creates a new AsFlasherPresenter attribute. - * - * @param string $alias The unique alias for the presenter (e.g., 'html', 'json') - */ public function __construct(public string $alias) { } diff --git a/src/Symfony/Command/InstallCommand.php b/src/Symfony/Command/InstallCommand.php index 1bdda6a0..90fc5f7a 100644 --- a/src/Symfony/Command/InstallCommand.php +++ b/src/Symfony/Command/InstallCommand.php @@ -17,32 +17,15 @@ use Symfony\Component\Finder\Finder; use Symfony\Component\HttpKernel\KernelInterface; /** - * InstallCommand - Console command for installing PHPFlasher resources. - * - * This command provides a CLI interface for installing PHPFlasher resources, - * including assets (JS and CSS files) and configuration files. It discovers - * all registered PHPFlasher plugins and installs their resources. - * - * Design patterns: - * - Command Pattern: Implements the command pattern for console interaction - * - Discovery Pattern: Automatically discovers and processes registered plugins - * - Template Method Pattern: Defines a structured workflow with specific steps + * Console command for installing PHPFlasher resources. */ final class InstallCommand extends Command { - /** - * Creates a new InstallCommand instance. - * - * @param AssetManagerInterface $assetManager Manager for handling PHPFlasher assets - */ public function __construct(private readonly AssetManagerInterface $assetManager) { parent::__construct(); } - /** - * Configure the command options and help text. - */ protected function configure(): void { $this @@ -53,17 +36,6 @@ final class InstallCommand extends Command ->addOption('symlink', 's', InputOption::VALUE_NONE, 'Symlink PHPFlasher assets instead of copying them.'); } - /** - * Execute the command to install PHPFlasher resources. - * - * This method processes each registered bundle that implements PluginBundleInterface, - * installing its assets and configuration files as requested. - * - * @param InputInterface $input The input interface - * @param OutputInterface $output The output interface - * - * @return int Command status code (SUCCESS or FAILURE) - */ protected function execute(InputInterface $input, OutputInterface $output): int { // Display PHPFlasher banner and info message @@ -166,16 +138,7 @@ final class InstallCommand extends Command } /** - * Publishes assets from the plugin's assets directory to the public directory. - * - * This method copies or symlinks asset files from the plugin's assets directory - * to the public directory for web access. - * - * @param PluginInterface $plugin The plugin containing assets - * @param string $publicDir Target directory for assets - * @param bool $useSymlinks Whether to symlink files instead of copying - * - * @return string[] List of target paths for generated manifest + * @return string[] */ private function publishAssets(PluginInterface $plugin, string $publicDir, bool $useSymlinks): array { @@ -207,16 +170,6 @@ final class InstallCommand extends Command return $files; } - /** - * Publishes configuration files to the application's config directory. - * - * This method copies plugin configuration files to the Symfony config directory, - * but only if the target file doesn't already exist (to avoid overwriting user customizations). - * - * @param PluginInterface $plugin The plugin containing configuration - * @param string|null $configDir Target config directory - * @param string $configFile Source configuration file path - */ private function publishConfig(PluginInterface $plugin, ?string $configDir, string $configFile): void { if (null === $configDir || !file_exists($configFile)) { @@ -232,15 +185,6 @@ final class InstallCommand extends Command $filesystem->copy($configFile, $target); } - /** - * Gets the path to the public directory. - * - * This method tries to locate the public directory using multiple strategies: - * 1. First, it looks for a standard 'public' directory in the project - * 2. If not found, it falls back to the composer.json configuration - * - * @return string|null Path to the public directory or null if not found - */ private function getPublicDir(): ?string { $projectDir = $this->getProjectDir(); @@ -257,15 +201,6 @@ final class InstallCommand extends Command return $this->getComposerDir('public-dir'); } - /** - * Gets the path to the config directory. - * - * This method tries to locate the config/packages directory using multiple strategies: - * 1. First, it looks for a standard 'config/packages' directory in the project - * 2. If not found, it falls back to the composer.json configuration - * - * @return string|null Path to the config directory or null if not found - */ private function getConfigDir(): ?string { $projectDir = $this->getProjectDir(); @@ -283,11 +218,6 @@ final class InstallCommand extends Command return $this->getComposerDir('config-dir'); } - /** - * Gets the project root directory from the kernel. - * - * @return string|null The project directory path or null if not available - */ private function getProjectDir(): ?string { $kernel = $this->getKernel(); @@ -303,13 +233,6 @@ final class InstallCommand extends Command return \is_string($projectDir) ? $projectDir : null; } - /** - * Gets a directory path from composer.json extra configuration. - * - * @param string $dir The directory key to look for in composer.json extra section - * - * @return string|null The directory path or null if not found - */ private function getComposerDir(string $dir): ?string { $projectDir = $this->getProjectDir(); @@ -330,11 +253,6 @@ final class InstallCommand extends Command return $composerConfig['extra'][$dir] ?? null; } - /** - * Gets the kernel instance from the application. - * - * @return KernelInterface|null The Symfony kernel or null if not available - */ private function getKernel(): ?KernelInterface { $application = $this->getApplication(); diff --git a/src/Symfony/Component/FlasherComponent.php b/src/Symfony/Component/FlasherComponent.php index c3e17f84..d810d266 100644 --- a/src/Symfony/Component/FlasherComponent.php +++ b/src/Symfony/Component/FlasherComponent.php @@ -5,42 +5,15 @@ declare(strict_types=1); namespace Flasher\Symfony\Component; /** - * FlasherComponent - Twig component for rendering notifications. - * - * This class implements a Twig component that can be used in templates to render - * PHPFlasher notifications. It supports customizing the filtering criteria, - * presenter format, and rendering context. - * - * Design patterns: - * - Component-based Architecture: Implements Twig's component pattern - * - Data Transfer Object: Holds configuration for notification rendering - * - * Usage in templates: - * ```twig - * - * ``` + * Twig component for rendering PHPFlasher notifications. */ final class FlasherComponent { - /** - * Filtering criteria for notifications. - * - * @var array - */ + /** @var array */ public array $criteria = []; - /** - * Presentation format (e.g., 'html', 'json'). - */ public string $presenter = 'html'; - /** - * Additional context for rendering. - * - * @var array - */ + /** @var array */ public array $context = []; } diff --git a/src/Symfony/DependencyInjection/Compiler/EventListenerCompilerPass.php b/src/Symfony/DependencyInjection/Compiler/EventListenerCompilerPass.php index 4bcf5539..2bf39052 100644 --- a/src/Symfony/DependencyInjection/Compiler/EventListenerCompilerPass.php +++ b/src/Symfony/DependencyInjection/Compiler/EventListenerCompilerPass.php @@ -9,24 +9,10 @@ use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Reference; /** - * EventListenerCompilerPass - Registers event listeners with the event dispatcher. - * - * This compiler pass finds all services tagged with 'flasher.event_listener' - * and registers them with the PHPFlasher event dispatcher. This allows for - * automatic discovery and registration of event listeners. - * - * Design patterns: - * - Compiler Pass: Modifies container definitions during compilation - * - Service Discovery: Automatically discovers tagged services - * - Observer Pattern: Helps set up the event dispatch/observer system + * Registers event listeners with the event dispatcher. */ final class EventListenerCompilerPass implements CompilerPassInterface { - /** - * Process the container to register event listeners. - * - * @param ContainerBuilder $container The service container builder - */ public function process(ContainerBuilder $container): void { $definition = $container->findDefinition('flasher.event_dispatcher'); diff --git a/src/Symfony/DependencyInjection/Compiler/PresenterCompilerPass.php b/src/Symfony/DependencyInjection/Compiler/PresenterCompilerPass.php index 31558c00..3506cba4 100644 --- a/src/Symfony/DependencyInjection/Compiler/PresenterCompilerPass.php +++ b/src/Symfony/DependencyInjection/Compiler/PresenterCompilerPass.php @@ -10,24 +10,10 @@ use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Reference; /** - * PresenterCompilerPass - Registers response presenters with the response manager. - * - * This compiler pass finds all services tagged with 'flasher.presenter' - * and registers them with the PHPFlasher response manager. This allows for - * automatic discovery and registration of response presenters. - * - * Design patterns: - * - Compiler Pass: Modifies container definitions during compilation - * - Service Discovery: Automatically discovers tagged services - * - Strategy Pattern: Helps set up pluggable response presentation strategies + * Registers response presenters with the response manager. */ final class PresenterCompilerPass implements CompilerPassInterface { - /** - * Process the container to register presenters. - * - * @param ContainerBuilder $container The service container builder - */ public function process(ContainerBuilder $container): void { $definition = $container->findDefinition('flasher.response_manager'); diff --git a/src/Symfony/EventListener/FlasherListener.php b/src/Symfony/EventListener/FlasherListener.php index 639d202d..6d5256a3 100644 --- a/src/Symfony/EventListener/FlasherListener.php +++ b/src/Symfony/EventListener/FlasherListener.php @@ -11,36 +11,14 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\HttpKernel\Event\ResponseEvent; /** - * FlasherListener - Injects PHPFlasher assets into responses. - * - * This event subscriber listens for kernel.response events and injects - * PHPFlasher JavaScript and CSS assets into appropriate HTTP responses. - * It adapts Symfony's request and response objects to PHPFlasher's interfaces. - * - * Design patterns: - * - Observer Pattern: Observes Symfony's kernel events - * - Adapter Pattern: Adapts Symfony's request/response to PHPFlasher's interfaces - * - Event Subscriber: Subscribes to Symfony's event dispatcher system + * Injects PHPFlasher assets into responses. */ final readonly class FlasherListener implements EventSubscriberInterface { - /** - * Creates a new FlasherListener instance. - * - * @param ResponseExtensionInterface $responseExtension Service for extending responses with notifications - */ public function __construct(private ResponseExtensionInterface $responseExtension) { } - /** - * Processes the response to inject PHPFlasher assets. - * - * This handler adapts Symfony's request and response objects to PHPFlasher's - * interfaces, then delegates to the response extension for asset injection. - * - * @param ResponseEvent $event The response event - */ public function onKernelResponse(ResponseEvent $event): void { $request = new Request($event->getRequest()); @@ -49,14 +27,6 @@ final readonly class FlasherListener implements EventSubscriberInterface $this->responseExtension->render($request, $response); } - /** - * {@inheritdoc} - * - * Returns events this subscriber listens to and their corresponding handlers. - * The low priority (-20) ensures this runs after most other response listeners. - * - * @return array> The events and handlers - */ public static function getSubscribedEvents(): array { return [ diff --git a/src/Symfony/EventListener/SessionListener.php b/src/Symfony/EventListener/SessionListener.php index 040550e9..b781b8c8 100644 --- a/src/Symfony/EventListener/SessionListener.php +++ b/src/Symfony/EventListener/SessionListener.php @@ -11,36 +11,14 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\HttpKernel\Event\ResponseEvent; /** - * SessionListener - Processes session flash messages. - * - * This event subscriber listens for kernel.response events and converts - * Symfony's session flash messages to PHPFlasher notifications. This enables - * PHPFlasher to work with existing code that uses Symfony's flash messaging. - * - * Design patterns: - * - Observer Pattern: Observes Symfony's kernel events - * - Adapter Pattern: Adapts Symfony's flash messages to PHPFlasher notifications - * - Transformer Pattern: Transforms data from one format to another + * Processes session flash messages. */ final readonly class SessionListener implements EventSubscriberInterface { - /** - * Creates a new SessionListener instance. - * - * @param RequestExtensionInterface $requestExtension Service for processing request flash messages - */ public function __construct(private RequestExtensionInterface $requestExtension) { } - /** - * Processes the request to convert flash messages to notifications. - * - * This handler adapts Symfony's request and response objects to PHPFlasher's - * interfaces, then delegates to the request extension for flash processing. - * - * @param ResponseEvent $event The response event - */ public function onKernelResponse(ResponseEvent $event): void { $request = new Request($event->getRequest()); @@ -49,13 +27,6 @@ final readonly class SessionListener implements EventSubscriberInterface $this->requestExtension->flash($request, $response); } - /** - * {@inheritdoc} - * - * Returns events this subscriber listens to and their corresponding handlers. - * - * @return array> The events and handlers - */ public static function getSubscribedEvents(): array { return [ diff --git a/src/Symfony/Factory/NotificationFactoryLocator.php b/src/Symfony/Factory/NotificationFactoryLocator.php index 9315fe6e..41d22b82 100644 --- a/src/Symfony/Factory/NotificationFactoryLocator.php +++ b/src/Symfony/Factory/NotificationFactoryLocator.php @@ -8,51 +8,20 @@ use Flasher\Prime\Factory\NotificationFactoryInterface; use Flasher\Prime\Factory\NotificationFactoryLocatorInterface; use Symfony\Component\DependencyInjection\ServiceLocator; -/** - * NotificationFactoryLocator - Locator for notification factories using Symfony's ServiceLocator. - * - * This class adapts Symfony's ServiceLocator to PHPFlasher's NotificationFactoryLocatorInterface, - * enabling runtime discovery and lazy-loading of notification factories. - * - * Design patterns: - * - Adapter Pattern: Adapts Symfony's ServiceLocator to PHPFlasher's interface - * - Service Locator Pattern: Provides unified access to notification factory services - * - Lazy Loading: Services are only instantiated when requested - */ final readonly class NotificationFactoryLocator implements NotificationFactoryLocatorInterface { /** - * Creates a new NotificationFactoryLocator instance. - * - * @param ServiceLocator $serviceLocator Symfony's service locator + * @param ServiceLocator $serviceLocator */ public function __construct(private ServiceLocator $serviceLocator) { } - /** - * {@inheritdoc} - * - * Checks if a notification factory with the given ID exists. - * - * @param string $id The factory identifier - * - * @return bool True if the factory exists, false otherwise - */ public function has(string $id): bool { return $this->serviceLocator->has($id); } - /** - * {@inheritdoc} - * - * Gets a notification factory by ID. - * - * @param string $id The factory identifier - * - * @return NotificationFactoryInterface The notification factory - */ public function get(string $id): NotificationFactoryInterface { return $this->serviceLocator->get($id); diff --git a/src/Symfony/FlasherSymfonyBundle.php b/src/Symfony/FlasherSymfonyBundle.php index df8dd250..3260780d 100644 --- a/src/Symfony/FlasherSymfonyBundle.php +++ b/src/Symfony/FlasherSymfonyBundle.php @@ -14,24 +14,10 @@ use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Extension\ExtensionInterface; /** - * FlasherSymfonyBundle - Main bundle for PHPFlasher Symfony integration. - * - * This bundle serves as the entry point for integrating PHPFlasher with Symfony. - * It registers compiler passes, configures the container extension, and sets up - * the global container instance for PHPFlasher. - * - * Design patterns: - * - Bundle: Implements Symfony's bundle pattern for packaging functionality - * - Registry: Sets up the container registry for PHPFlasher - * - Extension: Extends the base plugin bundle with PHPFlasher-specific functionality + * Main bundle for PHPFlasher Symfony integration. */ final class FlasherSymfonyBundle extends Support\PluginBundle // Symfony\Component\HttpKernel\Bundle\Bundle { - /** - * Set up the global container reference when the bundle boots. - * - * This allows PHPFlasher to access services from Symfony's container. - */ public function boot(): void { if ($this->container instanceof ContainerInterface) { @@ -39,32 +25,17 @@ final class FlasherSymfonyBundle extends Support\PluginBundle // Symfony\Compone } } - /** - * Register compiler passes with the container. - * - * @param ContainerBuilder $container The container builder - */ public function build(ContainerBuilder $container): void { $container->addCompilerPass(new EventListenerCompilerPass()); $container->addCompilerPass(new PresenterCompilerPass()); } - /** - * Get the container extension for this bundle. - * - * @return ExtensionInterface The bundle extension - */ public function getContainerExtension(): ExtensionInterface { return new FlasherExtension($this->createPlugin()); } - /** - * Create the core PHPFlasher plugin. - * - * @return FlasherPlugin The core PHPFlasher plugin - */ public function createPlugin(): FlasherPlugin { return new FlasherPlugin(); diff --git a/src/Symfony/Http/Request.php b/src/Symfony/Http/Request.php index 5d28d536..894c2b08 100644 --- a/src/Symfony/Http/Request.php +++ b/src/Symfony/Http/Request.php @@ -11,24 +11,10 @@ use Symfony\Component\HttpFoundation\Session\FlashBagAwareSessionInterface; use Symfony\Component\HttpFoundation\Session\SessionInterface; /** - * Request - Adapter for Symfony's HTTP request. - * - * This class implements PHPFlasher's RequestInterface for Symfony's HTTP request, - * providing a consistent interface for request inspection and session interaction - * regardless of the underlying framework. - * - * Design patterns: - * - Adapter Pattern: Adapts framework-specific request to PHPFlasher's interface - * - Decorator Pattern: Adds PHPFlasher-specific functionality to request objects - * - Null Object Pattern: Gracefully handles missing sessions + * Adapter for Symfony's HTTP request. */ final readonly class Request implements RequestInterface { - /** - * Creates a new Request adapter. - * - * @param SymfonyRequest $request The underlying Symfony request object - */ public function __construct(private SymfonyRequest $request) { } @@ -92,11 +78,6 @@ final readonly class Request implements RequestInterface $this->getType($type); } - /** - * Gets the session from the request, with graceful handling of missing sessions. - * - * @return SessionInterface|null The session or null if not available - */ private function getSession(): ?SessionInterface { try { diff --git a/src/Symfony/Http/Response.php b/src/Symfony/Http/Response.php index 66097d49..ee8073a6 100644 --- a/src/Symfony/Http/Response.php +++ b/src/Symfony/Http/Response.php @@ -9,24 +9,10 @@ use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\HttpFoundation\Response as SymfonyResponse; /** - * Response - Adapter for Symfony's HTTP response. - * - * This class implements PHPFlasher's ResponseInterface for Symfony's HTTP response, - * providing a consistent interface for response manipulation regardless of the framework. - * It allows PHPFlasher to work with Symfony responses in a framework-agnostic way. - * - * Design patterns: - * - Adapter Pattern: Adapts framework-specific response to PHPFlasher's interface - * - Decorator Pattern: Adds PHPFlasher-specific functionality to response objects - * - Composition: Uses composition to delegate to the underlying response object + * Adapter for Symfony's HTTP response. */ final readonly class Response implements ResponseInterface { - /** - * Creates a new Response adapter. - * - * @param SymfonyResponse $response The underlying Symfony response object - */ public function __construct(private SymfonyResponse $response) { } diff --git a/src/Symfony/Profiler/FlasherDataCollector.php b/src/Symfony/Profiler/FlasherDataCollector.php index 2acd4a03..f50f349a 100644 --- a/src/Symfony/Profiler/FlasherDataCollector.php +++ b/src/Symfony/Profiler/FlasherDataCollector.php @@ -15,16 +15,7 @@ use Symfony\Component\HttpKernel\Kernel; use Symfony\Component\VarDumper\Cloner\Data; /** - * FlasherDataCollector - Collects PHPFlasher data for the Symfony profiler. - * - * This data collector captures information about PHPFlasher notifications, - * both dispatched and displayed, for the Symfony web profiler. It also collects - * configuration and version information. - * - * Design patterns: - * - Data Collector: Implements Symfony's data collector pattern for profiling - * - Late Collection: Collects data after a request is completed - * - Type Safety: Uses PHPDoc annotations for complex type declarations + * Collects PHPFlasher data for the Symfony profiler. * * @phpstan-type NotificationShape array{ * title: string, @@ -62,11 +53,6 @@ use Symfony\Component\VarDumper\Cloner\Data; final class FlasherDataCollector extends AbstractDataCollector implements LateDataCollectorInterface { /** - * Creates a new FlasherDataCollector instance. - * - * @param NotificationLoggerListener $logger The notification logger for accessing dispatched notifications - * @param array $config The PHPFlasher configuration - * * @phpstan-param ConfigShare $config */ public function __construct( @@ -75,25 +61,11 @@ final class FlasherDataCollector extends AbstractDataCollector implements LateDa ) { } - /** - * Initial data collection - called during request processing. - * - * This implementation doesn't collect data here, deferring to lateCollect. - * - * @param Request $request The request object - * @param Response $response The response object - * @param \Throwable|null $exception Any exception that occurred - */ public function collect(Request $request, Response $response, ?\Throwable $exception = null): void { // No action needed here since we're collecting data in lateCollect } - /** - * Late data collection - called after response is sent. - * - * Collects information about notifications, configuration, and versions. - */ public function lateCollect(): void { $this->data = [ @@ -111,28 +83,18 @@ final class FlasherDataCollector extends AbstractDataCollector implements LateDa } /** - * Gets the collector data. - * - * @return DataShape|Data + * @return array|Data */ public function getData(): array|Data { return $this->data; } - /** - * Gets the collector name for the profiler panel. - * - * @return string The collector name - */ public function getName(): string { return 'flasher'; } - /** - * Resets the collector between requests when using kernel.reset. - */ public function reset(): void { $this->logger->reset(); @@ -140,9 +102,7 @@ final class FlasherDataCollector extends AbstractDataCollector implements LateDa } /** - * Gets the displayed notification envelopes. - * - * @return NotificationShape[]|Data + * @return array|Data */ public function getDisplayedEnvelopes(): array|Data { @@ -150,9 +110,7 @@ final class FlasherDataCollector extends AbstractDataCollector implements LateDa } /** - * Gets the dispatched notification envelopes. - * - * @return NotificationShape[]|Data + * @return array|Data */ public function getDispatchedEnvelopes(): array|Data { @@ -160,8 +118,6 @@ final class FlasherDataCollector extends AbstractDataCollector implements LateDa } /** - * Gets the PHPFlasher configuration. - * * @phpstan-return ConfigShare|Data */ public function getConfig(): array|Data @@ -170,20 +126,13 @@ final class FlasherDataCollector extends AbstractDataCollector implements LateDa } /** - * Gets version information. - * - * @return array{php_flasher: string, php: string, symfony: string}|Data + * @return array|Data */ public function getVersions(): array|Data { return $this->data['versions'] ?? []; } - /** - * Gets the template path for the profiler panel. - * - * @return string The template path - */ public static function getTemplate(): string { return '@FlasherSymfony/profiler/flasher.html.twig'; diff --git a/src/Symfony/Storage/FallbackSession.php b/src/Symfony/Storage/FallbackSession.php index 768fe3bd..7ede012b 100644 --- a/src/Symfony/Storage/FallbackSession.php +++ b/src/Symfony/Storage/FallbackSession.php @@ -5,24 +5,11 @@ declare(strict_types=1); namespace Flasher\Symfony\Storage; /** - * FallbackSession - In-memory session storage fallback. - * - * This class provides a simple in-memory storage mechanism that can be used - * when the regular Symfony session is not available. It stores values in a - * static array, making them available for the duration of the request. - * - * Design patterns: - * - Null Object Pattern: Provides a non-failing alternative to a missing session - * - In-Memory Repository: Stores data in memory as a simple alternative to persistence - * - Singleton-like Pattern: Uses a static storage array shared across instances + * In-memory session storage fallback. */ final class FallbackSession implements FallbackSessionInterface { - /** - * In-memory storage for session data. - * - * @var array - */ + /** @var array */ private static array $storage = []; public function get(string $name, mixed $default = null): mixed diff --git a/src/Symfony/Storage/FallbackSessionInterface.php b/src/Symfony/Storage/FallbackSessionInterface.php index bf7b7903..6f1c9cdf 100644 --- a/src/Symfony/Storage/FallbackSessionInterface.php +++ b/src/Symfony/Storage/FallbackSessionInterface.php @@ -5,34 +5,11 @@ declare(strict_types=1); namespace Flasher\Symfony\Storage; /** - * FallbackSessionInterface - Contract for alternative session storage. - * - * This interface defines methods for a fallback storage mechanism when the - * regular Symfony session is not available. This is particularly useful in - * stateless contexts or when the session hasn't been started. - * - * Design patterns: - * - Interface Segregation: Defines a minimal interface for session-like storage - * - Strategy Pattern: Allows different storage implementations to be used - * - Fallback Strategy: Provides an alternative when primary storage is unavailable + * Contract for alternative session storage. */ interface FallbackSessionInterface { - /** - * Retrieves a value from the fallback session storage. - * - * @param string $name the name of the value - * @param mixed $default the default value to return if the name is not found - * - * @return mixed the value from storage or default - */ public function get(string $name, mixed $default = null): mixed; - /** - * Stores a value in the fallback session storage. - * - * @param string $name the name of the value to store - * @param mixed $value the value to store - */ public function set(string $name, mixed $value): void; } diff --git a/src/Symfony/Storage/SessionBag.php b/src/Symfony/Storage/SessionBag.php index 8002b8ee..5115cafa 100644 --- a/src/Symfony/Storage/SessionBag.php +++ b/src/Symfony/Storage/SessionBag.php @@ -11,48 +11,19 @@ use Symfony\Component\HttpFoundation\RequestStack; use Symfony\Component\HttpFoundation\Session\SessionInterface; /** - * SessionBag - Symfony session storage for PHPFlasher notifications. - * - * This class implements PHPFlasher's storage interface using Symfony's session - * system, providing persistence for notifications across requests. It includes - * fallback behavior for stateless contexts. - * - * Design patterns: - * - Adapter Pattern: Adapts Symfony's session to PHPFlasher's storage interface - * - Strategy Pattern: Uses different storage strategies based on context - * - Fallback Strategy: Falls back to in-memory storage when session unavailable - * - Repository Pattern: Provides CRUD operations for notification storage + * Symfony session storage for PHPFlasher notifications. */ final readonly class SessionBag implements BagInterface { - /** - * Session key for storing notification envelopes. - */ public const ENVELOPES_NAMESPACE = 'flasher::envelopes'; - /** - * Fallback storage for contexts where session is unavailable. - */ private FallbackSessionInterface $fallbackSession; - /** - * Creates a new SessionBag instance. - * - * @param RequestStack $requestStack Symfony's request stack for accessing session - * @param FallbackSessionInterface|null $fallbackSession Optional custom fallback storage - */ public function __construct(private RequestStack $requestStack, ?FallbackSessionInterface $fallbackSession = null) { $this->fallbackSession = $fallbackSession ?: new FallbackSession(); } - /** - * {@inheritdoc} - * - * Gets all notification envelopes from storage. - * - * @return Envelope[] The stored notification envelopes - */ public function get(): array { $session = $this->getSession(); @@ -63,13 +34,6 @@ final readonly class SessionBag implements BagInterface return $envelopes; } - /** - * {@inheritdoc} - * - * Stores notification envelopes in storage. - * - * @param array $envelopes The notification envelopes to store - */ public function set(array $envelopes): void { $session = $this->getSession(); @@ -77,14 +41,6 @@ final readonly class SessionBag implements BagInterface $session->set(self::ENVELOPES_NAMESPACE, $envelopes); } - /** - * Gets the appropriate session storage implementation. - * - * Uses Symfony session if available and request is not stateless, - * otherwise falls back to the fallback session implementation. - * - * @return SessionInterface|FallbackSessionInterface The storage implementation - */ private function getSession(): SessionInterface|FallbackSessionInterface { try { diff --git a/src/Symfony/Support/PluginBundle.php b/src/Symfony/Support/PluginBundle.php index f6a7d2c5..7626357d 100644 --- a/src/Symfony/Support/PluginBundle.php +++ b/src/Symfony/Support/PluginBundle.php @@ -11,40 +11,14 @@ use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigura use Symfony\Component\HttpKernel\Bundle\AbstractBundle; /** - * PluginBundle - Base class for PHPFlasher plugin bundles. - * - * This abstract class provides common functionality for all PHPFlasher plugin bundles. - * It extends Symfony's AbstractBundle to integrate with the kernel bundle system, - * while implementing PluginBundleInterface to provide PHPFlasher-specific functionality. - * - * Design patterns: - * - Template Method: Defines skeleton of common bundle operations - * - Factory Method: Creates plugin instances - * - Bridge: Connects Symfony bundle system with PHPFlasher plugin system - * - Extension: Extends AbstractBundle with PHPFlasher-specific functionality + * Base class for PHPFlasher plugin bundles. */ abstract class PluginBundle extends AbstractBundle implements PluginBundleInterface { - /** - * Creates an instance of the plugin. - * - * This factory method must be implemented by child classes to instantiate - * the specific plugin that the bundle integrates. - * - * @return PluginInterface The plugin instance - */ abstract public function createPlugin(): PluginInterface; /** - * Loads bundle configuration into the Symfony container. - * - * This method registers the plugin's factory service in the container and - * configures it appropriately. The core FlasherSymfonyBundle is exempt from - * this process since it has special handling. - * - * @param array $config The processed bundle configuration - * @param ContainerConfigurator $container The container configurator - * @param ContainerBuilder $builder The container builder + * @param array $config */ public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void { @@ -67,15 +41,6 @@ abstract class PluginBundle extends AbstractBundle implements PluginBundleInterf } } - /** - * Prepends default plugin configuration for Flasher. - * - * This method adds the plugin's scripts, styles, and options to the Flasher - * configuration before the container is compiled. - * - * @param ContainerConfigurator $container The container configurator - * @param ContainerBuilder $builder The container builder - */ public function prependExtension(ContainerConfigurator $container, ContainerBuilder $builder): void { if ($this instanceof FlasherSymfonyBundle) { @@ -95,27 +60,11 @@ abstract class PluginBundle extends AbstractBundle implements PluginBundleInterf ]); } - /** - * Gets the path to the plugin's configuration file. - * - * Returns the absolute path to the plugin's configuration file - * based on the bundle's path. - * - * @return string Absolute path to the configuration file - */ public function getConfigurationFile(): string { return rtrim($this->getPath(), '/').'/Resources/config/config.yaml'; } - /** - * Gets the bundle's directory path. - * - * Uses reflection to determine the location of the bundle class file, - * then returns its directory. - * - * @return string The bundle directory path - */ public function getPath(): string { if (!isset($this->path)) { diff --git a/src/Symfony/Support/PluginBundleInterface.php b/src/Symfony/Support/PluginBundleInterface.php index 1b2850d3..62c36940 100644 --- a/src/Symfony/Support/PluginBundleInterface.php +++ b/src/Symfony/Support/PluginBundleInterface.php @@ -7,32 +7,11 @@ namespace Flasher\Symfony\Support; use Flasher\Prime\Plugin\PluginInterface; /** - * PluginBundleInterface - Contract for PHPFlasher plugin bundles. - * - * This interface defines the basic requirements for a Symfony bundle that - * integrates a PHPFlasher plugin. It focuses on plugin creation and configuration. - * - * Design patterns: - * - Factory Method: Defines interface for creating plugin instances - * - Plugin Architecture: Supports extensible plugin system - * - Bridge: Connects Symfony bundle system with PHPFlasher plugin system + * Contract for PHPFlasher plugin bundles. */ interface PluginBundleInterface { - /** - * Creates an instance of the plugin. - * - * This factory method is responsible for instantiating the plugin that - * this bundle integrates with Symfony. - * - * @return PluginInterface The plugin instance - */ public function createPlugin(): PluginInterface; - /** - * Gets the path to the plugin's configuration file. - * - * @return string Absolute path to the configuration file - */ public function getConfigurationFile(): string; } diff --git a/src/Symfony/Template/TwigTemplateEngine.php b/src/Symfony/Template/TwigTemplateEngine.php index 652ef9ee..6c97058c 100644 --- a/src/Symfony/Template/TwigTemplateEngine.php +++ b/src/Symfony/Template/TwigTemplateEngine.php @@ -8,37 +8,14 @@ use Flasher\Prime\Template\TemplateEngineInterface; use Twig\Environment; /** - * TwigTemplateEngine - Adapter for Symfony's Twig template engine. - * - * This class adapts Symfony's Twig environment to PHPFlasher's template engine - * interface, enabling notification templates to be rendered using Twig. - * - * Design patterns: - * - Adapter Pattern: Adapts Twig to PHPFlasher's template interface - * - Null Object Pattern: Gracefully handles a missing Twig dependency - * - Bridge Pattern: Bridges PHPFlasher's templating needs with Symfony's templating system + * Adapter for Symfony's Twig template engine. */ final readonly class TwigTemplateEngine implements TemplateEngineInterface { - /** - * Creates a new TwigTemplateEngine instance. - * - * @param Environment|null $twig The Twig environment or null if Twig is not available - */ public function __construct(private ?Environment $twig = null) { } - /** - * Renders a template using Twig. - * - * @param string $name The template name or path - * @param array $context The template variables - * - * @return string The rendered template - * - * @throws \LogicException If Twig is not available - */ public function render(string $name, array $context = []): string { if (null === $this->twig) { diff --git a/src/Symfony/Translation/Translator.php b/src/Symfony/Translation/Translator.php index 63a3fa1b..49d00750 100644 --- a/src/Symfony/Translation/Translator.php +++ b/src/Symfony/Translation/Translator.php @@ -9,42 +9,14 @@ use Symfony\Component\Translation\TranslatorBagInterface; use Symfony\Contracts\Translation\TranslatorInterface as SymfonyTranslatorInterface; /** - * Translator - Adapter for Symfony's translation service. - * - * This class adapts Symfony's translation system to PHPFlasher's TranslatorInterface, - * enabling notification messages to be translated using Symfony's translation capabilities. - * It searches for messages in multiple domains with cascading fallbacks. - * - * Design patterns: - * - Adapter Pattern: Adapts Symfony's translator interface to PHPFlasher's interface - * - Facade Pattern: Simplifies the translation process with a unified interface - * - Chain of Responsibility: Tries multiple translation domains in sequence + * Adapter for Symfony's translation service. */ final readonly class Translator implements TranslatorInterface { - /** - * Creates a new Translator instance. - * - * @param SymfonyTranslatorInterface $translator The Symfony translator service - */ public function __construct(private SymfonyTranslatorInterface $translator) { } - /** - * Translates a message using Symfony's translation system. - * - * This method attempts to translate the message in the following order: - * 1. In the 'flasher' domain (flasher-specific translations) - * 2. In the 'messages' domain (application-wide translations) - * 3. Returns the original ID if no translation is found - * - * @param string $id The message ID or key - * @param array $parameters The translation parameters - * @param string|null $locale The locale or null to use the default - * - * @return string The translated string - */ public function translate(string $id, array $parameters = [], ?string $locale = null): string { if (!$this->translator instanceof TranslatorBagInterface) { @@ -62,13 +34,6 @@ final readonly class Translator implements TranslatorInterface return $id; } - /** - * Gets the current locale from Symfony's translator. - * - * Falls back to system default locale if translator doesn't provide one. - * - * @return string The current locale code - */ public function getLocale(): string { if (method_exists($this->translator, 'getLocale')) { // @phpstan-ignore-line diff --git a/src/Symfony/Twig/FlasherTwigExtension.php b/src/Symfony/Twig/FlasherTwigExtension.php index fcbc0209..2152d04d 100644 --- a/src/Symfony/Twig/FlasherTwigExtension.php +++ b/src/Symfony/Twig/FlasherTwigExtension.php @@ -9,33 +9,14 @@ use Twig\Extension\AbstractExtension; use Twig\TwigFunction; /** - * FlasherTwigExtension - Twig extension for rendering notifications. - * - * This class provides Twig functions that allow notification rendering - * directly from Twig templates. It exposes PHPFlasher's rendering - * capabilities to template files. - * - * Design patterns: - * - Extension Pattern: Extends Twig's functionality - * - Adapter Pattern: Adapts PHPFlasher's API for Twig templates - * - Delegation: Delegates actual rendering to the Flasher service + * Twig extension for rendering PHPFlasher notifications. */ final class FlasherTwigExtension extends AbstractExtension { - /** - * Creates a new FlasherTwigExtension instance. - * - * @param FlasherInterface $flasher The PHPFlasher service - */ public function __construct(private readonly FlasherInterface $flasher) { } - /** - * Returns the Twig functions provided by this extension. - * - * @return TwigFunction[] Array of Twig functions - */ public function getFunctions(): array { return [ @@ -44,13 +25,8 @@ final class FlasherTwigExtension extends AbstractExtension } /** - * Renders the flash notifications based on the specified criteria, presenter, and context. - * - * @param array $criteria the criteria to filter the notifications - * @param "html"|"json"|string $presenter The presenter format for rendering the notifications (e.g., 'html', 'json'). - * @param array $context additional context or options for rendering - * - * @return mixed The rendered output (HTML string, JSON string, etc.) + * @param array $criteria + * @param array $context */ public function render(array $criteria = [], string $presenter = 'html', array $context = []): mixed {