Composer Require Checker Shim Laravel Package

Technical Evaluation

What this actually is. irstea/composer-require-checker-shim is not an application library — it is a packaging artifact whose sole job is to make maglnet/composer-require-checker installable and pinned inside IRSTEA's environment. Composer Require Checker (CRC) is a static analysis CLI that verifies every symbol your code references (classes, functions, constants) is backed by an explicit require in composer.json, catching "soft dependencies" introduced by transitive packages. The shim exists to control how that tool is delivered, not what it does.

Architecture fit. Excellent, because the footprint is zero. It is a require-dev dependency that produces a console binary and never ships to production. It imposes no runtime coupling, no autoloading contract, no framework assumptions. Any Laravel codebase — Lumen through Laravel 11, PHP 7.4 through 8.3 — can adopt or drop it without touching application code. The architectural decision is therefore not "should this be in our app" but "should this be in our CI pipeline."

Integration feasibility. Straightforward mechanically, with one non-obvious dependency: Composer must be able to reach the private GitLab host. That means a repositories entry (VCS type or a Satis/Private Packagist mirror) plus credentials available to every CI runner. If the shim re-declares or replaces the upstream package name, Composer resolution behaves differently than a normal wrapper and must be verified explicitly before rollout — this is the single highest-uncertainty item in the package and cannot be answered from the metadata provided.

Technical risk. Low-to-moderate, and mostly supply-chain rather than engineering:

• Provenance opacity. Zero stars, zero dependents, empty metadata. For an internal artifact this is expected and not itself a red flag, but it means there is no community validation, no public changelog, and no external signal on health.
• Drift. Shims rot. Upstream CRC adds PHP version support and rule changes; a shim that vendors or pins will silently lag, eventually producing false positives on modern syntax or failing on a new PHP minor.
• Shadowing hazard. If the shim occupies the upstream package name, a future upstream security fix or bugfix will not reach consumers without a manual pull. This is the failure mode most likely to bite silently.
• Licensing. Upstream is MIT; a shim that repackages it should carry the same license and attribution. Worth a five-minute check rather than an assumption.
• Bus factor. No visible maintainer, no dependents, no issue tracker reference. One departing engineer could leave the shim unowned.

Key questions for the owning team.

1. Is this a mirror (byte-identical passthrough), a pinned fork, or a patch carrier? What patches, if any, diverge from upstream?
2. Does it replace/provide maglnet/composer-require-checker, or is it a separately-named wrapper?
3. Who owns it, and what is the documented process for pulling upstream releases?
4. Which CRC version is currently mirrored, and what is the refresh cadence?
5. Is it reachable from CI without personal credentials (deploy token vs. shared bot account)?
6. Does it declare a PHP constraint, and does that constraint block our current Laravel/PHP matrix?

Integration Approach

Stack fit. Adopt as require-dev in each Laravel repository, invoked as a CI job alongside PHPStan/Larastan, Pint, and PHPUnit. It is complementary, not overlapping: PHPStan reasons about types and correctness, CRC reasons about dependency declarations. The gap it closes is real in Laravel shops specifically — facades, helpers, and illuminate/* split packages make it easy to use a symbol that only resolves because some other package pulled it in, and that breakage surfaces as a confusing runtime error during a routine composer update.

Migration path. Do not attempt a fleet-wide rollout.

1. Confirm shim semantics against upstream — diff the composer.json, confirm what, if anything, is patched.
2. Pilot on one mid-sized Laravel repo with the most active dependency churn. Install, run locally, capture the violation count.
3. Baseline, then ratchet. CRC supports an allowlist/ignore file. Seed it with current violations so the job is green on day one, then require the list to shrink rather than grow. A pipeline that fails on 400 pre-existing violations on day one gets disabled within a week.
4. Promote to shared CI template (a GitLab include: of a common job), so adoption is a two-line change per repo.
5. Expand to services with the highest dependency surface first.

Compatibility. CRC historically pins symfony/console and webmozart/assert-class dependencies. In a shim scenario these pins may be older than what the host project otherwise resolves, which can produce a composer update conflict rather than a clean install. Verify install on the pilot repo with an unmodified lockfile before assuming compatibility; do not infer it from the shim's declared constraints alone. Also confirm Composer 2 compatibility and any allow-plugins implications if the shim ships as a plugin rather than a bare binary.

Sequencing. Shim verification → single-repo pilot → baseline allowlist → shared CI template → fleet rollout → scheduled upstream re-sync review (quarterly is adequate). Keep the upstream direct dependency as a documented fallback so any repo can be un-blocked in minutes if the shim fails.

Operational Impact

Maintenance. Near-zero engineering maintenance — a static binary run in CI has no runtime surface, no migrations, no on-call exposure. The real maintenance is governance: tracking upstream CRC releases and refreshing the shim. Estimate one to two hours per quarter, contingent on the shim being a clean mirror. If it carries local patches, cost rises with each upstream release and the patches must be rebased.

Support. There is no vendor. Support is whoever owns the internal GitLab group. Publish a one-page runbook: how to bypass the check (and when that is legitimate), how to add an allowlist entry and who approves it, and the escalation contact. Without this, the first false positive becomes a Slack thread and an ad-hoc --no-verify.

Scaling. Effectively free. Cost scales with repository count and CI minutes, not with traffic. Typical runtimes are seconds to a low single-digit minute per repo; parallelizes trivially. No shared state, no service to keep warm. The only scaling concern is credential distribution as the repo count grows — solve once with a group-level CI variable or deploy token, not per-project.

Failure modes and mitigations.

Ramp-up. Low for application developers: the output is a list of "you used X but did not require it," and the fix is a one-line composer.json edit. Budget an hour of documentation and a short team walkthrough on why the check exists — teams that understand the soft-dependency failure mode adopt it; teams that don't will treat it as noise. Ramp-up for the platform team owning the shim is moderate and is dominated by the upstream-tracking process, not by the tool itself.

Bottom line. Correctly scoped, low-blast-radius developer tooling with a genuine payoff for Laravel monorepos and split-package dependency graphs. The technology is not the risk; the ownership and freshness of an unmaintained-looking internal shim is. Proceed on a pilot, but make the shim's provenance, patch status, and refresh cadence explicit preconditions rather than assumptions.