Makefiles Laravel Package

Getting Started

This is not a Laravel library — it is a Composer-installed generator that writes a Makefile (and a set of QA configs) into a PHP package so that every quality gate runs inside Docker. Assess it as a "standardise your QA entrypoints" tool, not as an application dependency.

Minimal path:

1. composer require --dev wyrihaximus/makefiles
2. Run composer install / composer update. Generation is triggered from Composer lifecycle hooks, so the Makefile is produced as part of the install/update rather than by a manual command (0.10.0 moved image/version decisions to generation time for faster subsequent runs).
3. Inspect the generated Makefile at the repo root and the generated configs under etc/qa/ (e.g. etc/qa/infection.json5). These are the artefacts you will actually live with day to day.
4. Confirm Docker is available and working for your user — nearly every target routes through docker run/docker compose, and since 0.10.0 the socket may be mounted so PHPUnit/Infection can spin up test containers.
5. Run make all as the first end-to-end use case; it is the aggregate target and, per 0.10.2/0.10.3, is expected to run through Docker with the socket when appropriate.

Where to look first, in order: the generated Makefile (to see target names and the DOCKER_RUN / DOCKER_SHELL split introduced in 0.9.0), composer.json → extra.wyrihaximus.supported-features, then etc/qa/*. The README is essentially installation plus license; the release notes are the real documentation, so treat CHANGELOG/releases as required reading before upgrading.

For a Laravel-shaped codebase the realistic first use case is a package you publish (a Laravel package repo), where you want make cs, make static-analysis, make unit-testing-filter FILTER=... to behave identically on your machine and in CI without installing PHP, extensions, or QA binaries locally.

Implementation Patterns

Feature-gated QA. The main integration lever is composer.json:

{
  "extra": {
    "wyrihaximus": {
      "supported-features": {
        "code-style": false,
        "composer-dependency-checkers": false,
        "static-analysis": false,
        "unit-tests": false,
        "windows": false,
        "zts": true
      }
    }
  }
}

Set this before the first generation pass. Disabling unit-tests in 0.11.0 removes the PHPUnit and InfectionPHP configs and stops PHPStan from analysing tests/; disabling code-style removes the PHPCS and Rector configs. This is the correct way to opt out — do not hand-delete generated files, because regeneration on the next composer update will bring them back.

Target-driven workflow. Treat the Makefile as the single interface and stop invoking tools directly. Typical daily loop: make cs-fix locally, make cs in CI (0.10.5 deliberately made cs-fix fail into make cs so failures surface as actionable); make unit-testing-filter FILTER=SomeTest (0.8.2/0.10.1) for a single test while iterating; make cs-fix-debug (0.10.5) when the fixer misbehaves and you need to see the raw invocation. make all is the pre-push gate.

Keep CI thin. Because every target is Dockerised and the image decisions are baked at generation time, a CI job whose only step is make all is a legitimate pattern — you are not pinning PHP versions in two places. Note 0.11.0 added composer validate and composer show targets, so make all also guards your composer.json and lockfile sanity.

Renovate/constraint coupling. 0.8.0/0.8.1 include behaviour that keeps Renovate's constraints.php in sync with composer.json's config.platform.php, and keeps constraints.composer at 2.x. If you use Renovate, let these generated pieces own that config rather than duplicating it — 0.10.0's "expand requirements list beyond direct required packages and extensions" also means indirect requirements influence image choice, so bump your config.platform.php deliberately.

Migration helpers as one-shot codemods. The release notes reference migrations that strip @psalm-suppress, @phpstan-ignore-next-line/@phpstan-ignore-line, and lines containing @internal. Use these as deliberate refactor passes on a branch, never as part of routine installs on a codebase you haven't reviewed, since they rewrite source.

ZTS / non-ZTS split. 0.10.5/0.10.6 set OTEL_PHP_FIBERS_ENABLED appropriately, and 0.11.0 runs shell commands in ZTS images and always on non-slim images. If your package is extension-sensitive, set zts: true and prefer DOCKER_SHELL for interactive composer require experiments so extension installation works.

Gotchas and Tips

• This is a package workflow, not an app workflow. It assumes library layout (src/, tests/, etc/qa/). Dropping it into a full Laravel app will fight your existing tooling: PHPCS vs Pint, PHPStan/Larastan config, Pest vs PHPUnit. If you go ahead, disable code-style and static-analysis and keep only unit-tests, or keep the package confined to package repos.
• Generated files are the source of truth, and they are disposable. Edits to the Makefile and etc/qa/* survive only until the next Composer install/update triggers regeneration. Express intent through extra.wyrihaximus.supported-features and, failing that, through Composer script hooks that run after generation.
• Composer hooks do real work. Because generation and "on-install-or-update" run inside Docker (0.8.3 batched this into a single container), a composer install now depends on a working Docker daemon. In restricted CI or on a laptop without Docker, this fails in a confusing place. Have an escape hatch documented for contributors who only want vendor/.
• Docker socket mounting. 0.10.0 mounts the socket and uses -root variants when test containers are found in the requirement tree; 0.10.1/0.10.2 patched cases where the socket wasn't applied. On macOS/Colima or rootless Docker this is the most likely breakage, and it will manifest as testcontainers timing out inside PHPUnit rather than as an obvious Docker error. 0.10.4's ulimit bump to 1m is also worth knowing when you see odd resource errors in the container.
• make all is not a fast feedback loop. Use unit-testing-filter and cs-fix for the inner loop; reserve all (which pulls in Mutation testing via Infection) for pre-push. 0.10.3's change to surface all warnings/deprecations that cause a non-happy PHPUnit exit means previously "green" runs may go red on upgrade — expect that on the 0.10.x line.
• Version upgrades are behaviour upgrades. The 0.10 → 0.11 range changes what files exist on disk, so pin the version ("wyrihaximus/makefiles": "0.11.*"), read each release note, and regenerate on a branch and diff the resulting Makefile. There is no upgrade guide beyond the release bodies.
• Debugging checklist, in order: is Docker running → does the generated Makefile reference the image you expect → is composer.json's supported-features correct → does the target use DOCKER_RUN (scripted) or DOCKER_SHELL (interactive) → re-run with make cs-fix-debug or a plain docker run derived from the printed command.
• Extension points are thin. There is no plugin API documented; the practical extension surface is (a) the supported-features flags, (b) Composer scripts that run after generation, and (c) your own additional Makefile includes layered on top. If you need bespoke QA steps, add your own targets in a separate .mk file rather than editing the generated one.
• Adoption risk is real. Zero dependents and a release cadence driven by a single maintainer mean you are betting on one person's opinionated toolchain. It is excellent as a reference implementation of "all QA in Docker," and reasonable if your project already looks like a WyriHaximus-style PHP package; it is a poor fit for anything that needs to diverge from that shape, since customisation is mostly by disabling features.