Dev Pack Laravel Package

Getting Started

irstea/dev-pack is a Composer meta-package — it contains no application code, only a require block pinning the dev tooling IRSTEA standardises on (PHPUnit/Pest, PHPStan/Larastan, php-cs-fixer, PHP_CodeSniffer, Rector, PHPMD — whatever the manifest lists). You don't call it; you inherit a toolchain from it. Everything below assumes that mental model.

Step 1 — Get access working before anything else. The repo lives on gitlab.irstea.fr, not Packagist. Without auth, every composer install fails with Could not find package irstea/dev-pack, which misreads as "package doesn't exist" rather than "you're not authenticated."

# Local workstation
composer config --global gitlab-token.gitlab.irstea.fr <personal-access-token>

# CI — prefer a read-only deploy token via env
export COMPOSER_AUTH='{"gitlab-token":{"gitlab.irstea.fr":"<deploy-token>"}}'

If you'd rather not edit global auth, add a vcs entry with an inline URL:

"repositories": [
  { "type": "vcs", "url": "https://gitlab.irstea.fr/pole-is/tools/php-dev-pack.git" }
]

Step 2 — Install and read the manifest first. The composer.json is the documentation; there is no changelog that matters for a meta-package.

composer require --dev irstea/dev-pack
cat vendor/irstea/dev-pack/composer.json
composer show --tree irstea/dev-pack
ls vendor/bin        # what actually landed

Step 3 — Check for shipped config stubs. Look inside vendor/irstea/dev-pack/ for phpstan.neon, phpunit.xml.dist, .php-cs-fixer.dist.php, rector.php, or a service provider. If it declares publishes:

php artisan vendor:publish --provider="Irstea\\DevPack\\DevPackServiceProvider"

Step 4 — First real use case. Delete the individual require-dev entries the pack supersedes (PHPUnit, PHPStan, php-cs-fixer, etc.), then composer update --with-dependencies irstea/dev-pack on a branch and read the lock diff before merging. The interesting lines are tool majors and anything arriving transitively you didn't expect. Then run the full gate — vendor/bin/phpunit, vendor/bin/phpstan analyse, vendor/bin/php-cs-fixer fix --dry-run --diff — and a composer install --no-dev on a throwaway clone to confirm nothing leaked into the runtime set.

Implementation Patterns

The one-line require-dev (the whole point). Replace N entries with:

"require-dev": {
    "irstea/dev-pack": "dev-main#<commit-sha>"
}

Pin to a tag or commit SHA, never bare dev-main. A meta-package on dev-main means every composer update silently mutates your quality gate for the whole team. A SHA also survives force-pushes and ref deletion.

Pilot → CI template → fleet. Correct rollout order:

1. Inventory require-dev across repos — union and intersection. If the pack isn't a superset, quantify conflicts before committing.
2. Sandbox: throwaway composer.json with only the pack, fresh install, read the lock.
3. One low-risk repo as pilot, lock diff reviewed.
4. Bake into the shared CI image/template so new repos inherit it rather than via tribal knowledge.

Scripts as the team interface. Meta-packages work best when consumers invoke a stable entry point instead of remembering tool flags. Add to composer.json:

"scripts": {
    "lint":   "php-cs-fixer fix --dry-run --diff",
    "lint:fix":"php-cs-fixer fix",
    "stan":   "phpstan analyse --memory-limit=1G",
    "test":   "phpunit",
    "check":  ["@lint", "@stan", "@test"]
}

Now composer check is the gate locally and composer check in CI is the same gate. If the pack ships its own scripts, they'll be merged — your project's definitions win on name collision.

Laravel integration. If the pack includes Larastan and ships a phpstan.neon, extend rather than copy:

includes:
    - vendor/irstea/dev-pack/phpstan.neon
    - phpstan-baseline.neon
parameters:
    level: 6
    paths: [app, src]

