Webman Eloquent Ide Helper Laravel Package

Getting Started

This is a webman port of barryvdh/laravel-ide-helper: it scans your Eloquent models against the live database schema and emits PHPDoc blocks (@property, @method, relation return types) so your IDE and static analyser stop treating every model as a bag of mixed.

Minimal setup:

composer require --dev kriss/webman-eloquent-ide-helper

It leans on webman/console (command registration) and webman/database (the illuminate/database Eloquent layer). Both are usually already present in a webman app; if php webman list shows nothing new after install, that is the first thing to check. Commands generally follow the Laravel naming (ide-helper:models, ide-helper:generate), so:

php webman list | grep ide-helper
php webman ide-helper:models --nowrite   # writes _ide_helper_models.php instead of editing models

Where to look first: the package's src/Command/ directory (the exact command signatures are the real documentation here, not the README), then config/plugin/kriss/webman-eloquent-ide-helper/ after publishing — that is where model paths, excluded tables, and the target filename are configured.

The first use case that pays for itself: a legacy database with 40+ tables where you hand-wrote models. Run --nowrite once, get a single _ide_helper_models.php, and autocomplete on $user->created_at starts working without touching a single model file.

Implementation Patterns

Generate to a side file, not into models. --nowrite produces one _ide_helper_models.php you can gitignore locally or commit as a single reviewable artifact. Writing docblocks directly into model files (--write) turns every schema migration into a diff across dozens of files and creates merge conflicts on any branch that touches a model.

Wire it into a composer script and a CI job. The generated file is only useful if it is fresh:

"scripts": {
  "ide-helper": "php webman ide-helper:models --nowrite --reset"
}

--reset wipes the previous output first, which keeps the file deterministic — important if you commit it and run a "did the committed helper drift from the schema?" check in CI. For static analysis, run the generator before PHPStan so the analyser sees the docblocks; PHPStan does not read the database, it reads the file.

Scope generation per app in a multi-app webman project. webman's app/<name>/model layout means the default model path usually misses everything except the main app. Point the config at each app's model directory (or pass paths on the command line if the port supports it), and run once per namespace. Mixing namespaces into one helper file is fine; mixing them into one config is where people lose an hour.

Pair with PHPStan, not Larastan. Larastan assumes a full Laravel bootstrap. For webman, use plain PHPStan plus the generated model docblocks — that is precisely the gap this package fills. Add _ide_helper_models.php to the analysed paths.

Use it as a schema-diff tool, not just an IDE tool. Generating docblocks after a migration and looking at the diff is a fast way to catch a column you renamed in SQL but forgot to update in a cast, $fillable, or accessor.

Gotchas and Tips

Treat this as a small, single-maintainer package. 14 stars and zero dependents means no crowd-sourced bug reports. Pin the version in composer.json, keep it in require-dev, and isolate invocation behind a composer script so swapping to a fork or to barryvdh/laravel-ide-helper directly is a one-line change rather than a grep across the codebase.

Connection resolution is the #1 failure mode. The helper must connect using the same credentials webman/database uses. In webman the database config location has shifted between versions (plugin config vs. config/database.php), so if you get "no tables found" or an empty output file, verify which config file the running process actually reads before assuming the package is broken. Use -vvv — connection errors are often swallowed.

Models must extend Illuminate\Database\Eloquent\Model. If your base model is support\Model or a custom class that only aliases Eloquent, discovery can miss it. Check the generated file has entries for the models you expect; silent omission is common and easy to overlook because the command still exits 0.

Custom relations and casts degrade to mixed. Non-standard relation classes, Attribute-style accessors, and JSON columns typically produce weak or wrong return types. Fix them in the model itself with explicit @return HasMany<Comment, $this> docblocks — the generator will not overwrite hand-written relation docblocks when using --nowrite, and with --write you should verify it does not clobber them.

Do not generate in production deploy hooks. The command needs a live, reachable database and read access to information_schema. In CI, either spin up a schema-only MySQL container, point at a read replica, or commit the generated file and skip generation entirely in the deploy pipeline.

Stale output is worse than no output. A _ide_helper_models.php from three migrations ago will actively mislead you and your static analyser (phantom properties that no longer exist). If you commit it, add a CI check that regenerates and fails on a non-empty diff.

Debugging checklist when a command does nothing: (1) composer dump-autoload after install, (2) php webman list to confirm registration in config/plugin/*/*/command.php, (3) publish and inspect the plugin config for model paths, (4) run with -vvv and confirm the DB connection, (5) check the output file's mtime to be sure you are looking at the file the command actually wrote.