Facade System

Purpose and Scope

The Facade System provides a static interface layer for accessing services registered in the dependency injection container. Facades allow application code to call methods on underlying services using a clean, expressive static syntax while maintaining testability and dependency injection principles. This document covers the base Facade class implementation, the service resolution mechanism, instance lifecycle management, and comprehensive testing capabilities including spying, mocking, and swapping.

For information about specific facade implementations (Request, Response, DB, etc.), see their respective sections in the HTTP Layer (4), View Layer (5), and Data Persistence Layer (6). For the service container and dependency injection concepts, see Service Provider System (3.3).

---

Base Facade Pattern

All facades extend the abstract Facade class located at src/Facades/Facade.php15 which implements the core resolution and proxying logic. Concrete facade classes must implement the getFacadeAccessor() method to specify which service they represent.

Facade Resolution Flow

Sources: src/Facades/Facade.php144-192

The __callStatic Magic Method

The __callStatic() method at src/Facades/Facade.php144-153 intercepts all static method calls on facade classes. It resolves the underlying service instance via getFacadeRoot() and forwards the method call:

Step	Method	Purpose
1	__callStatic($method, $args)	Intercept static call
2	getFacadeRoot()	Get resolved service instance
3	$instance->{$method}(...$args)	Forward call to instance

If no facade root is set, a RuntimeException is thrown at src/Facades/Facade.php149

Sources: src/Facades/Facade.php144-153

The getFacadeAccessor Method

Concrete facade classes must implement getFacadeAccessor() to return the service container binding identifier. The base implementation at src/Facades/Facade.php260-263 throws a RuntimeException if not overridden.

Example Facade Structure

Sources: src/Facades/Facade.php15-264

---

Facade Resolution Process

Facade resolution occurs through the resolveFacadeInstance() method at src/Facades/Facade.php177-192 which implements a three-tier resolution strategy:

Resolution Strategy

Priority	Source	Implementation
1	Direct object	If accessor is an object, return it immediately
2	Cached instance	Check $resolvedInstance[$name] static cache
3	Container resolution	Resolve from ApplicationContext::getContainer()->get($name)

Resolution Algorithm

Sources: src/Facades/Facade.php177-192

Container Integration

Facades integrate with Hyperf's dependency injection container through the ApplicationContext class. The container is accessed at src/Facades/Facade.php27-188 for service resolution, instance registration, and lifecycle callbacks.

Key Container Operations:

• has($name) - Check if service is registered src/Facades/Facade.php187
• get($name) - Resolve service instance src/Facades/Facade.php188
• resolved($name) - Check if service has been resolved src/Facades/Facade.php30
• afterResolving($name, $callback) - Register post-resolution callback src/Facades/Facade.php34-36
• instance($name, $instance) - Register singleton instance src/Facades/Facade.php135

Sources: src/Facades/Facade.php27-188

---

Facade Lifecycle

Facade instances are managed through a static $resolvedInstance array at src/Facades/Facade.php20 providing caching and lifecycle control.

Lifecycle Management Methods

Sources: src/Facades/Facade.php20-208

Instance Caching

Once resolved, instances are cached in the $resolvedInstance array indexed by the facade accessor name. Subsequent calls reuse the cached instance, avoiding repeated container resolution. The cache check occurs at src/Facades/Facade.php183-185 before container access.

Sources: src/Facades/Facade.php183-188

The swap() Method

The swap() method at src/Facades/Facade.php131-136 allows hot-swapping the underlying service instance. This is used extensively in testing but can also be used in production for dynamic service replacement:

Sources: src/Facades/Facade.php131-136

Clearing Resolved Instances

The facade system provides two methods for clearing cached instances:

Method	Scope	Implementation
clearResolvedInstance($name)	Single facade	Unsets $resolvedInstance[$name]
clearResolvedInstances()	All facades	Resets $resolvedInstance = []

These methods at src/Facades/Facade.php196-208 are typically used in testing to ensure clean state between tests.

Sources: src/Facades/Facade.php196-208

The resolved() Callback

The resolved() method at src/Facades/Facade.php25-37 registers callbacks that execute when a facade's underlying service is resolved. If the service is already resolved, the callback executes immediately. Otherwise, it registers with the container's afterResolving() hook:

