Next Ide Helper Laravel Package

Getting Started

soyhuce/next-ide-helper is a dev-only package that generates IDE metadata (_ide_helper.php and model docblocks) so your editor understands Eloquent magic — properties, relations, scopes, facades and macros.

composer require --dev soyhuce/next-ide-helper
php artisan vendor:publish --tag="next-ide-helper-config"

First run:

php artisan next-ide-helper:models   # model property/relation docblocks
php artisan next-ide-helper:meta     # facades, macros, container bindings

Start by looking at config/next-ide-helper.php — that is where the real day-to-day surface lives (model directories to scan, excluded models, output paths, cast handling). Then open one generated docblock next to a model and confirm your editor resolves $user->email and $user->posts without a @property you wrote by hand.

The first use case worth wiring up is a single "regenerate after schema change" habit: run the two commands immediately after adding a migration or a relation, and check that the new attribute appears in the model's docblock before you start typing against it.

Implementation Patterns

Regenerate as part of the dev loop, not by hand. Add both commands to a Composer script or an Artisan alias so the helper files can never lag behind the migrations:

"scripts": {
  "ide-helper": [
    "@php artisan next-ide-helper:models --no-interaction",
    "@php artisan next-ide-helper:meta --no-interaction"
  ]
}

Hook it to post-autoload-dump if you want it on every composer install, or to a pre-commit step if you prefer committing the generated files.

Commit the output, or don't — but pick one. Committing _ide_helper.php gives every developer the same experience and makes regeneration diffs reviewable in PRs. Gitignoring it avoids merge conflicts but requires each developer to run the script. Mixed setups are the common failure mode.

Lean on generics for relations. The docblocks are most valuable when they describe collections precisely (Collection<int, Post> rather than plain Collection). That precision is what makes Larastan/PHPStan pass on $user->posts->pluck('title'), so treat the generated file as the input to static analysis, not just to autocomplete.

Pair with PHPStan/Larastan. Run the generator in CI before the analysis step so the analyser sees the same metadata your IDE does. This catches the case where a model was changed but nobody regenerated locally.

Custom casts. Register project-specific cast classes in the config so the generator can map them to a PHP type. For casts the package can't infer (anything requiring constructor arguments or a runtime value), fall back to an explicit @property on the model — an explicit annotation wins and is stable across regenerations.

Per-model overrides. Use the config's include/exclude lists to skip models from third-party packages, and keep hand-written @property/@method blocks in the model itself rather than in the generated file, so regeneration never destroys them.

Gotchas and Tips

• Stale output is worse than no output. A docblock that lists a column you dropped last week will happily autocomplete code that fails at runtime. Regenerate after every migration, and treat a generated-file diff as part of the migration PR.
• AsCollection casts (fixed in 2.2.3). Earlier releases mishandled Laravel's AsCollection cast, so models using it could end up with wrong or missing collection types in the generated docblocks. If you use AsCollection, upgrade to >=2.2.3. Note the fix corrects the cast handling, not element-type inference: a bare AsCollection cast still can't tell the generator what's inside, so you'll get Collection<int, mixed>. Add an explicit @property Collection<int, Post> $posts when you need the precise generic.
• Parameterised casts. Casts declared with arguments (AsCollection::class.':...', AsEnumCollection::class.':App\Enums\Status') behave differently from bare ones. If the generated type looks vague, check whether the cast string is being parsed or falling through to a generic.
• Editor caches lie. After regenerating, invalidate the IDE index (PhpStorm: Invalidate Caches, VS Code/Intelephense: restart the language server). "The fix didn't work" is usually a cached symbol table.
• Clear Laravel's caches too (php artisan clear-compiled, optimize:clear) if the generator reads bootstrapped providers or config.
• CI drift check. Run the generator in a job and follow it with git diff --exit-code on the helper files. This is the cheapest way to enforce that nobody merges a schema change without regenerating.
• Never ship it. Keep it in require-dev and ensure the config/commands aren't exposed in production; the generated files are metadata only and add nothing at runtime.