Handling Errors and Displaying Status Messages

You will often need to pass error and success messages between different actions, or from an action to a view. There is a built-in method, called flash, which helps to solve this task. For example, to pass a error message to a view, you should assign the error message to the $session->flash['error'] array element:

Phpr::$session->flash['error'] = 'Order #120 not found';

To pass a success message, you should use the success index:

Phpr::$session->flash['success'] = '1 order has been successfully deleted.';

To output the messages on the page, in a view file you should call the flash() function:

<?= flash() ?>

This function reads a content of the Phpr::$session->flash[] array and displays all messages in a standard LemonStand style:

It is a good idea to call the flash() function in all views.

There is one important feature of the flash approach - it does not clears messages from the session until you display them. It means that you can use this method for passing messages between different actions or event handlers.

For proper styling flash messages require the forms.css file to be included to the view document. The simplest way to accomlish it is to extend the controller class with Db_FormBehavior class. Example:

class My_Controller extends Backend_Controller
{
  public $implement = 'Db_FormBehavior';
  ...
}

Handling exceptions

Exceptions can occur during code execution inside a controller action. If you do not add any error error handling code to actions and views, LemonStand will display a system error page, with all details about the exception, which include an error message, a PHP script name where the exception occurred, a line in the PHP script, a stack trace information and some other things. Usually you do not need to show all this information to users. Instead of this, you should wrap actions code to a try..catch block and call the handlePageError() controller method in the catch block:

public function some_action()
{
  try
  {
    ... some code which could throw an exception ...
  }
  catch (Exception $ex)
  {
    $this->handlePageError($ex);
  }
}

The handlePageError() method does two things - it saves the error message to the session flash array, as it was described above, and generates the $fatalError PHP variable which is available in a view document in case of error. In other words the handlePageError() method executes the following code:

Phpr::$session->flash['error'] = $exceptionObj->getMessage();
$this->viewData['fatalError'] = true;

In some cases you may want to replace the handlePageError() method call with a custom code. To process the exception in a view document you should use the following page structure:

<?= flash() ?>

<? if (!isset($fatalError)): ?>

  /*
   * Your normal page content is here
   */

<? else: ?>
  <p><a href="<?= url('/shop/customers') ?>">Return to the customer list</a></p>
<? endif ?>

You should use this page structure for all actions which can throw an exception. The code outputs an error message using the flash() function. After that it checks whether the $fatalError variable exists. If it does not exist the code displays a normal page content. If the variable exists, in case of exception, you should display some fallback message, allowing a user to take some action. This is a screenshot of the Edit Customer page, which you can see if you try to edit a non-existing customer:

The process of handling exceptions in AJAX event handlers will be described in a separate article.

Next: Extending the Administration Area menu
Previous: Standard Page Elements
Return to Adding a Back-End User Interface