Download the PHP package tresbientech/drupal-patch-check without Composer

Drupal Patch Check

A composer plugin for sites that keep Drupal patches. It says which of your patches still apply after an update, which ones a release already fixed, and it re-rolls the ones that broke.

Remote service call

The plugin cannot judge a patch on its own. It posts your patches to api.tresbien.tech/v1/composer/scan, which holds a mirror of every drupal.org release and does the work. It is run by Très Bien Tech, a long time Drupal contributor.

Installing the plugin sends nothing. Four commands call the service: the check, the re-roll, the add and the upgrade. With the hook setting on, every composer update, require and remove calls it too. The pin sends it nothing.

The DRUPATCH_ENDPOINT environment variable sends the call to another address. Nothing in composer.json can change it.

Settings says what the request holds and what you can leave out.

Install

An interactive install prints this once per site:

The first two lines print when composer.json has no hook setting. The last three print on a site running cweagans/composer-patches 1.x, and no setting turns them off.

The commands

composer drupal-patch-check runs the check too.

They read your declarations where cweagans/composer-patches reads them: extra.patches in composer.json, and the patches file your settings point at. Both the title-to-file map and the expanded object form are read.

A re-roll leaves out the files a release package does not ship, read from the release tag's own archive. --from-source keeps every hunk instead, for a site installed from source, which holds every file. The run prints a count, as in the re-roll left out 2 files your release does not ship, so your patch holds the fix alone.

The re-roll, the pin and the add ask git about composer.json and the patches file before they ask the service or write anything. The run stops and prints the file when:

• the patches declared there differ from the last commit
• the site is not in git

--force skips the question, and --dry-run never asks it.

Moving to cweagans/composer-patches 2.x

2.x applies every patch with git apply alone. A patch that applied under 1.x only with fuzz stops applying. One command moves the site:

It re-rolls each patch 2.x would refuse and moves your declarations into a patches file. It moves your settings and requires ^2. Then it runs composer update cweagans/composer-patches --with-dependencies, composer patches-relock and composer patches-repatch. The site ends on 2.x with its patches applied.

The patches file is the one 1.x extra.patches-file points at, or patches.json when that is unset. The settings change this way:

• extra.patches-ignore becomes extra.composer-patches.ignore-dependency-patches
• extra.patches-file becomes extra.composer-patches.patches-file
• extra.patchLevel, extra.enable-patching and extra.composer-exit-on-patch-failure are dropped, because 2.x reads none of them
• a patch records a depth only when it applies at a depth other than its package default: 2 for drupal/core, 1 for the rest

--dry-run prints what the run would change and the commands it would run. A command that fails stops the run, and the report lists the commands left. Running the upgrade again runs them.

The upgrade writes neither composer.json nor the patches file, and the site stays on 1.x, when:

• a re-roll leaves regions to decide
• a patch 2.x would refuse has no clean re-roll
• a copy or a re-roll could not be written

The report lists those patches. For open regions, decide them, run composer drupatch:reroll, then run the upgrade again.

The upgrade writes nothing when git reports composer.json or the patches file changed, or the site is not in git. Commit them first, or pass --force.

Adding a patch from an issue

composer drupatch:add <issue> takes a drupal.org issue URL, its GitLab work-item form, or a merge request URL. It needs cweagans/composer-patches 2.x, and a 1.x site is sent to drupatch:upgrade-patch-manager.

The run:

• takes the issue's only merge request, or lists them and asks which one
• copies the diff into the site and asks the service for a verdict
• re-rolls a patch that fails, over the copy
• removes the copy and declares nothing when the release already holds the fix
• declares nothing when a re-roll leaves regions to decide, and prints them
• otherwise declares the patch, then runs composer patches-relock and composer patches-repatch

Patches declared as a URL

A patch declared as https://git.drupalcode.org/project/webform/-/merge_requests/940.patch is downloaded on every install. On a site running cweagans/composer-patches 1.x, these runs warn about it:

• composer install, update, require and remove
• composer drupatch:check, drupatch:reroll and drupatch:pin

A check run also prints declared as a merge request URL under each such row. No setting turns the warning off, and it costs no network call. The add and the upgrade do not print it. 2.x records a hash per patch and refuses bytes that moved, so a 2.x site never sees it.

composer drupatch:pin copies the patch into your repository and points the declaration at the file:

The copy is written under patch/, or wherever patch-directory says. It goes in a folder named after the package: webform for drupal/webform, core for drupal/core.

The file holds the diff and nothing else. Where the bytes came from goes on the declaration, under extra.drupatch, which cweagans/composer-patches 2.x copies into patches.lock.json untouched:

Once the declaration points at a file, that record is the only link back to the merge request. pin --refresh reads it, asks whether the request has new commits, and takes them. A bare pin run asks nothing about a copy already in place. Nothing else takes new bytes.

