Implementazione interna dell'helper once() — Once, Onceable e PreventsCircularRecursion

Cos’è once()

once() è un helper globale che esegue una callback e memorizza il risultato in memoria per la durata della richiesta. Se viene chiamato di nuovo dallo stesso punto con la stessa callback, restituisce il risultato memorizzato.

function random(): int
{
    return once(function () {
        return random_int(1, 1000);
    });
}

random(); // 123
random(); // 123 (risultato in cache)
random(); // 123 (risultato in cache)

Se chiamato all’interno del metodo di un’istanza, la cache è indipendente per ciascuna istanza.

class NumberService
{
    public function all(): array
    {
        return once(fn () => [1, 2, 3]);
    }
}

$service = new NumberService;

$service->all();
$service->all(); // (risultato in cache)

$secondService = new NumberService;

$secondService->all();
$secondService->all(); // (risultato in cache, separato da quello di $service)

Questo meccanismo “cache indipendente per punto di chiamata e per istanza” differisce da un semplice helper di memoizzazione come memoize. Per capire il funzionamento occorre guardare le due classi Illuminate\Support\Once e Illuminate\Support\Onceable.

La chiamata in helpers.php

La funzione once() in Illuminate\Support\helpers.php è molto semplice.

use Illuminate\Support\Once;
use Illuminate\Support\Onceable;

if (! function_exists('once')) {
    function once(callable $callback)
    {
        $onceable = Onceable::tryFromTrace(
            debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2),
            $callback,
        );

        return $onceable
            ? Once::instance()->value($onceable)
            : call_user_func($callback);
    }
}

Il punto chiave è che once() di per sé non contiene alcuna cache: assembla un’istanza di Onceable con le informazioni sul chiamante ottenute da debug_backtrace() e delega l’elaborazione alla classe Once.

Onceable — calcolo dell’hash che identifica il punto di chiamata

La classe Onceable ha il compito di calcolare, a partire dalla backtrace, un hash che identifica univocamente “da quale punto è stata effettuata la chiamata”.

class Onceable
{
    public function __construct(
        public string $hash,
        public ?object $object,
        public $callable,
    ) {
        //
    }

    public static function tryFromTrace(array $trace, callable $callable)
    {
        if (! is_null($hash = static::hashFromTrace($trace, $callable))) {
            $object = static::objectFromTrace($trace);

            return new static($hash, $object, $callable);
        }
    }

    protected static function objectFromTrace(array $trace)
    {
        return $trace[1]['object'] ?? null;
    }

    protected static function hashFromTrace(array $trace, callable $callable)
    {
        if (str_contains($trace[0]['file'] ?? '', 'eval()\'d code')) {
            return null;
        }

        $uses = array_map(
            static function (mixed $argument) {
                if ($argument instanceof HasOnceHash) {
                    return $argument->onceHash();
                }

                if (is_object($argument)) {
                    return spl_object_id($argument);
                }

                return $argument;
            },
            $callable instanceof Closure
                ? (new ReflectionClosure($callable))->getClosureUsedVariables()
                : [],
        );

        $class = $callable instanceof Closure
            ? (new ReflectionClosure($callable))->getClosureCalledClass()?->getName()
            : null;

        $class ??= $trace[1]['class'] ?? null;

        return hash('xxh128', sprintf(
            '%s@%s%s:%s (%s)',
            $trace[0]['file'],
            $class ? $class.'@' : '',
            $trace[1]['function'],
            $trace[0]['line'],
            serialize($uses),
        ));
    }
}

Le informazioni da cui deriva l’hash sono percorso del file + nome della classe + nome della funzione + numero di riga + valori delle variabili use della closure. In altre parole, anche una once() chiamata dalla stessa riga viene considerata una cache diversa se cambiano i valori delle variabili in use.

function greet(string $name)
{
    return once(fn () => "Hello, {$name}!");
}

greet('Alice'); // Calcola "Hello, Alice!" e lo mette in cache
greet('Bob');   // $name è diverso, l'hash cambia e viene ricalcolato

