A Better Magento 404 Page

One of the most common Magento questions on Stack Overflow or the Magento Stack Exchange is a variation on “why does my MVC controller 404?” While powerful, Magento’s configuration based MVC system leaves lots of room for subtle configuration errors. Not only do you need to name your controller file correctly, you also need to have a multiple node XML configuration string in your module’s config.xml file. A multiple node configuration string that contains terms like router, frontName, and args — all of which mean something to programmers, but whose meanings are unclear in Magento.

As part of my unofficial December 2013 open-source extravaganza, I decided it was time to fix this problem with a better Magento 404 page, (download connect package).

Programmer’s 404 Pages

Most PHP frameworks have a programmatic 404 page. That is, when running in non-production mode, the framework will throw some sort of exception letting you know it couldn’t find a route to a controller action method for the specified URL. Take, for example, this Kohana 404 page.

While Magento has a default 404 page, Magento also has the burden of marketing itself directly to ecommerce business owners, and (the increasingly less-tech-savvy) agency owners. Because of these marketing requirements, the stock Magento 404 page is a standard end-user 404 page.

While most experienced Magento programmers will recognize this page as the no route 404 page, developers new to Magento don’t have that institutional knowledge. Additionally, there’s no hint on this page as to why the system produced a 404 error. That’s the problem my new Better 404 module solves.

Debugging a Route

The 404 page provided by the Better 404 module attempts to deduce why a particular URL has no MVC route. It does this in three steps

1. Does a module claim the front name?

2. If yes, is there a correctly named controller file for the module?

3. If yes, is there a correctly named action method for the controller object?

While this next section assumes a familiarly with Magento’s controller dispatch, anyone with a passing familiarity with MVC routing should be able to follow along.

Front Names and config.xml

First, let’s consider the following URL

http://magento.example.com/nosuchpage

With the Better 404 module installed, this URL results in the following page

The most import thing here is

No modules claim [no-such-page] as a <frontName/>.

When you see this error, it means there’s a problem in your config.xml file. Magento can’t find a module that “claims” the URL front name. The front name is the first portion of the URL string — in our example above that’s nosuchpage. The “front name” is a concept borrowed from the Zend Framework, where each PHP module “owns” a particular URL. This practice has fallen out of favor in more modern MVC systems, and even Magento has the ability to configure extra modules to check for controllers. Better 404 knows about these additional modules.

For example, if you attempt to access a nonexistent admin page.

http://magento.example.com/admin/nosuchpage

You’ll see something like this.

That is, the Better 404 module correctly reports the Mage_Adminhtml module has claimed the admin front name, but it also lets you know there’s a number of other modules Magento will look for controller matches in.

Which leads in nicely to our next section.

Incorrect Controller File

Consider the following URL

http://magento.example.com/catalog/nosuchpage

This URL results in a page that looks like this

Here the Better 404 page tells us which Magento module has claimed the catalog front name. (The catalog front name is part of the standard Magento distribution).

The Module/Front Name [catalog] is claimed by the Magento module Mage_Catalog.

However, it also lets us know it couldn’t find a controller file for the second part of the URL (nosuchpage)

The controller name no-such-page matches the following controller file, but this file does not exist.

/path/to/magento/app/code/core/Mage/Catalog/controllers/NosuchpageController.php

When you see this error, it means your controller file is misnamed, or there’s a different module claiming this URL front name.

Incorrect Action Method

Finally, let’s consider the URL

http://magento.example.com/catalog/category/nosuchpage

This URL results in the following 404 page

Here we’ve fixed the previous problem by using the category controller in the Mage_Catalog model. However, we still have a problem

The action method nosuchpageAction is not present in the controller file.

When you see this error, it means you have a correctly configured module, with a correctly named controller file, but you’ve failed to add a correctly named publicly accessible action method.

Wrap Up

Controller routing is the first step is learning how to program in Magento, and initial frustrations setting up a basic hello world controller can drive new developers away from the platform. The Better 404 module aims to be one small step towards fixing that. Questions, comments, and feature suggestions are always welcome.