Trait Macroable - Knowledge of Laravel

Qu’est-ce que le trait Macroable

Le trait Macroable permet d’ajouter dynamiquement des méthodes à une classe après coup, sans la modifier. Beaucoup de classes du cœur de Laravel l’utilisent, ce qui vous permet d’étendre les fonctionnalités sans toucher au code du cœur. L’implémentation réside dans Illuminate\Support\Traits\Macroable. En interne, les macros enregistrées sont stockées dans la propriété statique $macros, et sont invoquées via les méthodes magiques __call / __callStatic.

Classes utilisant Macroable

Laravel comporte de nombreuses classes compatibles Macroable.

Classe	Rôle
`Illuminate\Support\Collection`	Manipulation de collections
`Illuminate\Support\Str`	Manipulation de chaînes
`Illuminate\Support\Arr`	Manipulation de tableaux
`Illuminate\Http\Request`	Requêtes HTTP
`Illuminate\Http\Response`	Réponses HTTP
`Illuminate\Routing\Router`	Routeur
`Illuminate\Routing\ResponseFactory`	Fabrique de réponses
`Illuminate\Database\Schema\Blueprint`	Schema Builder
`Illuminate\Pipeline\Pipeline`	Pipeline
`Illuminate\Testing\TestResponse`	Réponse de test

macro() — ajouter une méthode

Passez le nom de la méthode en premier argument et une closure en second à macro().

use Illuminate\Support\Collection;

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

$result = collect(['pomme', 'orange', 'raisin'])->toSentence();
// 'pomme, orange, raisin'

Le $this de la closure est lié à l’instance qui a appelé la macro. Vous pouvez ainsi accéder directement aux propriétés et méthodes de la classe.

mixin() — ajouter plusieurs méthodes d’un coup

Pour enregistrer beaucoup de macros à la fois, utilisez mixin(). Toutes les méthodes public / protected de la classe de mixin sont enregistrées comme macros.

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] ?? '');
        };
    }
}

Les méthodes de mixin() doivent renvoyer la closure à enregistrer comme macro. C’est la valeur de retour de la méthode qui devient l’implémentation de la macro.

Enregistrement dans un service provider

Les macros doivent être enregistrées au démarrage de l’application. La méthode boot() d’AppServiceProvider est l’endroit approprié.

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
    {
        // Enregistrer une seule macro
        Collection::macro('toSentence', function (string $separator = ', ') {
            return $this->implode($separator);
        });

        // Enregistrer un mixin en une passe
        Collection::mixin(new CollectionMixin);

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

Cas d’utilisation pratiques

Étendre les collections

Ajouter des méthodes personnalisées aux collections est l’usage le plus courant.

// Méthode statistique pour une collection de nombres
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 renvoyant une collection paginée
Collection::macro('paginateArray', function (int $perPage = 15, int $page = 1) {
    return $this->slice(($page - 1) * $perPage, $perPage)->values();
});

Étendre la classe Str

// Compter les caractères en tenant compte du multi-octet
Str::macro('mbLength', function (string $value) {
    return mb_strlen($value, 'UTF-8');
});

// Convertir un snake_case en notation pointée
Str::macro('toDotNotation', function (string $value) {
    return str_replace('_', '.', $value);
});

$length = Str::mbLength('こんにちは'); // 5
$dot = Str::toDotNotation('user_profile_name'); // 'user.profile.name'

Étendre 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 = ['fr', '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';
});

// Utilisation dans un contrôleur
public function index(Request $request)
{
    if ($request->isFromMobile()) {
        return response()->json($this->getMobileData());
    }

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

Étendre Blueprint (migrations)

Regrouper des définitions de colonnes sous forme de macros permet de garder une conception de base de données cohérente.

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();
});

// Utilisation dans une migration
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->addTimestampsWithTimezone();
    $table->addUserTracking();
});

Étendre les réponses de test

Vous pouvez ajouter des méthodes d’assertion propres aux tests.

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);
});

// Utilisation dans les tests
$this->getJson('/api/posts')->assertPaginated();
$this->postJson('/api/orders', $data)->assertApiSuccess();

hasMacro() — vérifier l’existence d’une macro

use Illuminate\Support\Collection;

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

flushMacros() — réinitialiser les macros

À utiliser pour réinitialiser les macros dans les tests.

use Illuminate\Support\Collection;

// Réinitialisation dans un test
Collection::flushMacros();

flushMacros() supprime toutes les macros de la classe. On peut l’appeler dans tearDown() pour préserver l’indépendance des tests, mais attention : les macros enregistrées par d’autres tests sont aussi supprimées.

Macros statiques

Les macros fonctionnent aussi bien comme méthodes d’instance que comme méthodes statiques. C’est __callStatic qui les gère.

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

// Appel statique
$hex = Str::randomHex(16);

Utiliser le trait Macroable dans vos propres classes

Vous pouvez également intégrer Macroable à vos classes.

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);
    }
}

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

// Exemple d'utilisation
$report = app(ReportBuilder::class)
    ->withSummary('Rapport mensuel')
    ->addSection('data', fn () => ['rows' => 42])
    ->build();

Détails de l’implémentation interne

// Implémentation de __call (appel de méthode d'instance)
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) {
        // Liaison de $this à l'instance via bindTo
        $macro = $macro->bindTo($this, static::class);
    }

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

La closure est liée à l’instance via Closure::bindTo(). Ainsi, $this pointe vers l’objet appelant. Pour d’autres types (objets invokables, par exemple), aucune liaison n’est effectuée.

Pour obtenir la prise en charge de l’IDE, vous pouvez déclarer les macros via une annotation @mixin dans un bloc doc, ou utiliser le package Laravel IdeHelper pour générer automatiquement un fichier d’aide.

Étapes suivantes

Pattern Pipeline

Découvrez comment enchaîner en série plusieurs étapes de traitement grâce au pattern pipeline.

​Qu’est-ce que le trait Macroable

​Classes utilisant Macroable

​macro() — ajouter une méthode

​mixin() — ajouter plusieurs méthodes d’un coup

​Enregistrement dans un service provider

​Cas d’utilisation pratiques

​Étendre les collections

​Étendre la classe Str

​Étendre la classe Request

​Étendre Blueprint (migrations)

​Étendre les réponses de test

​hasMacro() — vérifier l’existence d’une macro

​flushMacros() — réinitialiser les macros

​Macros statiques

​Utiliser le trait Macroable dans vos propres classes

​Détails de l’implémentation interne

​Étapes suivantes

Pattern Pipeline

Qu’est-ce que le trait Macroable

Classes utilisant Macroable

macro() — ajouter une méthode

mixin() — ajouter plusieurs méthodes d’un coup

Enregistrement dans un service provider

Cas d’utilisation pratiques

Étendre les collections

Étendre la classe Str

Étendre la classe Request

Étendre Blueprint (migrations)

Étendre les réponses de test

hasMacro() — vérifier l’existence d’une macro

flushMacros() — réinitialiser les macros

Macros statiques

Utiliser le trait Macroable dans vos propres classes

Détails de l’implémentation interne

Étapes suivantes