Composer Patches Plugin Laravel Package

Getting Started

1. Install the plugin as a project dependency (not a global install):

   composer require --dev netresearch/composer-patches-plugin
   

   If your production build runs composer install --no-dev, install it in require instead so patches are applied in production builds too.

2. Allow the plugin on Composer 2.2+:

   {
     "config": {
       "allow-plugins": {
         "netresearch/composer-patches-plugin": true
       }
     }
   }
   

   Without this, interactive installs prompt and CI installs fail.

3. Add patch definitions under extra in composer.json. The package follows the common Composer patch convention of mapping package names to patch locations (confirm the exact key and schema in the package README; it is typically extra.patches):

   {
     "extra": {
       "patches": {
         "vendor/package": {
           "Fix null handling in importer": "patches/vendor/package/fix-null-importer.patch"
         }
       }
     }
   }
   

4. Run a clean install and watch the plugin output:

   rm -rf vendor/vendor/package
   composer install -v
   

   A successful run reports that the patch was applied. A failed run aborts the install and shows the patch command output.

5. Where to look first

   • The package README for the exact extra key, supported patch value formats (local path, URL, nested arrays), and any CLI commands.
   • composer.json / src/ of the plugin for the config schema and the Composer event(s) it subscribes to (typically post-install-cmd / post-update-cmd or package install events).
   • The plugin’s tests/fixtures for canonical examples of patch files and configuration.
   • Your project’s composer.lock before and after an upgrade when a patch starts failing.

6. First real use case: patch a one-line bug in a vendor package that has no upstream release yet. Put a git diff-style patch in patches/, reference it from extra.patches, commit both, and verify with a clean composer install in CI.

Implementation Patterns

• Keep patches in the repository. Store them under a predictable tree such as patches/<vendor>/<package>/<short-description>.patch. This makes them reviewable and ensures every developer and CI run uses the same patch content.
• Generate patches from the package root. Check out or copy the dependency, make the change, and produce a unified diff with a/ and b/ prefixes:

  git diff --no-index --src-prefix=a/ --dst-prefix=b/ original/ modified/ > fix.patch
  

  Patches are normally applied with -p1, so paths should look like a/src/Foo.php and b/src/Foo.php.
• Prefer local files over remote URLs. Remote patch URLs drift or disappear. If you must use a URL, pin it to a commit SHA or immutable release asset, and consider vendoring the patch into the repo later.
• Name patches after the problem, not the package version. Example: fix-null-importer.patch, not vendor-package-1.2.3.patch. The patch is tied to code, not to the installed version string.
• Treat patches as version-coupled technical debt. When upgrading a patched dependency, run composer update vendor/package --with-dependencies, then immediately do a clean install to see whether the patch still applies. If it fails, regenerate it against the new version rather than adding fuzz.
• Make patch application part of CI. A CI job that runs composer install from a clean checkout is the only reliable way to prove patches apply. Developers with an existing vendor/ directory may never exercise the plugin.
• Rebuild rather than mutate. To re-test a patch after editing it, remove the affected package directory (or the whole vendor/) and reinstall. Changing a patch file alone usually does not cause the plugin to reapply it.
• Document each patch. Add a short comment or a patches/README.md entry with the upstream issue/PR link, the reason for the patch, and a removal condition (“remove when >= 2.4.1 is released”). This prevents patches from becoming permanent folklore.
• Use patches surgically. Patch the smallest possible surface and avoid patching generated files, lockfiles, or files that are frequently rewritten by the package’s own tooling. Large patches conflict more often and are harder to review.
• Build-time vs runtime. If you commit vendor/ or ship a build artifact, the plugin only needs to run in the build environment. Keep the patch files in the repository regardless so future builds are reproducible.
• Migration pattern from other patch plugins. If you are moving from another Composer patch plugin, do it in a dedicated commit: move patch files, translate config keys, remove the old plugin from require/allow-plugins, and run a clean install to compare results.

Gotchas and Tips

• allow-plugins is the most common first failure. On Composer 2.2+, CI will refuse to run the plugin unless it is explicitly allowed. Commit the config.allow-plugins entry.
• Patches are not recorded in composer.lock. Two environments can have identical lockfiles but different vendor/ contents if one did not run the plugin. Enforce clean installs in CI and avoid committing a vendor/ directory that was built without patches.
• Editing a patch does not reapply it. The plugin runs during install/update, not on every Composer command. Remove the target package or run a clean install after changing a patch.
• Failed patches abort the install by default. That is usually desirable, but it means an upstream release can block all installs until the patch is updated. Check whether the plugin exposes a “skip/ignore failure” option; use it only temporarily and never in committed CI configuration.
• Fuzz is not success. patch can apply a hunk with offset or fuzz against a slightly different version. Inspect output with -v and prefer regenerating the patch against the exact installed version.
• Line endings and whitespace matter. Patches generated on Windows (CRLF) may fail on Linux CI, and trailing-whitespace differences cause rejected hunks. Normalize with .gitattributes and generate patches in the same environment as CI where possible.
• Binary diffs need special handling. Plain patch does not apply Git binary patches; verify whether this plugin uses git apply --binary or supports binary patches before relying on them.
• Patch ordering can matter. If two patches touch the same file, the second may fail or apply incorrectly. Keep patches on the same package disjoint, or combine them into one patch applied in a known order.
• Windows environments may lack a usable patch binary or behave differently with path separators. Confirm the plugin’s patch backend and test on the same OS family as your developers/CI.
• --no-dev can silently skip the plugin. If the plugin is in require-dev and production builds use --no-dev, patches will not be applied in production. Put it in require if production builds install from source.
• AGPL-3.0 licensing. The plugin is AGPL-licensed. If your organization has restrictions on AGPL tooling, review this before adding it to the build chain. Because it runs at build time, the practical exposure is usually limited, but policy varies.
• Abandonment/maintenance risk. This is a small, niche package. Check its compatibility with your Composer version and recent PHP releases, and compare against more widely used patch plugins before standardizing on it. Keep patch files in a format that can be reused by another patch plugin if you need to migrate.
• Debugging: run composer install -vvv, capture the exact patch command and working directory, and reproduce it manually from the package root. Most failures are path-prefix (-p1 vs -p0), wrong package version, or a stale patch.
• Extension points: inspect the plugin source for the Composer event it subscribes to and whether it exposes config for the patch command, patch path resolution, or failure behavior. If the built-in behavior is too rigid, a small Composer script hooked into the same event is often simpler than forking the plugin.