README

A Composer plugin that extends cweagans/composer-patches version 2 to support version-constrained patches. This plugin allows you to define patches that are only applied when specific version constraints are met, providing fine-grained control over when patches are applied based on package versions.

Features

Version-constrained patches: Apply patches only when package versions match specific constraints
Automatic version detection: Patches are resolved and applied based on installed package versions
Lock file management: Maintains a dependent-patches.lock.json file for reproducible builds
Separate patch management: Works alongside regular patches without conflicts
Custom commands: Dedicated commands for managing dependent patches

Installation

composer require openeuropa/composer-dependent-patches

Usage

Defining Dependent Patches

Version-constrained patches must be defined under the extra.dependent-patches key in your composer.json. Use the expanded format with version constraints in the extra section:

{
  "extra": {
    "dependent-patches": {
      "vendor/package": [
        {
          "description": "Fix for legacy versions",
          "url": "/path/to/legacy-fix.patch",
          "extra": {
            "version": "<2.0"
          }
        },
        {
          "description": "Modern version compatibility fix",
          "url": "/path/to/modern-fix.patch",
          "extra": {
            "version": ">=2.0 <3.0"
          }
        },
        {
          "description": "Latest version enhancement",
          "url": "/path/to/latest-enhancement.patch",
          "extra": {
            "version": "^3.0"
          }
        }
      ]
    }
  }
}

Version Constraint Syntax

The plugin supports standard Composer version constraint syntax:

^1.0 - Compatible with version 1.0
>=2.0 <3.0 - Version 2.0 or higher, but less than 3.0
~2.1 - Reasonably close to 2.1
2.0.* - Any version starting with 2.0
<2.0 - Less than version 2.0

Lock File Management

The plugin maintains a dependent-patches.lock.json file that:

Tracks which patches are applied based on current package versions
Ensures reproducible builds across different environments
Regenerates automatically when package versions change

Commands

The plugin provides dedicated commands for managing dependent patches:

`composer dependent-patches-relock`

Regenerates the dependent-patches.lock.json file based on current package versions and defined constraints.

composer dependent-patches-relock
# or use the short alias
composer dprl

`composer dependent-patches-repatch`

Removes and reinstalls packages that have dependent patches, ensuring all version-appropriate patches are applied.

composer dependent-patches-repatch
# or use the short alias
composer dprp

How It Works

Resolution: The plugin analyzes installed package versions against defined constraints
Selection: Only patches matching current version constraints are selected for application
Application: Selected patches are applied during package installation
Tracking: Applied patches are tracked in the lock file with package version information
Regeneration: Lock file is automatically regenerated when package versions change

Integration with Regular Patches

This plugin works seamlessly alongside the base cweagans/composer-patches plugin:

Regular patches (defined in extra.patches) → managed by base plugin → patches.lock.json
Dependent patches (defined in extra.dependent-patches) → managed by this plugin → dependent-patches.lock.json
Both types of patches are applied during composer install
Use respective commands to manage each type independently

Requirements

PHP 8.1 or higher
Composer 2.0 or higher
cweagans/composer-patches ^2.0@beta

Development

Testing

The plugin includes automated tests using PHPUnit. To run the tests:

# Install development dependencies.
composer install

# Run tests.
composer test

# Run tests with coverage (requires Xdebug).
composer test-coverage

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

The project uses GitHub Actions for continuous integration, testing against multiple PHP and Composer versions.

openeuropa / composer-dependent-patches

Maintainers

Details