tamtamchik/simple-flash

Easy, framework agnostic flash notifications for PHP.

Simple Flash Messages

![Total Downloads][ico-downloads] ![Software License][ico-license] ![Coverage Status][ico-scrutinizer] ![SensioLabsInsight][ico-insight], _(*1)

Easy, framework-agnostic flash notifications for PHP. Inspired by laracasts/flash and plasticbrain/PHP-Flash-Messages. It supports multiple CSS frameworks out of the box:, _(*2)

• Bootstrap (default)
• Foundation
• Bulma
• Materialize
• Tailwind
• Premier
• UIKit
• Semantic UI
• Spectre.css
• Halfmoon

, _(*3)

[!NOTE] The documentation below is for version 3.x!
If you are looking the documentation for version 2.x look here.
If you are looking the documentation for version 1.x look here., _(*4)

Install

Via Composer., _(*5)

$ composer require tamtamchik/simple-flash

Inside your project make sure to start a session and load Composer autoload to make everything work., _(*6)

````php message('Tea.'); // Static Flash::message('Earl Gray.'); // Function flash()->message('Hot!'); ``` Messages added by calling `message($message, $type = 'info')` method. In case of calling a function `flash()` you can pass `$message, $type` just to function like so: `flash('resistance is futile')`. Because any of creation types return `\Tamtamchik\SimpleFlash\Flash` instance, so you can always use chaining to add multiple messages. Shortcuts available for all types of base message types, also you can pass arrays as `$message`. ```php use function Tamtamchik\SimpleFlash\flash; flash()->error(['Invalid email!', 'Invalid username!']) ->warning('Warning message.') ->info('Info message.') ->success('Success message!'); ``` Out of the box library support 4 different types of messages: `error`, `warning`, `info`, `success`. ```html , _(*7)

``` Rendering is simple: ```php use function Tamtamchik\SimpleFlash\flash; // Rendering specific type $output = flash()->display('error'); // Rendering all flash $output = flash()->display(); // Also rendering possible when you just read instance of \Tamtamchik\SimpleFlash\Flash object as a string (string) flash(); // or ... it's totally just for display, never do this in real life... warning('It is totally just for display, never do this in real life...'); // ... some other code ?>

## Templates

Using templates you can customize how flash messages will be rendered. 
Package comes with a set of templates for most popular CSS frameworks:

```php
Templates::BASE; // Same as Templates::BOOTSTRAP
Templates::BOOTSTRAP;   // https://getbootstrap.com
Templates::FOUNDATION;  // https://get.foundation
Templates::BULMA;       // https://bulma.io
Templates::MATERIALIZE; // https://materializecss.com
Templates::TAILWIND;    // https://tailwindcss.com
Templates::PRIMER;      // https://primer.style
Templates::UIKIT;       // https://getuikit.com
Templates::SEMANTIC;    // https://semantic-ui.com
Templates::SPECTRE;     // https://picturepan2.github.io/spectre
Templates::HALFMOON;    // https://www.gethalfmoon.com

Shortcuts

You cah pass template name as a second argument to display() function:, _(*13)

use function Tamtamchik\SimpleFlash\flash;

flash()->success('Success message!');
...
// rendering with Halfmoon template using Templates::HALFMOON as a shortcut
echo flash()->display('success', Templates::HALFMOON);

Or you can use descriptive display functions:, _(*14)

use function Tamtamchik\SimpleFlash\flash;

flash()->success('Success message!');
...
echo flash()->displayBootstrap();
echo flash()->displayFoundation();
echo flash()->displayBulma();
echo flash()->displayMaterialize();
echo flash()->displayTailwind();
echo flash()->displayPrimer();
echo flash()->displayUiKit();
echo flash()->displaySemantic();
echo flash()->displaySpectre();
echo flash()->displayHalfmoon();

Factory

Package comes with a set of templates for most popular CSS frameworks:, _(*15)

This templates can be created using TemplateFactory that comes with package. All templates have aliases defined in Templates., _(*16)

use Tamtamchik\SimpleFlash\Flash;
use Tamtamchik\SimpleFlash\TemplateFactory;
use Tamtamchik\SimpleFlash\Templates;

// get template from factory, e.g. template for Foundation
$template = TemplateFactory::create(Templates::FOUNDATION);

// passing template via function
flash('Info message using Foundation 6 template!', 'info', $template);

// passing to constructor
$flash = new Flash($template);

// using setTemplate function
$flash->setTemplate($template);

Creating templates

Template is basically any class that implements TemplateInterface. But to make it easy you can extend BaseTemplate, it already contains most of the functions., _(*17)

Defining and using this sample class as template:, _(*18)

use Tamtamchik\SimpleFlash\BaseTemplate;
use Tamtamchik\SimpleFlash\TemplateInterface;
use function Tamtamchik\SimpleFlash\flash;

class CustomTemplate extends BaseTemplate implements TemplateInterface
{
    protected $prefix  = '<li>'; // every line prefix
    protected $postfix = '</li>'; // every line postfix
    protected $wrapper = '

%s

'; // wrapper over messages of same type /** * @param $messages - message text * @param $type - message type: success, info, warning, error * * @return string */ public function wrapMessages($messages, $type) { return sprintf($this->getWrapper(), $type, $messages); } } flash() ->setTemplate(new CustomTemplate) ->error(['Invalid email!', 'Invalid username!']) ->warning('Warning message.') ->info('Info message.') ->success('Success message!') ->display();

Will output following:, _(*19)

<ul class="alert-error">
    <li>Invalid email!</li>
    <li>Invalid username!</li>
</ul>
<ul class="alert-warning">
    <li>Warning message.</li>
</ul>
<ul class="alert-info">
    <li>Info message.</li>
</ul>
<ul class="alert-success">
    <li>Success message!</li>
</ul>

Interface

Package provides TemplateInterface for Simple Flash templates., _(*20)

Change log

Please see CHANGELOG for more information what has changed recently., _(*21)

Testing

``` bash $ composer tests, <sub>(*22)</sub>

## Examples

``` bash
$ composer examples

And then just visit http://localhost:8000, <sub>(*23)</sub>

Contributing

Please see CONTRIBUTING and CONDUCT for details., <sub>(*24)</sub>

Security

If you discover any security related issues, please email yuri.tam.tkachenko@gmail.com instead of using the issue tracker., <sub>(*25)</sub>

Credits

• Yuri Tkachenko
• All Contributors

License

The MIT License (MIT). Please see License File for more information., <sub>(*26)</sub>

, <sub>(*27)</sub>