Php Dev Tools Laravel Package

Getting Started

composer require --dev stanislas-poisson/php-dev-tools:^1.1

This is a dev-only toolchain package — it never ships to production, so install it with --dev and keep it out of your runtime dependency graph. First things to check after install:

1. composer.json scripts — the package's whole value proposition is that it wires up the quality tools for you. Run composer run --list (or inspect the scripts block) to see what entry points it registered. Expect something like composer lint, composer analyse, composer insights, composer refactor.
2. Published config files — check vendor/stanislas-poisson/php-dev-tools/ for the shipped defaults (PHP Insights config, PHPStan level, CS ruleset). If the package offers php artisan vendor:publish, run it so you own the config rather than editing inside vendor/.
3. PHP Insights version — 1.1.1 exists specifically to keep the floor at 2.12. Verify with composer show phpinsights/phpinsights; if you were already pulling an older 2.x, this release is the reason your composer update now resolves.

First use case: run the aggregate quality command on a fresh branch before touching anything, to get a baseline. On a legacy Laravel app the first run will be noisy — capture the baseline, then ratchet.

Note the version pin: ^1.1 gets you 1.1.x. If you are on 1.0.x, upgrading is low-risk (see Gotchas).

Implementation Patterns

Baseline-then-ratchet. Run the full suite once, commit the baseline score/config, then fail CI only on regressions. PHP Insights supports --min-quality, --min-complexity, --min-architecture, --min-style — set these just below your current score and bump them as you clean up. This is the single highest-leverage pattern with a package like this.

Split fast vs. slow checks in CI.

• Pre-commit hook (Husky, or a simple .git/hooks/pre-commit): style/lint only — must run in seconds.
• PR pipeline: static analysis + Insights with thresholds.
• Nightly: full Insights with architecture/complexity, which is slower and more likely to be flaky on thresholds.

Pin the toolchain in CI to match local. Because this package constrains transitive versions (phpinsights >=2.12 as of 1.1.1), always run composer install from the committed composer.lock in CI, never composer update. Otherwise a developer's local green run and CI's red run diverge on a tool-version bump rather than a code change.

Exclude generated and vendor-adjacent paths once, centrally. Put exclusions in the published config (e.g. config/insights.php, phpstan.neon) rather than scattering // @phpstan-ignore and --exclude flags across scripts. Typical Laravel exclusions: bootstrap/cache, storage, database/migrations (if you treat them as immutable history), app/Console/Kernel.php in older skeletons.

Use it as a guardrail on new code, not a rewrite mandate. The practical workflow: enable the full ruleset, then add per-directory overrides that are strict for app/ and lenient for legacy folders you have not touched. New PRs get the strict path automatically.

Wrap it in a Composer script alias so the whole team uses one command:

"scripts": {
  "check": ["@lint", "@analyse", "@insights"],
  "check:ci": ["@check -- --format=checkstyle"]
}

Don't let it become the only gate. Pair with tests. Static analysis and Insights catch shape and complexity smells; they will not catch a broken query. The package is a floor, not a ceiling.

Gotchas and Tips

1.1.1 is a dependency-resolution fix, not a behaviour change. It bumps the minimum phpinsights constraint to 2.12. Practical consequences:

• If your lockfile pinned phpinsights below 2.12, a composer update will now move it. Re-run your Insights baseline — scores and rule names can shift between minor versions, so a previously-passing threshold may suddenly fail on unchanged code.
• If you have your own explicit phpinsights requirement in composer.json, keep it compatible (^2.12) or Composer will report a conflict. The PRs in this release (#41, #42) both fixed the same constraint, so if you hit an odd conflict, check you are not on a stale 1.1.0.

2. Dev dependency, but it still affects CI reproducibility. Treat the package version like production code: pin it exactly (1.1.1) in app repos if your pipeline is sensitive to tool upgrades, and let the ^1.1 float only in repos where you review the lockfile diff.

3. Config resolution order is the usual trap. Most of these toolchains ship defaults inside vendor/ and only read a root-level config file if one exists. If you edit vendor/stanislas-poisson/php-dev-tools/config/..., it will vanish on the next composer install. Always publish or copy to the project root first.

4. PHP version mismatch. Quality tools frequently require a newer PHP than your app targets, and static analysis needs to know your target version, not the runtime. Set phpVersion in the PHPStan config explicitly — otherwise you get false positives for syntax your production host cannot run.

5. Baseline files hide real regressions. PHPStan baselines and Insights ignore-lists are convenient but silently absorb new violations if regenerated carelessly. Rule of thumb: never regenerate a baseline in the same PR that changes application logic. Keep baseline regeneration as its own isolated commit so the diff is reviewable.

6. Exit codes. Some of these tools exit non-zero on any finding, including style nits. If your pre-commit hook blocks on the full suite, developers will start using --no-verify, and you lose the gate entirely. Keep hooks to the fast, auto-fixable subset (--fix on style) and push thresholds to CI.

7. Extension points. Most of these bundles let you append rulesets rather than replace them (e.g. adding a framework-specific PHPStan extension, or a custom Insights sniffer). Prefer additive config — forking the shipped ruleset means you stop receiving improvements on package upgrades.

8. Debugging a failing run. Reproduce with the most verbose flag (-v/-vv), check composer show <tool> to confirm which version actually resolved, then diff your config against the vendor default. Nearly every "it works locally, fails in CI" report on packages like this is a lockfile or config-path difference.

9. Scope check before adopting widely. This package is a single-maintainer bundle of otherwise independently maintained tools. That is fine and often convenient — but confirm each underlying tool is on a supported major so you can drop the bundle and call the tools directly if maintenance lags. Nothing in this release changes that trade-off.