Laravel Actions Ide Helper Laravel Package

Getting Started

Preconditions. This package is only worth installing if lorisleiva/laravel-actions (v2.3+) is already load-bearing in the codebase. It generates docblock stubs for Actions' magic method surface — asController, asListener, asJob, asCommand, asObject, plus handle, authorize, rules, and constructor parameters with their defaults. If the project is controller/service oriented, there is nothing here for you.

Install. It is a dev-only dependency; never let it into require:

composer require --dev wulfheart/laravel-actions-ide-helper

No config file, no publish step, no service provider registration in the common case.

Generate.

php artisan ide-helper:actions

The command scans action classes via Composer/package discovery and writes a generated stub file. Confirm the exact output filename from the command's own output rather than assuming — then verify your IDE indexes it.

Where to look first. Open one action that is invoked statically (StorePost::run($data)) or via asController(), and check that the IDE now resolves the call signature and return type instead of falling back to mixed. That single check tells you whether the install worked; everything else is repetition of that same pattern across the action surface.

First useful case. An action routed as an invokable controller:

Route::post('/posts', StorePost::class);

Before the helper, hovering StorePost::class in the route file gives you nothing actionable. After generation, the IDE knows the __invoke/asController shape, the request parameter, and the return contract — which is precisely the information you lose when a framework leans on __call.

Implementation Patterns

Regenerate deliberately, not automatically. The stub is derived state. Two viable workflows:

• Manual, documented. Add php artisan ide-helper:actions to the onboarding doc and to the "new action" section of the team conventions. Zero CI surface, zero failure mode.
• Composer hook. "post-autoload-dump": ["@php artisan ide-helper:actions"] gives you regeneration on composer install/dump-autoload at no cognitive cost. Only do this if you have verified it succeeds on a repo with zero actions and does not slow composer install noticeably.

Avoid running it as a CI gate. A generator error on unrelated work turns a dev convenience into a red pipeline.

Gitignore versus commit. Default to gitignoring the artifact: it is cheap to rebuild, and a committed generated file is a merge-conflict magnet on any branch that adds actions. Commit it only if you need it for CI static analysis — in which case wire it into PHPStan/Larastan's scanFiles/bootstrapFiles so run() and asController() calls type-check, and add a "regenerate and commit" step to your PR checklist.

Use the generated diff as a contract-change detector. This is the most underrated pattern here. Before upgrading lorisleiva/laravel-actions, regenerate on a clean tree and commit the stub; after the upgrade, regenerate again and diff. If signatures shift, you see it as a readable text diff rather than as a silent loss of IDE accuracy or a runtime surprise three sprints later. Costs nothing and gives you a cheap canary for the failure mode the README's YOLO-ware stance makes most likely.

Coexist with barryvdh/laravel-ide-helper. They are complementary, not overlapping — that package handles facades, models, and container bindings; this one handles actions. Both write root-level stub files, both are dev-only, both share the "regenerate when the codebase changes shape" hygiene rule. Treat them as one tooling line item in the onboarding doc rather than two separate discoveries.

Pair with a static analyser. The helper's real payoff lands when Larastan/PHPStan consumes the same stubs your editor does. Without that, you improve hover text only; with it, you turn a class of "cannot resolve magic method" false positives into real enforcement on action signatures.

Gotchas and Tips

Read the README's YOLO-ware section before you commit. No guarantees, community-powered fixes, changes merged without maintainer testing, and an explicit call for a new maintainer. Pin to a specific minor version — an unpinned ^0.x will absorb an untested community merge on a Friday composer update. This is a small, single-command package; if upstream goes dark, forking or vendoring is a realistic few-day internalization, but only if someone owns that decision. Name an owner.

Dependency conflicts are the real install risk. The release history is dominated by third-party bumps: lorisleiva/lody (v0.10.0), phpdocumentor/reflection (v0.8.0), and an explicit fix for phpdocumentor/reflection-docblock 5.4.0 (v0.7.2). If your static analysis or documentation toolchain constrains those libraries, the install or a later composer update stalls. Pre-flight it:

composer why-not wulfheart/laravel-actions-ide-helper

Silent staleness is the expected failure mode. The generator is coupled to Actions' method surface. When Actions changes shape, you do not get an error — you get a stub that confidently describes the old contract. Mitigation: regenerate after every composer update that touches laravel-actions, and re-run the diff check described above.

Missing methods after generation usually means discovery, not the generator. Verify the action class is inside an autoloaded path the package scans, then clear compiled/cached state and regenerate. If a specific action still does not appear, isolate: a minimal action in the same namespace reproducing the omission tells you instantly whether it is a class-shape issue or a package bug — and with a YOLO-ware project, that minimal reproduction is also the PR you will end up writing.

IDE-side configuration is half the battle. PHPStorm may need an index rebuild before the new stub resolves. Intelephense users should confirm the generated file sits inside the workspace root and is not excluded by file-size or path filters. If half the team runs an editor without a functioning PHP language server, you are paying a dependency for half its value.

Keep the stub out of runtime autoloading. It is a docblock artifact, not executable code. Do not add it to a classmap, do not require it in a service provider, and do not let it into production builds — a dev-only package that leaks a generated PHP file into the request lifecycle is a self-inflicted wound.

Debugging checklist, in order: does the file exist and is it non-empty → does it contain the action you expect → is that file indexed by the IDE → does the IDE resolve the signature after a cache invalidation → does PHPStan see it with the correct scanFiles config. Ninety percent of "the helper doesn't work" reports stop at step two.

Extension points are thin by design. One command, one generator, no config. If you need behaviour the package does not offer (custom output path, filtering by namespace), the honest answer is a fork — which, given the size and the stated support model, is probably the right long-term posture anyway.