Makefiles Laravel Package

Product Decisions This Supports

• Build vs. buy for internal developer tooling. Instead of spending engineering weeks hand-rolling Makefiles and QA wiring per repository, this package supplies pre-built blocks (PHPUnit, Infection mutation testing, PHPStan, PHPCS, Rector, composer validate, license/readme year updaters) that regenerate on composer install/update. The decision it informs is whether developer-experience work belongs on the roadmap as an owned internal platform or as an adopted open-source dependency — this is the low-cost "buy" side of that trade-off.
• Standardizing the QA gate across PHP repositories. Because behaviour is driven declaratively from composer.json (extra.wyrihaximus.supported-features toggling code-style, static-analysis, unit-tests, composer-dependency-checkers, windows, zts), a PM can mandate one baseline pipeline for all PHP services while letting each repo opt out of checks that don't apply. That turns "should every repo run mutation testing?" from a per-team argument into a policy default.
• Reducing time-to-first-commit and CI runtime. The 0.10.0 change set moves image/version decisions to Makefile generation time and only mounts the Docker socket when test containers are actually required — a direct lever on pipeline latency and onboarding friction. Useful when justifying DevEx investment against an OKR like "new engineer ships to production in under a day."
• Scoping Docker-based reproducibility vs. host-native tooling. Forcing QA through containers means a developer's local result matches CI. That is a platform-architecture decision (container-first dev environments) that this package makes cheap to trial, and cheap to abandon, rather than something requiring a bespoke build.
• Not a product-feature decision. This is a build- and CI-time dependency only; it adds no runtime surface to a Laravel application. It should never appear on a customer-facing roadmap, only on an engineering-enablement one.
• Greenfield vs. retrofit triage. Release notes show migration/replace tasks (e.g. migrations-php-set-phpstan-paths-in-config, cleanup of @psalm-suppress/@phpstan-ignore-next-line lines, removal of PHPUnit/Infection configs when unit-tests is disabled). That tells a PM the package is designed to own the config files it manages — a good fit for new repositories, a negotiation for existing ones.

When to Consider This Package

Consider it when:

• The organization maintains multiple Composer-based PHP repositories (libraries, packages, internal services) and is paying a real, repeated cost for inconsistent make targets and QA configuration drift.
• The team is already Docker-native — CI and laptops both have a working Docker daemon, and the team accepts containerized test runs as the source of truth.
• You want opinionated defaults fast, and your stack overlaps the author's: PHPStan, PHPCS, Rector, PHPUnit, Infection, Renovate/Dependabot. Adjacent tooling is where most of the leverage lives.
• The work is internal/platform-scoped, where a 0.x dependency with a single maintainer and no external documentation is an acceptable, reversible risk.
• You need per-repo feature gating rather than a rigid all-or-nothing template — the supported-features flags are the main reason to prefer this over a copied-and-pasted Makefile.

Look elsewhere when:

• The target is a single Laravel application. Laravel Sail, Pint, Pest and the default composer scripts already cover most of this ground with first-party support; layering a second, opinionated Makefile system on top creates two competing sources of truth.
• No Docker allowed (locked-down CI runners, rootless/daemonless policy, strict sandboxing). The package's value is substantially container-mediated; without that, you are paying the dependency cost for a fraction of the benefit.
• You need vendor support, an SLA, or a security-review trail. Zero stars, zero dependents, a single contributor, and a README that documents installation and licensing but no usage, targets, or configuration reference are all maturity signals a PM should weigh explicitly.
• The team needs configuration beyond composer.json extras — custom target graphs, non-PHP steps, monorepo path selection. This is a curated block set, not a general build system.
• You require API stability. Pre-1.0 with frequent minor releases that change behaviour (image selection strategy, socket usage, config file ownership) means upgrade work lands on you. Prefer it only where you can pin and revisit.
• Windows-primary developer fleets: a windows feature flag exists, which implies it is a supported-but-conditional path rather than a proven one.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, MIT-licensed Composer dependency that standardizes how our PHP repositories run their quality checks — tests, static analysis, code style, dependency audits — so every repo behaves the same way with almost no per-repo maintenance. The pitch is consistency and speed, not features: less duplicated build configuration, faster CI, quicker onboarding, and one policy for quality gates instead of a dozen local variants. Adoption cost is measured in hours, there is no runtime footprint in our products, and removing it is a config change, not a migration. The trade-off we are accepting is maturity risk — it is a pre-1.0 package from a single maintainer with no formal support — which we mitigate by piloting on internal, non-customer-facing repositories first and pinning versions.

To engineering (the substance):

• What it replaces: the copy-pasted Makefiles and per-repo QA config that rot independently. Targets are generated at install time, and feature flags in composer.json let each repo declare what it actually supports.
• What it assumes: Docker on every dev machine and CI runner, plus our existing tool choices (PHPStan, PHPCS, Rector, PHPUnit, Infection). It makes image and version decisions at generation time to cut container startup overhead, and it will take ownership of PHPUnit/Infection/PHPStan/PHPCS/Rector config files — expect migration churn in repos that have hand-tuned those.
• What we own: version pinning, upgrade cadence, and a fallback plan. Because the license is permissive and the code is small, forking or vendoring is a realistic hedge if the maintainer disappears or the direction diverges.
• Proposed rollout: pilot on two to three internal libraries, measure CI wall-clock and onboarding time before and after, then decide on broader adoption with data rather than enthusiasm.

Recommendation: treat it as a low-cost, reversible bet on developer-experience standardization — worth a scoped pilot, not worth a mandate until the pilot proves CI time and onboarding gains and we have confirmed the config-file ownership model is acceptable to the teams involved.