Trait Macroable - Knowledge of Laravel

Qué es el trait Macroable

El trait Macroable es un mecanismo que permite añadir métodos dinámicamente a una clase después de haberla escrito, sin modificarla. Muchas clases del core de Laravel lo utilizan, así que puedes extender sus funcionalidades sin tocar el código del framework. La implementación real del trait está en Illuminate\Support\Traits\Macroable. Internamente guarda las macros registradas en una propiedad estática $macros y las invoca a través de los métodos mágicos __call / __callStatic.

Clases que usan Macroable

Laravel tiene muchas clases compatibles con Macroable.

Clase	Uso
`Illuminate\Support\Collection`	Operaciones sobre colecciones.
`Illuminate\Support\Str`	Operaciones sobre cadenas.
`Illuminate\Support\Arr`	Operaciones sobre arrays.
`Illuminate\Http\Request`	Peticiones HTTP.
`Illuminate\Http\Response`	Respuestas HTTP.
`Illuminate\Routing\Router`	Router.
`Illuminate\Routing\ResponseFactory`	Factory de respuestas.
`Illuminate\Database\Schema\Blueprint`	Constructor de esquema.
`Illuminate\Pipeline\Pipeline`	Pipeline.
`Illuminate\Testing\TestResponse`	Respuestas en tests.

macro() — añadir un método

Al macro() le pasas el nombre del método como primer argumento y un closure como segundo.

use Illuminate\Support\Collection;

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

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

El $this dentro del closure queda vinculado a la instancia que invocó la macro. Así puedes acceder directamente a las propiedades y métodos de la clase.

mixin() — añadir varios métodos a la vez

Para registrar muchas macros en bloque, usa mixin(). Todos los métodos public / protected de la clase mixin se registran como 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] ?? '');
        };
    }
}

Los métodos del mixin() deben devolver el closure que se registrará como macro. El valor devuelto por el método es la implementación real de la macro.

Registro en un service provider

Las macros deben registrarse durante el arranque de la aplicación. El sitio adecuado es el método boot() de AppServiceProvider.

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

        // Registro de un mixin completo
        Collection::mixin(new CollectionMixin);

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

Casos de uso prácticos

Extensión de Collection

Añadir métodos personalizados a las colecciones es el caso más habitual.

// Método estadístico para colecciones numéricas
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 que devuelve la colección paginada
Collection::macro('paginateArray', function (int $perPage = 15, int $page = 1) {
    return $this->slice(($page - 1) * $perPage, $perPage)->values();
});

Extensión de la clase Str

// Contar caracteres multibyte
Str::macro('mbLength', function (string $value) {
    return mb_strlen($value, 'UTF-8');
});

// Convertir snake_case a notación con puntos
Str::macro('toDotNotation', function (string $value) {
    return str_replace('_', '.', $value);
});

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

Extensión de la clase 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 = ['es', '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';
});

// Uso en un controlador
public function index(Request $request)
{
    if ($request->isFromMobile()) {
        return response()->json($this->getMobileData());
    }

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

Extensión de Blueprint (migraciones)

Al convertir en macros las definiciones de columnas del esquema, mantienes un diseño de BD consistente.

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

// Uso en una migración
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->addTimestampsWithTimezone();
    $table->addUserTracking();
});

Extensión de TestResponse

Puedes añadir métodos de assertion específicos para 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);
});

// Uso en un test
$this->getJson('/api/posts')->assertPaginated();
$this->postJson('/api/orders', $data)->assertApiSuccess();

hasMacro() — comprobar si existe una macro

use Illuminate\Support\Collection;

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

flushMacros() — resetear las macros

Se usa cuando quieres resetear las macros en un test.

use Illuminate\Support\Collection;

// Reset dentro del test
Collection::flushMacros();

flushMacros() elimina todas las macros de esa clase. A veces se llama en tearDown() para mantener aisladas las pruebas, pero también borrará las macros registradas por otros tests, así que hay que tener cuidado.

Macros estáticas

Las macros funcionan también como métodos estáticos, no solo como métodos de instancia. Las gestiona __callStatic.

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

// Llamada estática
$hex = Str::randomHex(16);

Usar Macroable en tus propias clases

Puedes incorporar Macroable también a tus propias clases.

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

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

// Ejemplo de uso
$report = app(ReportBuilder::class)
    ->withSummary('Informe mensual')
    ->addSection('data', fn () => ['rows' => 42])
    ->build();

Detalles de la implementación interna

// Implementación de __call (llamadas a métodos de instancia)
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) {
        // bindTo vincula $this a la instancia
        $macro = $macro->bindTo($this, static::class);
    }

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

El closure se vincula a la instancia con Closure::bindTo(). Así, dentro de la macro, $this apunta al objeto que la invocó. Si el macro no es un closure (por ejemplo, un objeto invokable), no se realiza el bind.

Para obtener soporte del IDE, define anotaciones de las macros con @mixin en el docblock o utiliza el paquete Laravel IdeHelper para generar los archivos helper automáticamente.

Próximos pasos

Patrón Pipeline

Aprende cómo componer varios pasos de procesamiento en serie usando el patrón Pipeline.

​Qué es el trait Macroable

​Clases que usan Macroable

​macro() — añadir un método

​mixin() — añadir varios métodos a la vez

​Registro en un service provider

​Casos de uso prácticos

​Extensión de Collection

​Extensión de la clase Str

​Extensión de la clase Request

​Extensión de Blueprint (migraciones)

​Extensión de TestResponse

​hasMacro() — comprobar si existe una macro

​flushMacros() — resetear las macros

​Macros estáticas

​Usar Macroable en tus propias clases

​Detalles de la implementación interna

​Próximos pasos

Patrón Pipeline

Qué es el trait Macroable

Clases que usan Macroable

macro() — añadir un método

mixin() — añadir varios métodos a la vez

Registro en un service provider

Casos de uso prácticos

Extensión de Collection

Extensión de la clase Str

Extensión de la clase Request

Extensión de Blueprint (migraciones)

Extensión de TestResponse

hasMacro() — comprobar si existe una macro

flushMacros() — resetear las macros

Macros estáticas

Usar Macroable en tus propias clases

Detalles de la implementación interna

Próximos pasos