Error Handling

Overview

Let’s face it: sometimes things go wrong. It is important to intercept errors and respond to them appropriately. A Skinny application provides helper methods to respond to errors and exceptions.

Important Notes

A Skinny application respects your existing error_reporting setting;
A Skinny application only handles errors and exceptions generated inside the Skinny application;
A Skinny application converts errors into ErrorException objects and throws them;
A Skinny application uses its built-in error handler if its debug setting is true; otherwise, it uses the custom error handler.

500 System Error

You may use the Skinny application’s error() method to specify a custom error handler to be invoked when an error or exception occurs. Custom error handlers are only invoked if application debugging is disabled.

A custom error handler should render a user-friendly message that mitigates user confusion. Similar to the Skinny application’s notFound() method, the error() method acts as both a getter and a setter.

Set custom error handler

You may set a custom error handler by passing a callable into the Skinny application’s error() method as its first and only argument.

<?php
$app = \Skinny\Skinny::newInstance();
$app->error(function (\Exception $e) use ($app) {
    $app->render('error.php');
});

In this example, the custom error handler accepts the caught Exception as its argument. This allows you to respond appropriately to different exceptions.

Invoke custom error handler

Usually, the Skinny application will automatically invoke the error handler when an exception or error occurs. However, you may also manually invoke the error handler with the Skinny application’s error() method (without an argument).

404 Not Found

It is an inevitability that someone will request a page that does not exist. The Skinny application lets you easily define a custom Not Found handler with the Skinny application’s notFound() method. The Not Found handler will be invoked when a matching route is not found for the current HTTP request. This method acts as both a getter and a setter.

Set not found handler

If you invoke the Skinny application’s notFound() method and specify a callable object as its first and only argument, this method will register the callable object as the Not Found handler. However, the registered handler will not be invoked.

<?php
$app = \Skinny\Skinny::newInstance();
$app->notFound(function () use ($app) {
    $app->render('404.html');
});

Invoke not found handler

If you invoke the Skinny application’s notFound() method without any arguments, this method will invoke the previously registered Not Found handler.

<?php
$app = \Skinny\Skinny::newInstance();
$app->get('/hello/:name', function ($name) use ($app) {
    if ( $name === 'Waldo' ) {
        $app->notFound();
    } else {
        echo "Hello, $name";
    }
});

Debug Mode

You can enable debugging during application instantiation with this setting:

<?php
$app = \Skinny\Skinny::newInstance(array(
    'debug' => true
));

You may also enable debugging during runtime with the Skinny application’s config() instance method:

<?php
$app = \Skinny\Skinny::newInstance();

//Enable debugging (on by default)
$app->config('debug', true);

//Disable debugging
$app->config('debug', false);

If debugging is enabled and an exception or error occurs, a diagnostic screen will appear with the error description, the affected file, the file line number, and a stack trace. If debugging is disabled, the custom Error handler will be invoked instead.

Output

The Skinny application’s environment will always contain a key, skinny.errors, with a value that is a writable resource to which log and error messages may be written. The Skinny application’s log object will write log messages to skinny.errors whenever an Exception is caught or the log object is manually invoked.

If you want to redirect error output to a different location, you can define your own writable resource by modifying the Skinny application’s environment settings. Middleware is the recommended way to update the environment:

<?php
class CustomErrorMiddleware extends \Skinny\Middleware
{
    public function call()
    {
        // Set new error output
        $env = $this->app->environment;
        $env['skinny.errors'] = fopen('/path/to/output', 'w');

        // Call next middleware
        $this->next->call();
    }
}

Remember, skinny.errors does not have to point to a file; it can point to any valid writable resource.