Phpmd Config Laravel Package

Technical Evaluation

Architecture fit. This is not a Laravel package in any operational sense: no service provider, no autoloaded classes, no framework coupling, no runtime footprint. It is a PHPMD ruleset distribution — an XML artifact defining complexity, design, unused-code, and naming thresholds — published from an internal IRSTEA GitLab group. It never enters the application dependency graph, never affects composer install --no-dev, and places no constraint on PHP or Laravel versions at runtime. The correct mental model for a TPM is a coding-standard asset that informs a quality-gate policy decision, not a library to evaluate for adoption.

Integration feasibility. Mechanically trivial, procedurally awkward. The package is not on Packagist and lives on an institute-controlled GitLab host, so any composer require path requires a VCS repositories entry plus deploy keys or an access token — meaning every developer workstation and CI runner inherits a live credential dependency on an external research organisation's infrastructure. Because the payload is a single XML file, the integration collapses naturally to a file copy: vendor the ruleset into tools/phpmd/phpmd.xml and point vendor/bin/phpmd at it. That is the recommended shape. Note that running it presupposes PHPMD itself, which is a mature but comparatively declining tool next to PHPStan/Larastan, Pint, and Rector — adopting a ruleset for a tool the team does not otherwise run is new toolchain surface, not a config swap.

Technical risk. Low at runtime, medium-high on supply chain and process:

Key questions.

1. What rules and thresholds does the XML actually contain, and is it self-contained or does it <rule ref> into external rulesets (hidden transitive config)?
2. Which PHPMD major/minor is it validated against — is there a composer.json constraint?
3. Are there release tags, or only a default branch? Can we pin to a commit SHA?
4. What is the license and redistribution posture? IRSTEA is a public research body; confirm we may vendor and modify, or treat it as read-only reference material.
5. Does the naming ruleset overlap or conflict with PSR-12/Pint, creating duplicate noise across two analyzers?
6. Can we stand up an internal mirror (Satis, private Packagist, or a vendored file) to sever the external dependency on day one?

Integration Approach

Stack fit. Laravel/PHP 8.x stacks absorb this cleanly as a dev-only quality gate, wired as a Composer script:

"scripts": {
  "analyse:pmd": "phpmd app,src text tools/phpmd/phpmd.xml --exclude vendor,tests/fixtures"
}

No service provider, no publish step, no autoload impact. It complements PHPStan/Larastan and Pint rather than replacing them — PHPMD's niche is complexity and design smells (cyclomatic complexity, NPath, coupling, unused code), which PHPStan covers poorly. For Laravel-specific correctness and anti-patterns, Larastan and Enlightn remain the backbone; PHPMD is the third, optional gate.

Migration path. Additive, never a replacement:

• Team does not run PHPMD today: adding both a new tool and a new ruleset is a double change. Justify PHPMD on its own merits before importing someone else's thresholds.
• Team already runs PHPMD: diff imported rules against the local phpmd.xml, adopt rule-by-rule, retire the local file only at parity.
• Preferred end state: fork the XML into our repo under tools/phpmd/ with a header crediting the upstream source and pinned commit. This is roughly a 30-minute task and eliminates auth, availability, and versioning risk simultaneously. Keep upstream as a reference for future rule updates only.

Compatibility. Validate against PHP 8.1–8.3 with PHPMD ≥ 2.15 (required for enums, attributes, readonly, match, first-class callables, and intersection types). Confirm the naming rules do not duplicate PHP_CodeSniffer/Pint output; disable PHPMD's style-adjacent rules if they do, keeping complexity and design only.

Sequencing.

1. Request read access; capture the license text and the exact commit SHA.
2. Inventory the XML — rules, thresholds, PHPMD version target, external refs.
3. Dry run against the largest repo with relaxed --minimumpriority and no CI gate; measure violation volume and review the top 50 findings for signal vs. noise.
4. Set policy: fix-forward, baseline file, or targeted suppression.
5. Mirror the ruleset into our SCM; remove the external VCS repository entry.
6. Run a non-blocking CI job for 2–4 weeks; tune thresholds.
7. Flip to blocking on new/changed files only (--exclude legacy paths); document ownership and the update procedure.

Operational Impact

Maintenance. Runtime maintenance is effectively nil — a static file cannot page anyone. The real cost is stewardship: a named owner must track PHPMD releases and PHP upgrades, because un-owned config rots quietly. Within 18 months an unattended ruleset either stops parsing on a PHP bump or becomes so noisy that developers suppress everything. Assign an owner in CODEOWNERS and schedule a quarterly review.

Support. Assume zero upstream support. Zero stars, zero dependents, and a private GitLab host imply no issue triage, no SLA, and possibly no active maintainer. The escalation path is entirely internal: fork, patch, document. Do not represent this to stakeholders as a supported third-party dependency.

Scaling. Computationally trivial — seconds to low minutes for a few thousand files, scaling linearly with lines of code, not with traffic or tenants. For monorepos, shard PHPMD across packages in a CI matrix and cache the binary. The genuine constraint is social: onboarding N teams onto a sudden blocking gate produces a wave of @SuppressWarnings annotations that permanently erodes signal. Stage enforcement by directory and by rule class.

Failure modes.

Ramp-up. Low for engineers — under a day to run locally and interpret output; PHPMD messages are self-describing. The effort sits entirely in calibration and change management: choosing thresholds the team will accept, writing the baseline, and explaining why complexity gates exist. Budget 2–3 days of a senior engineer's time for trial, tuning, and CI wiring, plus ongoing quarterly review.

TPM bottom line. Leverage this as prior art, not a dependency. The decision it informs — do we gate merges on complexity metrics, and at what threshold — is a policy decision we should own internally. Adopt the artifact by copying it in, credit the source, verify the license, and keep the gate advisory until thresholds are proven. Cost of doing so: near zero. Cost of depending on it as-is: a silently broken quality gate nobody notices for months.