Sources: src/Facades/Facade.php25-37

---

Testing Capabilities

The facade system provides comprehensive testing utilities through integration with the Mockery library. These methods enable spying, partial mocking, expectation setting, and instance swapping.

Testing Method Overview

Sources: src/Facades/Facade.php42-164

The spy() Method

The spy() method at src/Facades/Facade.php42-53 creates a Mockery spy that records method calls without altering behavior. It automatically swaps the spy into the facade using the swap() method:

Spy Creation Flow:

1. Check if facade is already mocked via isMock() src/Facades/Facade.php44
2. Get mockable class via getMockableClass() src/Facades/Facade.php48
3. Create Mockery spy with or without class src/Facades/Facade.php50
4. Swap spy into facade src/Facades/Facade.php51
5. Return spy instance for assertions

Sources: src/Facades/Facade.php42-53

The partialMock() Method

The partialMock() method at src/Facades/Facade.php58-67 creates a partial mock that only mocks specified methods, allowing real methods to execute normally:

Sources: src/Facades/Facade.php58-67

The shouldReceive() Method

The shouldReceive() method at src/Facades/Facade.php72-81 enables Mockery expectation syntax for facades. Like partialMock(), it reuses existing mocks or creates new ones:

Implementation Details:

• Accepts method names and arguments via func_get_args() src/Facades/Facade.php80
• Reuses existing mock if isMock() returns true src/Facades/Facade.php76-77
• Creates fresh mock via createFreshMockInstance() otherwise src/Facades/Facade.php78
• Forwards arguments to Mockery's shouldReceive() src/Facades/Facade.php80

Sources: src/Facades/Facade.php72-81

Mock Creation Infrastructure

The facade system uses several protected methods to create and configure mocks:

Method	Purpose	Key Logic
createFreshMockInstance()	Create and swap new mock	Calls createMock(), then swap(), enables protected method mocking
createMock()	Create Mockery mock	Gets mockable class, creates typed or untyped mock
getMockableClass()	Get class name to mock	Retrieves class from getFacadeRoot()
isMock()	Check if instance is mock	Checks if $resolvedInstance[$name] is LegacyMockInterface
isFake()	Check if instance is fake	Checks if $resolvedInstance[$name] is Fake

Sources: src/Facades/Facade.php86-164

Testing Pattern Example

Sources: src/Facades/Facade.php72-153

---

Default Facade Aliases

The facade system provides a comprehensive list of default facade aliases through the defaultAliases() method at src/Facades/Facade.php213-253 This static method returns a Collection containing 37 facade mappings:

Facade Categories

Category	Facades	Example Classes
Core	App, Artisan, Config, Environment	App::class, Config::class
HTTP	Request, Response, Cookie, Route, URL	Request::class, Route::class
Data	DB, Cache, Redis, Queue	DB::class, Cache::class
View	View, Blade	View::class, Blade::class
Communication	Event, Broadcast, Http, Mail, Notification	Event::class, Http::class
Security	Auth, Gate, Hash, Crypt, JWT	Auth::class, Gate::class
Infrastructure	Bus, Log, File, Storage, Process, Schedule	Bus::class, Log::class
Utilities	Date, Validator, RateLimiter, Session	Date::class, Validator::class

These aliases enable shorter, more expressive syntax (e.g., DB instead of Hypervel\Support\Facades\DB) when registered in the application's class alias system.

Sources: src/Facades/Facade.php213-253

---

Integration with Reflection

While the facade system primarily relies on PHP's __callStatic magic method, the codebase includes reflection utilities in src/Reflector.php1-137 that can be used for advanced facade introspection and parameter type resolution. The Reflector class provides:

• isCallable() - PHP 7.4 compatible callable checking src/Reflector.php18-55
• getParameterClassName() - Extract class names from parameter types src/Reflector.php62-71
• getParameterClassNames() - Handle union types src/Reflector.php78-97
• isParameterSubclassOf() - Type hierarchy checking src/Reflector.php128-135

These utilities support scenarios where facades need to inspect method signatures or validate parameter types at runtime, particularly useful in advanced testing or dynamic method binding scenarios.

Sources: src/Reflector.php1-137