simple-flash - GitLite

KO | EN

gitlite — search

#javascript #react #golang #android #deep-learning #linux #docker #nodejs #java #awesome #kubernetes #vue #pytorch #ios

simple-flash

(★ 106)

Easy, framework-agnostic flash notifications for PHP.

파일 탐색기

최종 버전 다운로드 (.zip)

- - devcontainer.json
  - Dockerfile
- - devcontainer.json
  - Dockerfile
- devcontainer.json
- Dockerfile
- - bug_report.md
  - feature_request.md
- - tests.yml
- dependabot.yml
- _init.php
- _menu.php
- _ribbon.php
- beercss.php
- bootstrap.php
- bulma.php
- cirrus.php
- custom.php
- fomantic.php
- foundation.php
- index.php
- primer.php
- tailwind.php
- uikit.php
- vanilla.php
- - index.php
- - create_msg.php
  - msg.php
- - Engine.php
  - MessageManager.php
  - SessionManager.php
  - TemplateManager.php
- - FlashSingletonException.php
  - FlashTemplateException.php
  - FlashTemplateNotFoundException.php
- - BeercssTemplate.php
  - BootstrapTemplate.php
  - BulmaTemplate.php
  - CirrusTemplate.php
  - FomanticTemplate.php
  - FoundationTemplate.php
  - PrimerTemplate.php
  - TailwindTemplate.php
  - UikitTemplate.php
  - VanillaTemplate.php
- BaseTemplate.php
- Flash.php
- function.php
- TemplateFactory.php
- TemplateInterface.php
- Templates.php
- BadTemplate.php
- DisplayTest.php
- FactoryTest.php
- FlashTest.php
.editorconfig
.gitattributes
.gitignore
.scrutinizer.yml
_config.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
composer.json
composer.lock
CONDUCT.md
CONTRIBUTING.md
LICENSE.md
phpunit.xml
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Simple Flash Messages

