Overview

This document provides an introduction to the Maho Composer Plugin, a Composer plugin that extends Composer's functionality to support Maho and Magento-style project structures. The plugin manages three critical aspects of Maho project deployment: PHP autoloading for legacy code pools, module deployment via symlinks, and distribution of web assets to the project root.

Scope: This page introduces the plugin's purpose, architecture, and core components. For detailed information about specific subsystems, see:

• Installation and configuration: Installation and Usage
• Asset copying mechanism: FileCopyPlugin Asset Management
• Autoloading system: AutoloadPlugin System
• Module deployment: ModmanPlugin Module Deployment
• Development workflows: Development and Quality Assurance

Sources: composer.json1-28 README.md1-4

Purpose and Problem Statement

The Maho Composer Plugin solves the integration gap between Composer's modern dependency management and Maho/Magento's legacy architectural patterns. Composer expects PSR-4 autoloading and dependency isolation, while Maho uses PSR-0 with code pools (local, community, core), modman-based module deployment, and direct web asset access in the public/ directory.

Without this plugin, developers would need to:

• Manually configure PSR-0 autoloading for each installed module
• Create symlinks for module files according to modman definitions
• Copy web assets from vendor packages to the public web root
• Maintain executable permissions for CLI tools

The plugin automates all these tasks during composer install and composer update operations.

Sources: composer.json2-3

Plugin Registration and Core Components

The plugin registers three specialized components with Composer's plugin API, each handling a distinct deployment concern:

Sources: composer.json6-8 composer.json21-27

Component Responsibilities

Component	Primary Responsibility	Key Output
AutoloadPlugin	Generate PHP autoload configuration for Maho's code pool structure	Modifications to vendor/autoload.php
ModmanPlugin	Parse modman files and create symlinks for module files	Symlinks in vendor/mahocommerce/maho-modman-symlinks/
FileCopyPlugin	Copy web assets and executables to project root	Files in public/, executable ./maho
AutoloadRuntime	Discover and classify installed Maho/Magento packages	Package metadata used by other plugins

Sources: composer.json22-26

Package Type Support

The plugin processes three distinct package types, each requiring specialized handling:

Sources: composer.json1-28

Package Type Characteristics

Package Type	Typical Source	Contains	Deployment Method
maho-source	mahocommerce/maho	Core framework code, CLI tools, base assets	Direct file copying for assets; autoload scanning for code
maho-module	Third-party modules	Module code, templates, assets, modman file	Symlinks via modman; autoload registration; asset copying
magento-module	Magento 1.x modules	Legacy module structure	Same as maho-module (backward compatibility)

Sources: composer.json1-28

Composer Plugin API Integration

The plugin implements Composer's Plugin API v2.1+, which requires:

1. Plugin Package Type: Declared as "type": "composer-plugin" in composer.json4
2. Plugin Class Registration: Classes listed in extra.class array in composer.json22-26
3. API Dependency: Explicit dependency on composer-plugin-api: ^2.1 in composer.json7
4. Runtime API: Dependency on composer-runtime-api: ^2 for package discovery in composer.json8

Each plugin class implements Composer\Plugin\PluginInterface and subscribes to specific Composer events:

Plugin Class	Primary Event	Execution Phase
AutoloadPlugin	PRE_AUTOLOAD_DUMP	Before Composer generates vendor/autoload.php
ModmanPlugin	POST_PACKAGE_INSTALL, POST_PACKAGE_UPDATE	Immediately after each package installation
FileCopyPlugin	POST_INSTALL_CMD, POST_UPDATE_CMD	After all packages are installed/updated

Sources: composer.json4 composer.json6-8 composer.json21-27

Event Execution Flow

Sources: composer.json1-28

Development Environment and Quality Assurance

The plugin maintains high code quality through:

• PHP Version Support: Compatible with PHP 8.2, 8.3, and 8.4
• Static Analysis: PHPStan level 10 with strict rules and deprecation detection
• Development Dependencies: PHPStan tooling and Composer API for testing
• Automated Testing: GitHub Actions workflows for validation, syntax checking, and analysis

Development dependencies are declared in composer.json10-15:

See Development and Quality Assurance for detailed information about testing infrastructure and CI/CD workflows.

Sources: composer.json10-15

License and Distribution

The plugin is distributed under the MIT License, allowing unrestricted use, modification, and distribution with proper attribution. The package is published to Packagist as mahocommerce/maho-composer-plugin and can be installed in any Composer-managed project.

For licensing details and contribution guidelines, see License and Contributing.

Sources: composer.json1-2 composer.json5

Namespace and Autoloading

The plugin uses PSR-4 autoloading with the namespace Maho\ComposerPlugin\, mapping to the src/ directory:

Maho\ComposerPlugin\
├── AutoloadPlugin
├── AutoloadRuntime
├── ModmanPlugin
└── FileCopyPlugin

This structure is defined in composer.json16-20 ensuring Composer can load the plugin classes during its bootstrap phase.

Sources: composer.json16-20

Key Design Principles

The plugin architecture follows several key design principles:

1. Separation of Concerns: Each plugin handles one deployment aspect (autoloading, symlinks, or file copying)
2. Event-Driven Execution: Plugins respond to Composer events rather than polling or continuous operation
3. Idempotent Operations: Multiple executions produce the same result without side effects
4. Non-Invasive: The plugin only modifies generated files and isolated directories, never touching user code
5. Backward Compatibility: Supports both modern Maho packages and legacy Magento 1.x modules

These principles ensure the plugin integrates seamlessly with existing Composer workflows while maintaining predictable, reliable behavior.

Sources: composer.json1-28