Composer Patches

Composer Patches is a Composer plugin that lets you apply patches from local or remote files to any package installed by Composer. Instead of forking a dependency to fix a bug or tweak behavior, you declare the patches in your composer.json (or an external patches file), and the plugin applies them automatically whenever the affected package is installed or updated.

Widely used across the Drupal ecosystem and beyond, it supports resolving patches from multiple sources, locking applied patches for reproducibility, and pluggable resolvers, downloaders, and patchers so teams can customize how patches are found and applied.

What You Get

• Automatic application of patches to Composer dependencies on install/update
• Support for local file paths and remote URLs as patch sources
• A patch lock file for reproducible, deterministic builds
• Pluggable resolvers, downloaders, and patchers for custom workflows
• Composer commands to relock patches and diagnose problems

Common Use Cases

• Applying an upstream bug fix to a third-party package without forking it
• Maintaining local modifications to vendor code across Composer updates
• Managing patches for Drupal core and contributed modules
• Pinning and locking applied patches for reproducible deployments

Under The Hood

Architecture - The plugin is built around three composable capabilities: resolvers gather the patches that apply to a package (src/Resolver, src/Capability/Resolver), downloaders fetch each patch (src/Downloader), and patchers apply it to the installed files (src/Patcher). A central Plugin subscribes to Composer’s package events, a PatchCollection/Patch model represents the work, and a Locker writes a lock file for reproducibility. Console commands (src/Command) add relock and doctor diagnostics.

Tech Stack - PHP (>=8.0) implemented as a composer-plugin against composer-plugin-api ^2.0, with PSR-4 autoloading under cweagans\Composer. It builds on cweagans/composer-configurable-plugin and uses the Composer API for events, downloads, and install paths. Tests run under Codeception.

Code Quality - The codebase is cleanly separated into capability providers with base/core implementations, making each concern extensible. It is covered by unit and acceptance test suites via Codeception, with static analysis and style checks wired through GrumPHP, PHP_CodeSniffer, and parallel-lint.

API Design - For most users the interface is purely declarative: add a patches section to composer.json and run composer install. Advanced users extend behavior through the resolver/downloader/patcher capability interfaces rather than modifying the plugin, keeping the common path simple while allowing deep customization.