Getting Started

This package is a PHPStan configuration preset, not a runtime library. It ships .neon files (typically phpstan.neon, extension.neon, maybe a baseline.neon) that you include: from your own project config. There is no service provider, no facade, nothing to register in config/app.php. Your whole job is to compose its config into yours and keep it pinned.

Minimal steps:

Register the private repository. It lives on gitlab.irstea.fr, so Packagist will never resolve it:

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

Install as a dev dependency, alongside PHPStan and (for Laravel) Larastan:

composer require --dev irstea/phpstan-config phpstan/phpstan
composer require --dev larastan/larastan   # if you're on Laravel

Read the package before writing a line of config. The include filename, exported parameters (level, paths, ignoreErrors, rule registrations) and any PHPStan version constraint are the contract you code against:
```
ls vendor/irstea/phpstan-config
cat vendor/irstea/phpstan-config/*.neon
cat vendor/irstea/phpstan-config/composer.json   # check the phpstan/phpstan constraint
```

First use case — wire it up and run once against a small slice, not the whole app:

# phpstan.neon
includes:
    - vendor/irstea/phpstan-config/phpstan.neon

vendor/bin/phpstan analyse app/Models --memory-limit=1G -v

That single run tells you the effective level and how noisy the preset is. From there you decide: adopt, override, or fork.

Implementation Patterns

Preset as a base, project as the override layer. Never edit files in vendor/. Treat the package as the bottom of a stack and put your opinions on top of your own phpstan.neon:

includes:
    - vendor/irstea/phpstan-config/phpstan.neon

parameters:
    level: 6                      # override the preset's level
    paths:
        - app
        - src
    excludePaths:
        - app/Console/Kernel.php
    ignoreErrors:
        - '#Call to an undefined method Illuminate\\#'

Verify what actually survived the merge. NEON include merging is not a simple "append" — later definitions can replace earlier ones, and list parameters (ignoreErrors, excludePaths) don't always behave the way you'd expect. Dump the resolved config and diff it against your intent:

vendor/bin/phpstan dump-parameters > /tmp/effective.neon

This one habit prevents hours of "my ignoreErrors isn't matching."

Stack Larastan on top for Laravel work. The IRSTEA preset is a generic PHP preset. Laravel projects need larastan/larastan for facade/property/magic-method awareness. Include both and confirm ordering:

includes:
    - vendor/irstea/phpstan-config/phpstan.neon
    - vendor/larastan/larastan/extension.neon

Larastan registers custom rules and stubFiles. If the preset also touches those keys, the last include wins — keep Larastan last and re-check dump-parameters.

Baseline for legacy code, not for new code. On an existing codebase at a preset level of 6+, don't fight the noise by widening ignoreErrors. Generate a baseline:

vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon

includes:
    - vendor/irstea/phpstan-config/phpstan.neon
    - phpstan-baseline.neon

Then make the baseline a ratchet: it can only shrink. Commit it, review additions in code review, and reject PRs that grow it for new files.

Per-directory levels for incremental adoption. You don't have to adopt the preset's level everywhere at once. Set a conservative global level and tighten the newest code first:

parameters:
    level: 5
    paths:
        - app
        - domain
    ignoreErrors:
        - identifier: missingType.iterableValue

New domain/ code can be held to a stricter pass via a dedicated CI job or a --level override on that path.

CI integration that developers actually read:

- run: vendor/bin/phpstan analyse --no-progress --memory-limit=1G --error-format=github

--error-format=github renders inline annotations on PRs; --error-format=gitlab uses the Code Quality report format if you're on GitLab. Pair with a cache directory:

parameters:
    tmpDir: var/phpstan-cache

Composer script so nobody memorizes flags:

"scripts": {
    "analyse": "phpstan analyse --memory-limit=1G",
    "analyse:baseline": "phpstan analyse --generate-baseline"
}

