Ide Helper Extension Laravel Package

Getting Started

This is a PyroCMS 3 (Laravel) extension addon — not a generic Composer utility. Its job is to generate PHPDoc stubs (@property, @method, @mixin annotations) for PyroCMS stream entry models and addon classes so your IDE can autocomplete things like $entry->title or stream repository methods. Without it you get a wall of "undefined property" warnings in PhpStorm every time you touch a stream model.

The order of operations that matters:

1. Install the package via Composer in the PyroCMS project root:

   composer require newebtime/ide_helper-extension
   

2. Install the addon into PyroCMS (Composer install alone does not register it):

   php artisan addon:install newebtime.extension.ide_helper
   

   Confirm it appears under Admin → Addons → Extensions as enabled.
3. Run your migrations first. The generator reads your database schema to produce property annotations; running it against an empty or unmigrated database produces empty/useless stubs.
4. Generate the helper file — check php artisan list for the command (typically namespaced under the extension, e.g. ide-helper:generate or ide_helper:generate). This is the first thing to look for; the command name is the entry point to everything else.
5. Point your IDE at the output. The generated _ide_helper_*.php file is usually written to the project root or storage/. Open it once so PhpStorm/VS Code indexes it, and exclude it from static analysis if needed.

First concrete use case: you've just created a stream called blog_posts with fields title, slug, body. Before running the generator, PhpStorm flags $post->title as undefined because the stream entry model is dynamic. After running the generator, you get autocomplete and type hints for all three fields across the whole project. That round trip — create stream → migrate → regenerate → code — is the core daily loop.

Implementation Patterns

The regenerate-on-schemachange loop. The single most valuable habit: treat the generated helper file as a build artifact of your schema. Any time you add/modify a stream field, add an assignment, or change an addon, re-run the generator. Teams typically wire this into a Composer script or a Git hook:

"scripts": {
  "post-install-cmd": ["@ide-helper"],
  "ide-helper": "php artisan <generator-command>"
}

Commit the artifact, don't gitignore it (usually). Unlike barryvdh/laravel-ide-helper — which is commonly gitignored — a PyroCMS extension's generated stubs are tightly coupled to this project's streams. Committing them means new team members get autocomplete on day one without needing a working DB. If you do gitignore, add the regenerate step to your onboarding docs and CI.

CI integration. Run the generator as a validation step and git diff --exit-code on the generated file. That catches the common failure where someone renamed a stream field but never regenerated — a silent source of stale autocomplete.

Docker/CI parity. Because the generator may need a live DB connection to introspect streams, run it after migrations in your container build, not in a bare Composer step. If the extension can introspect from stream definitions rather than the DB, prefer that mode in CI so it works without a database.

Pairing with barryvdh/laravel-ide-helper. These are complementary: barryvdh handles framework facades and Eloquent, this extension handles PyroCMS-specific dynamic types (stream entries, addon classes, module registries). Run both, but keep their output files separate so a regeneration of one doesn't clobber the other.

Per-addon scoping for large projects. If you have many addons and the generate step is slow, narrow the output to the namespaces you actually work in. This keeps IDE memory usage sane — a single 5MB stub file with thousands of @property lines can slow PhpStorm's indexing noticeably.

Extending via custom generators. If the extension exposes a generator registry or events (common in PyroCMS extensions), you can register your own stub emitter for bespoke patterns — e.g. annotating your own base model with @method signatures for magic repository methods your team relies on. Look for a service provider binding or a tagged collection of generators.

Gotchas and Tips

Stale stubs are the #1 problem. Nothing errors when the helper file is out of date — you just get wrong autocomplete and phantom type errors that send you debugging the wrong thing. Rule of thumb: if a stream field's type looks wrong in the IDE, regenerate before you touch a single line of code.

Migrations must run before generation. The generator typically reads column types from the database to decide between string, int, Carbon, etc. Generating against a partially migrated DB produces wrong types (mixed everywhere) and you'll waste an hour thinking the extension is broken.

IDE caches lie. After regenerating, PhpStorm often doesn't pick up changes until you File → Invalidate Caches and Restart (or at minimum Synchronize). VS Code's PHP Intelephense has its own index cache. If your new annotations "don't work," clear the IDE cache before re-debugging the generator.

Watch install order. This extension depends on the PyroCMS streams platform being present and migrated. Installing it into a fresh project before the base addons are set up will produce empty output or install failures. Install it last in your bootstrap sequence.

File write permissions. The generator writes to a path that may be outside storage/ (often project root). In containerized or read-only-filesystem deployments, the write silently fails or errors. Ensure the target path is writable, or configure an output path inside storage/ that survives your build.

Version pinning matters more than usual. With near-zero stars and dependents, this package has no ecosystem pressure to keep it compatible with new PyroCMS/Laravel majors. Pin the version in composer.json and note the PyroCMS version it targets in your README. Expect to fork if the upstream is abandoned — the code is small, so patching a broken generator is usually faster than finding a replacement.

Extension points are your escape hatch. If a stream pattern isn't annotated correctly (polymorphic fields, JSON casts, custom field types), the fix is almost always a small custom generator or a manual @property block in a trait/mixin rather than fighting the tool. Look for the generator interface and add your own case — that's the intended customization seam.

Don't let it run in production hot paths. Regenerating stubs is a dev/CI concern. Keep it out of composer install on production images (use --no-dev and --no-scripts there) so you don't add a DB-dependent step to your deploy.

Document the command name. Given the low adoption, there's essentially no community knowledge to fall back on. The one thing worth putting in your team runbook verbatim is the exact regenerate command and where the output lands — future-you will not remember.