README

PHPFlasher: Beautiful Notifications Made Simple

🚀 See It In Action

// In your controller
public function updateProfile(Request $request)
{
    // Process form submission
    $user = Auth::user();
    $user->update($request->validated());
    
    // Show a beautiful notification to the user
    flash()->success('Your profile has been updated successfully!');
    
    return redirect()->back();
}

That's it! PHPFlasher will display an elegant success notification to your user. No JavaScript to write, no frontend setup needed.

🔄 Compatibility

Requirements	Version
PHP	≥ 8.2
Laravel	≥ 11.0
Symfony	≥ 7.0

📑 Table of Contents

Introduction
Features
Installation
Usage Examples
Themes
Adapters
Advanced Configuration
Adapter Documentation Example
Community & Support
Contributors
License

🌟 Introduction

PHPFlasher is a powerful, framework-agnostic library that makes it simple to add beautiful flash messages to your web applications. It provides a consistent API for displaying notifications across your PHP applications, whether you're using Laravel, Symfony, or any other PHP framework.

Flash messages are short-lived notifications that appear after a user performs an action, such as submitting a form. PHPFlasher helps you create these notifications with minimal effort while ensuring they look great and behave consistently.

✨ Key Features

Zero JavaScript Required: Write only PHP code - frontend functionality is handled automatically
Framework Support: First-class Laravel and Symfony integration
Beautiful Themes: Multiple built-in themes ready to use out of the box
Multiple Notification Types: Success, error, warning, and info notifications
Highly Customizable: Positions, timeouts, animations, and more
Third-Party Adapters: Integration with popular libraries like Toastr, SweetAlert, and more
API Response Support: Works with AJAX and API responses
TypeScript Support: Full TypeScript definitions for frontend customization
Lightweight: Minimal performance impact

📦 Installation

For Laravel Projects

# Install the Laravel adapter
composer require php-flasher/flasher-laravel

# Set up assets automatically
php artisan flasher:install

PHPFlasher automatically injects the necessary JavaScript and CSS assets into your Blade templates. No additional setup required!

For Symfony Projects

# Install the Symfony adapter
composer require php-flasher/flasher-symfony

# Set up assets automatically
php bin/console flasher:install

PHPFlasher automatically injects the necessary JavaScript and CSS assets into your Twig templates.

📚 Usage Examples

Basic Notifications

// Success notification
flash()->success('Operation completed successfully!');

// Error notification
flash()->error('An error occurred. Please try again.');

// Info notification
flash()->info('Your account will expire in 10 days.');

// Warning notification
flash()->warning('Please backup your data before continuing.');

With Custom Titles

flash()->success('Your changes have been saved!', 'Update Successful');
flash()->error('Unable to connect to the server.', 'Connection Error');

With Custom Options

flash()->success('Profile updated successfully!', [
    'timeout' => 10000,       // Display for 10 seconds
    'position' => 'bottom-right',
    'closeButton' => true,
]);

flash()->error('Failed to submit form.', 'Error', [
    'timeout' => 0,           // No timeout (stay until dismissed)
    'position' => 'center',
]);

In Controllers

// Laravel
public function store(Request $request)
{
    // Process form...
    
    flash()->success('Product created successfully!');
    return redirect()->route('products.index');
}

// Symfony
public function store(Request $request, FlasherInterface $flasher)
{
    // Process form...
    
    $flasher->success('Product created successfully!');
    return $this->redirectToRoute('products.index');
}

Specific Use Cases

// Form validation errors
if ($validator->fails()) {
    flash()->error('Please fix the errors in your form.');
    return redirect()->back()->withErrors($validator);
}

// Multi-step process
flash()->success('Step 1 completed!');
flash()->info('Please complete step 2.');

// With HTML content (must enable HTML option)
flash()->success('Your <strong>account</strong> is ready!', [
    'escapeHtml' => false
]);

🎨 Themes

PHPFlasher comes with beautiful built-in themes ready to use immediately:

Default Theme (Flasher)

The default theme provides clean, elegant notifications that work well in any application:

flash()->success('Operation completed!');

Other Built-In Themes

PHPFlasher includes multiple themes to match your application's design:

// Set the theme in your configuration or per notification
flash()->success('Operation completed!', [
    'theme' => 'amazon'    // Amazon-inspired theme
]);

// Other available themes:
// - amber: Warm amber styling
// - aurora: Subtle gradient effects
// - crystal: Clean, transparent design
// - emerald: Green-focused modern look
// - facebook: Facebook notification style
// - google: Google Material Design inspired
// - ios: iOS notification style
// - jade: Soft jade color palette
// - material: Material Design implementation
// - minimal: Extremely clean and simple
// - neon: Bright, attention-grabbing
// - onyx: Dark mode sleek design
// - ruby: Bold ruby red accents
// - sapphire: Blue-focused elegant style
// - slack: Slack-inspired notifications

Theme Configuration

You can configure theme defaults in your configuration file:

// Laravel: config/flasher.php
return [
    'themes' => [
        'flasher' => [
            'options' => [
                'timeout' => 5000,
                'position' => 'top-right',
            ],
        ],
        'amazon' => [
            'options' => [
                'timeout' => 3000,
                'position' => 'bottom-right',
            ],
        ],
    ],
];

🧩 Adapters

Beyond PHPFlasher's built-in themes, you can use third-party notification libraries:

Available Adapters

Toastr

composer require php-flasher/flasher-toastr-laravel # For Laravel
composer require php-flasher/flasher-toastr-symfony # For Symfony

flash('toastr')->success('Message with Toastr!');

SweetAlert

composer require php-flasher/flasher-sweetalert-laravel # For Laravel
composer require php-flasher/flasher-sweetalert-symfony # For Symfony

flash('sweetalert')->success('Message with SweetAlert!');

Noty

composer require php-flasher/flasher-noty-laravel # For Laravel
composer require php-flasher/flasher-noty-symfony # For Symfony

flash('noty')->success('Message with Noty!');

Notyf

composer require php-flasher/flasher-notyf-laravel # For Laravel
composer require php-flasher/flasher-notyf-symfony # For Symfony

flash('notyf')->success('Message with Notyf!');

⚙️ Advanced Configuration

Laravel Configuration

Publish and customize the configuration:

php artisan vendor:publish --tag=flasher-config

This creates config/flasher.php where you can configure:

return [
    // Default adapter to use
    'default' => 'flasher',
    
    // Theme configuration
    'themes' => [
        'flasher' => [
            'options' => [
                'timeout' => 5000,
                'position' => 'top-right',
            ],
        ],
    ],
    
    // Auto-convert Laravel session flash messages
    'auto_create_from_session' => true,
    
    // Automatically render notifications
    'auto_render' => true,
    
    // Type mappings for Laravel notifications
    'types_mapping' => [
        'success' => 'success',
        'error' => 'error',
        'warning' => 'warning',
        'info' => 'info',
    ],
];

Symfony Configuration

Create or edit config/packages/flasher.yaml:

flasher:
    default: flasher
    
    themes:
        flasher:
            options:
                timeout: 5000
                position: top-right
    
    auto_create_from_session: true
    auto_render: true
    
    types_mapping:
        success: success
        error: error
        warning: warning
        info: info

Notification Options

Common options you can customize:

flash()->success('Message', [
    // Display duration in milliseconds (0 = until dismissed)
    'timeout' => 5000,
    
    // Notification position
    'position' => 'top-right', // top-right, top-left, bottom-right, bottom-left, top-center, bottom-center
    
    // Display a close button
    'closeButton' => true,
    
    // Show progress bar during timeout
    'progressBar' => true,
    
    // Right-to-left text direction
    'rtl' => false,
    
    // Allow HTML content in notifications
    'escapeHtml' => false,
    
    // Custom CSS class
    'class' => 'my-custom-notification',
]);

📘 Adapter Documentation Example

Here's a detailed example of using the Toastr adapter with PHPFlasher:

Installation

composer require php-flasher/flasher-toastr

For Laravel:

composer require php-flasher/flasher-toastr-laravel

For Symfony:

composer require php-flasher/flasher-toastr-symfony

Usage

Basic Usage

use Flasher\Toastr\Prime\ToastrFactory;

// Inject the factory
public function __construct(private ToastrFactory $toastr)
{
}

