Composer Patches Laravel Package

Product Decisions This Supports

• Ship-blocker triage: patch vs. fork vs. wait. When a vendor package has a bug blocking a release, this package turns "fork the library and maintain a divergent branch" into "add a three-line patch entry." That's the core product decision it de-risks: unblock the roadmap today without owning a fork.
• Build vs. buy for the patching capability itself. Buying (adopting this) is a clear win over building an in-house Composer plugin or shelling out to patch in a build script — it already handles project-level and package-level patch definitions, so you don't have to invent a convention.
• Reproducibility as a release criterion. Patches are declared in Composer config, so the patched state is versioned with the code and applied on every install — that makes "what's actually running in production" auditable, which is a compliance/release-readiness decision, not just a dev-convenience one.
• Hotfix SLA commitments. If sales or support is promising fixes on a timeline shorter than a vendor's release cadence, this package is the mechanism that makes that promise deliverable. That's a commitment you can make in a contract.
• Scope of the "we support this stack" claim. With patch versioning and sequencing, you can maintain a tested matrix of vendor versions plus patch sets — which is what lets you claim support for multiple PHP/framework versions without doubling the engineering surface.
• Roadmap sequencing for vendor-upgrade work. Because patches are the first thing to break on a dependency bump, the size of the patch set is a direct measure of upgrade risk. A shrinking patch list is a roadmap signal that a fork or an upstream fix has landed.
• Troubleshooting as a support cost driver. The bundled Composer commands for testing and troubleshooting patches mean failed-patch diagnostics don't require an engineer to read plugin internals — relevant to whether you can hand patching to mid-level devs or CI.
• Ecosystem fit. Authored by a Magento/Adobe Commerce agency; strongest fit where you have many third-party modules and a slow upstream (Magento, Drupal, WordPress, legacy PHP stacks). Weakest fit in a narrow, modern dependency set where you control most of the code.
• Portfolio honesty. With ~300 stars and a low opportunity score (~14), this is commodity plumbing, not a differentiator. The right decision is "adopt cheaply, don't invest in extending it, don't build a strategy on top of it."

When to Consider This Package

Adopt when most of these hold:

• You have vendor code you cannot modify at source and an upstream fix is slower than your release cadence.
• Your patch set is small and short-lived — ideally 1–10 patches, each targeted at a specific release you intend to drop once upstream fixes it.
• You need multiple patches applied in a defined order to the same package, or you need to patch a package that isn't yours to fork.
• You want patches declared in version control and applied automatically in CI and production builds, rather than manually reapplied by whoever remembers.
• You're in a PHP/Composer ecosystem with a known-slow vendor layer (Adobe Commerce, Drupal, legacy plugins).
• Your team already understands Composer well enough that a plugin failure is diagnosable, not a mystery.

Look elsewhere, or choose a different strategy, when:

• You'd be patching more than a handful of files, or the patch touches the same code every vendor release. Rebase cost will exceed fork cost; fork or vendor the package instead.
• The vendor will accept an upstream PR on a reasonable timeline. Patching is a tax you pay on every upgrade; an upstream fix is a one-time cost. Escalate to the vendor first.
• The change is security-critical. A locally applied patch means your security posture depends on a patch file staying in sync with your lockfile and a plugin actually failing loudly when it doesn't apply. Verify that failure mode before relying on it.
• You need supply-chain guarantees (signed artifacts, provenance, SBOM-grade traceability). This is a patch-application convenience, not a supply-chain control.
• Your dependency set is modern and self-owned, where forking an internal package is cheaper than a patch workflow.
• Maintainer risk matters to you. Small-star-count, agency-published plugin: check issue responsiveness and whether it's actively tracking new Composer and PHP releases before putting it on the critical path of every install. Pin the version, and have a fallback plan if it stalls.
• Nobody on the team owns it. An unowned patch set becomes silent tech debt — the patches quietly accumulate and nobody prunes them.

How to Pitch It (Stakeholders)

For executives (one paragraph): We're sometimes blocked by bugs in third-party code we don't control, and today the only options are to wait for the vendor, or to copy their library into our codebase and maintain it forever. This package is the third option: a small, MIT-licensed Composer plugin that lets us apply targeted fixes to vendor code declaratively, checked into version control and applied automatically on every build. It converts a multi-day fork-and-maintain project into an hours-long task, and it keeps an auditable record of exactly what we've changed. It's low-cost infrastructure, not a strategic investment — we adopt it narrowly, keep the patch count small, and treat each patch as temporary debt with an owner and a removal plan.

For engineering (summary): vaimo/composer-patches is a Composer plugin that applies local or remote patch files to any package in the dependency graph. Patches can be defined at project level or shipped inside a package, with optional versioning, explicit sequencing, and configurable patch appliers. It adds Composer commands for testing and troubleshooting patches so failures are diagnosable rather than silent. Standard install, MIT license, no service dependency.

What we're explicitly not claiming: it isn't a fork-management strategy, it doesn't fix a bad vendor relationship, and it doesn't replace getting the fix upstream. Success looks like a short patch list that shrinks over time — not a growing one.

Guardrails we'd set at adoption: pin the plugin version; fail the build (don't warn) if a patch doesn't apply; require an owner and an upstream ticket reference on every patch; review the patch list at each dependency upgrade; and re-evaluate forking if any single patch survives two consecutive vendor upgrades.