openeuropa/composer-dependent-patches

A Composer plugin that extends cweagans/composer-patches to support dependent patches functionality

0.1.0 2025-09-24 10:54 UTC

This package is auto-updated.

Last update: 2025-10-01 10:15:48 UTC


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

  1. Resolution: The plugin analyzes installed package versions against defined constraints
  2. Selection: Only patches matching current version constraints are selected for application
  3. Application: Selected patches are applied during package installation
  4. Tracking: Applied patches are tracked in the lock file with package version information
  5. 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

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

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