X-Cart:New module initialization routine

From X-Cart 4 Classic
Revision as of 17:01, 22 June 2011 by Seyfin (talk | contribs)
Jump to: navigation, search

Overview

A new module initialization routine was introduced in X-Cart 4.4.3, which improves the code and boosts the performance. This article covers the most important facts about the new module initialization routine.

Why change the module initialization routine?

The module initialization routine was changed to optimize the code and improve the performance of X-Cart. On certain configurations, the improvement can give up 6-times increase in the operation performance.

What is the old module initialization routine?

In the earlier versions (prior to 4.4.3) all the modules were initialized at the same time in <xcart_dir>/init.php (config.php, func.php and init.php for each module were included in <xcart_dir>/init.php):

if ($active_modules) {

foreach ($active_modules as $active_module => $tmp) {

$_module_dir  = $xcart_dir . XC_DS . 'modules' . XC_DS . $active_module;
$_config_file = $_module_dir . XC_DS . 'config.php';
$_func_file   = $_module_dir . XC_DS . 'func.php';

if (
file_exists($_config_file)
&& is_readable($_config_file)
) {
include $_config_file;
}

if (
file_exists($_func_file)
&& is_readable($_func_file)
) {
include $_func_file;
}

}

}

# ... skipped code ... #

**
* Init modules
*/
if (is_array($active_modules)) {
$_active_modules = $active_modules;

foreach ($_active_modules as $__k => $__v) {

if (file_exists($xcart_dir . '/modules/' . $__k . '/init.php')) {

include $xcart_dir . '/modules/' . $__k . '/init.php';

}
}
unset($_active_modules);
}

What is the new module initialization routine?

With the new module initialization routine, each module's config.php is included in <xcart_dir>/init.php, just the way it has always been. And each module's files func.php and init.php get included in the respective module's file config.php, at the very end of the file, just before the "?>" string. See, for example, the file modules/Google_Checkout/config.php:

$_module_dir  = $xcart_dir . XC_DS . 'modules' . XC_DS . 'Google_Checkout';
/*
Load module functions
*/
if (!empty($include_func))
require_once $_module_dir . XC_DS . 'func.php';

/*
Module initialization
*/
if (!empty($include_init))
include $_module_dir . XC_DS . 'init.php';

?>

Besides that, the new routine sets the initialization order for the built-in modules in the file include/data_cache.php:

/**
* Sort active_modules according order to initialization
*/
function func_sort_active_modules($a, $b)
{
static $sort_order = array(
'Amazon_Checkout' => 1, #can be unsetted in config/init.php
'Flyout_Menus' => 1, #can be unsetted in config/init.php
'Google_Checkout' => 1, #can be unsetted in config/init.php
'Magnifier' => 1, #can be unsetted in config/init.php
'Wishlist' => 11, #Gift_Registry depends on Wishlist
'Gift_Registry' => 12, #can be unsetted in config/init.php
'News_Management' => 31,
'Survey' => 32,
'Image_Verification' => 33,# Image_Verification depends on Survey/News_Management
'Manufacturers' => 23,
'XAffiliate' => 24, #XAffiliate depends on Manufacturers
);
$key_a = isset($sort_order[$a]) ? -$sort_order[$a] : -1000;
$key_b = isset($sort_order[$b]) ? -$sort_order[$b] : -1001;
return $key_b - $key_a;
}

The modules are initialized according to their order number, set for each module (see the above example).

When installing a new module, you need to define its initialization order, keeping in mind its dependence on other modules. Here are the guidelines for defining an order number:

  • If the module depends on other modules, its order number must be greater than the order number of the module it depends on.
  • If other modules depend on this module, its order number must be lesser than the order number of the module that depends on it.
  • If no other modules depend on this module, the module may have the greatest order number.
  • If the order number of the module is not set explicitly, it is assumed to be 1000.

Example. A new module initialization order:

