Documentation

    Background

    When a user makes a request for a certain page, a "router" gets that request and determines the module, controller and action. The "dispatcher" receives the module, controller, and action and does some final checks before running the module's controller action.

    Currently, in the Magento standard router, Magento rolls the router and the dispatcher functionality into one method match(). This makes it rather difficult to define custom logic to determine the module, controller and action.

    Features

    This extension introduces a new Fontis dispatcher, giving you control over the routing logic while keeping compatibility with existing routers. You can define your own routing logic for a given request and use the Fontis standard dispatcher to dispatch that action without having to deal with Magento's routing logic.

    Another feature to this extension is that any modules that use the Fontis Router extension to invoke a controller action can have their controllers overridden by putting them in local. Normally, Magento does not support local overrides of controllers and would just ignore them. Any modules using the Fontis Router extension to dispatch their controller actions will support local overrides out of the box without any extra configuration.

    Installation

    We recommend that you install this extension onto a staging or development copy of your Magento website first. You should also take a backup before starting the installation. Fontis community extensions are provided without any support or warranty so we cannot provide any help if anything goes wrong.

    The recommended way to install a Fontis extension is using Composer. If you don't already have Composer installed, you can install it using the instructions mentioned on the Composer documentation.

    Note that none of our extension packages can be installed with the Magento Connect Manager.

    Installing

    To add the extension to your website, run the following command from the Magento root (or wherever composer.json is located):

    composer require fontis/router
    

    Updating

    To update the extension to a newer version, just run the following command:

    composer update fontis/router
    

    Setting up dependencies

    Composer Autoloader

    You will need to update the configuration for the Fontis Composer Autoloader extension, to tell it where the vendor directory is located. This will allow it to autoload all of the required files.

    Using this extension

    In a nutshell, when integrating your module with the Fontis Router, you need to tell your module to use the Fontis Router, define a class that contains your routing logic and add that class to the list of routers managed by Magento.

    1. In your module, define a class that extends Mage_Core_Controller_Varien_Router_Abstract.
      • This will be your class that contains your routing logic.
    2. In that class, implement the match() method that defines your routing logic.
      • To call a specific controller action in your module, you should call setModuleName(), setControllerName() and setActionName() on the request object.
      • Once you have set those values, you MUST return true.
      • This method MUST return false if there's no module name, controller and action to be set.
      • This method MUST NOT call the dispatch method. The Fontis Router will take care of that.
    3. Add an observer to the controller_front_init_routers event.
      • This will allow you to add your newly created class to the list of routers that Magento manages.
    4. When controller_front_init_routers fires, adds the new class as a router.
      • This should be done in the <global> scope.
      • You will need to define your own method that is called when controller_front_init_routers fires to add the class as a router.
    5. In config.xml, under frontend/routers, add a new node that uses the fontis router.
      • This tells Magento that your module uses the Fontis router instead of the Standard router.

    Example

    Here's a bare bones example to get you started.

    1. Let's define a class that extends Mage_Core_Controller_Varien_Router_Abstract:

      class Foo_Bar_Controller_Router extends Mage_Core_Controller_Varien_Router_Abstract
      {
      }
    2. Let's implement the abstract method match():

      class Foo_Bar_Controller_Router extends Mage_Core_Controller_Varien_Router_Abstract
      {
          public function match(Zend_Controller_Request_Http $request)
          {
              $request->setModuleName("bar")
                      ->setControllerName("fizz")
                      ->setActionName("buzz");
              return true;
          }
      }
    3. Lets add an observer to the controller_front_init_routers event:

      <global>
          <events>
              <controller_front_init_routers>
                  <observers>
                      <bar>
                          <type>singleton</type>
                          <class>Foo_Bar_Controller_Router</class>
                          <method>initControllerRouters</method>
                      </bar>
                  </observers>
              </controller_front_init_routers>
          </events>
      </global>
    4. Define that method:

      class Foo_Bar_Controller_Router extends Mage_Core_Controller_Varien_Router_Abstract
      {
          public function initControllerRouters(Varien_Event_Observer $observer)
          {
              /** @var $front Mage_Core_Controller_Varien_Front */
              $front = $observer->getEvent()->getFront();
              $front->addRouter("bar", $this);
          }
      
          public function match(Zend_Controller_Request_Http $request)
          {
              ...
          }
      }
    5. In config.xml, under frontend/routers, add a new node that uses the fontis router:

      <frontend>
          <routers>
              <bar>
                  <use>fontis</use>
                  <args>
                      <module>Foo_Bar</module>
                  </args>
              </bar>
          </routers>
      </frontend>
    6. Refresh your caches, hit some random page that normally 404s.

    Obviously, the router logic should be tailored for your module. For a complete example, the Fontis Blog extension makes heavy use of this extension.

    Notes

    1. When making calls to Mage::getUrl(), you cannot use wildcards to automatically fill in parts of the URL on pages that are routed by this extension. The method of using asterisks was designed with Magento's traditional module/controller/action URL structure, and does not make sense in the context of this extension.