public function index()
{
    $this->toastr->success('Toastr is working!');
    
    // Or using the global helper with the specified adapter
    flash('toastr')->success('Toastr is awesome!');
}

With Options

flash('toastr')->success('Success message', 'Success Title', [
    'timeOut' => 5000,
    'closeButton' => true,
    'newestOnTop' => true,
    'progressBar' => true,
    'positionClass' => 'toast-top-right',
]);

Available Methods

// Standard notification types
flash('toastr')->success('Success message');
flash('toastr')->info('Information message');
flash('toastr')->warning('Warning message');
flash('toastr')->error('Error message');

// Custom notification
flash('toastr')->flash('custom-type', 'Custom message');

Toastr Specific Options

Option	Type	Default	Description
closeButton	Boolean	false	Display a close button
closeClass	String	'toast-close-button'	CSS class for close button
newestOnTop	Boolean	true	Add notifications to the top of the stack
progressBar	Boolean	true	Display progress bar
positionClass	String	'toast-top-right'	Position of the notification
preventDuplicates	Boolean	false	Prevent duplicates
showDuration	Number	300	Show animation duration in ms
hideDuration	Number	1000	Hide animation duration in ms
timeOut	Number	5000	Auto-close duration (0 = disable)
extendedTimeOut	Number	1000	Duration after hover
showEasing	String	'swing'	Show animation easing
hideEasing	String	'linear'	Hide animation easing
showMethod	String	'fadeIn'	Show animation method
hideMethod	String	'fadeOut'	Hide animation method

Advanced Configuration

Laravel Configuration

Publish the configuration file:

php artisan vendor:publish --tag=flasher-toastr-config

Symfony Configuration

Edit your config/packages/flasher.yaml:

flasher:
    toastr:
        options:
            timeOut: 5000
            progressBar: true

Learn More

For additional information, see the PHPFlasher documentation.

👥 Community & Support

Getting Help

Documentation: Visit https://php-flasher.io
GitHub Issues: Report bugs or request features
Stack Overflow: Ask questions with the php-flasher tag

Common Use Cases

Form submission feedback
AJAX request notifications
Authentication messages
Error reporting
Success confirmations
System alerts

🌟 Contributors and Sponsors

Join our team of contributors and make a lasting impact on our project!

We are always looking for passionate individuals who want to contribute their skills and ideas. Whether you're a developer, designer, or simply have a great idea, we welcome your participation and collaboration.

Shining stars of our community:

_{Younes ENNAJI} 💻 📖 🚧	_{Salma Mourad} 💵	_{Nashwan Abdullah} 💵	_{Arvid de Jong} 💵	_{Ash Allen} 🎨	_{Tony Murray} 💻	_{Stéphane P} 📖
_{Lucas Maciel} 🎨	_{Ahmed Gamal} 💻 📖	_Brooke. 📖

📬 Contact

PHPFlasher is being actively developed by yoeunes. You can reach out with questions, bug reports, or feature requests on any of the following:

📝 License

PHPFlasher is open-sourced software licensed under the MIT license.

Made with ❤️ by Younes ENNAJI

⭐ Star if you found this useful ⭐

php-flasher / php-flasher

Maintainers

Details

README

PHPFlasher: Beautiful Notifications Made Simple

🚀 See It In Action

🔄 Compatibility

📑 Table of Contents

🌟 Introduction

✨ Key Features

📦 Installation

For Laravel Projects

For Symfony Projects

📚 Usage Examples

Basic Notifications

With Custom Titles

With Custom Options

In Controllers

Specific Use Cases

🎨 Themes

Default Theme (Flasher)

Other Built-In Themes

Theme Configuration

🧩 Adapters

Available Adapters

Toastr

SweetAlert

Noty

Notyf

⚙️ Advanced Configuration

Laravel Configuration

Symfony Configuration

Notification Options

📘 Adapter Documentation Example

Installation

Usage

Basic Usage

With Options

Available Methods

Toastr Specific Options

Advanced Configuration

Laravel Configuration

Symfony Configuration

Learn More

👥 Community & Support

Getting Help

Common Use Cases

🌟 Contributors and Sponsors

📬 Contact

📝 License