Se chiami once() da codice eseguito con eval(), hashFromTrace() restituisce null e non viene effettuata alcuna cache. Si tratta di una misura di sicurezza pensata per l’esecuzione tramite eval, come nelle viste Blade compilate.

object indica “se il chiamante è un metodo di istanza”. $trace[1]['object'] è l’oggetto un livello sopra nella debug_backtrace() (cioè chi ha chiamato once()), quindi contiene $this all’interno di un metodo di istanza e null in un metodo statico o in una funzione globale.

Once — il vero contenitore della cache basato su WeakMap

La conservazione effettiva della cache è a carico di Illuminate\Support\Once.

class Once
{
    protected static ?self $instance = null;

    protected static bool $enabled = true;

    protected function __construct(protected WeakMap $values)
    {
        //
    }

    public static function instance()
    {
        return static::$instance ??= new static(new WeakMap);
    }

    public function value(Onceable $onceable)
    {
        if (! static::$enabled) {
            return call_user_func($onceable->callable);
        }

        $object = $onceable->object ?: $this;

        $hash = $onceable->hash;

        if (! isset($this->values[$object])) {
            $this->values[$object] = [];
        }

        if (array_key_exists($hash, $this->values[$object])) {
            return $this->values[$object][$hash];
        }

        return $this->values[$object][$hash] = call_user_func($onceable->callable);
    }

    public static function enable()
    {
        static::$enabled = true;
    }

    public static function disable()
    {
        static::$enabled = false;
    }

    public static function flush()
    {
        static::$instance = null;
    }
}

La tecnologia chiave è WeakMap. Usa $onceable->object (l’istanza chiamante) come chiave e conserva come valore un array associativo hash → risultato. Quando object è assente (funzione globale o metodo statico), la chiave diventa $this di Once stesso, che di fatto rappresenta un’unica area di cache condivisa in tutto il processo.

Poiché viene usata una WeakMap, quando non esistono più altri riferimenti all’oggetto usato come chiave, anche la cache associata a quell’oggetto diventa candidata alla garbage collection. È un design pensato per evitare memory leak anche quando once() viene chiamato da un gran numero di oggetti.

Uso nei test — enable / disable / flush

Chiamando Once::disable() la cache viene completamente disabilitata e once() esegue la callback ogni volta. È utile nei test quando “vuoi un nuovo valore a ogni chiamata”.

use Illuminate\Support\Once;

beforeEach(function () {
    Once::disable();
});

afterEach(function () {
    Once::enable();
    Once::flush();
});

Once::flush() scarta l’intera cache e ricrea una nuova WeakMap al prossimo accesso. È utile nei test dei comandi Artisan o in ambienti come Octane in cui i processi vengono riutilizzati e non vuoi che la cache sopravviva alle richieste.

PreventsCircularRecursion — un’applicazione di Onceable

Onceable::tryFromTrace() non è esclusiva di once(): viene riutilizzata anche nel trait Illuminate\Database\Eloquent\Concerns\PreventsCircularRecursion di Eloquent. Questo trait serve a “evitare che lo stesso punto di chiamata sullo stesso oggetto rientri nella stessa call stack”.

trait PreventsCircularRecursion
{
    protected static $recursionCache;

    protected function withoutRecursion($callback, $default = null)
    {
        $trace = debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT, 2);

        $onceable = Onceable::tryFromTrace($trace, $callback);

        if (is_null($onceable)) {
            return call_user_func($callback);
        }

        $stack = static::getRecursiveCallStack($this);

        if (array_key_exists($onceable->hash, $stack)) {
            return is_callable($stack[$onceable->hash])
                ? static::setRecursiveCallValue($this, $onceable->hash, call_user_func($stack[$onceable->hash]))
                : $stack[$onceable->hash];
        }

        try {
            static::setRecursiveCallValue($this, $onceable->hash, $default);

            return call_user_func($onceable->callable);
        } finally {
            static::clearRecursiveCallValue($this, $onceable->hash);
        }
    }

    // getRecursiveCallStack() / getRecursionCache() / setRecursiveCallValue()
    // / clearRecursiveCallValue() sono tutti implementati con WeakMap
}

