Trait Macroable - Knowledge of Laravel

Cos’è il trait Macroable

Il trait Macroable permette di aggiungere dinamicamente metodi a una classe, senza modificarla. Molte delle classi core di Laravel usano questo trait, quindi puoi estenderne le funzionalità senza toccare il codice del core. Il trait vero e proprio si trova in Illuminate\Support\Traits\Macroable. Internamente memorizza le macro registrate nella proprietà statica $macros e le richiama tramite le magic method __call / __callStatic.

Classi che usano Macroable

In Laravel ci sono molte classi che supportano Macroable.

Classe	Uso
`Illuminate\Support\Collection`	Manipolazione delle collection
`Illuminate\Support\Str`	Manipolazione delle stringhe
`Illuminate\Support\Arr`	Manipolazione degli array
`Illuminate\Http\Request`	Richiesta HTTP
`Illuminate\Http\Response`	Risposta HTTP
`Illuminate\Routing\Router`	Router
`Illuminate\Routing\ResponseFactory`	Response factory
`Illuminate\Database\Schema\Blueprint`	Schema builder
`Illuminate\Pipeline\Pipeline`	Pipeline
`Illuminate\Testing\TestResponse`	Test response

macro() — aggiungere un metodo

A macro() passi come primo argomento il nome del metodo e come secondo argomento una closure.

use Illuminate\Support\Collection;

Collection::macro('toSentence', function (string $separator = ', ') {
    /** @var Collection $this */
    return $this->implode($separator);
});

$result = collect(['mela', 'arancia', 'uva'])->toSentence();
// 'mela, arancia, uva'

Il $this all’interno della closure viene collegato all’istanza che ha invocato la macro. In questo modo puoi accedere direttamente a proprietà e metodi della classe.

mixin() — aggiungere più metodi in blocco

Per registrare tante macro insieme usa mixin(). Tutti i metodi public / protected della classe mixin vengono registrati come macro.

namespace App\Mixins;

class CollectionMixin
{
    public function toCsv(): Closure
    {
        return function (string $separator = ',') {
            /** @var \Illuminate\Support\Collection $this */
            return $this->map(function ($item) use ($separator) {
                return is_array($item) ? implode($separator, $item) : $item;
            })->implode("\n");
        };
    }

    public function filterEmpty(): Closure
    {
        return function () {
            /** @var \Illuminate\Support\Collection $this */
            return $this->filter(fn ($item) => ! empty($item))->values();
        };
    }

    public function groupByFirst(): Closure
    {
        return function (string $key) {
            /** @var \Illuminate\Support\Collection $this */
            return $this->groupBy(fn ($item) => $item[$key][0] ?? '');
        };
    }
}

I metodi del mixin() devono restituire la closure da registrare come macro. Il valore restituito dal metodo diventa l’implementazione della macro.

Registrazione nel service provider

Le macro devono essere registrate all’avvio dell’applicazione. Il metodo boot() di AppServiceProvider è il posto giusto.

namespace App\Providers;

use App\Mixins\CollectionMixin;
use Illuminate\Support\Collection;
use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Str;
use Illuminate\Http\Request;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // registra una singola macro
        Collection::macro('toSentence', function (string $separator = ', ') {
            return $this->implode($separator);
        });

        // registra un mixin in blocco
        Collection::mixin(new CollectionMixin);

        // macro per Str
        Str::macro('initials', function (string $name) {
            return collect(explode(' ', $name))
                ->map(fn ($word) => strtoupper($word[0]))
                ->implode('');
        });
    }
}

Casi d’uso pratici

Estendere Collection

L’aggiunta di metodi personalizzati alle collection è l’uso più comune.

// metodi statistici per collection numeriche
Collection::macro('median', function () {
    $sorted = $this->sort()->values();
    $count = $sorted->count();

    if ($count === 0) {
        return null;
    }

    $middle = (int) floor($count / 2);

    if ($count % 2 === 0) {
        return ($sorted->get($middle - 1) + $sorted->get($middle)) / 2;
    }

    return $sorted->get($middle);
});

$median = collect([3, 1, 4, 1, 5, 9, 2, 6])->median();
// 3.5

// macro che restituisce una collection con informazioni di paginazione
Collection::macro('paginateArray', function (int $perPage = 15, int $page = 1) {
    return $this->slice(($page - 1) * $perPage, $perPage)->values();
});

Estendere la classe Str

// conteggio caratteri (compatibile multi-byte)
Str::macro('mbLength', function (string $value) {
    return mb_strlen($value, 'UTF-8');
});

// converte snake_case in notazione a punti
Str::macro('toDotNotation', function (string $value) {
    return str_replace('_', '.', $value);
});

$length = Str::mbLength('ciao'); // 4
$dot = Str::toDotNotation('user_profile_name'); // 'user.profile.name'

Estendere la classe Request

use Illuminate\Http\Request;

Request::macro('isFromMobile', function () {
    /** @var Request $this */
    $userAgent = $this->userAgent() ?? '';

    return preg_match('/Mobile|Android|iPhone|iPad/i', $userAgent) === 1;
});

Request::macro('preferredLocale', function (array $available = ['it', 'en']) {
    /** @var Request $this */
    foreach ($this->getLanguages() as $lang) {
        $short = substr($lang, 0, 2);
        if (in_array($short, $available)) {
            return $short;
        }
    }

    return $available[0] ?? 'en';
});

// utilizzo nel controller
public function index(Request $request)
{
    if ($request->isFromMobile()) {
        return response()->json($this->getMobileData());
    }

    $locale = $request->preferredLocale(['it', 'en', 'zh']);
    // ...
}

