php-med-trans-lightLast week I wrote an article about extending my framework (Pho framework courtsey of Kien La) to DRY your code and to be more similar to Rails.

Today, I would like to present to you another class that will help extend your framework in similar fashion.

The Flash

If you aren't familiar with the way RoR uses "flash" messaging, you can take a look at the RoR API, or you can read this explanation:

The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed to the very next action and then cleared out.

The flash allows you to place messages in a user's session that can be viewed when navigating (or redirecting) to different pages or even the current page. If you read further into the API, you will see that the RoR flash offers you the following behavior:

  • Set a regular message (viewable upon next http request)
  • Create a "now" message (viewable now and not upon next http request)
  • "Keep" a message or all messages (is a message is viewable now, it will now also be viewable upon the next http request)
  • Discard/unset a message or all messages

If you're a good little coder, you would first attempt to steal this code from somewhere else. I have found a few sites that offer 'some' of the functionality of the RoR flash; however, I would like to have the flash in its full capacity. Therefore, I have created my own class.

The behavior of the flash is rather simple and so is my class. If you think about the lifetime of the messages, it should hit you that we have essentially two types of flash messages: now and later (next http request). Even though we have two types of messages, we actually only have one corresponding message. This means that a certain flash message "error" could have a now and a later message. The reason behind this is beceause we want to use discard() and keep() which we should be able to pass a 'key' to when invoked so that discard would remove all traces of our "error" message (or all messages if no key is passed). My class requires php >= version 5. Keep in mind that you will only want one instance of this class, so you could make it a singleton if you'd like. The constructor does all of the work by removing old messages and such, so you only have to worry about setting messages. Okay, let's see some code.

<!--p
# Instantiate flash which will remove old messages;
$flash = new UserSessionFlash;
$flash->error = 'This is an error message for the next page request.';
$flash-&gt;now('notice', 'Message will be available for the current page request.');
 
# Allows you to use the 'notice' for the next page request.
# If you do not pass a key, then it will keep ALL messages.
$flash-&gt;keep('notice'); 
 
# The $flash-&gt;error above has now been erased.
# Just like keep, if you do not pass a key, then ALL messages will be erased.
$flash-&gt;discard('error');
# Delete all messages.
$flash-&gt;discard();
?&gt;

As you can see this is all fairly basic. Simply add the flash instance to your action controller, and you access it via your page controller. What I have done is included a function in my action controller called flash() that returns my instance of the flash class. So my page controller would call

$this-&gt;flash()-&gt;error = 'This is an error msg.';
$this-&gt;flash()-&gt;now('notice', 'Show me the money.');

If you'd like, you can check out some other implementations below. Again, none of the other classes I've found offer the full rails flash behavior.

http://poorbuthappy.com/ease/archives/2007/04/22/3589/rails-flash-in-php
http://www.phpclasses.org/browse/package/3668.html
http://shabadeehoob.com/2007/03/17/rails-like-flash-messages-in-cakephp/
http://api.phpontrax.com/__filesource/fsource_PHPonTrax__vendortraxsession.php.html