leviathonbeast/php-flasher
1
0
Fork 0
mirror of https://github.com/php-flasher/php-flasher.git synced 2026-03-31 15:07:47 +01:00
Code Issues Packages Projects Releases Wiki Activity

Simplify PHPDoc comments in SweetAlert integration

Browse Source 
Remove verbose documentation pattern references and redundant
explanations, keeping only essential type annotations.
This commit is contained in:
Younes ENNAJI
2026-01-15 23:08:40 +01:00
parent fcf5c63f58
commit e212c0157e
12 changed files with 20 additions and 612 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Noty/Prime/NotyBuilder.php
+1 -1
View File
@@ -180,7 +180,7 @@ final class NotyBuilder extends NotificationBuilder
}
/**
* @param 'open'|'close' $option
* @param 'open'|'close' $option
* @param 'noty_effects_open'|'noty_effects_close'|string $effect
*/
public function animation(string $option, string $effect): self
src/Notyf/Prime/NotyfBuilder.php
+1 -1
View File
@@ -36,7 +36,7 @@ final class NotyfBuilder extends NotificationBuilder
}
/**
* @param 'x'|'y' $position
* @param 'x'|'y' $position
* @param 'left'|'center'|'right'|'top'|'bottom' $value
*
* @phpstan-param ($position is 'x' ? "left"|"center"|"right" : "top"|"center"|"bottom") $value
src/SweetAlert/Laravel/Facade/SweetAlert.php
-34
View File
@@ -10,35 +10,6 @@ use Flasher\SweetAlert\Prime\SweetAlertBuilder;
use Illuminate\Support\Facades\Facade;
/**
* SweetAlert - Laravel facade for SweetAlert notifications.
*
* This facade provides a static interface to SweetAlert's extensive functionality within Laravel,
* following Laravel's facade pattern. It offers comprehensive IDE autocompletion for all
* SweetAlert builder methods, making it easy to create rich interactive dialogs.
*
* Design patterns:
* - Facade: Provides a simplified, static interface to a complex subsystem
* - Proxy: Acts as a proxy to the underlying SweetAlert service
*
* Usage examples:
* ```php
* // Simple notification
* SweetAlert::success('Operation completed successfully');
*
* // Confirmation dialog
* SweetAlert::question('Are you sure?')
* ->showCancelButton()
* ->confirmButtonText('Yes, delete it!')
* ->cancelButtonText('Cancel')
* ->push();
*
* // Input form dialog
* SweetAlert::title('Enter your email')
* ->input('email')
* ->inputPlaceholder('name@example.com')
* ->push();
* ```
*
* @method static SweetAlertBuilder success(string $message, array<string, mixed> $options = array())
* @method static SweetAlertBuilder error(string $message, array<string, mixed> $options = array())
* @method static SweetAlertBuilder warning(string $message, array<string, mixed> $options = array())
@@ -128,11 +99,6 @@ use Illuminate\Support\Facades\Facade;
*/
final class SweetAlert extends Facade
{
/**
* Get the registered name of the component.
*
* @return string The service container binding key for SweetAlert
*/
protected static function getFacadeAccessor(): string
{
return 'flasher.sweetalert';
src/SweetAlert/Laravel/FlasherSweetAlertServiceProvider.php
-30
View File
@@ -8,48 +8,18 @@ use Flasher\Laravel\Support\PluginServiceProvider;
use Flasher\Prime\EventDispatcher\EventDispatcherInterface;
use Flasher\SweetAlert\Prime\SweetAlertPlugin;
/**
* FlasherSweetAlertServiceProvider - Laravel service provider for SweetAlert2 integration.
*
* This service provider registers the SweetAlert2 plugin with Laravel's service container
* and sets up the Livewire integration for interactive dialogs. It extends the base plugin
* service provider to inherit common registration logic while providing SweetAlert-specific
* plugin implementation and event listeners.
*
* Design patterns:
* - Service Provider: Implements Laravel's service provider pattern
* - Factory Method: Creates the plugin instance
* - Observer: Registers event listeners for framework integration
*/
final class FlasherSweetAlertServiceProvider extends PluginServiceProvider
{
/**
* Creates the SweetAlert plugin instance.
*
* @return SweetAlertPlugin The SweetAlert plugin instance
*/
public function createPlugin(): SweetAlertPlugin
{
return new SweetAlertPlugin();
}
/**
* Performs additional setup after the service provider is booted.
*
* This method is called after all service providers have been registered.
* It's used here to set up the Livewire integration for interactive dialogs.
*/
protected function afterBoot(): void
{
$this->registerLivewireListener();
}
/**
* Registers the Livewire event listener for SweetAlert dialogs.
*
* This listener enables SweetAlert's interactive dialogs to work with
* Livewire's AJAX-based component updates.
*/
private function registerLivewireListener(): void
{
if (!$this->app->bound('livewire')) {
src/SweetAlert/Laravel/LivewireListener.php
-27
View File
@@ -7,30 +7,8 @@ namespace Flasher\SweetAlert\Laravel;
use Flasher\Prime\EventDispatcher\Event\ResponseEvent;
use Flasher\Prime\EventDispatcher\EventListener\EventListenerInterface;
/**
* LivewireListener - Enables SweetAlert interactivity with Livewire components.
*
* This event listener injects JavaScript code that bridges SweetAlert's promise-based
* API with Livewire's event system. It enables Livewire components to respond to
* user interactions with SweetAlert dialogs (confirm, deny, dismiss actions).
*
* Design patterns:
* - Observer: Observes PHPFlasher response events
* - Bridge: Connects SweetAlert's JavaScript API to Livewire's event system
* - Event-driven: Uses event-driven architecture for loose coupling
*/
final readonly class LivewireListener implements EventListenerInterface
{
/**
* Handles the response event by injecting SweetAlert-Livewire bridge code.
*
* When an HTML response is being prepared, this method adds JavaScript that will:
* 1. Listen for SweetAlert promise events
* 2. Forward these events to the appropriate Livewire component
* 3. Include payload data for the component to process
*
* @param ResponseEvent $event The response event being processed
*/
public function __invoke(ResponseEvent $event): void
{
// Only process HTML responses
@@ -92,11 +70,6 @@ JAVASCRIPT;
$event->setResponse($response);
}
/**
* Specifies which events this listener should subscribe to.
*
* @return string The event class name this listener handles
*/
public function getSubscribedEvents(): string
{
return ResponseEvent::class;
src/SweetAlert/Prime/SweetAlert.php
-18
View File
@@ -7,28 +7,10 @@ namespace Flasher\SweetAlert\Prime;
use Flasher\Prime\Factory\NotificationFactory;
/**
* SweetAlert - Factory implementation for SweetAlert2 notifications.
*
* This class implements the notification factory for SweetAlert2, creating
* specialized notification builders configured for SweetAlert2's extensive feature set.
* It serves as the primary entry point for creating SweetAlert notifications.
*
* Design patterns:
* - Factory: Creates specialized notification builders
* - Bridge: Connects PHPFlasher's notification system to SweetAlert2
* - Composition: Delegates to SweetAlertBuilder for construction details
*
* @mixin \Flasher\SweetAlert\Prime\SweetAlertBuilder
*/
final class SweetAlert extends NotificationFactory implements SweetAlertInterface
{
/**
* {@inheritdoc}
*
* Creates a new SweetAlert-specific notification builder.
*
* @return SweetAlertBuilder A builder configured for SweetAlert2 notifications
*/
public function createNotificationBuilder(): SweetAlertBuilder
{
return new SweetAlertBuilder('sweetalert', $this->storageManager);
src/SweetAlert/Prime/SweetAlertBuilder.php
+10 -374
View File
@@ -8,21 +8,6 @@ use Flasher\Prime\Notification\Envelope;
use Flasher\Prime\Notification\NotificationBuilder;
/**
* SweetAlertBuilder - Builder implementation for SweetAlert2 notifications.
*
* This class provides a comprehensive fluent interface for configuring
* SweetAlert2 notifications. It extends the core notification builder with
* SweetAlert2's extensive range of options, including modal dialogs, custom
* styling, input forms, and interactive features.
*
* SweetAlert2 is a complete replacement for JavaScript's alert(), confirm(),
* and prompt() functions, offering far more customization and interactivity.
*
* Design patterns:
* - Builder: Provides a fluent interface for constructing complex objects
* - Fluent Interface: Methods return $this for method chaining
* - Type Safety: Uses PHPStan annotations for compile-time type checking
*
* @phpstan-type NotificationType "success"|"info"|"warning"|"error"|"question"
* @phpstan-type CustomClassType "container"|"popup"|"header"|"title"|"closeButton"|"icon"|"image"|"content"|"input"|"inputLabel"|"validationMessage"|"actions"|"confirmButton"|"denyButton"|"cancelButton"|"loader"|"footer"
* @phpstan-type OptionsType array{
@@ -98,11 +83,7 @@ use Flasher\Prime\Notification\NotificationBuilder;
final class SweetAlertBuilder extends NotificationBuilder
{
/**
* Sets the notification type with SweetAlert-specific type checking.
*
* @phpstan-param NotificationType $type The notification type
*
* @return static The builder instance
* @phpstan-param NotificationType $type
*/
public function type(string $type): static
{
@@ -110,13 +91,7 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Creates a success notification with SweetAlert-specific options.
*
* @param string $message The notification message
* @param OptionsType $options SweetAlert-specific options
* @param string|null $title The notification title
*
* @return Envelope The notification envelope
* @phpstan-param OptionsType $options
*/
public function success(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -124,13 +99,7 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Creates an error notification with SweetAlert-specific options.
*
* @param string $message The notification message
* @param OptionsType $options SweetAlert-specific options
* @param string|null $title The notification title
*
* @return Envelope The notification envelope
* @phpstan-param OptionsType $options
*/
public function error(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -138,13 +107,7 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Creates an info notification with SweetAlert-specific options.
*
* @param string $message The notification message
* @param OptionsType $options SweetAlert-specific options
* @param string|null $title The notification title
*
* @return Envelope The notification envelope
* @phpstan-param OptionsType $options
*/
public function info(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -152,13 +115,7 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Creates a warning notification with SweetAlert-specific options.
*
* @param string $message The notification message
* @param OptionsType $options SweetAlert-specific options
* @param string|null $title The notification title
*
* @return Envelope The notification envelope
* @phpstan-param OptionsType $options
*/
public function warning(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -166,17 +123,8 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Creates a notification of the specified type with SweetAlert-specific options.
*
* @param string|null $type The notification type
* @param string|null $message The notification message
* @param array $options SweetAlert-specific options
* @param string|null $title The notification title
*
* @phpstan-param NotificationType|null $type The notification type
* @phpstan-param OptionsType $options SweetAlert-specific options
*
* @return Envelope The notification envelope
* @phpstan-param NotificationType|null $type
* @phpstan-param OptionsType $options
*/
public function flash(?string $type = null, ?string $message = null, array $options = [], ?string $title = null): Envelope
{
@@ -184,12 +132,7 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Sets notification options with SweetAlert-specific type checking.
*
* @param OptionsType $options The notification options
* @param bool $append Whether to append or replace existing options
*
* @return static The builder instance
* @phpstan-param OptionsType $options
*/
public function options(array $options, bool $append = true): static
{
@@ -197,18 +140,11 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Sets a specific notification option with SweetAlert-specific type checking.
*
* @template T of OptionsType
* @template K of key-of<T>
*
* @param string $name The option name
* @param mixed $value The option value
*
* @phpstan-param K $name
* @phpstan-param T[K] $value
*
* @return static The builder instance
*/
public function option(string $name, mixed $value): static
{
@@ -216,15 +152,7 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Creates a question type dialog with a cancel button.
*
* SweetAlert2 provides a specific question type for creating confirmation dialogs,
* which is a common UI pattern for actions that need user confirmation.
*
* @param string|null $message The question message
* @param array<string, mixed> $options Additional options
*
* @return self The builder instance
* @phpstan-param array<string, mixed> $options
*/
public function question(?string $message = null, array $options = []): self
{
@@ -241,13 +169,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this->type('question');
}
/**
* Sets the title of the popup as HTML.
*
* @param string $title The title content
*
* @return static The builder instance
*/
public function title(string $title): static
{
parent::title($title);
@@ -257,15 +178,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Sets the title of the popup as plain text.
*
* Useful to avoid HTML injection.
*
* @param string $text The title text
*
* @return self The builder instance
*/
public function titleText(string $text): self
{
$this->option('titleText', $text);
@@ -273,17 +185,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Sets HTML content for the popup.
*
* [Security] SweetAlert2 does NOT sanitize this parameter. It is the developer's
* responsibility to escape any user input when using the html option,
* so XSS attacks would be prevented.
*
* @param string $html The HTML content
*
* @return self The builder instance
*/
public function html(string $html): self
{
$this->option('html', $html);
@@ -291,9 +192,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* A description for the popup. If "text" and "html" parameters are provided in the same time, "text" will be used.
*/
public function text(string $text): self
{
$this->option('text', $text);
@@ -308,11 +206,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this->text($message);
}
/**
* The icon of the popup. SweetAlert2 comes with 5 built-in icon which will show a corresponding icon animation:
* warning, error, success, info, and question. It can either be put in the array under the key "icon" or passed as
* the third parameter of the function.
*/
public function icon(string $icon): self
{
$this->option('icon', $icon);
@@ -320,9 +213,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the color of the icon.
*/
public function iconColor(string $color): self
{
$this->option('iconColor', $color);
@@ -330,9 +220,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* The custom HTML content for an icon.
*/
public function iconHtml(string $html): self
{
$this->option('iconHtml', $html);
@@ -340,9 +227,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* CSS classes for animations when showing a popup (fade in).
*/
public function showClass(string $showClass, string $value): self
{
$option = $this->getEnvelope()->getOption('showClass', []);
@@ -353,9 +237,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* CSS classes for animations when hiding a popup (fade out).
*/
public function hideClass(string $hideClass, string $value): self
{
$option = $this->getEnvelope()->getOption('hideClass', []);
@@ -366,9 +247,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* The footer of the popup. Can be either plain text or HTML.
*/
public function footer(string $footer): self
{
$this->option('footer', $footer);
@@ -376,10 +254,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Whether or not SweetAlert2 should show a full screen click-to-dismiss backdrop. Can be either a boolean or a
* string which will be assigned to the CSS background property.
*/
public function backdrop(bool|string $backdrop = true): self
{
$this->option('backdrop', $backdrop);
@@ -388,17 +262,7 @@ final class SweetAlertBuilder extends NotificationBuilder
}
/**
* Configures a toast notification.
*
* Toast notifications are smaller, less intrusive notifications typically
* shown at the screen edge. This is a convenience method that configures
* several properties at once for toast behavior.
*
* @param bool $toast Whether to enable toast mode
* @param "top"|"top-start"|"top-end"|"center"|"center-start"|"center-end"|"bottom"|"bottom-start"|"bottom-end" $position
* @param bool $showConfirmButton Whether to show the confirm button
*
* @return self The builder instance
* @param 'top'|'top-start'|'top-end'|'center'|'center-start'|'center-end'|'bottom'|'bottom-start'|'bottom-end' $position
*/
public function toast(bool $toast = true, string $position = 'top-end', bool $showConfirmButton = false): self
{
@@ -413,9 +277,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* The container element for adding popup into.
*/
public function target(string $target): self
{
$this->option('target', $target);
@@ -425,9 +286,6 @@ final class SweetAlertBuilder extends NotificationBuilder
/**
* @phpstan-param OptionsType['input'] $input
*
* Input field type, can be text, email, password, number, tel, range, textarea, select, radio, checkbox, file and
* url
*/
public function input(string $input): self
{
@@ -436,9 +294,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Popup window width, including paddings (box-sizing: border-box). Can be in px or %. The default width is 32rem.
*/
public function width(string $width): self
{
$this->option('width', $width);
@@ -446,9 +301,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Popup window padding. The default padding is 1.25rem.
*/
public function padding(string $padding): self
{
$this->option('padding', $padding);
@@ -456,9 +308,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Popup window background (CSS background property). The default background is '#fff'.
*/
public function background(string $background): self
{
$this->option('background', $background);
@@ -468,9 +317,6 @@ final class SweetAlertBuilder extends NotificationBuilder
/**
* @phpstan-param OptionsType['position'] $position
*
* Popup window position, can be 'top', 'top-start', 'top-end', 'center', 'center-start', 'center-end', 'bottom',
* 'bottom-start', or 'bottom-end'
*/
public function position(string $position): self
{
@@ -481,9 +327,6 @@ final class SweetAlertBuilder extends NotificationBuilder
/**
* @phpstan-param "column"|"fullscreen"|"row"|false $grow
*
* Paired with window position, sets the direction the popup should grow in, can be set to 'row', 'column',
* 'fullscreen', or false
*/
public function grow(string|false $grow): self
{
@@ -494,8 +337,6 @@ final class SweetAlertBuilder extends NotificationBuilder
/**
* @phpstan-param CustomClassType $customClass
*
* A custom CSS class for the popup
*/
public function customClass(string $customClass, string $value): self
{
@@ -508,9 +349,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Auto close timer of the popup. Set in ms (milliseconds).
*/
public function timer(int $timer): self
{
$this->option('timer', $timer);
@@ -518,10 +356,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to true, the timer will have a progress bar at the bottom of a popup. Mostly, this feature is useful with
* toasts.
*/
public function timerProgressBar(bool $timerProgressBar = true): self
{
$this->option('timerProgressBar', $timerProgressBar);
@@ -529,10 +363,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* By default, SweetAlert2 sets html's and body's CSS height to auto !important. If this behavior isn't compatible
* with your project's layout, set heightAuto to false.
*/
public function heightAuto(bool $heightAuto = true): self
{
$this->option('heightAuto', $heightAuto);
@@ -540,10 +370,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to false, the user can't dismiss the popup by clicking outside it. You can also pass a custom function
* returning a boolean value, e.g. if you want to disable outside clicks for the loading state of a popup.
*/
public function allowOutsideClick(bool|string $allowOutsideClick = true): self
{
$this->option('allowOutsideClick', $allowOutsideClick);
@@ -551,10 +377,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to false, the user can't dismiss the popup by pressing the Esc key. You can also pass a custom function
* returning a boolean value, e.g. if you want to disable the Esc key for the loading state of a popup.
*/
public function allowEscapeKey(bool|string $allowEscapeKey = true): self
{
$this->option('allowEscapeKey', $allowEscapeKey);
@@ -562,10 +384,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to false, the user can't confirm the popup by pressing the Enter or Space keys, unless they manually focus
* the confirm button. You can also pass a custom function returning a boolean value.
*/
public function allowEnterKey(bool|string $allowEnterKey = true): self
{
$this->option('allowEnterKey', $allowEnterKey);
@@ -573,9 +391,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to false, SweetAlert2 will allow keydown events propagation to the document.
*/
public function stopKeydownPropagation(bool $stop = true): self
{
$this->option('stopKeydownPropagation', $stop);
@@ -583,11 +398,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Useful for those who are using SweetAlert2 along with Bootstrap modals. By default keydownListenerCapture is
* false which means when a user hits Esc, both SweetAlert2 and Bootstrap modals will be closed. Set
* keydownListenerCapture to true to fix that behavior.
*/
public function keydownListenerCapture(bool $capture = true): self
{
$this->option('keydownListenerCapture', $capture);
@@ -595,9 +405,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to false, a "Confirm"-button will not be shown.
*/
public function showConfirmButton(bool $showConfirmButton = true, ?string $confirmButtonText = null, ?string $confirmButtonColor = null, ?string $confirmButtonAriaLabel = null): self
{
$this->option('showConfirmButton', $showConfirmButton);
@@ -617,9 +424,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to true, a "Deny"-button will be shown. It can be useful when you want a popup with 3 buttons.
*/
public function showDenyButton(bool $showDenyButton = true, ?string $denyButtonText = null, ?string $denyButtonColor = null, ?string $denyButtonAriaLabel = null): self
{
$this->option('showDenyButton', $showDenyButton);
@@ -639,9 +443,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If set to true, a "Cancel"-button will be shown, which the user can click on to dismiss the modal.
*/
public function showCancelButton(bool $showCancelButton = true, ?string $cancelButtonText = null, ?string $cancelButtonColor = null, ?string $cancelButtonAriaLabel = null): self
{
$this->option('showCancelButton', $showCancelButton);
@@ -661,9 +462,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the text on the "Confirm"-button.
*/
public function confirmButtonText(string $confirmButtonText, ?string $confirmButtonColor = null, ?string $confirmButtonAriaLabel = null): self
{
$this->option('confirmButtonText', $confirmButtonText);
@@ -679,9 +477,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the text on the "Deny"-button.
*/
public function denyButtonText(string $denyButtonText, ?string $denyButtonColor = null, ?string $denyButtonAriaLabel = null): self
{
$this->option('denyButtonText', $denyButtonText);
@@ -697,9 +492,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the text on the "Cancel"-button.
*/
public function cancelButtonText(string $cancelButtonText, ?string $cancelButtonColor = null, ?string $cancelButtonAriaLabel = null): self
{
$this->option('cancelButtonText', $cancelButtonText);
@@ -715,9 +507,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the background color of the "Confirm"-button. The default color is #3085d6.
*/
public function confirmButtonColor(string $confirmButtonColor): self
{
$this->option('confirmButtonColor', $confirmButtonColor);
@@ -725,9 +514,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the background color of the "Deny"-button. The default color is #dd6b55.
*/
public function denyButtonColor(string $denyButtonColor): self
{
$this->option('denyButtonColor', $denyButtonColor);
@@ -735,9 +521,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the background color of the "Cancel"-button. The default color is #aaa.
*/
public function cancelButtonColor(string $cancelButtonColor): self
{
$this->option('cancelButtonColor', $cancelButtonColor);
@@ -745,9 +528,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the aria-label for the "Confirm"-button.
*/
public function confirmButtonAriaLabel(string $label): self
{
$this->option('confirmButtonAriaLabel', $label);
@@ -755,9 +535,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the aria-label for the "Deny"-button.
*/
public function denyButtonAriaLabel(string $denyButtonAriaLabel): self
{
$this->option('denyButtonAriaLabel', $denyButtonAriaLabel);
@@ -765,9 +542,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the aria-label for the "Cancel"-button.
*/
public function cancelButtonAriaLabel(string $label): self
{
$this->option('cancelButtonAriaLabel', $label);
@@ -775,10 +549,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Apply default styling to buttons. If you want to use your own classes (e.g. Bootstrap classes) set this parameter
* to false.
*/
public function buttonsStyling(bool $buttonsStyling = true): self
{
$this->option('buttonsStyling', $buttonsStyling);
@@ -786,9 +556,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Set to true if you want to invert default buttons positions ("Confirm"-button on the right side).
*/
public function reverseButtons(bool $reverseButtons = true): self
{
$this->option('reverseButtons', $reverseButtons);
@@ -796,9 +563,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Set to false if you want to focus the first element in tab order instead of "Confirm"-button by default.
*/
public function focusConfirm(bool $focusConfirm = true): self
{
$this->option('focusConfirm', $focusConfirm);
@@ -806,9 +570,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Set to true if you want to focus the "Deny"-button by default.
*/
public function focusDeny(bool $focusDeny = true): self
{
$this->option('focusDeny', $focusDeny);
@@ -816,9 +577,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Set to true if you want to focus the "Cancel"-button by default.
*/
public function focusCancel(bool $focusCancel = true): self
{
$this->option('focusCancel', $focusCancel);
@@ -826,9 +584,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Set to true to show close button in top right corner of the popup.
*/
public function showCloseButton(bool $showCloseButton = true): self
{
$this->option('showCloseButton', $showCloseButton);
@@ -836,9 +591,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the content of the close button.
*/
public function closeButtonHtml(string $closeButtonHtml): self
{
$this->option('closeButtonHtml', $closeButtonHtml);
@@ -846,9 +598,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the aria-label for the close button.
*/
public function closeButtonAriaLabel(string $closeButtonAriaLabel): self
{
$this->option('closeButtonAriaLabel', $closeButtonAriaLabel);
@@ -856,9 +605,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Use this to change the HTML content of the loader.
*/
public function loaderHtml(string $loaderHtml): self
{
$this->option('loaderHtml', $loaderHtml);
@@ -866,10 +612,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Set to true to disable buttons and show that something is loading. Use it in combination with the preConfirm
* parameter.
*/
public function showLoaderOnConfirm(bool $showLoaderOnConfirm = true): self
{
$this->option('showLoaderOnConfirm', $showLoaderOnConfirm);
@@ -877,9 +619,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Set to false to disable body padding adjustment when the page scrollbar gets hidden while the popup is shown.
*/
public function scrollbarPadding(bool $scrollbarPadding = true): self
{
$this->option('scrollbarPadding', $scrollbarPadding);
@@ -887,13 +626,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Function to execute before confirming, may be async (Promise-returning) or sync.
* Returned (or resolved) value can be:
* - false to prevent a popup from closing
* - anything else to pass that value as the result.value of Swal.fire()
* - undefined to keep the default result.value.
*/
public function preConfirm(bool|string $preConfirm): self
{
$this->option('preConfirm', $preConfirm);
@@ -901,13 +633,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Function to execute before denying, may be async (Promise-returning) or sync.
* Returned (or resolved) value can be:
* - false to prevent a popup from closing
* - anything else to pass that value as the result.value of Swal.fire()
* - undefined to keep the default result.value.
*/
public function preDeny(string $preDeny): self
{
$this->option('preDeny', $preDeny);
@@ -915,10 +640,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If you want to return the input value as result.value when denying the popup, set to true. Otherwise, the denying
* will set result.value to false.
*/
public function returnInputValueOnDeny(bool $inputValue = true): self
{
$this->option('returnInputValueOnDeny', $inputValue);
@@ -933,16 +654,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Makes the dialog persistent, requiring the user to interact with it.
*
* This prevents the dialog from being dismissed via outside clicks or escape key.
*
* @param bool $showConfirmBtn Whether to show the confirm button
* @param bool $showCloseBtn Whether to show the close button
*
* @return self The builder instance
*/
public function persistent(bool $showConfirmBtn = true, bool $showCloseBtn = false): self
{
$this->allowEscapeKey(false);
@@ -954,9 +665,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Add a customized icon for the popup. Should contain a string with the path or URL to the image.
*/
public function imageUrl(string $imageUrl, ?int $imageWidth = null, ?int $imageHeight = null, ?string $imageAlt = null): self
{
$this->option('imageUrl', $imageUrl);
@@ -976,9 +684,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If imageUrl is set, you can specify imageWidth to describes image width in px.
*/
public function imageWidth(int $imageWidth): self
{
$this->option('imageWidth', $imageWidth);
@@ -986,9 +691,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Custom int height in px.
*/
public function imageHeight(int $imageHeight): self
{
$this->option('imageHeight', $imageHeight);
@@ -996,9 +698,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* An alternative text for the custom image icon.
*/
public function imageAlt(string $imageAlt): self
{
$this->option('imageAlt', $imageAlt);
@@ -1006,20 +705,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Configures an image dialog with customizable dimensions.
*
* This method configures a dialog with an image as the main content.
*
* @param string $title The dialog title
* @param string $text The dialog text
* @param string $imageUrl The URL of the image
* @param int $imageWidth The width of the image in pixels
* @param int $imageHeight The height of the image in pixels
* @param string|null $imageAlt Alternative text for the image
*
* @return self The builder instance
*/
public function image(string $title, string $text, string $imageUrl, int $imageWidth = 400, int $imageHeight = 200, ?string $imageAlt = null): self
{
$this->title($title);
@@ -1038,20 +723,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Creates and immediately pushes an image notification.
*
* This is a shortcut method that combines image configuration and pushing.
*
* @param string $title The dialog title
* @param string $text The dialog text
* @param string $imageUrl The URL of the image
* @param int $imageWidth The width of the image in pixels
* @param int $imageHeight The height of the image in pixels
* @param string|null $imageAlt Alternative text for the image
*
* @return Envelope The notification envelope
*/
public function addImage(string $title, string $text, string $imageUrl, int $imageWidth = 400, int $imageHeight = 200, ?string $imageAlt = null): Envelope
{
$this->image($title, $text, $imageUrl, $imageWidth, $imageHeight, $imageAlt);
@@ -1059,9 +730,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this->push();
}
/**
* Input field label.
*/
public function inputLabel(string $inputLabel): self
{
$this->option('inputLabel', $inputLabel);
@@ -1069,9 +737,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Input field placeholder.
*/
public function inputPlaceholder(string $inputPlaceholder): self
{
$this->option('inputPlaceholder', $inputPlaceholder);
@@ -1079,12 +744,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Input field initial value.
* - If the input type is select, inputValue will represent the selected <option> tag.
* - If the input type is checkbox, inputValue will represent the checked state.
* - If the input type is text, email, number, tel or textarea a Promise can be accepted as inputValue.
*/
public function inputValue(string $inputValue): self
{
$this->option('inputValue', $inputValue);
@@ -1092,12 +751,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* If input parameter is set to "select" or "radio", you can provide options. Can be a Map or a plain object, with
* keys that represent option values and values that represent option text. You can also provide plain object or Map
* as values that will represented a group of options, being the label of this <optgroup> the key. Finally, you can
* also provide a Promise that resolves with one of those types.
*/
public function inputOptions(string $inputOptions): self
{
$this->option('inputOptions', $inputOptions);
@@ -1105,10 +758,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Automatically remove whitespaces from both ends of a result string. Set this parameter to false to disable
* auto-trimming.
*/
public function inputAutoTrim(bool $inputAutoTrim = true): self
{
$this->option('inputAutoTrim', $inputAutoTrim);
@@ -1116,10 +765,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* HTML input attributes (e.g. min, max, autocomplete, accept), that are added to the input field. Object keys will
* represent attributes names, object values will represent attributes values.
*/
public function inputAttributes(string $inputAttributes): self
{
$this->option('inputAttributes', $inputAttributes);
@@ -1127,12 +772,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* Validator for input field, may be async (Promise-returning) or sync.
* Returned (or resolved) value can be:
* - a falsy value (undefined, null, false) for indicating success
* - a string value (error message) for indicating failure.
*/
public function inputValidator(string $inputValidator): self
{
$this->option('inputValidator', $inputValidator);
@@ -1140,9 +779,6 @@ final class SweetAlertBuilder extends NotificationBuilder
return $this;
}
/**
* A custom validation message for default validators (email, url).
*/
public function validationMessage(string $validationMessage): self
{
$this->option('validationMessage', $validationMessage);
src/SweetAlert/Prime/SweetAlertInterface.php
-11
View File
@@ -7,17 +7,6 @@ namespace Flasher\SweetAlert\Prime;
use Flasher\Prime\Factory\NotificationFactoryInterface;
/**
* SweetAlertInterface - Contract for SweetAlert notification factories.
*
* This interface defines the contract for SweetAlert notification factories.
* It extends the core notification factory interface to ensure compatibility
* with PHPFlasher's notification system, while allowing IDE completion for
* SweetAlert-specific methods through the mixin annotation.
*
* Design patterns:
* - Interface Segregation: Provides a specific interface for SweetAlert functionality
* - Contract: Defines a contract for creating SweetAlert notifications
*
* @mixin \Flasher\SweetAlert\Prime\SweetAlertBuilder
*/
interface SweetAlertInterface extends NotificationFactoryInterface
src/SweetAlert/Prime/SweetAlertPlugin.php
+2 -41
View File
@@ -6,60 +6,25 @@ namespace Flasher\SweetAlert\Prime;
use Flasher\Prime\Plugin\Plugin;
/**
* SweetAlertPlugin - Plugin definition for SweetAlert2 integration with PHPFlasher.
*
* This class defines the core plugin configuration for the SweetAlert2 notification
* library integration. It specifies the required JavaScript and CSS assets,
* factory class, and service identifiers for dependency injection containers.
*
* SweetAlert2 offers rich, customizable modal dialogs beyond simple notifications,
* including confirm dialogs, input forms, and custom content.
*
* Design patterns:
* - Plugin: Implements the plugin pattern for extending core functionality
* - Registry: Registers the plugin's assets and identifiers with the core system
* - Metadata: Provides metadata about the plugin's requirements
*/
final class SweetAlertPlugin extends Plugin
{
/**
* {@inheritdoc}
*
* Returns the plugin's unique identifier.
*/
public function getAlias(): string
{
return 'sweetalert';
}
/**
* {@inheritdoc}
*
* Returns the factory class responsible for creating SweetAlert notifications.
*/
public function getFactory(): string
{
return SweetAlert::class;
}
/**
* {@inheritdoc}
*
* Returns the service alias for dependency injection containers.
*/
public function getServiceAliases(): string
{
return SweetAlertInterface::class;
}
/**
* {@inheritdoc}
*
* Returns the required JavaScript files for SweetAlert2 integration.
* Includes both the core SweetAlert2 library and the PHPFlasher adapter.
*
* @return string[] Array of script paths
* @return string[]
*/
public function getScripts(): array
{
@@ -70,11 +35,7 @@ final class SweetAlertPlugin extends Plugin
}
/**
* {@inheritdoc}
*
* Returns the required CSS files for SweetAlert2 styling.
*
* @return string[] Array of stylesheet paths
* @return string[]
*/
public function getStyles(): array
{
src/SweetAlert/Prime/functions.php
+2 -27
View File
@@ -8,25 +8,9 @@ use Flasher\Prime\Container\FlasherContainer;
use Flasher\Prime\Notification\Envelope;
use Flasher\Prime\Notification\Type;
/*
* Namespace-specific helper functions for SweetAlert notifications.
*
* This file provides a namespace-specific helper function that simplifies
* the creation of SweetAlert notifications from code that uses imports.
*
* Design pattern: Facade - Provides a simplified interface to a complex subsystem
*/
if (!\function_exists('Flasher\SweetAlert\Prime\sweetalert')) {
/**
* Creates a SweetAlert notification or returns the SweetAlert factory.
*
* This function simplifies the process of creating SweetAlert notifications.
* When called with no arguments, it returns an instance of SweetAlertInterface.
* When called with arguments, it creates a SweetAlert notification and returns an Envelope.
*
* @param string|null $message the message content of the notification
* @param "success"|"info"|"warning"|"error"|"question" $type The type of the notification (e.g., success, error, warning, info).
* @param "success"|"info"|"warning"|"error"|"question" $type
* @param array{
* title?: string,
* titleText?: string,
@@ -95,18 +79,9 @@ if (!\function_exists('Flasher\SweetAlert\Prime\sweetalert')) {
* inputAttributes?: string,
* inputValidator?: string,
* validationMessage?: string,
* } $options additional options for the SweetAlert notification
* @param string|null $title the title of the notification
*
* @return Envelope|SweetAlertInterface Returns an Envelope containing the notification details when arguments are provided.
* Returns an instance of SweetAlertInterface when no arguments are provided.
* } $options
*
* @phpstan-return ($message is empty ? SweetAlertInterface : Envelope)
*
* Usage:
* 1. Without arguments - Get the SweetAlert factory: $sweetalert = sweetalert();
* 2. With arguments - Create and return a SweetAlert notification:
* sweetalert('Message', Type::SUCCESS, ['option' => 'value'], 'Title');
*/
function sweetalert(?string $message = null, string $type = Type::SUCCESS, array $options = [], ?string $title = null): Envelope|SweetAlertInterface
{
src/SweetAlert/Prime/helpers.php
+4 -32
View File
@@ -7,25 +7,10 @@ use Flasher\Prime\Notification\Envelope;
use Flasher\Prime\Notification\Type;
use Flasher\SweetAlert\Prime\SweetAlertInterface;
/*
* Global helper functions for SweetAlert notifications.
*
* This file provides a global helper function that simplifies
* the creation of SweetAlert notifications from any PHP code.
*
* Design pattern: Facade - Provides a simplified interface to a complex subsystem
*/
if (!function_exists('sweetalert')) {
/**
* Creates a SweetAlert notification or returns the SweetAlert factory.
*
* This function simplifies the process of creating SweetAlert notifications.
* When called with no arguments, it returns an instance of SweetAlertInterface.
* When called with arguments, it creates a SweetAlert notification and returns an Envelope.
*
* @phpstan-param string|null $message the message content of the notification
* @phpstan-param "success"|"info"|"warning"|"error"|"question" $type The type of the notification (e.g., success, error, warning, info).
* @phpstan-param string|null $message
* @phpstan-param "success"|"info"|"warning"|"error"|"question" $type
* @phpstan-param array{
* title?: string,
* titleText?: string,
@@ -94,23 +79,10 @@ if (!function_exists('sweetalert')) {
* inputAttributes?: string,
* inputValidator?: string,
* validationMessage?: string,
* } $options additional options for the SweetAlert notification
* @phpstan-param string|null $title the title of the notification
*
* @return Envelope|SweetAlertInterface Returns an Envelope containing the notification details when arguments are provided.
* Returns an instance of SweetAlertInterface when no arguments are provided.
* } $options
* @phpstan-param string|null $title
*
* @phpstan-return ($message is empty ? SweetAlertInterface : Envelope)
*
* Usage:
* 1. Without arguments - Get the SweetAlert factory: $sweetalert = sweetalert();
* 2. With arguments - Create and return a SweetAlert notification:
* sweetalert('Message', Type::SUCCESS, ['option' => 'value'], 'Title');
*
* Examples of SweetAlert's rich dialogs:
* - Confirmation dialog: sweetalert('Are you sure?', 'question', ['showCancelButton' => true])
* - Input form: sweetalert('Enter your email', 'info', ['input' => 'email'])
* - Toast notification: sweetalert('Success', 'success', ['toast' => true, 'position' => 'top-end'])
*/
function sweetalert(?string $message = null, string $type = Type::SUCCESS, array $options = [], ?string $title = null): Envelope|SweetAlertInterface
{
src/SweetAlert/Symfony/FlasherSweetAlertSymfonyBundle.php
-16
View File
@@ -8,24 +8,8 @@ use Flasher\Prime\Plugin\PluginInterface;
use Flasher\SweetAlert\Prime\SweetAlertPlugin;
use Flasher\Symfony\Support\PluginBundle;
/**
* FlasherSweetAlertSymfonyBundle - Symfony bundle for SweetAlert2 integration.
*
* This bundle registers the SweetAlert2 plugin with Symfony's service container.
* It extends the base plugin bundle to inherit common registration logic
* while providing the SweetAlert-specific plugin implementation.
*
* Design patterns:
* - Bundle: Implements Symfony's bundle pattern for packaging functionality
* - Factory Method: Creates the plugin instance
*/
final class FlasherSweetAlertSymfonyBundle extends PluginBundle // Symfony\Component\HttpKernel\Bundle\Bundle
{
/**
* Creates the SweetAlert plugin instance.
*
* @return PluginInterface The SweetAlert plugin instance
*/
public function createPlugin(): PluginInterface
{
return new SweetAlertPlugin();