Controllers¶

Controller Structure¶

Each controller can contain the following logical blocks:

• Processing of POST request.
• Processing of GET request.
• Defining local functions used only within a controller.

The part [mode_name] of the parameter dispatch is used to set the operating mode for processing GET request.

POST Request¶

Processing of a POST request should always be performed prior to processing a GET request and there must be a string at the end of the block that returns control from a controller to the function fn_dispatch():

return array(CONTROLLER_STATUS_OK, "$index_script?dispatch=controller_name$suffix");

The parameter CONTROLLER_STATUS_OK contains a constant with the success status of the controller performance, the second parameter is a string with URI for redirection after processing the POST request.

Example:

if ($_SERVER['REQUEST_METHOD'] == 'POST') {

    if ($mode == 'add') {
        // here comes the code which should be executed when submitting product addition form
    }

    return array(CONTROLLER_STATUS_OK, "$index_script?dispatch=products$suffix");
}

GET Request¶

Section of processing a GET request is always placed after the POST block.

Example 1:

if ($mode == 'manage') {
     // here comes the code which should be executed when running "http://cscart_dir/admin.php?dispatch=products.manage"
}

Here is given a part of code that checks the value of the parameter mode (dispatch=controller.mode) and executes the code within a conditional operator when the value equals manage. This code will be executed on GET request.

At the end of the GET mode operation, the controller usually performs one of the following closing actions:

• Transfer of control to the display subsystem or templater, which is the same.
• Redirection by GET method.
• Completion of controller execution and the program itself without any additional actions: exit;

In the first case, the control will be transferred to the function fn_dispatch() automatically, if it is not explicitly defined, that it is necessary to perform actions under points 2 and 3. To transfer data to the templater for further display, the following structure is used:

$view->assign('template_var_name', $php_var_name);

Here template_var_name defines a name of the variable available in the templater, and $php_var_name defines the content of this variable.

Example 2:

if ($mode == 'manage') {
    $product_name = 'Product 1';
    $product_description = 'Product description';
    $view->assign('tpl_product_name', $product_name);
    $view->assign('tpl_product_description', $product_description);

}

After this code is executed in the controller, the control is transferred to the templater, for which two variables $tpl_product_name and $tpl_product_description will be available.

Functions¶

Functions within a controller are defined in accordance with general rules of function formatting. If a function of the controller is required to be called in another controller, such a function should be located in the core of the program or an add-on.

Available Data¶

To work with program data in a controller, you should use the following standard arrays:

• $_REQUEST - contains all variables coming from GET and POST requests. All variables in this array are handled in a special way: HTML tags are removed; slashes that are automatically added by PHP (if a corresponding setting is enabled) are deleted.
• $_SESSION - a standard PHP array that stores session data.
• Registry - a special static class-repository for the data that should be accessed from any place of the program. For instance, configurational parameters of the program, read during startup, are entered into class Registry. Peculiarity of this class is that any data stored in it can be cached. This allows, for example, to avoid repeated requests to the database for seldom updated information by storing it in cache of class Registry.

Running a Controller in the Console¶

• Backend controller:

  php /path/to/cart/admin.php --dispatch=controller.mode
  

• Frontend controller:

  php /path/to/cart/index.php --dispatch=controller.mode
  

• Common controller: any of the commands above (common controllers work with admin.php and index.php).

  Note

  Replace /path/to/cart with the path to CS-Cart or Multi-Vendor installation on your server. The name of admin.php will most likely be different as well (we recommend renaming admin.php as a security measure).

The parameters of the controller are passed as follows:

php admin.php --dispatch=controller.mode --param1=value --param2=value --param3[]=value1 --param3[]=value2 --param4[param5]=value

These parameters are passed to the controller as ordinary request parameters and are available in the $_REQUEST array. If the mode of a controller processes POST requests, pass the -p argument to the script after specifying the parameters.

Running a controller’s mode in the console will perform the actions implemented in that mode. If nothing appears in the command line after you use the command, it may mean that:

• The controller doesn’t return anything with fn_set_progress, fn_echo, fn_set_notification.
• A wrong mode was specified in the command.
• Incorrect parameters (or no parameters at all) were specified for the mode.
• The controller can’t be run with that script. For example, a backend controller can’t be run with index.php.