Dispatch Error Handling

There are many situations that result in problems during dispatching of controllers. Ideally, it would be easy to determine when spelling errors or mismatches occur in class names, directory names, and filenames. By examining the user's IP address reported by the web server, additional diagnostic information can be displayed for "local" network requests without interfering with public usage of a website. This section introduces a robust system for managing and reporting common errors, including "404 Page not found" errors.

Install this section by copying "zfdemo/section5_asession/index.php" to the "zfdemo" directory in your web server's document root directory.

1 Dispatch Error Handling

1.1 Analyzing Dispatch Errors
1.2 Adding a Custom 404 Error Page

Analyzing Dispatch Errors

In "section5_asession/config/config.ini", we change toggle analyzeDispatchErrors by enabling this feature (added below).

analyzeDispatchErrors = true

There are several possible reasons why an exception might arise after calling "dispatch()". In order to render helpful information after an exception occurred, the exception must be analyzed to discover possible reasons why an exception occurred during routing, dispatching, rendering a view, or otherwise trying to process the module's action controller.

public static function analyzeError($dispatcher, $exception, $request, $response)
    {
        if (self::isLocalRequest()) {
            self::$view->request   = Zend_Debug::dump($request, null, false);
            self::$view->response  = Zend_Debug::dump($response, null, false);
            self::$view->exception = self::filterException($exception);
        }

        ZFDemo_Log::log('ERROR when processing'
            . '   Module: ' . $request->getModuleName()
            . ' / Controller: ' . $request->getControllerName()
            . ' / Action: ' . $request->getActionName(), true);
        if ($exception instanceof Zend_Controller_Dispatcher_Exception) {

            if (!$dispatcher->isDispatchable($request)) {

                // Exception message: Invalid controller specified <controller name>
                $className = $dispatcher->getControllerClass($request);
                if (!$className) {
                    $msg = "ERROR: Unable to find controller class '$className'.";

                } else {
                    $fileSpec    = $dispatcher->classToFilename($className);
                    $dispatchDir = $dispatcher->getDispatchDirectory();
                    $realFilename= $dispatchDir . DIRECTORY_SEPARATOR . $fileSpec;
                    $msg = "ERROR: Unable to find controller file '$realFilename'.";
                }

            } else {
                // Exception message: Controller '<controller class name>' is not an instance of Zend_Controller_Action
                $msg = $exception->getMessage();
            }

        } else if ($exception instanceof Zend_Controller_Exception
                || $exception instanceof ZFDemo_Exception_404) {
            /*
             * Exception messages:
             *     No action specified and no default action has been defined in __call() for
             *     <controller class name>() does not exist and was not trapped in __call()
             */
             $msg = $exception->getMessage();

        } else if ($exception instanceof Zend_View_Exception) {
            /*
             * Exception messages:
             *      script 'indexindex.phtml' not found in path
             */
            $msg = $exception->getMessage() . "View script paths =\n    "
                 . implode("\n    ", self::$view->getScriptPaths());

        } else { // unknown exception, so die ungracefully to remind me to add code for this exception ;)
            $msg = 'Unhandled Exception on line #'.__LINE__.'!';
            if (self::isLocalRequest()) {
                ZFDemo_Log::show($exception);
                exit;
            }
            echo $msg; // reader excercise: do something prettier for non-local requests than encounter an unknown err
            exit;
        }

        ZFDemo_Log::log($msg, true); // prepend the exception analysis message to the log

        if (self::isLocalRequest()) {
            try {
                self::$view->msg = $msg;
                // insert $msg before body
                $response->insert('exception', self::$view->render('exception.php'), 'body', false);
                // now append dump *after* body segment
                $response->insert('dump', self::$view->render('dump.php'), 'body', true);
            } catch (Exception $exception) {
                echo 'ERROR: corrupt installation, can not find "dump.php".';
                exit; // reader excercise: prettier error handling
            }
        }
    }

    /**
     * Filter an exception object by truncating the lengthy trace output.
     */
    public static function filterException(Exception $exception)
    {
        return preg_replace('/(\[&quot;trace:private&quot;.{1,1024}).*/s', '\\1 => rest not shown</pre>',
            Zend_Debug::dump($exception, null, false));
    }

Adding a Custom 404 Error Page