La differenza decisiva rispetto a Once è che nel blocco finally la cache viene ripulita al termine della chiamata. Mentre Once “mette in cache in modo persistente per tutta la durata della richiesta”, PreventsCircularRecursion riutilizza lo stesso meccanismo Onceable per “mettere in cache (in pratica bloccare) solo per la durata della call stack in esecuzione”. Un esempio tipico di uso in un modello Eloquent è la prevenzione dei casi in cui il metodo toArray() o un accessor del modello finisce per riferirsi ricorsivamente a se stesso.

use Illuminate\Database\Eloquent\Concerns\PreventsCircularRecursion;
use Illuminate\Database\Eloquent\Model;

class Category extends Model
{
    use PreventsCircularRecursion;

    public function getPathAttribute(): string
    {
        return $this->withoutRecursion(function () {
            // Nella logica che consulta il path del parent
            // qui viene evitato il loop infinito anche se
            // si verifica un riferimento circolare
            return $this->parent
                ? $this->parent->path.' > '.$this->name
                : $this->name;
        }, default: $this->name);
    }
}

Applicazione nello sviluppo di pacchetti

Nel tuo pacchetto, quando vuoi “eseguire una sola volta per richiesta la stessa chiamata di metodo sulla stessa istanza”, il modo più semplice è usare direttamente once(). Raramente userai Onceable/Once in modo diretto, ma comprendere l’implementazione interna è utile nei seguenti casi:

Quando vuoi controllare il comportamento della cache nei comandi Artisan o nei test con Once::disable() / Once::flush()
Quando vuoi implementare in un tuo trait una cache “per punto di chiamata” o una prevenzione del rientro (puoi usare lo stesso schema di PreventsCircularRecursion)
Quando il risultato di once() non è quello atteso e devi fare debug: capire da quali elementi deriva l’hash (file, classe, funzione, riga, variabili use) rende più semplice individuare la causa

Poiché once() include nell’hash anche le variabili in use della closure, se dentro un ciclo passi una closure che cattura valori diversi a ogni iterazione, ti ritroverai involontariamente con una cache diversa ogni volta e di fatto non avrai alcuna cache. Quando lo usi in un ciclo, verifica che la granularità della chiave di cache sia quella voluta.

Pagine correlate

Helper tap() e trait Tappable

Pattern di implementazione dell’helper tap() che intercala side effect restituendo il valore.

Eloquent Observers ed eventi del modello

Gestione centralizzata tramite eventi e observer dei modelli Eloquent.

Sviluppo con AI

Design pattern

Sviluppo di pacchetti

Struttura dell'applicazione

Novità di Laravel 13

Approfondimento Eloquent

Estensione della validazione

Estensione dell'autenticazione

Sicurezza

Code

Test

Implementazione interna dell'helper once() — Once, Onceable e PreventsCircularRecursion

Cos’è once()

La chiamata in helpers.php

Onceable — calcolo dell’hash che identifica il punto di chiamata

Once — il vero contenitore della cache basato su WeakMap

Uso nei test — enable / disable / flush

PreventsCircularRecursion — un’applicazione di Onceable

Applicazione nello sviluppo di pacchetti

Pagine correlate

Helper tap() e trait Tappable

Eloquent Observers ed eventi del modello

​Cos’è once()

​La chiamata in helpers.php

​Onceable — calcolo dell’hash che identifica il punto di chiamata

​Once — il vero contenitore della cache basato su WeakMap

​Uso nei test — enable / disable / flush

​PreventsCircularRecursion — un’applicazione di Onceable

​Applicazione nello sviluppo di pacchetti

​Pagine correlate

Helper tap() e trait Tappable

Eloquent Observers ed eventi del modello

Cos’è once()

La chiamata in helpers.php

Onceable — calcolo dell’hash che identifica il punto di chiamata

Once — il vero contenitore della cache basato su WeakMap

Uso nei test — enable / disable / flush

PreventsCircularRecursion — un’applicazione di Onceable

Applicazione nello sviluppo di pacchetti

Pagine correlate