README

Simple flash toastr notifications for Yii2

Yii2 Toastr uses Toastr library
Demo: https://codeseven.github.io/toastr/demo.html

Yii2 Toastr

Installation

Install via Composer:

composer require diecoding/yii2-toastr "^1.0"

Or add to your composer.json:

{
    "require": {
        "diecoding/yii2-toastr": "^1.0"
    }
}

Dependencies

PHP 7.4+
yiisoft/yii2 (≥2.0.14)
npm-asset/toastr

Usage

Layouts/Views

Add ToastrFlash widget to your layout file (e.g., views/layouts/main.php):

Basic Usage

use diecoding\toastr\ToastrFlash;

ToastrFlash::widget();

Advanced Configuration

use diecoding\toastr\ToastrFlash;

ToastrFlash::widget([
    "typeDefault"       => ToastrFlash::TYPE_INFO,            // (string) default `ToastrFlash::TYPE_INFO`
    "titleDefault"      => "",                                // (string) default `""`
    "messageDefault"    => "",                                // (string) default `""`
    "closeButton"       => false,                             // (bool) default `false`
    "debug"             => false,                             // (bool) default `false`
    "newestOnTop"       => true,                              // (bool) default `true`
    "progressBar"       => true,                              // (bool) default `true`
    "positionClass"     => ToastrFlash::POSITION_TOP_RIGHT,   // (string) default `ToastrFlash::POSITION_TOP_RIGHT`
    "preventDuplicates" => true,                              // (bool) default `true`
    "showDuration"      => 300,                               // (int|null) default `300` in `ms`, `null` for skip
    "hideDuration"      => 1000,                              // (int|null) default `1000` in `ms`, `null` for skip
    "timeOut"           => 5000,                              // (int|null) default `5000` in `ms`, `null` for skip
    "extendedTimeOut"   => 1000,                              // (int|null) default `1000` in `ms`, `null` for skip
    "showEasing"        => "swing",                           // (string) default `swing`, `swing` and `linear` are built into jQuery
    "hideEasing"        => "swing",                           // (string) default `swing`, `swing` and `linear` are built into jQuery
    "showMethod"        => "slideDown",                       // (string) default `slideDown`, `fadeIn`, `slideDown`, and `show` are built into jQuery
    "hideMethod"        => "slideUp",                         // (string) default `slideUp`, `hide`, `fadeOut` and `slideUp` are built into jQuery
    "tapToDismiss"      => true,                              // (bool) default `true`
    "escapeHtml"        => true,                              // (bool) default `true`
    "rtl"               => false,                             // (bool) default `false`
    "skipCoreAssets"    => false,                             // (bool) default `false`, `true` if use custom or external toastr assets
    "options"           => [],                                // (array) default `[]`, Custom Toastr options and override default options
]);

Controllers

Use the standard Yii2 flash message system:

Simple Flash Messages

// Single message
Yii::$app->session->setFlash('error', 'Something went wrong!');
Yii::$app->session->setFlash('success', 'Operation completed successfully!');
Yii::$app->session->setFlash('info', 'Information message');
Yii::$app->session->setFlash('warning', 'Warning message');

Multiple Messages

Yii::$app->session->setFlash('error', [
    'Message 1',
    'Message 2', 
    'Message 3'
]);

Messages with Titles (< v1.4.0)

Yii::$app->session->setFlash('error', [
    ['Title', 'Message']
]);

// Multiple messages with titles
Yii::$app->session->setFlash('error', [
    ['Title 1', 'Message 1'], 
    ['Title 2', 'Message 2'], 
    ['Title 3', 'Message 3']
]);

Advanced Usage with Custom Options (≥ v1.4.0)

// Array format
Yii::$app->session->setFlash('error', [
    ['Title', 'Message', ['timeOut' => 10000]]
]);

// Associative array format
Yii::$app->session->setFlash('error', [
    [
        'title' => 'Custom Title',
        'message' => 'Custom message',
        'options' => [
            'progressBar' => true,
            'timeOut' => 5000,
            'hideDuration' => 1000
        ]
    ]
]);

Complex Example with Multiple Messages

Yii::$app->session->setFlash('info', [
    [
        'title' => 'Step 1 Complete', 
        'message' => 'Data validation passed', 
        'options' => ['progressBar' => true, 'timeOut' => 5000]
    ],
    [
        'title' => 'Step 2 Complete', 
        'message' => 'Data saved successfully',
        'options' => ['progressBar' => false, 'timeOut' => 3000]
    ],
    ['Simple message without custom options']
]);

Testing

Run the test suite using PHPUnit:

# Install dependencies
composer install

# Run tests
composer test

# Run tests with coverage (requires PCOV or Xdebug)
composer test:coverage

# Generate HTML coverage report
composer test:coverage-html

The test suite covers:

✅ ToastrBase - Base widget functionality and constants
✅ Toastr - Main notification widget properties and methods
✅ ToastrFlash - Flash message integration
✅ ToastrAsset - Asset bundle configuration

Coverage Requirements:

Target: >80% code coverage
Supports PHP 7.4, 8.0, 8.1, 8.2, 8.3
Automated testing via GitHub Actions

Code Quality

This project maintains high standards through automated quality checks:

PHP CodeSniffer - PSR-12 coding standards
PHP CS Fixer - Modern PHP code formatting
PHPStan - Static analysis (level 5)

# Run all quality checks
composer quality

# Individual commands
composer cs           # Check code style
composer cs:fix       # Auto-fix code style  
composer phpstan      # Run static analysis

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run quality checks (composer quality)
Run tests (composer test)
Commit your changes (git commit -am 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Requirements:

Write tests for new features
Follow PSR-12 coding standards
Ensure all quality checks pass
Update documentation as needed

License

This package is open-source software licensed under the MIT License.

Built with ❤️ for the Yii2 community.

diecoding / yii2-toastr

Maintainers

Details