Support Facades Laravel Package

Getting Started

Install and check the floor. composer require orchestra/support-facades alongside orchestra/support. v7 targets Laravel 9+ and PHP 8.1+, so confirm your framework version before anything else — this is a hard constraint, not a shim. If you are on Laravel 8, stop; you need the v6 line and a plan to move.

Where to look first.

• src/ — the facade classes themselves. They are small; read every one in ten minutes. Each should be a thin subclass with a getFacadeAccessor() returning a container key.
• composer.json — the illuminate/* and orchestra/support constraints tell you the effective support matrix more reliably than the release note.
• The service provider(s) — find out which accessors are registered and whether they are deferred. If there is no provider, the package is purely base classes and you register bindings yourself.
• orchestra/support — the actual behaviour lives there. This package is only the static skin over it.

First use case. Take one place in your package where you currently do $app->make(SomeHelper::class)->method() or resolve('orchestra.support.…'), and replace it with the facade call. That is the entire value proposition in one diff. If you cannot name that call site concretely, you probably do not need this package — Laravel's own Illuminate\Support\Facades\Facade plus a five-line subclass covers most needs.

First test. Write one test that fakes the facade (Facade::shouldReceive(...)) and one that hits the real container binding. If both pass, the wiring is correct and you can expand from there.

Implementation Patterns

Aliasing in application code. Register the facade either in config/app.php under aliases or, for a package, via your provider's $aliases array (Testbench-style). Prefer explicit use Orchestra\Support\Facades\Whatever; imports over global aliases in application code — global aliases are where name collisions (see Gotchas) come from.

Extending the base for your own package. The main reuse pattern is: your package defines a service, binds it in the container, then exposes it through a facade that extends the Orchestra base. The subclass is typically just:

class Reports extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'acme.reports';
    }
}

Keep the accessor string a constant somewhere shared so the binding and the facade cannot drift apart.

Keep facades at the edges. Day-to-day discipline: use facades in Blade templates, package-level static APIs, and artisan command output formatting — places where injection is awkward or impossible. Use constructor injection in controllers, jobs, listeners, and services. Your tests stay honest that way, and the facade layer stays a presentation concern rather than an architectural one.

Testing. Two modes:

• Fake it: Facade::shouldReceive('method')->once()->andReturn(...). Fast, no container.
• Swap it: Facade::swap($mock) or bind a fake into the container before resolution. Use this when the underlying service has state.

Always Facade::clearResolvedInstances() between test cases (or rely on Testbench's teardown) — resolved facade roots are cached statically and leak across tests in the same process.

Integration with Orchestra Testbench. If you write package tests with Testbench, the facades resolve naturally once your provider is loaded via getPackageProviders(). Add the facade to getPackageAliases() only if a test needs the global alias; otherwise skip it and import the class.

Wrapping for safety. If you are adopting this in a codebase that is not otherwise Orchestra-native, put a thin internal adapter in front of it — your own class with injected dependencies that internally calls the facade or the container. Then a future major bump or a decision to drop the package touches one file instead of every call site.

Gotchas and Tips

Alias collisions. Orchestra facade names shadow common Laravel and PHP names (Str, Arr, Json are the classic offenders). Registering them globally can break code that expects Illuminate\Support\Str. Import explicitly; do not rely on the global alias unless the whole codebase is Orchestra-native.

"A facade root has not been set." Almost always one of: the service provider is not registered; the facade's accessor returns a key nobody bound; or the provider is deferred and the facade is being used before the app boots (e.g. in a config file or a service provider's register()). Debug with get_class(Facade::getFacadeRoot()) and by checking the accessor string against $app->bound().

Stale mocks across tests. Because facade roots are static, a mock set in one test survives into the next unless cleared. Flaky "expected 1 call, got 0" failures are usually this, not your code.

Deferred providers and resolution timing. A deferred binding resolves on first facade call, which means the resolution point is invisible in the call stack. When debugging "why is this the wrong instance", log inside the binding closure, not at the call site.

Major versions are not drop-in. v7's release note mentions only the Laravel 9 support bump, but a facade package's public surface is its base class signatures and alias resolution. Diff the base classes between majors rather than assuming. Failures here appear at runtime, not at composer install.

Do not standardise on the package's framework floor. Laravel 9 as a minimum is not a target. Run a currently supported Laravel version and treat the constraint as a gate you clear.

Configuration drift. If the package or its provider publishes config, re-publish and diff on upgrade — merged config changes silently and is a common source of "it worked on the old version" reports.

Continuity risk is real for a package this size. Zero dependents, one maintainer, a very small surface. Mitigations are cheap: keep facade call sites behind your own adapter, note the package in your dependency inventory with an owner, and be prepared to vendor or fork — the code is small enough that a fork is hours, not weeks, of work.

When in doubt, don't. If the only reason to add this is "Orchestra packages use it", and you are not otherwise on the Orchestra Platform, write the five-line facade yourself. The recurring cost — an upgrade ticket per Laravel major, a review per release — is larger than the code you are avoiding.