README

Simple package for displaying various types of messages in a web app.

Usage

<?php
use werx\Messages\Messages;

// Import the composer autoloader, if you aren't already using it.
require '../vendor/autoload.php';

// Get an instance of the Messages class.
Messages::getInstance();

Now you can add some messages. Valid messages types are error, info, warning, and success.

Messages::error('Oops, something bad happened.');
Messages::info('Nothing big, this is just an informational message.');
Messages::warning('A little more serious than info, but not quite an error.');
Messages::success('Hooray! This is a success message.');
Messages::success('Here is another success message.');

You can also use printf compatible format codes in your message strings along with an array as the 2nd parameter containing string replacements to make it easier to embed dynamic data in your messages without doing a lot of string concatenation.

Messages::error('The quick %s %s jumped over the %s.', ['brown', 'fox', 'log']);

// The quick brown fox jumped over the log.

If you are only using one replacement, you can pass a string as the 2nd param instead of an array.

Messages::error('The quick brown fox jumped over the %s.', 'lazy dog');

// The quick brown fox jumped over the lazy dog.

Furthermore, you can add messages as an array:

Messages::warning(['This is a warning.', 'This is also a warning.']);

// This is a warning.
// This is also a warning.

Once you've added the messages to the stack, you have a couple options.

Fetch all the messages back as an array.

$items = Messages::all();
print_r($items);

/*
Array
(
	[error] => Array
		(
			[0] => Oops, something bad happened.
		)

	[info] => Array
		(
			[0] => Nothing big, this is just an informational message.
		)

	[success] => Array
		(
			[0] => Hooray! This is a success message.
			[1] => Here is another success message.
		)

	[warning] => Array
		(
			[0] => A little more serious than info, but not quite an error.
		)

)
*/

Display the messages using a decorator

$display = Messages::display();
print $display;

The above renders something like this:

<ul class="error">
	<li>Oops, something bad happened.</li>
</ul>

<ul class="warning">
	<li>A little more serious than info, but not quite an error.</li>
</ul>

<ul class="info">
	<li>Nothing big, this is just an informational message.</li>
</ul>

<ul class="success">
	<li>Hooray! This is a success message.</li>
	<li>Here is another success message.</li>
</ul>

Decorators

By default, a simple decorator will be used that wraps the messages in a series of unordered lists as shown above. The <ul> for each type of message (error, info, success) will be classed with the name of the message type.

If you are using Bootstrap for your design, you can specify that messages should be decorated using the Bootstrap Alert HTML Markup instead.

If you want to create your own decorator, just create a class that implements werx\Messages\Decorators\DecoratorInterface and pass an instance to Messages::setDecorator().

Messages::setDecorator(new Decorators\Bootstrap);
$display = Messages::display();
print $display;

Renders:

<div class="alert alert-danger">
	<button type="button" class="close" data-dismiss="alert">&times;</button>
	<ul>
		<li>Oops, something bad happened.</li>
	</ul>
</div>

<div class="alert alert-warning">
	<button type="button" class="close" data-dismiss="alert">&times;</button>
	<ul>
		<li>A little more serious than info, but not quite an error.</li>
	</ul>
</div>

<div class="alert alert-info">
	<button type="button" class="close" data-dismiss="alert">&times;</button>
	<ul>
		<li>Nothing big, this is just an informational message.</li>
	</ul>
</div>

<div class="alert alert-success">
	<button type="button" class="close" data-dismiss="alert">&times;</button>
	<ul>
		<li>Hooray! This is a success message.</li>
		<li>Here is another success message.</li>
	</ul>
</div>

Sessions

By storing messages in session, they can persist across multiple page loads until you either display or delete them.

By default, this library will create a new instance of the Symfony Native Session Storage object for storage of messages. If you already have an instance of a Symfony Session Interface, you can pass that to Messages::getInstance().

// Create a new session object.
$session = new \Symfony\Component\HttpFoundation\Session\Session(
				new \Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage(['cookie_lifetime' => 604800])
);

Messages::getInstance($session);

Installation

This package is installable and autoloadable via Composer as werx/messages. If you aren't familiar with the Composer Dependency Manager for PHP, you should read this first.

$ composer require werx/messages --prefer-dist

Contributing

Unit Testing

$ vendor/bin/phpunit

Coding Standards

This library uses PHP_CodeSniffer to ensure coding standards are followed.

I have adopted the PHP FIG PSR-2 Coding Standard EXCEPT for the tabs vs spaces for indentation rule. PSR-2 says 4 spaces. I use tabs. No discussion.

To support indenting with tabs, I've defined a custom PSR-2 ruleset that extends the standard PSR-2 ruleset used by PHP_CodeSniffer. You can find this ruleset in the root of this project at PSR2Tabs.xml

Executing the codesniffer command from the root of this project to run the sniffer using these custom rules.

$ ./codesniffer

werx / messages

Maintainers

Details