包简介

A beautiful, performant toast notification package for Laravel Livewire with real-time support

README 文档

README

Flare

Production-Ready Toast Notifications for Laravel Livewire

Elegant • Performant • Customizable

Features • Installation • Quick Start • Documentation • Themes • Examples

🎯 Overview

Flare is a modern, feature-rich toast notification system built specifically for Laravel Livewire applications. With zero configuration required and three distinct visual themes, Flare provides beautiful user feedback out of the box while offering extensive customization for advanced use cases.

👉 Try the Live Playground

// Simple, elegant API
Flare::success('Profile updated successfully!');

// Full control when you need it
Flare::warning(
    text: 'Session expires in 5 minutes',
    heading: 'Warning',
    duration: 10000,
    position: 'top center'
);

✨ Features

🎨 Three Professional Themes

Classic - Minimal, clean, fastest performance
Modern - Balanced design with subtle effects (default)
Vibrant - Bold, colorful, attention-grabbing

All themes include:

✓ Light & dark mode support
✓ Smooth animations
✓ Responsive design
✓ RTL/LTR layouts

⚡ High Performance

Alpine.js powered (minimal overhead)
Optimized CSS transitions
Smart caching & compilation
No jQuery dependency
Lightweight footprint (~15KB)

🔧 Developer Experience

Zero Configuration - Works out of the box
Simple API - Intuitive, clean methods
Livewire Trait - use WithFlare
TypeScript Support - Full type definitions
IDE Autocomplete - PHPDoc annotations

📍 Flexible Positioning

6 position options (top/bottom × start/center/end)
Per-toast position override
RTL/LTR automatic adaptation
Responsive mobile behavior

🎭 Advanced Features

Stacking System - Configurable toast layering
Auto-Dismiss - Configurable duration
Hover Pause - Pause on mouse hover
Keyboard Shortcuts - Esc, Shift+Esc, Alt+D
Progress Bar - Visual countdown
Queue Management - Handle multiple toasts

🧪 Production Ready

✓ Comprehensive test suite (12 tests, 22 assertions)
✓ PHPStan Level 9 compliance
✓ PSR-12 code style
✓ CI/CD with GitHub Actions
✓ Semantic versioning
✓ Extensive documentation

📋 Requirements

Requirement	Version
PHP	8.3+
Laravel	12.0+ / 13.0+
Livewire	3.5+ / 4.0+
Alpine.js	3.x / 4.x

🚀 Installation

Step 1: Install via Composer

composer require alizharb/flare

Step 2: Publish Assets

IMPORTANT: Assets must be published for Flare to work.

php artisan vendor:publish --tag=flare-assets

Step 3: Add to Layout

<!DOCTYPE html>
<html lang="en">
<head>
    @flareStyles {{-- Required --}}
</head>
<body>
    <flare::toasts /> {{-- Required --}}

    @flareScripts {{-- Required --}}
</body>
</html>

That's it! 🎉 You're ready to use Flare.

Optional Configuration

# Publish config file
php artisan vendor:publish --tag=flare-config

# Publish views for customization
php artisan vendor:publish --tag=flare-views

⚡ Quick Start

Using the Facade

Perfect for controllers, services, and any PHP class:

use AlizHarb\Flare\Facades\Flare;

class UserController extends Controller
{
    public function store(Request $request)
    {
        User::create($request->validated());

        Flare::success('User created successfully!');

        return redirect()->route('users.index');
    }
}

Using the Livewire Trait

The easiest way in Livewire components:

use Livewire\Component;
use AlizHarb\Flare\Concerns\WithFlare;

class CreatePost extends Component
{
    use WithFlare;

    public function save()
    {
        Post::create($this->validate());

        $this->flareSuccess('Post published!', 'Success');
    }
}

Using JavaScript

For client-side notifications:

// Simple
Flare.success("Item added to cart!");

// Advanced
Flare.toast("Welcome back!", {
    heading: "Hello User",
    variant: "info",
    duration: 5000,
    position: "top center",
});

🎨 Themes

Flare includes three professionally designed themes. Choose the one that fits your application's aesthetic.

Classic

Minimal & Professional

Solid backgrounds
Single shadow
No blur
⚡ Fastest

'theme' => 'classic'

Modern

Balanced & Contemporary

Subtle gradients
Light blur (4px)
2 shadow layers
⚡ Fast (default)

'theme' => 'modern'

Vibrant

Bold & Colorful

Strong gradients
Glowing shadows
Moderate blur (8px)
⚡ Good

'theme' => 'vibrant'

All themes support light & dark modes automatically.

📚 Documentation

📖 Complete Documentation

Visit our comprehensive documentation:

Introduction - What is Flare?
Installation - Detailed setup guide
Quick Start - Get started in 5 minutes
Playground - Try it live
Themes - Visual customization
Configuration - All options explained
Examples - Real-world scenarios

🌐 Interactive Docs

Run the documentation website locally:

php -S localhost:8000 -t docs

Visit http://localhost:8000 for interactive documentation.

💡 API Reference

Toast Variants

Flare::success($text, $heading = null, $duration = 5000, $position = null);
Flare::warning($text, $heading = null, $duration = 5000, $position = null);
Flare::danger($text, $heading = null, $duration = 5000, $position = null);
Flare::error($text, $heading = null, $duration = 5000, $position = null); // Alias
Flare::info($text, $heading = null, $duration = 5000, $position = null);

Livewire Trait Methods

$this->flareSuccess($text, $heading = null, $duration = 5000, $position = null);
$this->flareWarning($text, $heading = null, $duration = 5000, $position = null);
$this->flareDanger($text, $heading = null, $duration = 5000, $position = null);
$this->flareError($text, $heading = null, $duration = 5000, $position = null);
$this->flareInfo($text, $heading = null, $duration = 5000, $position = null);

JavaScript API

Flare.toast(text, options);
Flare.success(text, options);
Flare.warning(text, options);
Flare.danger(text, options);
Flare.error(text, options);
Flare.info(text, options);

⚙️ Configuration

View Complete Configuration

return [
    // Visual theme
    'theme' => 'modern', // classic, modern, vibrant

    // Default position
    'position' => 'bottom end',

    // Default duration (ms)
    'duration' => 5000,

    // Stacking behavior
    'enable_stacking' => true,
    'stack_expanded' => false,
    'max_visible' => 3,

    // Features
    'icons' => ['enabled' => true],
    'actions' => ['enabled' => true],
    'priority' => ['enabled' => true],
    'rate_limit' => ['enabled' => true],
    'progress_bar' => ['enabled' => true],
];

Environment Variables

FLARE_THEME=modern
FLARE_POSITION="bottom end"
FLARE_DURATION=5000
FLARE_ENABLE_STACKING=true
FLARE_STACK_EXPANDED=false

🎯 Examples

Form Validation

class ContactForm extends Component
{
    use WithFlare;

    public function submit()
    {
        $this->validate([...]);

        // Send email...

        $this->flareSuccess(
            text: "Thank you! We'll get back to you soon.",
            heading: 'Message Sent',
            duration: 7000
        );
    }
}

CRUD Operations

public function destroy(Post $post)
{
    $post->delete();

    Flare::danger(
        text: 'Post has been permanently deleted',
        heading: 'Deleted',
        duration: 4000
    );

    return redirect()->route('posts.index');
}

Persistent Notifications

// Requires manual dismissal
Flare::danger(
    text: 'Critical error - please contact support',
    heading: 'Error',
    duration: 0 // Never auto-dismiss
);

See EXAMPLES.md for more real-world scenarios.

⌨️ Keyboard Shortcuts

Shortcut	Action
`Esc`	Dismiss most recent toast
`Shift + Esc`	Dismiss all toasts
`Alt + D`	Dismiss all toasts (alternative)

🧪 Testing

Flare includes a comprehensive test suite:

# Run tests
composer test

# Run tests with coverage
composer test:coverage

# Run static analysis
composer analyse

# Run code style fixer
composer format

Test Results: ✅ 12 tests, 22 assertions, 100% passing

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

git clone https://github.com/alizharb/flare.git
cd flare
composer install
composer test

📝 Changelog

See CHANGELOG.md for all changes and version history.

Latest Release: v1.1.0

✨ Three distinct themes (Classic, Modern, Vibrant)
🐛 Fixed all positioning issues
⚡ Improved stacking performance
🌍 Added RTL/LTR support
📚 Complete documentation

📄 License

Flare is open-source software licensed under the MIT License.

🙏 Credits

Built with ❤️ by Ali Harb

Special thanks to:

Laravel & Livewire teams
Alpine.js community
All contributors

🌟 Support

If you find Flare useful, please consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting features
📖 Improving documentation
💰 Sponsoring development

⬆ Back to Top

Made with ❤️ for the Laravel community

alizharb/flare 适用场景与选型建议

alizharb/flare 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 14 次下载、GitHub Stars 达 8，最近一次更新时间为 2025 年 10 月 05 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「notifications」「alerts」「laravel」「alpine」「flash-messages」「toast」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 alizharb/flare 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 alizharb/flare 我们能提供哪些服务？

定制开发 / 二次开发

基于 alizharb/flare 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 alizharb/flare 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

coreproc/nova-notification-feed 99

A Laravel Nova package that adds a notification feed in your Nova app.

ramesh-dada/bbcode-alerts 0

Add visual alerts / warnings to Flarum posts

hampel/alerts 0

Laravel package for managing session messages and alerts in view responses

palmtree/bootstrap-alerts 0

Bootstrap alerts

codium/laravel-sms-capture 2

Captures outgoing SMS notifications

howard/howard_special_alerts_feed 0

This module is designed to provide a special alerts feed block for Howard University

alizharb/flare

包简介

关键字：