Developer Experience Laravel Package

Technical Evaluation

Assessment basis. This evaluation is from package metadata and the Liberu modular-ecosystem conventions, not a source review. Findings marked verify require a 2–4 hour code read before any commitment.

Architecture fit. The value proposition — "foundation diagnostics and reproducible development/quality conventions" — is a developer-tooling layer, not a runtime capability. That is architecturally attractive: if correctly scoped to require-dev, the blast radius of failure is developer laptops and CI, not production traffic. Fit is high only if we are already on Laravel plus a modular monolith pattern congruent with Liberu's module discovery model (service providers, module manifests, per-module config). On a conventional Laravel app the package degrades from "foundation" to "a folder of config files and a few artisan commands we could write ourselves." The critical architectural question is whether diagnostics are passive (report-only commands) or invasive (registered routes, health endpoints, container introspection, boot-time hooks). Invasive diagnostics that register in AppServiceProvider or publish routes are the single biggest reason to reject.

Integration feasibility. MIT license, Composer-installable, no procurement friction. Integration effort is genuinely small — 0.5–2 days to install and observe behaviour on one repo, 3–5 days if we must reconcile its Pint/PHPStan/Rector/CI opinions with existing pipelines. The blocker is not effort, it is evidence: 0 stars, 0 dependents, and a package score of 19.9 mean there is no signal that anyone outside the author has run this against a real codebase. Treat it as an unreviewed internal proposal, not a vetted dependency.

Technical risk.

• Bus factor 1. No dependents means no downstream bug discovery; we would be the first serious adopter and therefore the de facto QA function.
• Release hygiene. A last-release date of 2026-10-27 is future-dated — either a tagging error or a scheduled release. Either way it undermines confidence in versioning discipline, which matters most for a package whose whole job is reproducibility.
• Rot rate. Dev-tooling packages decay faster than any other category: PHPStan levels, Pint presets, GitHub Action versions and Laravel support matrices shift every minor release. An unmaintained conventions module silently becomes wrong conventions.
• Convention lock-in. Opinionated tooling is sticky. Once 15 repos inherit its phpstan.neon and CI workflow, unwinding is a cross-team migration, not a composer remove.
• Supply chain. Verify install scripts, transitive dependencies (does it drag in a second modular framework or the full Liberu core?), and whether it writes to project files destructively versus publishing stubs.
• Accidental production surface. Verify that commands and any diagnostic endpoints are environment-guarded and excluded from the production autoload.

Key questions for the maintainer / code read.

1. Is the package require-dev only, and does it register anything at production boot?
2. What is the declared support matrix for PHP, Laravel, and the analysis toolchain?
3. What exactly are the "diagnostics" — custom artisan commands, a health-check endpoint, a static-analysis wrapper, or environment assertions?
4. Does it publish files non-destructively, or overwrite pint.json / phpstan.neon / .editorconfig?
5. Is there a test suite and CI badge, and does the pipeline actually pass?
6. What is the transitive dependency tree and its licence posture?
7. Is there a documented upgrade and deprecation policy, and who besides the author has committed?
8. Does it assume GitHub Actions specifically, and does it assume Liberu module scaffolding?

TPM recommendation: conditional, vendor-first. Extract the conventions as reference material into our own golden-path template; adopt the package as a dependency only if the diagnostics commands are non-trivial and demonstrably better than a 200-line internal script. Do not make it a required dependency of the platform template on current evidence.

Integration Approach

Stack fit. Best case is Laravel 10–12 on PHP 8.2+, Composer, Pint + Larastan + Rector + Pest, GitHub Actions. Fit degrades sharply against GitLab CI, Psalm, PHPCS, or a non-Laravel PHP service — in those cases roughly half the shipped value is inapplicable and the remainder is copy-paste config. Confirm the CI provider assumption before anything else; it is the cheapest disqualifier to check.

Migration path. Three options, in preference order:

1. Vendor the conventions (recommended). Run the package once in a scratch branch, capture the exact file and CI diff it produces, and commit that diff into an internal dev-conventions repository or a tools/ directory in the monorepo. Zero third-party dependency, full ownership, reversible by design.
2. Pilot as a dependency on one non-critical repo. Acceptable if the diagnostics commands prove genuinely useful and the package is require-dev with no production boot hooks. Pin the exact version; never float a caret constraint on a 0-dependent package.
3. Reject. Appropriate if the diagnostics are thin wrappers around php -l, composer validate, and artisan about — we already have those.

Compatibility. Pin an exact version and run composer why-not across the fleet before rollout. Test the package against both the lowest and highest Laravel/PHP versions we support in a CI matrix, since a diagnostics tool that crashes on the oldest supported version is worse than no tool. Check for duplicate tooling — two Pint configs or two PHPStan baselines in one repo produces confusing, non-deterministic lint results.

Sequencing.

1. Week 1: timeboxed spike (≤1 engineer-day) on a throwaway branch; produce a written diff of every file the package creates or modifies.
2. Week 1: code read against the key questions above; decision memo — vendor, pilot, or reject.
3. Week 2: if pilot, land in one internal repo with a named owner and a documented rollback (composer remove plus config revert, verified).
4. Weeks 3–4: extend to 2–3 repos only if the pilot produced no CI instability and no developer complaints.
5. Week 5: fold the outcome into the platform boilerplate so new services inherit it by default rather than by choice.
6. Day 90: maintenance review — commit activity, issue responsiveness, tool-version currency. Escalate to fork if abandoned.

Operational Impact

Maintenance. Production risk is near zero if correctly dev-scoped. Maintenance cost is entirely in currency: as a dependency, budget 1–2 engineer-days per quarter to track Laravel and analysis-tool releases, plus reaction time whenever an upstream bump breaks it. As vendored configs, cost drops to near zero but ownership is unambiguously ours — which is the better trade at this maturity level. Watch specifically for the moment the package's pinned PHPStan level or Pint preset diverges from current best practice; that is when "reproducible conventions" quietly become "outdated conventions applied uniformly."

Support. No commercial support, no SLA, no discernible user base. Support is self-support, and that only works with a named internal owner — realistically the developer-platform or tooling function, not an application team. Pair the adoption with a short internal handbook so the conventions survive the package; knowledge trapped in a vendored third-party module is a single point of failure.

Scaling. Technically trivial — dev tooling does not participate in request paths, horizontal scaling, or capacity planning. Organisationally it scales only through the golden-path template. Shipped as an opt-in package, adoption will fragment within two quarters and we will end up with three lint configurations; shipped in the boilerplate, it scales for free with every new repository. The ROI is a function of repo count, not developer count — which argues for deferring adoption until we have enough repos for standardisation to pay for itself, or for using it purely to accelerate the initial template build.

Failure modes.

• Fleet-wide CI block: a Laravel or PHP minor upgrade breaks the package's diagnostics, and every repo inheriting it goes red simultaneously. Mitigation: pin, and run the toolchain bump in one repo first.
• False negatives eroding trust: diagnostics that misread a non-standard app config report green on a broken setup, and teams learn to ignore the output. Worse than no diagnostics.
• Destructive publish: config overwrite silently reverts a team's customised static-analysis baseline, dropping coverage without anyone noticing.
• Transitive bloat: pulls in Liberu core or a second modular framework, creating a dependency conflict we only discover during a Laravel major upgrade.
• Accidental production exposure: diagnostic routes or commands reachable in production, leaking environment and configuration detail.
• Silent abandonment: package stops receiving updates, lint and analysis gaps accumulate for months before anyone checks.

Ramp-up. Low for application developers — if the package is genuinely just conventions, it is invisible day to day, and the reproducibility benefit (identical setup across machines, faster new-hire onboarding, fewer "works on my machine" tickets) is the strongest argument in its favour. Medium for the platform engineer who owns it: 1–2 days to internalise the Liberu module conventions, the CI expectations, and the publish semantics, plus ongoing currency work. Net: cheap to try, cheap to reverse, expensive to standardise prematurely — which is exactly the profile that justifies a one-week spike and does not yet justify a platform commitment.