AutoloadPlugin System

The AutoloadPlugin system dynamically generates PHP autoloading configuration for Maho projects during Composer's dependency installation process. This system consists of two primary components: AutoloadPlugin (src/AutoloadPlugin.php), which integrates with Composer's plugin API, and AutoloadRuntime (src/AutoloadRuntime.php), which performs package discovery and autoload artifact generation. Together, these components enable PHP class loading for Maho's multi-pool architecture (local, community, core, lib) and support both legacy PSR-0 conventions and modern autoloading standards.

For details about the modman-based module deployment that works alongside autoloading, see ModmanPlugin Module Deployment. For information about how asset files are copied to the project root, see FileCopyPlugin Asset Management.

System Components and Responsibilities

The AutoloadPlugin system separates concerns between Composer integration (AutoloadPlugin) and runtime logic (AutoloadRuntime). This separation allows the runtime component to be used independently in contexts where Composer classes are not available.

Sources: src/AutoloadPlugin.php14-115 src/AutoloadRuntime.php1-274

Component Responsibilities

Component	Primary Responsibilities	Key Methods
AutoloadPlugin	Composer plugin lifecycle management, event subscription, RootPackage modification	activate(), getSubscribedEvents(), onPreAutoloadDumpCmd()
AutoloadRuntime	Package discovery, path generation, PSR-0 mapping, classmap building	getInstalledPackages(), generatePsr0(), generateClassMap(), generateIncludePaths(), generateIncludeFiles()

Sources: src/AutoloadPlugin.php46-115 src/AutoloadRuntime.php16-274

Composer Event Integration

The AutoloadPlugin subscribes to the PRE_AUTOLOAD_DUMP event from Composer's event system. This event fires after all packages are installed but before Composer generates the vendor/autoload.php file, providing the optimal moment to inject Maho-specific autoload configuration.

The event handler onPreAutoloadDumpCmd() executes at src/AutoloadPlugin.php72-113 and performs the following sequence:

1. Retrieves the RootPackage and existing autoload definition
2. Calls AutoloadRuntime::generateIncludePaths() to build code pool paths
3. Converts absolute paths to relative paths using Filesystem::findShortestPath()
4. Calls AutoloadRuntime::generateIncludeFiles() for bootstrap and function files
5. Calls AutoloadRuntime::generateClassMap() for non-PSR classes
6. Conditionally generates PSR-0 prefixes or optimization classmaps based on flags
7. Modifies the RootPackage autoload configuration

Sources: src/AutoloadPlugin.php65-69 src/AutoloadPlugin.php72-113

Autoload Artifact Generation

The system generates four distinct types of autoload artifacts, each serving a specific purpose in the Maho class loading architecture.

Artifact Types and Generation Methods

Sources: src/AutoloadRuntime.php120-273 src/AutoloadPlugin.php82-112

Artifact Generation Details

Artifact Type	Generator Method	Purpose	Example Output
Include Paths	generateIncludePaths()	PHP set_include_path() compatibility, priority-ordered code pools	["app/code/local", "vendor/pkg/app/code/community", "vendor/maho/app/code/core"]
PSR-0 Prefixes	generatePsr0()	Namespace-to-directory mapping for autoloading	{"Mage_Core_": ["vendor/maho/app/code/core"], "Zend_": ["vendor/zf1/library"]}
Class Map	generateClassMap()	Direct class-to-file mappings for non-standard classes	{"Mage": "vendor/maho/app/Mage.php", "Mage_Core_IndexController": "..."}
Include Files	generateIncludeFiles()	Files that must be loaded before autoloading	["vendor/maho/app/code/core/Mage/Core/functions.php", "vendor/maho/app/bootstrap.php"]

Sources: src/AutoloadRuntime.php120-155 src/AutoloadRuntime.php169-194 src/AutoloadRuntime.php201-238 src/AutoloadRuntime.php245-273

Package Discovery and Classification

The AutoloadRuntime::getInstalledPackages() method discovers all Composer-installed packages and filters them by package type, returning only those relevant to Maho autoloading.

The package discovery process at src/AutoloadRuntime.php31-86 implements the following logic:

1. Caching: Static variable $installedPackages caches results across calls
2. Dataset Iteration: Processes all data from InstalledVersions::getAllRawData()
3. Root Exclusion: Skips the composer/composer root package to avoid self-reference
4. Type Filtering: Accepts only maho-source, maho-module, and magento-module types
5. Symlink Resolution: Prefers symlink paths in vendor/mahocommerce/maho-modman-symlinks/ when available
6. Ordering: Returns sources first, then modules alphabetically, then root package last

Sources: src/AutoloadRuntime.php31-86 src/AutoloadRuntime.php60-62

Package Type Definitions

Sources: src/AutoloadRuntime.php68-72 src/AutoloadRuntime.php207-214

Code Pool Priority and Path Ordering

The generateIncludePaths() method creates an ordered list of directories that respects Maho's code pool hierarchy. This ordering ensures that local customizations override community modules, which in turn override core code.

Priority Order

The include paths are ordered with highest priority first:

1. Root package: app/code/local/, app/code/community/ (if root is not maho-source)
2. Module packages (reverse alphabetical): Each module's local and community pools
3. Source packages: Core pools (app/code/core/, lib/)
4. Root package (if maho-source): Core pools

This reversal at src/AutoloadRuntime.php142 ensures that files in the project root are found before files in vendor packages, enabling local overrides.

Sources: src/AutoloadRuntime.php120-155 src/AutoloadRuntime.php127-132 src/AutoloadRuntime.php142-152

Optimization Mode Handling

The system adapts its behavior based on Composer's --optimize-autoloader flag. This flag is detected in the event handler and changes the autoload strategy.

In optimization mode (src/AutoloadPlugin.php98-100):

• All include paths are added to the classmap array
• Composer scans every directory and builds a complete class-to-file map
• Results in faster class loading but slower installation
• Recommended for production deployments

In normal mode (src/AutoloadPlugin.php101-109):

• PSR-0 prefixes are generated via generatePsr0()
• Composer uses prefix matching for lazy class loading
• Faster installation but slightly slower class resolution
• Recommended for development environments

Sources: src/AutoloadPlugin.php98-109 src/AutoloadRuntime.php169-194

Static Caching Strategy

The AutoloadRuntime class employs static variables to cache expensive computations across multiple method calls during a single request. This optimization is critical because package discovery and path scanning can be invoked multiple times.

Cached Data	Static Variable	Cache Location	Invalidation
Discovered packages	$installedPackages	src/AutoloadRuntime.php19	Never (single request)
Include paths	$includePaths	src/AutoloadRuntime.php22	Never (single request)

The caching pattern follows this structure:

Sources: src/AutoloadRuntime.php18-23 src/AutoloadRuntime.php33-35 src/AutoloadRuntime.php122-124