tamtamchik / simple-flash
Easy, framework agnostic flash notifications for PHP.
Installs: 76 912
Dependents: 6
Suggesters: 0
Security: 0
Stars: 103
Watchers: 6
Forks: 15
Open Issues: 0
Requires
- php: >=7.3
Requires (Dev)
README
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:
- Bootstrap (default)
- Foundation
- Bulma
- Materialize
- Tailwind
- Premier
- UIKit
- Semantic UI
- Spectre.css
- Halfmoon
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.
Install
Via Composer.
$ composer require tamtamchik/simple-flash
Inside your project make sure to start a session and load Composer autoload to make everything work.
<?php // Start a Session if( !session_id() ) { session_start(); } // Initialize Composer Autoload require_once 'vendor/autoload.php';
Usage
There are 3 ways to use library:
use \Tamtamchik\SimpleFlash\Flash; use function Tamtamchik\SimpleFlash\flash; // Instance $flash = new Flash(); $flash->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
.
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
.
<div class="alert alert-danger" role="alert"> <p>Invalid email!</p> <p>Invalid username!</p> </div> <div class="alert alert-warning" role="alert"><p>Warning message.</p></div> <div class="alert alert-info" role="alert"><p>Info message.</p></div> <div class="alert alert-success" role="alert"><p>Success message!</p></div>
Rendering is simple:
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... <?php // ... some code $flash = new Flash(); $flash->warning('It is totally just for display, never do this in real life...'); // ... some other code ?> <!-- ... some html --> <div class="flashes"> <?= $flash; ?> </div> <!-- ... some other html -->
Templates
Using templates you can customize how flash messages will be rendered. Package comes with a set of templates for most popular CSS frameworks:
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:
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:
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:
This templates can be created using TemplateFactory that comes with package. All templates have aliases defined in Templates.
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.
Defining and using this sample class as template:
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 = '<ul class="alert-%s">%s</ul>'; // 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:
<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.
Change log
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer tests
Examples
$ composer examples
And then just visit http://localhost:8000
Contributing
Please see CONTRIBUTING and CONDUCT for details.
Security
If you discover any security related issues, please email yuri.tam.tkachenko@gmail.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.