[![Latest Version on Packagist][ico-version]][link-packagist]
![PHP][ico-php]
[![Total Downloads][ico-downloads]][link-downloads]
[![Software License][ico-license]](https://raw.githubusercontent.com/tamtamchik/simple-flash/master/LICENSE.md)
[![Build Status][ico-scrutinizer-build]][link-scrutinizer]
[![Coverage Status][ico-scrutinizer]][link-scrutinizer]
[![Quality Score][ico-code-quality]][link-code-quality]

[![SensioLabsInsight][ico-insight]][link-insight]

Easy, framework-agnostic flash notifications for PHP. Inspired by [laracasts/flash](https://github.com/laracasts/flash) and [plasticbrain/PHP-Flash-Messages](https://github.com/plasticbrain/PHP-Flash-Messages). It supports multiple CSS frameworks out of the box:

* [Bootstrap](https://getbootstrap.com) (default)
* [Foundation](https://get.foundation)
* [Bulma](https://bulma.io)
* [Tailwind](https://tailwindcss.com)
* [Primer](https://primer.style)
* [UIKit](https://getuikit.com)
* [Fomantic UI](https://fomantic-ui.com)
* [Cirrus CSS](https://cirrus-ui.com)
* [Vanilla Framework](https://vanillaframework.io)
* [Beer CSS](https://www.beercss.com)

![simple-flash](https://cloud.githubusercontent.com/assets/265510/24695879/c87b32f2-1a11-11e7-972e-b4b2c75f35b5.png)

> [!NOTE]
> The documentation below is for version 4.x!
> If you are looking for the documentation for version 3.x look [here](https://github.com/tamtamchik/simple-flash/blob/3.0.x/README.md).
> If you are looking for the documentation for version 2.x look [here](https://github.com/tamtamchik/simple-flash/blob/2.0.x/README.md).
> If you are looking for the documentation for version 1.x look [here](https://github.com/tamtamchik/simple-flash/blob/1.2.x/README.md).

## Upgrading from 3.x

The set of bundled templates has been rotated — stalled frameworks were dropped and a new set of actively maintained ones added. The new templates are not drop-in replacements; pick whichever fits your project.

**Removed in 4.0:**
- `Templates::SEMANTIC` / `flash()->displaySemantic()`
- `Templates::SPECTRE` / `flash()->displaySpectre()`
- `Templates::HALFMOON` / `flash()->displayHalfmoon()`
- `Templates::MATERIALIZE` / `flash()->displayMaterialize()`

**Added in 4.0:**
- `Templates::FOMANTIC` / `flash()->displayFomantic()` — [Fomantic UI](https://fomantic-ui.com), the community fork of Semantic UI.
- `Templates::CIRRUS` / `flash()->displayCirrus()` — [Cirrus CSS](https://cirrus-ui.com).
- `Templates::VANILLA` / `flash()->displayVanilla()` — [Vanilla Framework](https://vanillaframework.io).
- `Templates::BEERCSS` / `flash()->displayBeercss()` — [Beer CSS](https://www.beercss.com).

If a removed framework is critical to your project, pin to `^3.0` until you migrate, or write your own template (see [Creating templates](#creating-templates)).

## Install

Via [Composer](http://getcomposer.org).

```bash
$ composer require tamtamchik/simple-flash
```

Inside your project make sure to start a session and load [Composer](http://getcomposer.org) autoload to make everything work.

````php
<?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:

```php
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`.

```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
<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:

```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...
<?php
// ... some code
$flash = new Flash();
$flash->warning('It is totally just for display, never do this in real life...');
// ... some other code
?>

<div class="flashes">
  <?= $flash; ?>
</div>

```

## 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::TAILWIND;    // https://tailwindcss.com
Templates::PRIMER;      // https://primer.style
Templates::UIKIT;       // https://getuikit.com
Templates::FOMANTIC;    // https://fomantic-ui.com
Templates::CIRRUS;      // https://cirrus-ui.com
Templates::VANILLA;     // https://vanillaframework.io
Templates::BEERCSS;     // https://www.beercss.com
```

### Shortcuts

You cah pass template name as a second argument to `display()` function:

```php
use function Tamtamchik\SimpleFlash\flash;

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

Or you can use descriptive display functions:

```php
use function Tamtamchik\SimpleFlash\flash;

flash()->success('Success message!');
...
echo flash()->displayBootstrap();
echo flash()->displayFoundation();
echo flash()->displayBulma();
echo flash()->displayTailwind();
echo flash()->displayPrimer();
echo flash()->displayUiKit();
echo flash()->displayFomantic();
echo flash()->displayCirrus();
echo flash()->displayVanilla();
echo flash()->displayBeercss();
```

### Factory

Package comes with a set of templates for most popular CSS frameworks:

This templates can be created using [TemplateFactory](src/TemplateFactory.php) that comes with package.
All templates have aliases defined in [Templates](src/Templates.php).

```php
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](src/TemplateInterface.php). But to make it easy
you can extend [BaseTemplate](src/BaseTemplate.php), it already contains most of the functions.

Defining and using this sample class as template:

```php
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:

```html
<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](CHANGELOG.md) for more information what has changed recently.

## Testing

``` bash
$ composer tests
```

## Examples

``` bash
$ composer examples
```
And then just visit [http://localhost:8000](http://localhost:8000)

## Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) and [CONDUCT](CONDUCT.md) for details.

## Security

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

## Credits

- [Yuri Tkachenko][link-author]
- [All Contributors][link-contributors]

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

[![Buy Me A Coffee][ico-coffee]][link-coffee]

[ico-version]: https://img.shields.io/packagist/v/tamtamchik/simple-flash.svg?style=flat-square
[ico-license]: https://img.shields.io/packagist/l/tamtamchik/simple-flash.svg?style=flat-square
[ico-scrutinizer-build]: https://img.shields.io/scrutinizer/build/g/tamtamchik/simple-flash.svg?style=flat-square
[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/tamtamchik/simple-flash.svg?style=flat-square
[ico-code-quality]: https://img.shields.io/scrutinizer/g/tamtamchik/simple-flash.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/tamtamchik/simple-flash.svg?style=flat-square
[ico-coffee]: https://img.shields.io/badge/Buy%20Me%20A-Coffee-%236F4E37.svg?style=flat-square
[ico-insight]: https://insight.symfony.com/projects/a92cacf2-ba32-4f36-b040-5a9f1d7f8f25/small.svg
[ico-php]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fgithub.com%2Ftamtamchik%2Fsimple-flash%2Fraw%2Fmaster%2Fcomposer.json&query=%24.require.php&style=flat-square&label=PHP

[link-packagist]: https://packagist.org/packages/tamtamchik/simple-flash
[link-scrutinizer]: https://scrutinizer-ci.com/g/tamtamchik/simple-flash/code-structure
[link-code-quality]: https://scrutinizer-ci.com/g/tamtamchik/simple-flash
[link-downloads]: https://packagist.org/packages/tamtamchik/simple-flash
[link-author]: https://github.com/tamtamchik
[link-contributors]: ../../contributors
[link-coffee]: https://www.buymeacoffee.com/tamtamchik
[link-insight]: https://insight.symfony.com/projects/a92cacf2-ba32-4f36-b040-5a9f1d7f8f25