Magento Admin Routers 404 Error – The Ultimate Fix

back to tech articles
| 8th June 2013
Magento CE 1.7.0.2

Ultimate fix, you say? Well, after trying every Google result I could find and gaining an education on Alan Storm’s awesome blog, this is what worked for me in the end.

The Problem

I’m building a custom module (extension, if you prefer). I want to have a new admin menu item, pointing to my new admin page. My controller is NOT called IndexController.php. Simple, yes? I’ve tried every config.xml setup possible and I still get a ‘Whoops’ 404 page in Magento.

The Solution

First, let me define my folder structure for clarity. Please note; in each example here, I’m only going to show you the relevant info so as not to confuse.

1
2
3
4
5
6
7
8
9
10
11
app
  code
    community
      Jason
        Extendo
          controllers
            Adminhtml
              ExtendoController.php
          etc
            adminhtml.xml
            config.xml

Now, our config.xml file. For the uninitiated, this is really where the meat and potatoes of Magento configuration goes down, hence the name.

File: app/code/community/Jason/Extendo/etc/config.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<?xml version="1.0"?>
<config>
    <modules>
        <Jason_Extendo>
            <version>0.1.0</version>
        </Jason_Extendo>
    </modules>
    <global>
        <helpers>
            <jason_extendo>
                <class>Jason_Extendo_Helper</class>
            </jason_extendo>
        </helpers>
    </global>
    <admin>
        <routers>
            <jason_extendo>
                <use>admin</use>
                <args>
                    <module>Jason_Extendo</module>
                    <frontName>jason_extendo</frontName>
                </args>
            </jason_extendo>
        </routers>
    </admin>
</config>

I prefer to use the above method for the routers definition (instead of this). According to their documentation, it is the ‘Magento’ way and also because the alternative has a track record of causing problems.

So, we have defined a simple admin router pointing to our controller by using the name jason_extendo. The link to this controller lives in the adminhtml.xml file.

File: app/code/community/Jason/Extendo/etc/adminhtml.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?xml version="1.0"?>
<config>
    <menu>
        <promo>
            <children>
                <jason_extendo translate="title" module="jason_extendo">
                    <title>My Awesome Sauce Extension</title>
                    <sort_order>10</sort_order>
                    <action>jason_extendo/adminhtml_extendo/index</action>
                </jason_extendo>
            </children>
        </promo>
    </menu>
</config>

This XML creates a sub-menu item in admin, under the ‘Promotions’ menu (notice the ‘promo‘ node). The sub-menu item points first to our module using the frontName we defined (jason_extendo), then our controller (adminhtml_extendo) and then the controller action we want (index).

The controller would normally live in the controllers folder, duh. However, I want to add more frontend and backend (admin) controllers later on, so mine lives in a sub-folder called Adminhtml.

Now, let’s take a look at this controller. I’ve stripped out everything except the basics of what we’re trying to achieve here – routing.

File: app/code/community/Jason/Extendo/controllers/Adminhtml/ExtendoController.php

1
2
3
4
5
6
7
8
9
10
11
12
<?php

class Jason_Extendo_Adminhtml_ExtendoController extends Mage_Adminhtml_Controller_Action
{
   
    public function indexAction()
    {
        echo 'You beauty, it works!';
        // $this->loadLayout()->renderLayout();
    }
   
}

The Controller part of the filename and class name are absolutely key here. This is where so many other potential solutions to this problem fall down. Without defining the Controller part, Magento will effectively ignore this file, resulting in your 404 error. Onward!

Well, that’s it, actually! When you put this all together, push the code to your Magento installation, clear cache, logout, login, sip your coffee, blink, pee and test.

Further Troubleshooting

Here are a few general pointers to get you on the right track.

  • Case is very important in Magento. For example, frontname and frontName are NOT the same thing.
  • You could try putting a default file called IndexController.php in the controllers folder to see if a basic call to your page works, then build out from there.
  • Strip out any complicated logic to see if you get to your controller(s), then put it all back piece by piece.
  • Don’t use a closing PHP tag. Magento is built on Zend Framework and one does not use a closing tag in Zend. You would fail the exam 😉
  • If you have a clump of your hair in each hand, try using a module creator to do all this for you.
  • Take a break. Seriously, it helps!

Conclusion

Well done for trying to develop a module, it’s very rewarding when it all works. Keep cracking and happy coding, programmer!

Please do share this article.