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

Refactors and improves documentation clarity

Browse Source
This commit is contained in:
Younes ENNAJI
2026-01-10 02:15:51 +01:00
parent 15da40c582
commit 1c5fbbba9a
11 changed files with 108 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_includes/_usage.md
+2 -2
View File
@@ -31,9 +31,9 @@ class BookController
<br />
Choose a message that is clear and tells the user what happened. For example, `"Book has been created successfully!"` is a good message, but you can adjust it to fit your application's context and language.
Choose a clear message that tells the user what happened. For example, `"Book has been created successfully!"` is a good message, but you can adjust it to fit your application's context and language.
> Using this package is easy. You can add notifications to your application with just one line of code.
> This package is easy to use. You can add notifications to your application with just one line of code.
{% assign id = '#/ usage success' %}
{% assign type = 'success' %}
docs/pages/installation.md
+1 -2
View File
@@ -378,8 +378,7 @@ flash()
|-----------|------------------------------------------------------------------------------|
| `$locale` | The locale to be used for the translation, or null to use the default locale |
It is **important** to note that the `translate()` method only sets the locale to be used for the translation of the flash message.
It does not actually perform the translation itself.
Note that the `translate()` method only sets the locale; it does not perform the translation itself.
In order to translate the flash message, you will need to provide the appropriate translation keys in your translation files.
docs/pages/javascript.md
+2 -2
View File
@@ -5,7 +5,7 @@ title: JavaScript
description: Easily add flash notification messages to your JavaScript application with PHPFlasher. Follow our step-by-step guide to install the library using npm or include it in your project using CDN links, and start engaging and informing your users with powerful flash messages.
---
<strong><span class="text-indigo-900">PHP<span class="text-indigo-500">Flasher</span></span></strong> assets can be installed from a cdn or using npm
<strong><span class="text-indigo-900">PHP<span class="text-indigo-500">Flasher</span></span></strong> assets can be installed from a CDN or using npm
## <i class="fa-duotone fa-list-radio"></i> Installation
Quick start guide for installing the <strong><span class="text-indigo-900">PHP<span class="text-indigo-500">Flasher</span></span></strong> from cdn or npm.
@@ -68,7 +68,7 @@ or if you are using a cdn like this:
### <i class="fa-duotone fa-list-radio"></i> Other adapters
First grad the cdn for any js library adapter supported by <strong><span class="text-indigo-900">PHP<span class="text-indigo-500">Flasher</span></span></strong> or install it with npm
First grab the CDN for any js library adapter supported by <strong><span class="text-indigo-900">PHP<span class="text-indigo-500">Flasher</span></span></strong> or install it with npm
and then call the `create()` method on flasher object :
```html
docs/pages/themes.md
+1 -1
View File
@@ -2,7 +2,7 @@
## Overview
The PHPFlasher theme system allows for consistent, customizable notification designs across your application. Themes define both the visual appearance (using CSS/SCSS) and the HTML structure (using template functions) of notifications.
The PHPFlasher theme system allows for consistent, customizable notification designs across your application. Themes define both the visual appearance (CSS/SCSS) and HTML structure of notifications.
## Core Concepts
src/Laravel/Resources/config.php
+13 -13
View File
@@ -14,33 +14,33 @@ use Flasher\Prime\Configuration;
* @return array<string, mixed> PHPFlasher configuration
*/
return Configuration::from([
// Default notification library (e.g., 'flasher', 'toastr', 'noty', 'notyf', 'sweetalert')
// Default notification adapter
'default' => 'flasher',
// Path to the main PHPFlasher JavaScript file
// Main script path
'main_script' => '/vendor/flasher/flasher.min.js',
// List of CSS files to style your notifications
// Stylesheet files
'styles' => [
'/vendor/flasher/flasher.min.css',
],
// Set global options for all notifications (optional)
// Global notification options
// 'options' => [
// 'timeout' => 5000, // Time in milliseconds before the notification disappears
// 'position' => 'top-right', // Where the notification appears on the screen
// 'timeout' => 5000,
// 'position' => 'top-right',
// ],
// Automatically inject JavaScript and CSS assets into your HTML pages
// Auto-inject assets into responses
'inject_assets' => true,
// Enable message translation using Laravel's translation service
// Enable automatic message translation
'translate' => true,
// URL patterns to exclude from asset injection and flash_bag conversion
// URL patterns to exclude from asset injection and flash bag conversion
'excluded_paths' => [],
// Map Laravel flash message keys to notification types
// Map Laravel session flash keys to notification types
'flash_bag' => [
'success' => ['success'],
'error' => ['error', 'danger'],
@@ -48,12 +48,12 @@ return Configuration::from([
'info' => ['info', 'notice', 'alert'],
],
// Set criteria to filter which notifications are displayed (optional)
// Filter criteria for notifications
// 'filter' => [
// 'limit' => 5, // Maximum number of notifications to show at once
// 'limit' => 5,
// ],
// Define notification presets to simplify notification creation (optional)
// Predefined notification configurations
// 'presets' => [
// 'entity_saved' => [
// 'type' => 'success',
src/Prime/EventDispatcher/EventDispatcher.php
+2 -5
View File
@@ -25,7 +25,7 @@ use Flasher\Prime\EventDispatcher\EventListener\EventListenerInterface;
final class EventDispatcher implements EventDispatcherInterface
{
/**
* Mapping of event names to their registered listeners.
* Mapping of event names to listeners.
*
* @var array<string, EventListenerInterface[]>
*/
@@ -54,7 +54,7 @@ final class EventDispatcher implements EventDispatcherInterface
* that implement StoppableEventInterface. It calls each listener in
* registration order until all listeners are called or propagation is stopped.
*
* @throws \InvalidArgumentException If a listener is not callable
* @throws \InvalidArgumentException
*/
public function dispatch(object $event): object
{
@@ -77,9 +77,6 @@ final class EventDispatcher implements EventDispatcherInterface
/**
* {@inheritdoc}
*
* This implementation registers a listener for all events it declares
* interest in through its getSubscribedEvents() method.
*/
public function addListener(EventListenerInterface $listener): void
{
src/Prime/Notification/FlasherBuilder.php
+41 -48
View File
@@ -28,11 +28,11 @@ namespace Flasher\Prime\Notification;
final class FlasherBuilder extends NotificationBuilder
{
/**
* Sets the notification type with type-safety.
* Sets the notification type.
*
* @phpstan-param NotificationType $type The notification type (success, info, warning, error)
* @phpstan-param NotificationType $type
*
* @return static The builder instance for method chaining
* @return static
*/
public function type(string $type): static
{
@@ -42,11 +42,11 @@ final class FlasherBuilder extends NotificationBuilder
/**
* Creates and stores a success notification.
*
* @param string $message The notification message
* @param OptionsType $options Optional configuration for the notification
* @param string|null $title Optional title for the notification
* @param string $message
* @param OptionsType $options
* @param string|null $title
*
* @return Envelope The created and stored notification envelope
* @return Envelope
*/
public function success(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -56,11 +56,11 @@ final class FlasherBuilder extends NotificationBuilder
/**
* Creates and stores an error notification.
*
* @param string $message The notification message
* @param OptionsType $options Optional configuration for the notification
* @param string|null $title Optional title for the notification
* @param string $message
* @param OptionsType $options
* @param string|null $title
*
* @return Envelope The created and stored notification envelope
* @return Envelope
*/
public function error(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -70,11 +70,11 @@ final class FlasherBuilder extends NotificationBuilder
/**
* Creates and stores an info notification.
*
* @param string $message The notification message
* @param OptionsType $options Optional configuration for the notification
* @param string|null $title Optional title for the notification
* @param string $message
* @param OptionsType $options
* @param string|null $title
*
* @return Envelope The created and stored notification envelope
* @return Envelope
*/
public function info(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -84,11 +84,11 @@ final class FlasherBuilder extends NotificationBuilder
/**
* Creates and stores a warning notification.
*
* @param string $message The notification message
* @param OptionsType $options Optional configuration for the notification
* @param string|null $title Optional title for the notification
* @param string $message
* @param OptionsType $options
* @param string|null $title
*
* @return Envelope The created and stored notification envelope
* @return Envelope
*/
public function warning(string $message, array $options = [], ?string $title = null): Envelope
{
@@ -98,16 +98,13 @@ final class FlasherBuilder extends NotificationBuilder
/**
* Creates and stores a notification with specified type.
*
* This is a general-purpose method that can be used to create notifications
* of any type, with complete control over all parameters.
* @phpstan-param NotificationType|null $type
* @phpstan-param OptionsType $options
*
* @phpstan-param NotificationType|null $type The notification type
* @phpstan-param OptionsType $options Optional configuration for the notification
* @param string|null $message
* @param string|null $title
*
* @param string|null $message The notification message
* @param string|null $title Optional title for the notification
*
* @return Envelope The created and stored notification envelope
* @return Envelope
*/
public function flash(?string $type = null, ?string $message = null, array $options = [], ?string $title = null): Envelope
{
@@ -115,12 +112,12 @@ final class FlasherBuilder extends NotificationBuilder
}
/**
* Sets multiple options for the notification.
* Sets multiple options.
*
* @param OptionsType $options Configuration options for the notification
* @param bool $append Whether to merge with existing options (true) or replace them (false)
* @param OptionsType $options
* @param bool $append
*
* @return static The builder instance for method chaining
* @return static
*/
public function options(array $options, bool $append = true): static
{
@@ -128,15 +125,15 @@ final class FlasherBuilder extends NotificationBuilder
}
/**
* Sets a single option for the notification.
* Sets a single option.
*
* @template T of OptionsType
* @template K of key-of<T>
*
* @phpstan-param K $name The option name
* @phpstan-param T[K] $value The option value
* @phpstan-param K $name
* @phpstan-param T[K] $value
*
* @return static The builder instance for method chaining
* @return static
*/
public function option(string $name, mixed $value): static
{
@@ -144,11 +141,11 @@ final class FlasherBuilder extends NotificationBuilder
}
/**
* Sets the display timeout for the notification.
* Sets the display timeout.
*
* @param int $milliseconds The timeout duration in milliseconds (0 for no timeout)
* @param int $milliseconds
*
* @return self The builder instance for method chaining
* @return self
*/
public function timeout(int $milliseconds): self
{
@@ -158,13 +155,11 @@ final class FlasherBuilder extends NotificationBuilder
}
/**
* Sets the stacking direction for notifications.
* Sets the stacking direction.
*
* @param "top"|"bottom" $direction The direction in which notifications should stack
* - 'top': newer notifications appear above older ones
* - 'bottom': newer notifications appear below older ones
* @param "top"|"bottom" $direction
*
* @return self The builder instance for method chaining
* @return self
*/
public function direction(string $direction): self
{
@@ -174,13 +169,11 @@ final class FlasherBuilder extends NotificationBuilder
}
/**
* Sets the display position for notifications.
* Sets the display position.
*
* @phpstan-param OptionsType['position'] $position The position on screen
* (top-right, top-left, top-center,
* bottom-right, bottom-left, bottom-center)
* @phpstan-param OptionsType['position'] $position
*
* @return self The builder instance for method chaining
* @return self
*/
public function position(string $position): self
{
src/Prime/Notification/Notification.php
+23 -23
View File
@@ -39,9 +39,9 @@ final class Notification implements NotificationInterface
private array $options = [];
/**
* Gets the title of the notification.
* Gets the title.
*
* @return string The notification title
* @return string
*/
public function getTitle(): string
{
@@ -49,9 +49,9 @@ final class Notification implements NotificationInterface
}
/**
* Sets the title of the notification.
* Sets the title.
*
* @param string $title The title to set
* @param string $title
*/
public function setTitle(string $title): void
{
@@ -59,9 +59,9 @@ final class Notification implements NotificationInterface
}
/**
* Gets the message of the notification.
* Gets the message.
*
* @return string The notification message
* @return string
*/
public function getMessage(): string
{
@@ -69,9 +69,9 @@ final class Notification implements NotificationInterface
}
/**
* Sets the message of the notification.
* Sets the message.
*
* @param string $message The message to set
* @param string $message
*/
public function setMessage(string $message): void
{
@@ -79,9 +79,9 @@ final class Notification implements NotificationInterface
}
/**
* Gets the type of the notification.
* Gets the type.
*
* @return string The notification type
* @return string
*/
public function getType(): string
{
@@ -89,9 +89,9 @@ final class Notification implements NotificationInterface
}
/**
* Sets the type of the notification.
* Sets the type.
*
* @param string $type The type to set
* @param string $type
*/
public function setType(string $type): void
{
@@ -99,9 +99,9 @@ final class Notification implements NotificationInterface
}
/**
* Gets all options of the notification.
* Gets all options.
*
* @return array<string, mixed> The notification options
* @return array<string, mixed>
*/
public function getOptions(): array
{
@@ -122,12 +122,12 @@ final class Notification implements NotificationInterface
}
/**
* Gets a specific option of the notification with a default fallback.
* Gets a specific option with a default fallback.
*
* @param string $name The name of the option
* @param mixed $default The default value to return if the option is not set
* @param string $name
* @param mixed $default
*
* @return mixed The option value or the default value
* @return mixed
*/
public function getOption(string $name, mixed $default = null): mixed
{
@@ -137,10 +137,10 @@ final class Notification implements NotificationInterface
}
/**
* Sets a specific option for the notification.
* Sets a specific option.
*
* @param string $name The name of the option
* @param mixed $value The value of the option
* @param string $name
* @param mixed $value
*/
public function setOption(string $name, mixed $value): void
{
@@ -148,9 +148,9 @@ final class Notification implements NotificationInterface
}
/**
* Unsets a specific option of the notification.
* Unsets a specific option.
*
* @param string $name The name of the option to unset
* @param string $name
*/
public function unsetOption(string $name): void
{
src/Prime/Response/Response.php
+4 -4
View File
@@ -108,7 +108,7 @@ final class Response
/**
* Gets the main script path.
*
* @return string The path to the main JavaScript file
* @return string
*/
public function getMainScript(): string
{
@@ -118,7 +118,7 @@ final class Response
/**
* Sets the main script path.
*
* @param string $mainScript The path to the main JavaScript file
* @param string $mainScript
*/
public function setMainScript(string $mainScript): void
{
@@ -128,7 +128,7 @@ final class Response
/**
* Gets the CSS stylesheets.
*
* @return string[] The stylesheet paths
* @return string[]
*/
public function getStyles(): array
{
@@ -138,7 +138,7 @@ final class Response
/**
* Gets the JavaScript scripts.
*
* @return string[] The script paths
* @return string[]
*/
public function getScripts(): array
{
src/Prime/Response/ResponseManager.php
+5 -5
View File
@@ -112,13 +112,13 @@ final class ResponseManager implements ResponseManagerInterface
/**
* Creates a Response object with notifications and context.
*
* This method creates a basic Response object and then populates it with
* resources (scripts, styles, options) using the ResourceManager.
* This method creates a Response object and populates it with resources
* (scripts, styles, options) using the ResourceManager.
*
* @param Envelope[] $envelopes The notification envelopes
* @param array<string, mixed> $context Additional context for the presentation
* @param Envelope[] $envelopes
* @param array<string, mixed> $context
*
* @return Response The populated response object
* @return Response
*/
private function createResponse(array $envelopes, array $context): Response
{
src/Prime/Storage/StorageManager.php
+14 -14
View File
@@ -46,9 +46,9 @@ final readonly class StorageManager implements StorageManagerInterface
}
/**
* Retrieves all stored notification envelopes.
* Retrieves all stored envelopes.
*
* @return Envelope[] Array of notification envelopes
* @return Envelope[]
*/
public function all(): array
{
@@ -56,17 +56,17 @@ final readonly class StorageManager implements StorageManagerInterface
}
/**
* Filters notifications based on provided criteria.
* Filters notifications by criteria.
*
* This method combines default criteria with the provided criteria,
* creates a filter using the filter factory, and applies it to the envelopes.
* This method combines default criteria with provided criteria,
* creates a filter using the filter factory, and applies it to envelopes.
* Before applying the filter, it dispatches a FilterEvent to allow modification.
*
* @param array<string, mixed> $criteria Filtering criteria
* @param array<string, mixed> $criteria
*
* @return Envelope[] Array of filtered notification envelopes
* @return Envelope[]
*
* @throws CriteriaNotRegisteredException If a requested filter criterion doesn't exist
* @throws CriteriaNotRegisteredException
*/
public function filter(array $criteria = []): array
{
@@ -80,12 +80,12 @@ final readonly class StorageManager implements StorageManagerInterface
}
/**
* Adds one or more notification envelopes to storage.
* Adds notification envelopes to storage.
*
* Before adding envelopes, it dispatches a PersistEvent to allow modification
* of the envelopes. After storage, it dispatches a PostPersistEvent.
*
* @param Envelope ...$envelopes One or more notification envelopes to store
* @param Envelope ...$envelopes
*/
public function add(Envelope ...$envelopes): void
{
@@ -99,12 +99,12 @@ final readonly class StorageManager implements StorageManagerInterface
}
/**
* Updates one or more notification envelopes in storage.
* Updates notification envelopes in storage.
*
* Before updating envelopes, it dispatches an UpdateEvent to allow modification
* of the envelopes. After update, it dispatches a PostUpdateEvent.
*
* @param Envelope ...$envelopes One or more notification envelopes to update
* @param Envelope ...$envelopes
*/
public function update(Envelope ...$envelopes): void
{
@@ -118,13 +118,13 @@ final readonly class StorageManager implements StorageManagerInterface
}
/**
* Removes one or more notification envelopes from storage.
* Removes notification envelopes from storage.
*
* Before removal, it dispatches a RemoveEvent to allow listeners to modify
* which envelopes should be removed or kept. After removal, it dispatches
* a PostRemoveEvent.
*
* @param Envelope ...$envelopes One or more notification envelopes to remove
* @param Envelope ...$envelopes
*/
public function remove(Envelope ...$envelopes): void
{