Open Source
The tools here are the ones I’ve shipped and maintain in the open — real software with a
test suite and CI behind it, not throwaway gists. Each came out of a problem I hit running my own
infrastructure and was hardened enough to hand to someone else. Not all of it is AI; some of the most
useful engineering is the unglamorous kind that quietly keeps a production system alive.
Upgrade H5P Medic
Moodle admin tool · PHP · GPL-v3 · Moodle 4.2–5.2 · PHPUnit + GitHub Actions CI
Upgrade H5P Medic (tool_h5pmedic) makes a Moodle upgrade safe and
reversible. It fingerprints your site before you upgrade, compares it afterwards, and tells you exactly
what dropped or broke — with special attention to H5P, the one part it can also automatically repair.
Why I built it
I run real Moodle course businesses on my own hardware, and a Moodle upgrade rewrites the database
underneath them. H5P interactive content is the most notorious casualty of that process. When Moodle’s
core-bundled H5P libraries change during an upgrade, content that was already deployed ends up pointing
at libraries that no longer resolve — and it simply stops rendering. Worse, the obvious fix doesn’t work:
re-deploying the broken items one at a time is unreliable, because H5P’s internal library cache will
cheerfully report a just-removed library as still installed and skip re-installing it. “Cross your
fingers and upgrade” is not a strategy when paying students are mid-course.
What it does
Three moves — snapshot, compare, repair:
- Snapshot — record an integrity fingerprint of the whole site: counts of courses,
activities per module type, questions, grades, files, every plugin version, and the full H5P state
(installed libraries, deployed content, and any content whose libraries don’t resolve). - Compare — diff a before and after fingerprint and flag every
regression: dropped activities, questions or courses; removed or downgraded plugins; removed H5P
libraries; and H5P content that went dark. Every check returns a scripting-friendly exit code. - Repair — when content has lost its libraries, deterministically rebuild the deployed
H5P subsystem from the original.h5ppackages: clear the deployed state and its
caches, re-install every library cleanly, then re-check against the pre-upgrade snapshot and flag
anything still broken for a human. It never touches your source packages or student attempt data.
The model: verify and mend, never guess
The safe way to upgrade a stateful system is full backup → verify what changed → whole-snapshot
rollback if you have to. H5P Medic is the verify-and-mend half. Pair it with your own backup and “cross
your fingers and upgrade” becomes “upgrade, then get an exact list of anything that regressed, with the
H5P breakage already repaired.” One command wraps the whole thing:
# before the upgrade — write the baseline
php admin/tool/h5pmedic/cli/guard.php --phase=pre --baseline=/tmp/baseline.json
# ... perform the Moodle upgrade ...
# after — compare, auto-repair H5P, re-check (exit 0 = clean, non-zero = review or roll back)
php admin/tool/h5pmedic/cli/guard.php --phase=post --baseline=/tmp/baseline.json --repairBecause compare, repair and guard all return non-zero when
something is wrong, the whole thing drops straight into an upgrade script or a CI job rather than living
in a runbook nobody reads.
Built to be trusted with a production LMS
This isn’t a weekend script. The comparison logic, the fingerprint generator, and the H5P repair guard
are covered by PHPUnit, and every push runs through GitHub Actions — PHP lint, the Moodle code checker,
PHPDoc, a mess detector, validation, and the test suite — across every supported Moodle from 4.2 to 5.2.
It’s GPL-v3, and it’s the tool that keeps the interactive content alive on my own
self-hosted course platforms through every upgrade.