Multi-repo: fork once, consume everywhere. Given zero stars, zero dependents, and a private GitLab host, the day-to-day pattern that ages well is to fork the .neon into a first-party acme/phpstan-config repo, add your own ignores and levels, tag it, and consume that by version:

"repositories": [
    { "type": "vcs", "url": "[email protected]:platform/phpstan-config.git" }
]

"require-dev": {
    "acme/phpstan-config": "^1.0"
}

For a monorepo, use a path repository pointing at tools/phpstan-config so changes test locally before you tag.

Pin PHPStan itself. The preset's composer.json will constrain phpstan/phpstan. Pin your own install to the same major (^1.12 or ^2.0) and bump deliberately — PHPStan majors restructure parameter names and error identifiers, and a preset written for 1.x will silently drop rules under 2.x.

Gotchas and Tips

Private-host resolution is the real gate, not the config. CI runners need either SSH keys, a COMPOSER_AUTH token, or a mirrored internal registry. Network policy changes, auth rotation, or a DNS move on gitlab.irstea.fr will break builds for reasons unrelated to your code. Vendor a pinned copy or fork it if any of that is uncertain.

The package has no maintainer signal. Zero stars, zero dependents, self-hosted GitLab. Assume no upstream support and no changelog. composer.lock plus a tag pin is your only stability guarantee; a fork is the stronger move.

Includes are resolved relative to the including file, not the CWD. vendor/irstea/phpstan-config/phpstan.neon is the safe form. Bare filenames in the preset that work when running from the package root can break when included from your project.

If the preset ships a baseline, do not ship it into your project. A baseline generated against IRSTEA's codebase will suppress your real errors or drown you in irrelevant ones. Generate your own, and diff the preset's ignoreErrors messages before adopting any of them — they're often tuned to framework idioms you don't use.

PHPStan 1.x → 2.x renamed things. excludePaths changed shape, checkMissingIterableValueType was removed, and rule config moved from message-regex to error identifiers. A preset pinned to 1.x applied to a 2.x install will either error out or quietly under-enforce. Check the constraint in composer.json before adopting any of its opinions.

NEON array merge semantics will bite you. If your ignoreErrors additions seem to be ignored, or excludePaths mysteriously overrides the preset's entries, that's the merge. Confirm with dump-parameters, and prefer narrowing with identifiers over broad message regexes.

Don't guess the exported parameter names. Read the shipped .neon. A preset that defines paths: [src] will analyze src even if your project uses app/. Overriding paths is almost always the first edit every consumer makes.

No Laravel awareness out of the box. This is a config preset, not Larastan. Without larastan/larastan you'll get floods of false positives on facades, Eloquent magic, and container bindings. If a preset's ignoreErrors list looks oddly heavy on Illuminate\* messages, that's the smell — the author was working around missing framework awareness rather than fixing it.

Debugging a failing run:

vendor/bin/phpstan analyse -vvv --debug app/Foo.php   # rule-by-rule trace
vendor/bin/phpstan dump-parameters                    # resolved config
vendor/bin/phpstan analyse --error-format=raw         # greppable output

--debug disables parallel workers and prints each rule as it runs — the fastest way to find which rule is tripping on which file.

Cache invalidation. Bumping the preset or PHPStan version should invalidate tmpDir. If results look stale, delete var/phpstan-cache before chasing ghosts.

Extension points, in order of preference:

Override in your own phpstan.neon — cheapest, zero new dependencies.
Fork into a first-party preset package — version it, review rule changes like code, own the governance.
Vendor a pinned copy into tools/phpstan-config/ with a path repository — good for monorepos and air-gapped CI.
Depend directly on irstea/phpstan-config — only if you're already inside the originating org and accept the maintenance vacuum.

Rule changes are a shared contract. A preset silently tightening a level turns every downstream CI red at once; loosening one silently lets regressions through. If you fork, add a CHANGELOG and treat level bumps as minor-version events that teams opt into.

Phpstan Config Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips