Facade

Come funzionano le facade di Laravel, come si usano, le real-time facade, come testarle e quando preferire la dependency injection.

​

Cos’è una facade

Una facade fornisce un’interfaccia “statica” alle classi disponibili nel service container dell’applicazione. Laravel include molte facade che danno accesso a quasi tutte le sue funzionalità.

Le facade di Laravel fungono da “proxy statici” alle classi reali all’interno del service container: offrono una sintassi concisa ed espressiva mantenendo maggiore testabilità e flessibilità rispetto ai metodi statici tradizionali.

Tutte le facade di Laravel sono definite nel namespace Illuminate\Support\Facades.

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Route;

Route::get('/cache', function () {
    return Cache::get('key');
});

Non è un problema se non comprendi ancora completamente il funzionamento delle facade. Impara prima come usarle e continua a studiare Laravel.

​

Come funzionano le facade

Nelle applicazioni Laravel, una facade è una classe che offre accesso a un oggetto proveniente dal container. Questo meccanismo è implementato dalla classe Facade. Tutte le facade di Laravel e le facade personalizzate estendono la classe base Illuminate\Support\Facades\Facade.

La classe base Facade usa il metodo magico __callStatic() per delegare le chiamate alla facade all’oggetto risolto dal container.

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Cache;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Mostra il profilo dell'utente specificato
     */
    public function showProfile(string $id): View
    {
        $user = Cache::get('user:'.$id);

        return view('profile', ['user' => $user]);
    }
}

All’inizio del file importi la facade Cache. Questa facade fa da proxy verso l’implementazione dell’interfaccia Illuminate\Contracts\Cache\Factory. Tutte le chiamate effettuate tramite la facade vengono passate all’istanza interna del servizio di cache di Laravel.

Se guardi la classe Illuminate\Support\Facades\Cache, non troverai un metodo statico get.

class Cache extends Facade
{
    /**
     * Restituisce il nome di registrazione del componente
     */
    protected static function getFacadeAccessor(): string
    {
        return 'cache';
    }
}

La facade Cache estende la classe base Facade e definisce il metodo getFacadeAccessor(). Questo metodo restituisce il nome del binding nel service container. Quando l’utente chiama un metodo statico della facade Cache, Laravel risolve il binding cache dal service container ed esegue su quell’oggetto il metodo richiesto (in questo caso get).

​

Quando usare (o non usare) le facade

​

Vantaggi delle facade

Le facade offrono molti vantaggi. Forniscono una sintassi concisa e memorabile che consente di usare le funzionalità di Laravel senza dover ricordare lunghi nomi di classi da iniettare e configurare manualmente. Inoltre, grazie all’uso peculiare dei metodi dinamici di PHP, sono facili da testare.

​

Attenzione allo scope creep

Il rischio principale nell’uso delle facade è lo “scope creep” delle classi. Poiché sono comode e non richiedono iniezione, si tende a far crescere una classe continuando ad aggiungere facade. Con la dependency injection, un costruttore che si allunga dà un chiaro segnale visivo. Quando usi le facade, presta attenzione alla dimensione delle classi e mantieni una responsabilità ristretta.

Se senti che una classe è cresciuta troppo, valuta di suddividerla in più classi più piccole.

​

Facade vs dependency injection

Uno dei principali vantaggi della dependency injection è la possibilità di sostituire l’implementazione della classe iniettata. Utile nei test: puoi iniettare mock o stub e verificare che vari metodi vengano invocati sullo stub.

Normalmente i metodi statici veri e propri non possono essere mockati né sostituiti, ma le facade — grazie ai metodi dinamici che fanno da proxy verso l’oggetto risolto dal service container — possono essere testate esattamente come un’istanza di classe iniettata.

use Illuminate\Support\Facades\Cache;

Route::get('/cache', function () {
    return Cache::get('key');
});

Per questa route puoi scrivere il seguente test per verificare che Cache::get sia stato chiamato con l’argomento atteso.

use Illuminate\Support\Facades\Cache;

test('basic example', function () {
    Cache::shouldReceive('get')
        ->with('key')
        ->andReturn('value');

    $response = $this->get('/cache');

    $response->assertSee('value');
});

​

Facade vs funzioni helper

Oltre alle facade, Laravel fornisce funzioni “helper” per svolgere compiti comuni come creare viste, emettere eventi, dispatchare job e inviare risposte HTTP. Molte funzioni helper eseguono la stessa funzione della facade corrispondente.

// Chiamata tramite facade
return Illuminate\Support\Facades\View::make('profile');

// Chiamata equivalente tramite funzione helper
return view('profile');

Non ci sono differenze sostanziali tra facade e funzioni helper. Anche usando le funzioni helper puoi testarle come le facade corrispondenti.

use Illuminate\Support\Facades\Cache;

test('cache helper test', function () {
    Cache::shouldReceive('get')
        ->with('key')
        ->andReturn('value');

    $response = $this->get('/cache');

    $response->assertSee('value');
});

​

Real-time facade

Con le real-time facade puoi trattare qualsiasi classe dell’applicazione come una facade. Per spiegare come si usano, vediamo prima un codice senza real-time facade.

Supponi che il modello Podcast abbia un metodo publish. Per pubblicare il podcast è però necessario iniettare un’istanza di Publisher.

<?php

namespace App\Models;

use App\Contracts\Publisher;
use Illuminate\Database\Eloquent\Model;

class Podcast extends Model
{
    /**
     * Pubblica il podcast
     */
    public function publish(Publisher $publisher): void
    {
        $this->update(['publishing' => now()]);

        $publisher->publish($this);
    }
}

Usando una real-time facade non serve più passare esplicitamente un’istanza di Publisher, pur mantenendo la stessa testabilità. Per generare una real-time facade aggiungi il prefisso Facades al namespace della classe da importare.

<?php

namespace App\Models;

use Facades\App\Contracts\Publisher;
use Illuminate\Database\Eloquent\Model;

class Podcast extends Model
{
    /**
     * Pubblica il podcast
     */
    public function publish(): void
    {
        $this->update(['publishing' => now()]);

        Publisher::publish($this);
    }
}

Quando si usa una real-time facade, l’implementazione del publisher viene risolta dal service container usando la parte di interfaccia o classe che appare dopo il prefisso Facades.

<?php

use App\Models\Podcast;
use Facades\App\Contracts\Publisher;
use Illuminate\Foundation\Testing\RefreshDatabase;

pest()->use(RefreshDatabase::class);

test('podcast can be published', function () {
    $podcast = Podcast::factory()->create();

    Publisher::shouldReceive('publish')->once()->with($podcast);

    $podcast->publish();
});

Le real-time facade sono comode quando vuoi eliminare la necessità di passare l’oggetto come argomento pur semplificando la creazione dei mock nei test.

​

Testare le facade

Per testare le facade usa il metodo shouldReceive, che restituisce un’istanza mock di Mockery. Poiché le facade sono realmente risolte e gestite dal service container, sono molto più testabili delle classi statiche tradizionali.

use Illuminate\Support\Facades\Cache;

test('mostra il profilo utente', function () {
    Cache::shouldReceive('get')
        ->once()
        ->with('user:1')
        ->andReturn(['name' => 'Taylor']);

    $response = $this->get('/users/1');

    $response->assertSee('Taylor');
});

I metodi di mock più comuni sono i seguenti.

Metodo	Descrizione
shouldReceive('method')	Ci si aspetta che il metodo venga chiamato
once()	Ci si aspetta che venga chiamato una sola volta
times(n)	Ci si aspetta che venga chiamato n volte
with(args)	Ci si aspetta che venga chiamato con determinati argomenti
andReturn(value)	Restituisce il valore indicato
andReturnNull()	Restituisce null

​

Elenco delle facade principali

Tabella di corrispondenza tra le facade più usate, la classe reale e il nome del binding nel service container.

Facade	Classe	Binding
App	Illuminate\Foundation\Application	app
Auth	Illuminate\Auth\AuthManager	auth
Cache	Illuminate\Cache\CacheManager	cache
Config	Illuminate\Config\Repository	config
Cookie	Illuminate\Cookie\CookieJar	cookie
Crypt	Illuminate\Encryption\Encrypter	encrypter
DB	Illuminate\Database\DatabaseManager	db
Event	Illuminate\Events\Dispatcher	events
File	Illuminate\Filesystem\Filesystem	files
Gate	Illuminate\Contracts\Auth\Access\Gate	—
Hash	Illuminate\Contracts\Hashing\Hasher	hash
Http	Illuminate\Http\Client\Factory	—
Log	Illuminate\Log\LogManager	log
Mail	Illuminate\Mail\Mailer	mailer
Notification	Illuminate\Notifications\ChannelManager	—
Queue	Illuminate\Queue\QueueManager	queue
RateLimiter	Illuminate\Cache\RateLimiter	—
Redirect	Illuminate\Routing\Redirector	redirect
Request	Illuminate\Http\Request	request
Route	Illuminate\Routing\Router	router
Schema	Illuminate\Database\Schema\Builder	—
Session	Illuminate\Session\SessionManager	session
Storage	Illuminate\Filesystem\FilesystemManager	filesystem
URL	Illuminate\Routing\UrlGenerator	url
Validator	Illuminate\Validation\Factory	validator
View	Illuminate\View\Factory	view

​

Prossimi passi

Contracts (contratti)

Impara i concetti dei Contracts, controparte delle facade, e quando preferire l’uno o l’altro.