Vendor Patches Laravel Package

Getting Started

This package allows developers to apply and manage patches to Composer-managed vendor dependencies without forking repositories or manually editing vendor files (which would be overwritten on updates). Start by installing it via Composer: composer require --dev symplify/vendor-patches. Then create a vendor-patches.yaml (or .json) config file in your project root to define patches—each patch maps a package name to one or more patch sources (e.g., local .patch files, URLs, or GitHub pull requests). The first use case is typically applying a critical bug fix from a GitHub PR to a package you rely on (e.g., drupal/core or symfony/http-foundation) until an official release is available.

Implementation Patterns

• Declarative patch definitions: Store all vendor patches in version-controlled config (e.g., vendor-patches.yaml), enabling teams and CI to reproducibly apply the same patches.
• Patch types support: Use local paths (patches/bugfix-123.patch), remote URLs (https://github.com/vendor/repo/pull/456.patch), or Drush-style "https://www.drupal.org/files/issues/2023-xx-xx.patch"—symplify/vendor-patches downloads and applies them automatically on composer install/update.
• Prevent re-application: Patches are tracked via SHA1 hashes; symmetric differences ensure patches apply cleanly and avoid duplicate application.
• Integration with CI/CD: Add vendor-patches as a dev dependency; in CI, patches apply silently during composer install, ensuring dev/staging/prod parity.
• Package-specific configs: Optionally split patches per package using config keys, or use extra.vendor-patches in composer.json.

Gotchas and Tips

• Apply only on clean vendor: Patches fail if vendor files are modified manually—always run patches before running composer update, or ensure clean state.
• Patch drift on updates: A patch may become invalid when the target package is upgraded. Monitor patch application errors after updates and regenerate/adjust patches using diff -u from a clean vendor install if needed.
• Relative paths in patches: Ensure patch files use relative paths compatible with the target package’s internal structure (e.g., src/SomeClass.php, not ../src/SomeClass.php).
• Testing patches locally: Before committing, test composer install --dry-run or temporarily comment out patches to verify clean vendor reinstalls.
• Use --quiet and debug output: Run composer update -vvv to see verbose patch application logs— invaluable for diagnosing apply failures (e.g., Hunk failed at line X).
• Avoid overuse: Only patch when necessary—ideally, submit PRs upstream and switch to patch-only as a temporary workaround.