This post covers a simple and, at the same time, a very important topic of module initialization in Magento. No extension can be developed without knowledge about it. As a rule, a developer takes a ready-to-use initialization template without even knowing how it works. That is why I want to provide a detailed picture of the correct way to initialize your module and construct complex systems of several dependent extensions.
So, here we go. Initialization of every module as well as “building” of the whole Magento configuration starts in the “magical” app/etc folder. Even earlier, to be more specific – from the Mage::run() method in the index.php file:
Let’s take a closer look at App.php (the Mage_Core_Model_App class) and the run(..) method:
/app/code/core/Mage/Core/Model/App.php
|
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 |
…. public function run($params) { $options = isset($params['options']) ? $params['options'] : array(); $this->baseInit($options); Mage::register('application_params', $params); if ($this->_cache->processRequest()) { $this->getResponse()->sendResponse(); } else { $this->_initModules(); $this->loadAreaPart(Mage_Core_Model_App_Area::AREA_GLOBAL, Mage_Core_Model_App_Area::PART_EVENTS); if ($this->_config->isLocalConfigLoaded()) { $scopeCode = isset($params['scope_code']) ? $params['scope_code'] : ''; $scopeType = isset($params['scope_type']) ? $params['scope_type'] : 'store'; $this->_initCurrentStore($scopeCode, $scopeType); $this->_initRequest(); Mage_Core_Model_Resource_Setup::applyAllDataUpdates(); } $this->getFrontController()->dispatch(); } return $this; } …. |
Here is the $this->_initModules() method and its code in the Mage_Core_Model_App class:
/app/code/core/Mage/Core/Model/App.php
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
…. protected function _initModules() { if (!$this->_config->loadModulesCache()) { $this->_config->loadModules(); if ($this->_config->isLocalConfigLoaded() && !$this->_shouldSkipProcessModulesUpdates()) { Varien_Profiler::start('mage::app::init::apply_db_schema_updates'); Mage_Core_Model_Resource_Setup::applyAllUpdates(); Varien_Profiler::stop('mage::app::init::apply_db_schema_updates'); } $this->_config->loadDb(); $this->_config->saveCache(); } return $this; } …. |
Our ultimate goal is the $this->_config->loadModules() method, wherein $this->_config = new Mage_Core_Model_Config($options) (from Mage.php).
This method itself collects and initializes all the Magento modules. Many of them depend on each other and are a part of each other. Let’s take a look at the method mentioned above – the one from the Mage_Core_Model_Config class.
/app/code/core/Mage/Core/Model/Config.php
|
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 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
…. public function loadModules() { Varien_Profiler::start('config/load-modules'); $this->_loadDeclaredModules(); $resourceConfig = sprintf('config.%s.xml', $this->_getResourceConnectionModel('core')); $this->loadModulesConfiguration(array('config.xml',$resourceConfig), $this); …. } …. protected function _loadDeclaredModules($mergeConfig = null) { $moduleFiles = $this->_getDeclaredModuleFiles(); if (!$moduleFiles) { return ; } …. } …. protected function _getDeclaredModuleFiles() { $etcDir = $this->getOptions()->getEtcDir(); $moduleFiles = glob($etcDir . DS . 'modules' . DS . '*.xml'); if (!$moduleFiles) { return false; } $collectModuleFiles = array( 'base' => array(), 'mage' => array(), 'custom' => array() ); foreach ($moduleFiles as $v) { $name = explode(DIRECTORY_SEPARATOR, $v); $name = substr($name[count($name) - 1], 0, -4); if ($name == 'Mage_All') { $collectModuleFiles['base'][] = $v; } else if (substr($name, 0, 5) == 'Mage_') { $collectModuleFiles['mage'][] = $v; } else { $collectModuleFiles['custom'][] = $v; } } return array_merge( $collectModuleFiles['base'], $collectModuleFiles['mage'], $collectModuleFiles['custom'] ); } …. |
After following a simple methods chain, we get to the _getDeclaredModuleFiles() method. It consists of the several stages:
- XML files names capturing from the [magento root]/app/etc/modules folder.
- Combining them into an array, sticking to the particular order.
Regarding this order, I cannot but mention that XML file named Mage_All always goes first. It contains all the Magento extensions initialization. Next XML files with the “Mage_” prefix are added, i.e. all the less important Magento modules. All the custom modules with any name of the XML file go at the end.
So, let’s proceed with the _loadDeclaredModules() method code:
/app/code/core/Mage/Core/Model/Config.php
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
…. protected function _loadDeclaredModules($mergeConfig = null) { …. Varien_Profiler::start('config/load-modules-declaration'); $unsortedConfig = new Mage_Core_Model_Config_Base(); $unsortedConfig->loadString('<config/>'); $fileConfig = new Mage_Core_Model_Config_Base(); // load modules declarations foreach ($moduleFiles as $file) { $fileConfig->loadFile($file); $unsortedConfig->extend($fileConfig); } …. } …. |
Everything is trivial here: we collect content of file and array we’ve mentioned above and add it to $unsortedConfig. Why it’s ‘unsorted ‘will be clarified in the subsequent description.
One would think, the goal is achieved and initializations file is assembled. Magento, however, has one very convenient tool to change the module initialization order. It becomes essential if modules depend on each other. Let’s take a look at the example of the Mage_Catalog module initialization structure in the Mage_All.xml file:
/app/etc/modules/Mage_All.xml
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
<?xml version="1.0"?> <config> <modules> …. <Mage_Catalog> <active>true</active> <codePool>core</codePool> <depends> <Mage_Eav/> <Mage_Dataflow/> <Mage_Cms/> <Mage_Index/> </depends> </Mage_Catalog> …. </modules> </config> |
Wherein <active>true</active> (can have true/false values) is used for module activation, <codePool>core</codePool> (core/local/community) determines the pool module will be located in; <Mage_Catalog>…</Mage_Catalog> is both module’s name and path to the pool location. This module will be therefore located in:
/app/code/core/Mage/Catalog
There is one more structure defining the module initialization order:
|
1 2 3 4 5 6 |
<depends> <Mage_Eav/> <Mage_Dataflow/> <Mage_Cms/> <Mage_Index/> </depends> |
I.e., the module follows the Mage_Eav, Mage_Dataflow, Mage_Cms, Mage_Index modules (if they are present). If the extension is enabled in the absence of one of the modules above, we will get the exception:
|
1 |
a:4:{i:0;s:65:"Module "Mage_Catalog" requires module "Mage_Dataflow".";i:... |
So, there is the <depends> construction, but how is its processing and module declaring sorting implemented? Let’s use the _loadDeclaredModules() method again:
/app/code/core/Mage/Core/Model/Config.php
|
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 |
…. protected function _loadDeclaredModules($mergeConfig = null) { …. $moduleDepends = array(); foreach ($unsortedConfig->getNode('modules')->children() as $moduleName => $moduleNode) { if (!$this->_isAllowedModule($moduleName)) { continue; } $depends = array(); if ($moduleNode->depends) { foreach ($moduleNode->depends->children() as $depend) { $depends[$depend->getName()] = true; } } $moduleDepends[$moduleName] = array( 'module' => $moduleName, 'depends' => $depends, 'active' => ('true' === (string)$moduleNode->active ? true : false), ); } // check and sort module dependence $moduleDepends = $this->_sortModuleDepends($moduleDepends); …. } |
As we can see, the $moduleDepends array, made up of $unsortedConfig, is prepared and passed into the _sortModuleDepends() method – the main sorting method based on the <depends> construction. Let’s consider this method in more detail:
/app/code/core/Mage/Core/Model/Config.php
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
…. protected function _sortModuleDepends($modules) { foreach ($modules as $moduleName => $moduleProps) { $depends = $moduleProps['depends']; foreach ($moduleProps['depends'] as $depend => $true) { if ($moduleProps['active'] && ((!isset($modules[$depend])) || empty($modules[$depend]['active']))) { Mage::throwException( Mage::helper('core')->__('Module "%1$s" requires module "%2$s".', $moduleName, $depend) ); } $depends = array_merge($depends, $modules[$depend]['depends']); } $modules[$moduleName]['depends'] = $depends; } $modules = array_values($modules); …. } …. |
It’s checked here if the modules, the current extension depends on, are present and active. If this condition is met
|
1 |
if ($moduleProps['active'] && ((!isset($modules[$depend])) || empty($modules[$depend]['active']))) |
the exception, mentioned above, happens to be.
It’s followed by the sorting process itself:
|
1 2 3 4 5 6 7 8 9 10 |
$size = count($modules) - 1; for ($i = $size; $i >= 0; $i--) { for ($j = $size; $i < $j; $j--) { if (isset($modules[$i]['depends'][$modules[$j]['module']])) { $value = $modules[$i]; $modules[$i] = $modules[$j]; $modules[$j] = $value; } } } |
And finally – the sorting “quality review”. Modules compatibility bugs are reported here. Typical bug is compatibility of two extensions. It’s impossible to define the order of these modules and the exception is being called.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
…. $definedModules = array(); foreach ($modules as $moduleProp) { foreach ($moduleProp['depends'] as $dependModule => $true) { if (!isset($definedModules[$dependModule])) { Mage::throwException( Mage::helper('core')->__('Module "%1$s" cannot depend on "%2$s".', $moduleProp['module'], $dependModule) ); } } $definedModules[$moduleProp['module']] = true; } return $modules; …. |
It’s all sorted (taking <depends> into account) and we return to the _loadDeclaredModules method again:
/app/code/core/Mage/Core/Model/Config.php
|
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 |
…. protected function _loadDeclaredModules($mergeConfig = null) { …. // create sorted config $sortedConfig = new Mage_Core_Model_Config_Base(); $sortedConfig->loadString('<config><modules/></config>'); foreach ($unsortedConfig->getNode()->children() as $nodeName => $node) { if ($nodeName != 'modules') { $sortedConfig->getNode()->appendChild($node); } } foreach ($moduleDepends as $moduleProp) { $node = $unsortedConfig->getNode('modules/'.$moduleProp['module']); $sortedConfig->getNode('modules')->appendChild($node); } $this->extend($sortedConfig); Varien_Profiler::stop('config/load-modules-declaration'); return $this; } …. |
So, the finite-length sequence of module declarations is formed, but it’s just a small part of the Magento module general configuration formation process. It’s next necessary to build each module’s configuration into the local configuration XML file, located in every extension.
Let’s go back the loadModules() method again:
/app/code/core/Mage/Core/Model/Config.php
|
1 2 3 4 5 6 7 8 9 |
…. public function loadModules() { …. $resourceConfig = sprintf('config.%s.xml', $this->_getResourceConnectionModel('core')); $this->loadModulesConfiguration(array('config.xml',$resourceConfig), $this); …. } …. |
I’ll leave the loadModulesConfiguration() method details out of this post, dwelling on two small issues only:
/app/code/core/Mage/Core/Model/Config.php
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
…. public function loadModulesConfiguration($fileName, $mergeToObject = null, $mergeModel=null) { $disableLocalModules = !$this->_canUseLocalModules(); …. foreach ($modules as $modName=>$module) { if ($module->is('active')) { if ($disableLocalModules && ('local' === (string)$module->codePool)) { continue; } .… } } …. } |
Here is where Magento verifies the <active> node value for the current module. It’s also checked if configuration of modules that are in the ‘local’ pool should be built. $module->is(‘active’) will return false only if the <active> value is false, off or this node doesn’t exist (/app/code/core/Mage/Core/Model/Config/Element.php). All other cases will activate the module.
Let’s turn our attention to the _canUseLocalModules() method:
/app/code/core/Mage/Core/Model/Config.php
|
1 2 3 4 5 6 7 8 9 10 11 12 |
protected function _canUseLocalModules() { …. $disableLocalModules = (string)$this->getNode('global/disable_local_modules'); if (!empty($disableLocalModules)) { $disableLocalModules = (('true' === $disableLocalModules) || ('1' === $disableLocalModules)); } else { $disableLocalModules = false; } …. } …. |
The method checks if the <disable_local_modules> node configurations are in the ‘global’ branch. If they are present, its value is being used. Magento thereby can disable all the modules from the ‘local’ pool with the help of the <disable_local_modules> directive.
The next interesting thing for us in loadModulesConfiguration():
/app/code/core/Mage/Core/Model/Config.php
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
…. public function loadModulesConfiguration($fileName, $mergeToObject = null, $mergeModel=null) { …. foreach ($fileName as $configFile) { $configFile = $this->getModuleDir('etc', $modName).DS.$configFile; if ($mergeModel->loadFile($configFile)) { $mergeToObject->extend($mergeModel, true); } …. } return $mergeToObject; } |
Next, the method collects all the files (config.xml in our case) from the /etc extension folder and unites them into the returned object. Configuration formation seems to be over, but there is another essential moment, somehow related to module initialization – repeated addition of the [magento root]/app/etc/local.xml file content to the already built configuration.
/app/code/core/Mage/Core/Model/Config.php
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
…. public function loadModulesConfiguration($fileName, $mergeToObject = null, $mergeModel=null) { …. /** * Prevent local.xml directives overwriting */ $mergeConfig = clone $this->_prototype; $this->_isLocalConfigLoaded = $mergeConfig->loadFile($this->getOptions()->getEtcDir().DS.'local.xml'); if ($this->_isLocalConfigLoaded) { $this->extend($mergeConfig); } $this->applyExtends(); Varien_Profiler::stop('config/load-modules'); return $this; } |
It helps redefine all the most important nodes playing the key role in Magento functioning (table_prefix or database accesses, for instance) in case these nodes were defined in some modules configuration.
Resuming, let’s define the main stages of module initialization in Magento:
- XML files names capturing from the [magento root]/app/etc/modules folder and combining them into an array, sticking to the particular order:
- Mage_all
- Mage_
- All the rest
- Modules sorting inside the object depending on the <depends> directive.
- Collecting the local configuration XML files in each module sticking to the particular order in light of <active> and <disable_local_modules> directives and its addition to the general configuration object.
- Repeating the /app/etc/local.xml file content uploading to the general configuration.
Partner With Us
Looking for a partner to grow your business? We are the right company to bring your webstore to success.
Talk to Igor
Hi. Why sorting modules at initialization? If you can please give an example. Thanks.
Denisa, configuration files from /app/etc are loaded in the Mage_Core_Model_Config::loadBase(). If you go through the whole request path it should be Index.php – Mage::run() (Mage::app()) – Mage_Core_Model_App::run() – Mage_Core_Model_App::run() – Mage_Core_Model_App::baseInit() – Mage_Core_Model_Config::loadBase().
You can check my articles about Magento Configuration flow: Explaining how Magento Loads and Manipulates Configuration Information part 1 and part 2
Also you can look at the Magento Request Flow
When is the first time when /app/etc/local.xml is added to array?