Extending an existing controller

To extend an existing controller for Web Store 3, in order to replace existing functionality with your own, use the following directions.

First, create your custom controller file in /custom/controllers using the naming convention XXXXXXController.php for both the filename and the classname inside. If you are extending a controller, you may wish to use the convention My plus the name you are extending, such as MySearchController.php which will be used in this example.

Please be advised that the underlying controller you are extending can be updated at any time, and may have unexpected results on your site. If you have extended controllers, you may wish to disable Auto Updating under Admin Panel->System->Configuration and then examine code changes on Github as releases come out (each tag is a squished commit of all the changes) to evaluate if you need to make code changes in your custom work. This may or may not be an issue depending on exactly what you are programming.

Here is the file for MySearchController.php

<?php

Yii::import("application.controllers.SearchController");

class MySearchController extends SearchController
{
    public function actionIndex()
    {
        echo "this is the default index function";
    }

    public function actionTest()
    {

        echo "This is the test function";
    }

}

This file is saved as /custom/controllers/MySearchController.php

The import is necessary to reference the original SearchController.php from the core files.

Next, we need to tell Yii that this controller should be used instead of the default, and we do this by modifying our /config/main.php file and adjusting (or enabling) the ControllerMap.

In /config/main.php locate lines 79-83 and uncomment the lines, and update them to read

'controllerMap'=>array(
        'search'=>array(
            'class'=>'custom.controllers.MySearchController',
        ),
    ),

This lets the Yii framework substitute the search controller with your custom work, so the url www.example.com/search would use yours instead of the default.

To test our function, we can use URLs such as

http://www.example.com/search (this runs the actionIndex() function)

http://www.example.com/search/test (this runs the actionTest() function)

Note in this case that the actionIndex() from your custom function runs instead of the actionIndex() from the original controller. In most cases, you would copy the existing function to make your own changes instead of starting from scratch.

The second example is a new actionTest() function which does not exist in the original. If you are extending a controller to add your own action that adds, not replaces, something in the controller, then you're generally safe from future changes and can leave Auto Update turned on.