Sending true HTTP 404 error responses to requests for invalid URLs fulfills a critical need of web crawlers to identify invalid URLs and avoid crawling countless invalid pages when a dynamically generated page contains numerous invalid URLs. Humans quickly stop surfing such accidentally created links, but search engines are infamous for getting "lost" amid a maze of pages linking to more invalid pages.

For controller actions, adding a new exception provides an easy way for the action to indicate the request is a "page not found". Remember, some systems cache URI's resulting in 404 HTTP responses, so only issue a 404 when certain that is the desired effect.

class ZFDemo_Exception extends Exception
{}

class ZFDemo_Exception_404 extends ZFDemo_Exception
{}

After adding the new analyzeError() and the new "404" exception type, it is time to do something about the error by showing the viewer a custom 404 "page not found" message. If the 404 error page should be unique and specific to the action controller requested, and that action controller exists, then use the magic method "__call()" to catch invalid actions and re-route or "_forward()" to a 404 error handler within the action controller:

public function __call($name, $parameters)
    {
        self::setHeaderStatus('404 Not Found'); // set HTTP response status
        $this->view->request = Zend_Debug::dump($this->getInvokeArg('origRequest'), null, false);
        $this->renderToSegment('body', 'error404'); // render view script 'error404' to response segment 'body'
    }

If the controller does not exist, then the ZFDemo bootstrap will dispatch a 404 error controller, specified in "config/config.ini":

error404.moduleName     = default
error404.controllerName = error
error404.actionName     = error404
error404.viewName       = error404

In order to make a default application 404 error handler, the function below is added to the "ErrorController" class in the default controllers directory. The default action is "indexAction", unless explicitly set to something else in the configuration file above. Below, the magic method "__call()" causes all request "actions" to execute the same method, showing a "404" error page. Simply add a new action to the "ErrorController" below, in order to add support for different error pages.

class ErrorController extends ZFDemo_Controller_Action
{
    public function __call($name, $parameters)
    {
        $this->view->request = Zend_Debug::dump($this->getInvokeArg('origRequest'), null, false);
        $this->renderToSegment('body', 'error404'); // render view script 'error404' to response segment 'body'
    }
}

Next, we need to configure a way to dispatch to this "default/controllers/ErrorController.php" action controller by adding the following dispatch code inside the "catch(Exception)" clause in STAGE 2 of "bootstrap.php":

$dispatcher = $frontController->getDispatcher();
            self::analyzeError($dispatcher, $exception, $request, $response);

            // now dispatch the 404 error controller
            // make original request available to the 404 action controller via both ->_getParam() and ->getInvokeArg()
            $dispatcher->setParam('origRequest', $request);
            $request = clone $request;
            $request->setPathInfo(($config->error404->moduleName === 'default' ?
                             '' : '/' . $config->error404->moduleName)
                                . '/' . $config->error404->controllerName
                                . '/' . $config->error404->actionName);

            try {
                $frontController->dispatch($request, $response); // dispatch the 404 action

            } catch (Exception $exception) {
                // reader excercise: make output "pretty" when dispatching the 404 action also fails
                if (self::isLocalRequest() && $config->view->showLog) {
                    ZFDemo_Log::log("ERROR: Dispatching failed to complete for: '" .  $config->error404->moduleName
                        . '_' . $config->error404->controllerName .  $config->error404->actionName . "'.\n", true);
                    #echo ZFDemo_Log::get();
                    echo ZFDemo_Log::get($exception);
                } else {
                    self::echo404(); // send a raw 404 page
                }
                exit;
            }

Before dispatching this error controller, a new requet object must be created using the configured module, controller, and action names for the error controller, in order for the normal route process to reach the desired error controller. If files are missing, or a view script contains a syntax error, etc., then the second catch() in STAGE2 (the "catch()" added above) will give our bootstrap the ability to still send a very basic 404 error page using:

/**
     * Send a raw 404 page, without using anything else that might break (e.g. any other files).
     */
    private static function echo404()
    {
        echo "An error occured while processing your request.\n\n";
        echo "An additional error occurred while trying to use this application's error action controller.\n";
        setHeaderStatus('404 Not Found');
    }

Now try a bogus URL, like:

http://www.yourwebsite.com/zfdemo/index.php/forum/indTYPOex/index/topic/1

Next Section: 6. Anonymous Sessions

Page Operations

Browse Space

5. Dispatch Error Handling and 404 Error Pages

Labels

Dispatch Error Handling

Analyzing Dispatch Errors

Adding a Custom 404 Error Page