Laravel Utils Laravel Package

Getting Started

mll-lab/laravel-utils is a grab-bag of opinionated Laravel helpers plus — as of v10.14.0 — a set of PHPStan rules. The first thing to do after composer require mll-lab/laravel-utils is read the README and the package src/ tree, then check whether the parts you need are runtime helpers (require normally) or static-analysis-only rules (require with --dev). Mixing the two is the most common setup mistake: if the app only consumes the PHPStan rules, keeping the package out of production autoload keeps your deploy image lean.

The fastest first use case for the new release is the PHPStan rules. Install phpstan/phpstan (and larastan/larastan if you're not already running it), point phpstan.neon at your app/ directory, and include or register the package's rules. Then run:

vendor/bin/phpstan analyse --level=5 app/

v10.14.0 adds a rule that forbids string-keyed Collection operations — i.e. using Collection as an associative map (->get('key'), ->put('key', …), ->has('key'), ['key'] access). Expect a batch of hits on the first run; that list is your adoption backlog. Confirm the exact method coverage by reading the rule class in vendor/mll-lab/laravel-utils/ before you plan the refactor.

Where to look first: the README for registration syntax, the CHANGELOG/release notes for rule additions, and the rule class itself for the precise set of flagged methods.

Implementation Patterns

Register the rules once, centrally. Either include the package's neon file (if one ships) or add each rule class under rules: in phpstan.neon. Prefer the include — new rules in future minors then arrive automatically, which is what you want from a linting package.

includes:
    - vendor/larastan/larastan/extension.neon
    - vendor/mll-lab/laravel-utils/phpstan.neon   # verify filename in vendor/

Adopt via baseline, not by switching off. Generate phpstan-baseline.neon on day one, commit it, and shrink it deliberately:

vendor/bin/phpstan analyse --generate-baseline

Every PR that touches a baselined file is a chance to delete the corresponding entry. Never add the new rule to a global ignoreErrors block — that silently disables future rules too.

Refactor pattern: move string-keyed maps out of collections. The rule is steering you toward typed structures. Replace map-shaped collections with one of:

• a plain array typed as array<string, Foo> where the key is genuinely dynamic;
• a DTO / value object with named properties when the keys are a fixed schema;
• ->keyBy('id') only at the boundary, immediately followed by ->all() back to an array.

Keep Collection for lists, and use Arr::get() / data_get() when you need defensive string access into arrays.

Scope ignores per-path, not per-project. For legacy modules you can't touch yet:

ignoreErrors:
    -
        message: '#string-keyed#'
        path: app/Legacy/*

Once the package exposes stable error identifiers, switch to identifier: matching — it survives message rewording, path: matching on regex does not.

CI wiring. Run PHPStan as its own job with dev dependencies installed (composer install without --no-dev), and cache vendor/ + PHPStan's result cache keyed on composer.lock + phpstan.neon. Fail the build on new errors; that's the only thing that keeps a baseline from growing.

Pair it with Larastan. Without Larastan, PHPStan sees untyped Collection in most Laravel code and the new rule fires imprecisely. With Larastan, return types from Eloquent relations and collect() calls are resolved and the rule's signal-to-noise improves markedly.

Gotchas and Tips

• Dev-only autoload. If you require the package with --dev, never reference its classes from app/ or config/. Production composer install --no-dev will not have them, and you'll only find out at runtime.
• PHPStan internals move fast. These rules are built against PHPStan's Rule API. When you bump phpstan/phpstan, re-run the full analysis before merging — a major PHPStan bump (2.x) can change node types the rule inspects and cause silent no-ops rather than loud failures.
• Untyped arrays trigger broad matches. array<mixed> from unannotated helpers makes it ambiguous whether a key is a string. Add generics (@return array<string, int>) or the rule will nag on code that's actually fine, and you'll be tempted to disable it.
• Exclude generated and vendor code. excludePaths for bootstrap/cache, migration stubs, IDE helpers, and anything under _ide_helper*.php. Otherwise the rule fires on code you cannot change.
• reportUnmatchedIgnoredErrors: false hides drift. Keep it at the default true in CI so stale ignores surface as failures instead of accumulating.
• Baseline regeneration is destructive. --generate-baseline overwrites. It does not merge. Commit the diff and review it in the PR or you will quietly un-suppress hundreds of errors.
• Debugging a single report: vendor/bin/phpstan analyse --debug app/Path/File.php isolates one file and prints the reflection it actually has — usually reveals a wrong @return annotation rather than a bug in the rule.
• Bump risk is low for 10.14.0. This is a minor feature addition with no deprecations or breaking changes listed. Read the rule's composer.json constraint on phpstan/phpstan before bumping the analyser itself in the same PR; land them separately so a bad interaction is easy to bisect.
• Extension point worth requesting: an error identifier for the new rule. File an issue upstream if it isn't present — it makes targeted suppression far more maintainable than message regexes.