Estendere Blueprint (migrazioni)

Se raggruppi in macro le definizioni delle colonne, mantieni un design del DB uniforme.

use Illuminate\Database\Schema\Blueprint;

Blueprint::macro('addTimestampsWithTimezone', function () {
    /** @var Blueprint $this */
    $this->timestampsTz();
    $this->softDeletesTz();
});

Blueprint::macro('addUserTracking', function () {
    /** @var Blueprint $this */
    $this->foreignId('created_by')->nullable()->constrained('users')->nullOnDelete();
    $this->foreignId('updated_by')->nullable()->constrained('users')->nullOnDelete();
});

// utilizzo in una migrazione
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->addTimestampsWithTimezone();
    $table->addUserTracking();
});

Estendere le test response

Puoi aggiungere metodi di assertion specifici per i test.

use Illuminate\Testing\TestResponse;

TestResponse::macro('assertPaginated', function () {
    /** @var TestResponse $this */
    return $this->assertJsonStructure([
        'data',
        'meta' => ['current_page', 'last_page', 'per_page', 'total'],
        'links' => ['first', 'last', 'prev', 'next'],
    ]);
});

TestResponse::macro('assertApiSuccess', function () {
    /** @var TestResponse $this */
    return $this->assertOk()->assertJsonPath('success', true);
});

// utilizzo nei test
$this->getJson('/api/posts')->assertPaginated();
$this->postJson('/api/orders', $data)->assertApiSuccess();

hasMacro() — verificare l’esistenza di una macro

use Illuminate\Support\Collection;

if (Collection::hasMacro('toSentence')) {
    $result = collect(['a', 'b'])->toSentence();
}

flushMacros() — resettare le macro

Utile quando vuoi resettare le macro nei test.

use Illuminate\Support\Collection;

// reset dentro un test
Collection::flushMacros();

flushMacros() rimuove tutte le macro della classe. Talvolta viene chiamato in tearDown() per garantire l’indipendenza tra i test, ma attenzione: cancella anche macro registrate da altri test.

Macro statiche

Le macro funzionano non solo come metodi d’istanza ma anche come metodi statici. Sono gestite da __callStatic.

Str::macro('randomHex', function (int $length = 8) {
    return substr(bin2hex(random_bytes($length)), 0, $length);
});

// chiamata statica
$hex = Str::randomHex(16);

Usare Macroable nelle tue classi

Puoi integrare Macroable anche in classi che scrivi tu.

namespace App\Services;

use Illuminate\Support\Traits\Macroable;

class ReportBuilder
{
    use Macroable;

    protected array $sections = [];

    public function addSection(string $name, callable $content): static
    {
        $this->sections[$name] = $content;

        return $this;
    }

    public function build(): array
    {
        return array_map(fn ($fn) => $fn(), $this->sections);
    }
}

// estensione nel service provider
ReportBuilder::macro('withSummary', function (string $title) {
    /** @var ReportBuilder $this */
    return $this->addSection('summary', fn () => [
        'title' => $title,
        'generated_at' => now()->toIso8601String(),
    ]);
});

// esempio d'uso
$report = app(ReportBuilder::class)
    ->withSummary('Report mensile')
    ->addSection('data', fn () => ['rows' => 42])
    ->build();

Dettagli dell’implementazione interna

// implementazione di __call (chiamata a metodo d'istanza)
public function __call($method, $parameters)
{
    if (! static::hasMacro($method)) {
        throw new BadMethodCallException(sprintf(
            'Method %s::%s does not exist.', static::class, $method
        ));
    }

    $macro = static::$macros[$method];

    if ($macro instanceof Closure) {
        // con bindTo collega $this all'istanza
        $macro = $macro->bindTo($this, static::class);
    }

    return $macro(...$parameters);
}

La closure viene collegata all’istanza con Closure::bindTo(). In questo modo $this fa riferimento all’oggetto che ha chiamato la macro. Per elementi non closure (ad esempio oggetti invokable) il bind non viene eseguito.

Per ottenere supporto dall’IDE puoi definire le annotazioni delle macro con un Docblock che usa @mixin, oppure generare automaticamente un file helper con il pacchetto Laravel IdeHelper.

Prossimi passi

Pattern Pipeline

Impara a comporre in serie più step di elaborazione con il pattern pipeline.

​Cos’è il trait Macroable

​Classi che usano Macroable

​macro() — aggiungere un metodo

​mixin() — aggiungere più metodi in blocco

​Registrazione nel service provider

​Casi d’uso pratici

​Estendere Collection

​Estendere la classe Str

​Estendere la classe Request

​Estendere Blueprint (migrazioni)

​Estendere le test response

​hasMacro() — verificare l’esistenza di una macro

​flushMacros() — resettare le macro

​Macro statiche

​Usare Macroable nelle tue classi

​Dettagli dell’implementazione interna

​Prossimi passi

Pattern Pipeline

Cos’è il trait Macroable

Classi che usano Macroable

macro() — aggiungere un metodo

mixin() — aggiungere più metodi in blocco

Registrazione nel service provider

Casi d’uso pratici

Estendere Collection

Estendere la classe Str

Estendere la classe Request

Estendere Blueprint (migrazioni)

Estendere le test response

hasMacro() — verificare l’esistenza di una macro

flushMacros() — resettare le macro

Macro statiche

Usare Macroable nelle tue classi

Dettagli dell’implementazione interna

Prossimi passi