Same shape for .php-cs-fixer.dist.php (use ->setRules() to layer overrides on top of an imported ruleset) and rector.php ($rectorConfig merged from the pack's config). Override at the project level; never edit files in vendor/.

Shared config, per-project overrides. The pack should own defaults, the project should own exclusions and level. Typical override set: PHPStan baseline path, php-cs-fixer finder paths (exclude storage/, generated files), PHPUnit <env> / coverage thresholds, Rector PHP version target.

Testing harness parity. If the pack pins PHPUnit, don't let anyone add a conflicting Pest or PHPUnit version to require-dev in a downstream package — Composer will resolve or fail noisily, and failing loudly on a version skew is exactly what you want. If you want Pest and the pack only ships PHPUnit, add Pest to the project and let Composer's resolver negotiate — but verify in the lock diff which PHPUnit version actually won.

CI with the deploy token. Keep the credential scoped and out of developer control:

# .gitlab-ci.yml
variables:
  COMPOSER_AUTH: '{"gitlab-token":{"gitlab.irstea.fr":"$GITLAB_DEPLOY_TOKEN"}}'
cache:
  key: { files: [composer.lock] }
  paths: [vendor/, ~/.composer/cache/]

Cache vendor/ and the Composer cache directory — resolving against a private VCS is slower than Packagist, and the cache is what keeps CI at tolerable times.

Fork path you already know how to take. Before you need it:

"repositories": [
  { "type": "vcs", "url": "https://gitlab.irstea.fr/your-team/dev-pack-fork.git" }
]

A two-line fork to bump one constraint upstream is the standard escape valve. Document the fork URL and the reason in the project README.

Publishing when the pack provides stubs. php artisan vendor:publish --provider=... copies phpstan.neon, phpunit.xml.dist, etc. into the project root where the team can edit them. Publish once, commit the result, freeze the pack's copies in vendor/.

Gotchas and Tips

require-dev only. Always. A meta-package pulled into production require bloats the artifact, drags test and static-analysis tooling into the runtime image, and can fail on --no-dev builds. Verify with composer install --no-dev before merging and composer why irstea/dev-pack if you suspect it's been added to the wrong block.

allow-plugins blocks silent surprises. If the pack pulls a Composer plugin, Composer 2.2+ refuses it unless explicitly allowed. Decide deliberately which side you're on:

"config": { "allow-plugins": { "vendor/plugin": true } }

Similarly check whether the pack declares scripts — a post-install-cmd running against your project can be a nasty surprise on first install in CI.

Credential expiry is the #1 fleet failure. A rotated GitLab token or stale SSH key breaks every consumer at once, including hotfix builds. Mitigations: use a long-lived read-only deploy token as a CI secret; monitor auth failures as a distinct alert class, separate from test failures — otherwise a token rotation looks like "all our tests broke simultaneously" and you debug the wrong thing for an hour.

Pinning risk cuts both ways. If the pack pins phpunit/phpunit: ^9 and your app is on ^10, you're blocked and the only remedy is upstream change or a local fork. Before adopting, composer why-not phpunit/phpunit "^10" in the sandbox — that tells you exactly how much room you have.

Lock file is the release note. Never merge a composer.lock diff you haven't read. The interesting deltas are tool majors (a PHPStan 1 → 2 bump will surface dozens of new errors) and anything arriving transitively. A composer update irstea/dev-pack --with-dependencies on a branch, diff reviewed, is the safe way to bump.

Ref deletion / force-push. If you pinned dev-main or a mutable tag, your lock file will eventually fail to resolve. Pinning to #<sha> removes this failure mode entirely. Do it from day one.

Runtime drift. The pack bumps its PHP floor; consumers on older runtimes fail at resolve time with a confusing constraint conflict that never mentions irstea/dev-pack in the top line. composer why-not php ^7.4 identifies the culprit immediately. Keep the pack's PHP/Laravel constraint in the CI matrix and in onboarding docs.

Static-analysis baseline before you trust the gate. Turning PHPStan L6 on for a legacy repo produces hundreds of errors. Generate a baseline (--generate-baseline) after the pilot install, commit it, and check the pack's bump cadence — every major PHPStan bump invalidates baselines partially. Treat baseline regeneration as a routine upgrade task, not an emergency.

Debug the resolution, not the code. Meta-package bugs are almost always Composer resolution: composer show --tree irstea/dev-pack, composer why-not <package> <constraint>, COMPOSER_DEBUG=1 composer require --dev .... There is no runtime code to step through.

Extension points, in order of preference. 1) Project-level config that imports the pack's stub and overrides — cheapest, survives pack bumps. 2) Add individual tools to require-dev alongside the pack (Composer negotiates). 3) Fork the pack — last resort, but know the URL.

Bus factor. Single internal repo, French-only description, no stated owner. Assign a named owner and a calendar reminder for a quarterly bump, or assume the pack will be six to twelve months stale by default. If nobody owns it, the honest alternative is copying its composer.json constraint set into your own template repository — same standardisation benefit, no dependency on an unmaintained private artifact.