Smart Realtime Facades Laravel Package

Getting Started

1. Install

composer require imanghafoori/smart-realtime-facades --dev

Keep it in require-dev — the package is a development-time convenience (generating IDE metadata). Runtime real-time facades are a core Laravel feature; this package only adds autocompletion on top.

2. Find the generator

The package registers artisan commands under a smart namespace. Confirm the exact signature for your installed version:

php artisan list | grep smart
php artisan help smart:facade   # or whatever the list shows

3. Generate your first facade

Pick a class you already call through the container — a service, action, or repository:

namespace App\Services;

class Greeter
{
    public function greet(string $name): string
    {
        return "Hello, {$name}";
    }
}

Generate a facade for it. The command produces a companion class (typically under app/SmartFacades or similar) containing @method static docblocks mirroring the public API of Greeter, plus a @see/@mixin reference back to the original.

namespace App\SmartFacades;

/**
 * @see \App\Services\Greeter
 *
 * @method static string greet(string $name)
 */
class Greeter extends \ImanGhafoori\SmartRealtimeFacades\SmartFacade
{
    //
}

4. Use it

use App\SmartFacades\Greeter;

Greeter::greet('Sara'); // typed, autocompleted, resolved from the container

Your IDE now sees greet() returning string, and Ctrl-click jumps to the real implementation via @see. That is the entire value proposition — Laravel's native real-time facades (\App\Services\Greeter::greet(...)) work identically at runtime but are invisible to your IDE.

Where to look first: the generated stub and the base class it extends. Understanding the forwarding mechanism (container make() per call) clarifies every behavior below.

Implementation Patterns

One facade per service class. Do not generate facades for Eloquent models (they already have facades and static methods) or for classes with a single method you call once — the docblock overhead outweighs the benefit.

Group by bounded context. Mirror your app/Services tree in the generated directory (App\SmartFacades\Billing\InvoiceIssuer). This keeps navigation predictable and makes it obvious which facade a service has.

Controllers stay thin and type-safe.

class WelcomeController
{
    public function __invoke(string $name): View
    {
        return view('welcome', ['msg' => Greeter::greet($name)]);
    }
}

Because the docblock declares @method static string greet(string $name), Larastan/PHPStan will validate the argument types at analysis time. A typo like Greeter::great() now fails CI instead of blowing up in production.

Testing: no change required. Real-time facades resolve through the container, so existing $this->mock(Greeter::class) or $this->instance(Greeter::class, $fake) bindings continue to work. The smart facade is a thin forwarding layer, not a new resolution path.

Regenerate on service change, and diff it in CI. The generated docblocks are derived state. A common workflow:

php artisan smart:facade App\\Services\\Greeter   # regenerate
git diff --exit-code app/SmartFacades/            # fail CI if stale

This guarantees the annotations never drift from the source signatures.

Compose with @mixin for third-party contracts. If your service implements an interface with a rich docblock, add @mixin \App\Contracts\GreeterContract above the generated block so the interface's method docs (and @throws, @deprecated) surface in the IDE too.

Use in Blade/view helpers sparingly. Since facades are globally resolvable, Greeter::greet() works in Blade, but prefer passing data from controllers — the facade indirection obscures where dependencies originate.

Gotchas and Tips

Stale signatures are the #1 failure mode. Rename greet() to sayHi() and the generated docblock still advertises greet(). Your IDE will autocomplete a method that no longer exists — worse than no autocompletion. Automate regeneration (CI diff check above) or add it to a file watcher.

Commit the generated files. They are source-of-truth-adjacent and your teammates, static analysers, and CI all need them. Do not .gitignore the output directory; do not regenerate on every checkout.

Composer autoload. Newly generated classes are only discoverable after composer dump-autoload (or composer dump-autoload -o in CI). If your IDE redsquiggles a freshly generated facade, this is usually why — then restart the IDE's PHP indexing.

Signatures the generator can't infer. Methods with mixed, union return types, variadics, or untyped parameters yield weak docblocks. Either add explicit return types to the source (good practice anyway) or hand-edit @method lines — edits survive regeneration only if you keep them in a separate, manually-maintained @mixin block.

No container binding = runtime failure. Unlike a normal facade, there is no service provider registration; the class is resolved by its concrete FQN. If Greeter requires constructor args the container can't build, both the smart facade and the native real-time facade will throw BindingResolutionException. Bind it in a provider if needed.

Do not shadow real facades. Naming a generated class Cache, Route, or DB invites use collisions. Prefix the directory (SmartFacades) as the package does by default.

Laravel version compatibility. The last release is dated February 2023, targeting the Laravel 9/10 era. On Laravel 11+, install and smoke-test the generator command before adopting it project-wide; the generated output is plain PHP so it will keep working, but the command auto-registration may not.

Extension points to check. Look for a publishable config (output path, namespace prefix, stub template) via php artisan vendor:publish. If you need a house style — e.g. adding a standard @package header or a @internal marker — a custom stub is cleaner than post-processing generated files.

Debugging: if a call fails with "method does not exist", the docblock and the actual class have diverged — diff the @method list against get_class_methods(Greeter::class). If it fails with a container error, the forwarding layer is fine and the problem is your binding.