Laravel Ide Facades Helper Laravel Package

Getting Started

Install it as a dev dependency — it has no runtime role, only generates docblocks for your editor and static analyser:

composer require --dev dragon-code/laravel-ide-facades-helper

Service provider is auto-discovered. Confirm the artisan namespace it registers with:

php artisan list | grep -i facade

Confirm which version you actually pulled — v1.8.0 is current, and if the tag is not what you expected, pin it explicitly in composer.json so a future release cannot silently change generator behaviour. Before running anything, look at two things first:

1. Your own facade classes — typically app/Facades/*.php. Each one extends Illuminate\Support\Facades\Facade and returns a container binding (string key or FQCN) from getFacadeAccessor().
2. The package config (publish it if you want to change scan paths / exclusions):

php artisan vendor:publish --tag=ide-facades-helper-config

The first realistic use case is a custom facade over a service that your IDE cannot resolve:

// app/Facades/ReportBuilder.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @method static \App\Reports\Report forUser(\App\Models\User $user)
 * @method static \App\Reports\Report period(string $from, string $to)
 */
class ReportBuilder extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return \App\Reports\Builder::class;
    }
}

Run the generator, and the @method lines are derived by reflecting the methods of the accessor class rather than being hand-written. That is the whole value proposition: you stop maintaining facade docblocks by hand, and you stop losing auto-completion the moment a service contract changes.

Implementation Patterns

Generate after every signature change, not just at install time. Treat the generator like a build step for your facades. Wire it into a Composer script so it can never drift silently:

"scripts": {
    "ide": [
        "@php artisan ide-facade-helper:generate",
        "@php artisan ide-helper:generate"
    ],
    "post-autoload-dump": ["@ide"]
}

Pair it with barryvdh/laravel-ide-helper. They solve different halves of the same problem: ide-helper writes a single _ide_helper.php for framework facades (Cache, DB, Log, Route), while this package annotates your facade classes in place. Run both — ide-helper first, then this one — and you get completion for framework and domain facades without either tool clobbering the other's output.

Keep facades thin and typed. The generator reflects the accessor's public API, so completion quality is directly proportional to how well-typed the underlying service is. A Builder class with real parameter and return types produces useful @method static signatures; a service that returns mixed produces noise.

Facade-per-domain, not facade-per-service. The pattern scales best when a facade is a deliberate public surface over a subsystem (ReportBuilder, Billing, Search) rather than a 1:1 wrapper around every class. Fewer, richer facades means fewer regenerations and a docblock set that a new team member can actually read.

Prefer FQCN accessors. Returning Builder::class from getFacadeAccessor() instead of a string alias like 'reports.builder' makes the reflection step deterministic and survives container alias changes — the generator can resolve the class without needing your service provider's binding configuration to be loaded in the exact right order.

In packages, run it in the package's dev environment. If you ship a Laravel package with facades, the generated docblocks are part of the developer experience for consumers. Commit them and regenerate on release; end users should not need to install this tool.

Commit the generated docblocks. They are written into the facade source files, so they belong in version control — a clone-and-open experience beats "run this command before your IDE works." Just make sure the generator is part of the PR checklist so a signature change does not leave a stale block behind.

Gotchas and Tips

The "abandoned package" caveat no longer holds — v1.8.0 has been published. Earlier guidance here called this package archived (last release January 2022). That is now out of date: v1.8.0 shipped against v1.7.0. However, the release announcement is only a version-compare link with no itemised changelog, so do not assume it adds Laravel 11/12 or PHP 8.2+ support, fixes the dynamic-properties deprecation, or changes any @method conventions. Install it, run the generator, and diff the output on your actual stack before trusting it. If it still misbehaves on a current framework, the fork/escape-hatch advice below remains valid — the maintenance status change removes the "definitely dead" argument, not the compatibility risk.

Reflection requires the container to be bootable. The generator has to app()->make() or reflect the accessor class, so a facade whose binding depends on request data, tenancy resolution, or config that only exists in staging will fail or emit an empty block. Look for silent no-ops here — the command often succeeds with exit code 0 while writing nothing.

Generated blocks overwrite hand-written ones. If you have carefully curated @method lines on a facade, the generator will replace them on the next run. Keep manual notes as @see, @property, or prose above the @method block, or you will lose them. Diff the facade files after the first run before committing anything.

Stale docblocks are worse than none. A @method that no longer matches the real signature gives your IDE — and PHPStan/Psalm if they read it — a confidently wrong answer. A CI step that regenerates and asserts a clean git diff catches drift early:

php artisan ide-facade-helper:generate
git diff --exit-code app/Facades/ || (echo "Facades out of date" && exit 1)

Static analysers are inconsistent about @method on facades. PHPStan resolves static calls on Facade subclasses through its own Laravel extensions, not necessarily through your docblock. If analysis disagrees with the IDE, trust the analyser and add a @mixin Builder alongside the generated @method block — it is the more robust annotation.

Variadics, unions, generics and static returns are lossy. Reflection-to-docblock conversion cannot express Collection<int, Report> or $this returns well. For anything with a fluent API, hand-write @method static static forUser(...) on top; the generator's output is a starting point, not a finished contract.

Scan paths are the usual config quirk. Default scope is your app's facade directory. If facades live elsewhere (app/Support/Facades, a domain module, packages/*/src/Facades), add the paths and exclude vendor/ explicitly — otherwise you regenerate the entire dependency tree's facades and get a multi-thousand-line diff.

Debugging a missing method: run with -v, verify getFacadeAccessor() returns something the container can resolve in the CLI environment, and confirm the method is public (protected/private members are skipped, as are __construct and inherited Facade internals). A quick sanity check is php artisan tinker → app(YourService::class) and confirming the object is what you expect.

Extension point worth knowing: because the output is plain PHPDoc in your own files, the ultimate escape hatch is to stop using the tool and freeze the docblocks. If a future release breaks on a framework upgrade, delete it from require-dev, keep the generated annotations, and maintain them by hand — often that is cheaper than patching a low-traffic dependency.