The record holds no hash. 2.x hashes every patch it locks, a local file included, and refuses one whose bytes moved.

Pin does not overwrite a copied patch that git reports as changed. --force does.

A commit URL is copied the same way, as commit-<first 12 characters of the sha>.diff. Any other URL is copied under the name it ends in.

Re-rolls

A re-roll that merges cleanly replaces the patch file. One that leaves markers is written as .conflict.patch beside it and is never referenced from your declarations, so a half-merged patch never gets installed. The declaration of a patch the release already holds is dropped.

Inside, each open region falls between a # drupatch region N file line and a # drupatch end N file line. Replace the text between them, or leave it empty to drop the region, then run composer drupatch:reroll again. The report gives every region as its file and index.

--decisions decides regions without editing the file. Each entry gives the patch as you declared it, the file and the region index. It then sets choice to release or patch, or gives the text to put there:

Where the document and a conflict file decide the same region, the document wins.

A patch declared as a URL has no file to replace. The re-roll refuses it and points at composer drupatch:pin.

On a 2.x site, a conflicting local patch can belong to a drupal.org issue. Its title starts with the issue number, or its file name holds it. The re-roll then takes one of that issue's merge requests, copies it in and merges from it. --mr <number> picks the request for a run that cannot ask.

Verdicts

A patch can apply and still leave a file the site cannot load. PHP, YAML, JSON, JavaScript and Twig are read for that. The verdict stays applies, and a line under the row opens with broken syntax and gives the file and line. The check headline counts every patch. The package tally, the patches: tally and the hook headline count broken syntax apart.

On a 2.x site, a patch that only a lenient apply accepts is refused by 2.x. The check, the re-roll and the add read it this way, and the hook prints the verdict as the service sent it. The verdict stays applies, and both tallies count it apart:

Exit codes

• 0: every patch in scope applies, is already in the release, or came back unknown
• 1: a patch conflicts, has broken syntax, is refused by 2.x, or came back with a verdict the installed plugin does not know
• 2: the check, the re-roll or the pin failed: no answer from the service, an unreadable site, or a failed write

The re-roll takes its exit code from the verdicts, so a run that wrote a clean re-roll still exits 1. The pin exits 1 when it could not copy a patch. The add and the upgrade exit 1 when they stop.

JSON output

--format=json prints one JSON document on stdout, and every note on stderr. Its top-level keys:

• check and re-roll: the service's answer as received, then summary, written and refused
• pin: vendored, kept, moved, refused and rewritten

Settings

Every setting lives under extra.drupal-patch-check in your composer.json.

hook covers the verdicts alone. The merge request warning prints either way.

A leftover private-paths setting prints drupatch: extra.drupal-patch-check.private-paths is no longer read: no path of your own leaves the site.

What the request holds

The request is about your drupal.org packages: the ones composer installed from packages.drupal.org, plus core.

Sent:

• four keys from composer.json: require, require-dev, minimum-stability and prefer-stable
• one trimmed composer.lock entry per package
• one entry per patch you declare in extra.patches or in the patches file
• client: the plugin name and plugin version
• target_core: the core the run judges against, empty without --target
• reroll: whether the run asks for re-rolls
• candidates: with --target, the release composer would install for each patched package
• installed_core: the core requirement each installed release declares, read from your vendor directory
• drop_tests: what a re-roll does with a file the release package leaves out, sent only with --from-source, which keeps every hunk

Per declaration, the request holds:

• package and patch: the package and the patch text
• merge_patch: the .diff form of a merge request declared as .patch
• upstream: the merge request URL, for a patch declared as one
• provenance: for a copied patch, where its bytes came from, as mr, commit and base, plus url when that URL is on drupal.org or git.drupalcode.org
• resolutions: the regions you decided in a conflict file or a --decisions document

Not sent:

• every other package you have, so a private module or a path repository is never mentioned
• your repositories, config, autoload and scripts
• the titles you gave your patches
• the paths you keep your patches at, and every patch URL you declared other than a merge request URL
• a copied patch's head commit, fetch date and re-roll release
• a copied patch's URL on any host other than drupal.org and git.drupalcode.org

A path can give something away. patch/acme_dam/CUP-1341_preview.patch tells a reader your client and your ticket number, so none of it travels. A URL on another host can tell as much, so it stays home too. A merge request URL travels, declared or copied, and so does the URL of a drupal.org attachment you pinned. Both point at public pages. The service reads a merge request to say whether a release already holds the fix.

The patch text always travels as written, because the service judges it. If a patch repeats the ticket number in a comment, that comment travels with it.

composer drupatch:check --dry-run prints the request.

Requirements

PHP 8.1 or newer and Composer 2.3 or newer. It adds no runtime dependency beyond ext-json, because it runs inside your own composer process.

License

MIT.