Code Pool Structure and Priority

This document explains the Magento/Maho code pool hierarchy and how the AutoloadRuntime system prioritizes include paths to ensure proper class loading order. The code pool structure consists of four directories (local, community, core, lib) that are searched in priority order when resolving class names.

For information about how PSR-0 prefixes are generated from these code pools, see PSR-0 and Class Map Generation. For details on how packages are discovered and classified, see AutoloadRuntime Package Discovery.

Code Pool Hierarchy

The Maho ecosystem inherits Magento's four-tier code pool structure, where classes can exist in multiple locations with a defined priority order for resolution.

Sources: src/AutoloadRuntime.php127-132

Include Path Generation Algorithm

The generateIncludePaths() method builds the include path list by processing packages in reverse order, ensuring that root package paths appear before maho-source package paths.

Package Processing Order

Sources: src/AutoloadRuntime.php120-155 src/AutoloadRuntime.php31-86

Code Pool Assembly Logic

The method uses a closure $addIfExists to conditionally add code pool directories when they exist in a package:

Package Type	Contributes to local	Contributes to community	Contributes to core	Contributes to lib
root package with type: maho-source	✓	✓	✗	✗
root package (other types)	✓	✓	✓	✓
maho-source packages	✓	✓	✓	✓
maho-module packages	✓	✓	✓	✓
magento-module packages	✓	✓	✓	✓

Sources: src/AutoloadRuntime.php142-152

Code Implementation: generateIncludePaths()

The following diagram maps the natural language concepts to actual code constructs in the generateIncludePaths() method:

Sources: src/AutoloadRuntime.php120-155

Priority Resolution Examples

Example 1: Override Core Class with Local Version

When a project needs to customize Mage_Core_Model_App, the class resolution follows this search order:

Priority	Search Path	Result
1	<root>/app/code/local/Mage/Core/Model/App.php	If exists, loads immediately
2	<module-z-a>/app/code/local/Mage/Core/Model/App.php	If exists, loads immediately
3	<root>/app/code/community/Mage/Core/Model/App.php	If exists, loads immediately
4	<module-z-a>/app/code/community/Mage/Core/Model/App.php	If exists, loads immediately
5	<module-z-a>/app/code/core/Mage/Core/Model/App.php	If exists, loads immediately
6	vendor/mahocommerce/maho/app/code/core/Mage/Core/Model/App.php	Core implementation
7	<module-z-a>/lib/Mage/Core/Model/App.php	Not applicable for modules
8	vendor/mahocommerce/maho/lib/Mage/Core/Model/App.php	Not applicable for core classes

Sources: src/AutoloadRuntime.php127-154

Example 2: Library Class Resolution

For a library class like Zend_Config, the search prioritizes local overrides:

Sources: src/AutoloadRuntime.php127-154

Special Handling: Root Package Type

The root package (the project being installed) receives different treatment based on its declared type:

This distinction prevents the root maho-source package from contributing its core and lib directories twice (once as root, once as a maho-source package in vendor/).

Sources: src/AutoloadRuntime.php143-151

Include Path Result Structure

The final self::$includePaths array contains absolute filesystem paths in priority order:

The array_merge(...array_values($codePools)) operation at line 154 flattens these grouped arrays into a single list, and array_unique() removes duplicate paths that might exist when packages share code pool directories.

Sources: src/AutoloadRuntime.php154

Symlink Path Resolution

When a package has been deployed via ModmanPlugin, the getInstalledPackages() method substitutes the symlink directory path:

This ensures that when ModmanPlugin has created symlinks for module deployment, the autoloader scans the symlinked structure (which may differ from the vendor directory structure) rather than the original package installation.

Sources: src/AutoloadRuntime.php60-62

Caching Mechanism

The generateIncludePaths() method implements static caching to avoid repeated filesystem scanning:

Variable	Type	Purpose	Cache Lifetime
self::$includePaths	?list<string>	Cached array of include paths	PHP request duration
Initial value	null	Indicates cache is empty	Cleared on script restart
After first call	list<string>	Complete include path list	Persists until script ends

The cache check at line 122-124 returns immediately if self::$includePaths !== null, preventing redundant package scanning and filesystem operations during a single PHP request.

Sources: src/AutoloadRuntime.php21-22 src/AutoloadRuntime.php122-124

Usage in PSR-0 Generation

The include paths generated by this method are consumed by generatePsr0() to build PSR-0 prefix mappings. For each include path, generatePsr0() scans for namespace directories and builds the prefix-to-path mappings that Composer's autoloader uses.

Sources: src/AutoloadRuntime.php169-194