/**
* Sort active_modules according order to initialization
*/
function func_sort_active_modules($a, $b)
{
static $sort_order = array(
'Amazon_Checkout' => 1, #can be unsetted in config/init.php
'Flyout_Menus' => 1, #can be unsetted in config/init.php
'Google_Checkout' => 1, #can be unsetted in config/init.php
'Magnifier' => 1, #can be unsetted in config/init.php
'Wishlist' => 11, #Gift_Registry depends on Wishlist
'Gift_Registry' => 12, #can be unsetted in config/init.php
'News_Management' => 31,
'Survey' => 32,
'Image_Verification' => 33,# Image_Verification depends on Survey/News_Management
'Manufacturers' => 23,
'3dPartyModule1' => 24,
'XAffiliate' => 25, #XAffiliate depends on Manufacturers
'3dPartyModule2' => 100,
);
$key_a = isset($sort_order[$a]) ? -$sort_order[$a] : -1000;
$key_b = isset($sort_order[$b]) ? -$sort_order[$b] : -1001;
return $key_b - $key_a;
}

This code means that:

  • 3dPartyModule1 depends on Manufacturers, and XAffiliate depends on 3dPartyModule1, thus 3dPartyModule1 will be initialized before Manufacturers and after XAffiliate.
  • 3dPartyModule2 will be initialized last for this array of modules.

Peculiarities of upgrading from versions 4.4.0-4.4.2 to version 4.4.3 and newer with X-Cart add-on modules or 3rd-party add-on modules installed

When upgrading from versions 4.4.0-4.4.2 to version 4.4.3 and newer, the program adds a new module initialization routine and a new option, "Use new module initialization routine" (disabled by default), which enables/disables this feature.

If prior to launching the upgrade your X-Cart had any X-Cart add-on modules or 3rd-party add-on modules installed, before enabling this option in the upgraded X-Cart, you need:

Option A. Install the new versions of the add-on modules, which match the version of the upgraded X-Cart and support the new module initialization routine.

Notes:
  • To obtain the new version of an add-on module that support the new module initialization routine, please contact the add-on module vendor.
  • After installing the add-on module, it may be necessary to re-implement the customizations made earlier over the add-on module's.

Option B. Bring the previously installed add-on modules to compliance with the new module initialization routine. To do so:

1. Edit config.php for the respective add-on module to include the required func.php and init.php according to the new module initialization routine.

2. Set the initialization order for the add-on module in include/data_cache.php (optional - required only if the add-on module uses other modules' functions/variables).

See examples of including files func.php and init.php for modules and setting module initialization order in section "What is the new module initialization routine?".

Notes:
  • Option B is not applicable to add-on modules with closed (encrypted) source code of config.php.
  • Customizations made over the add-on module's files remain intact and, therefore, do not require re-implementation, which is the case when installing a new version of the add-on module (Option A).
IMPORTANT! If an upgraded X-Cart has ANY add-on modules that do NOT support the new module initialization routine, it is recommended to keep the option "Use new module initialization routine" DISABLED. When disabled, the program will use the old module initialization routine.

The add-on modules which support the new module initialization routine, will still operate correctly with the option "Use new module initialization routine" DISABLED.

Attention users who use regular 4.4.3 install, or upgrade their install using upgrade packs 4.4.0/2->4.4.3 released until 10 June, 2011

IMPORTANT!

To eliminate the compatibility issue between the add-on modules and the new module initialization routine implemented in 4.4.3 version, make sure to apply the patches, which:

  • Restore the old module initialization routine, as an alternative to the new one.
  • Add a new option "Use new module initialization routine" to the admin area, which enables/disables the new module initialization routine; the option is disabled by default.

If you upgrade your install using new upgrade packs 4.4.0/2->4.4.3 released 10 June, 2011, you do not need to apply any patches.

These improvements will be included into version 4.4.4 as well.

See also:

IMPORTANT! If your regular or upgraded X-Cart 4.4.3 has ANY add-on modules that do NOT support the new module initialization routine, it is recommended to keep the option "Use new module initialization routine" DISABLED. When disabled, the program will use the old module initialization routine.

The add-on modules which support the new module initialization routine, will still operate correctly with the option "Use new module initialization routine" DISABLED.

Attention to third-party vendors developing add-on modules for X-Cart 4.4.3 (and later versions)

It is recommended to bring all add-on modules to compliance with the new module initialization routine. To do so:

1. Modify config.php for the respective add-on module to include the required func.php and init.php.

2. Set the initialization order for the add-on module in include/data_cache.php (optional - required only if the add-on module uses other modules' functions/variables).

See examples of including files func.php and init.php for modules and setting module initialization order in section "What is the new module initialization routine?".

Patches for 4.4.3

The patches can be downloaded here:

See section "Attention users who use regular 4.4.3 install, or upgrade their install using upgrade packs 4.4.0/2->4.4.3 released until 10 June, 2011" for more information about the patches.