0x55aa
← Back to Blog

Laravel Macros: Stop Monkey-Patching and Start Extending Like a Pro 🐒

•6 min read
"laravel""php""web-dev""architecture"

Laravel Macros: Stop Monkey-Patching and Start Extending Like a Pro 🐒

Every Laravel developer has been there. You're deep in a project, you reach for $collection->someMethod(), and it doesn't exist. So you write a helper function, stick it in a helpers.php somewhere, and three months later nobody knows what formatForExport($collection) does or where it lives.

There's a better way. And it's been sitting in the framework this whole time.

What the Heck Is a Macro? 🤔

A macro in Laravel is a way to add your own methods to classes you don't own — think Collection, Builder, Request, Response, Stringable, even Carbon — without touching vendor code or subclassing everything.

It works because those classes use the Macroable trait. When you call a method that doesn't exist, the trait's __call magic kicks in and checks a static registry of custom methods you've registered.

Think of it like a plugin system built directly into the framework. Chef's kiss. 🤌

The Basic Pattern 🎯

// In AppServiceProvider::boot()
Collection::macro('toAssoc', function () {
    return $this->mapWithKeys(fn ($item) => [$item['key'] => $item['value']]);
});

// Anywhere in your app
$result = collect([
    ['key' => 'name', 'value' => 'Anuragh'],
    ['key' => 'role', 'value' => 'Tech Lead'],
])->toAssoc();
// ['name' => 'Anuragh', 'role' => 'Tech Lead'] ✨

You defined it once. Now it works everywhere Collection is used. No imports. No helper functions floating in the void.

Real Talk: How I Actually Use This 💬

In production systems I've built — specifically a multi-vendor e-commerce backend at Cubet — we had a recurring pattern where we needed to pluck specific fields from API responses and reformat them before caching. Every controller was copy-pasting the same 5-line transformation.

Before (the embarrassing version):

// ProductController.php
$formatted = $products->map(fn ($p) => [
    'id'    => $p->id,
    'label' => "{$p->name} ({$p->sku})",
    'price' => number_format($p->price / 100, 2),
]);

// OrderController.php — literally the same thing 3 files later
$formatted = $items->map(fn ($p) => [
    'id'    => $p->id,
    'label' => "{$p->name} ({$p->sku})",
    'price' => number_format($p->price / 100, 2),
]);

DRY? More like WET (Write Everything Twice). 😅

After (the macro version):

// In AppServiceProvider::boot()
Collection::macro('toProductOptions', function () {
    return $this->map(fn ($p) => [
        'id'    => $p->id,
        'label' => "{$p->name} ({$p->sku})",
        'price' => number_format($p->price / 100, 2),
    ]);
});

// Every controller, every time
$formatted = $products->toProductOptions();

Now when the product manager says "add the category to the label" (and they will), you fix it in exactly one place.

The Macroable Classes You Care About 📦

Laravel ships with Macroable baked into the classes you use most:

  • Illuminate\Support\Collection — add custom collection transforms
  • Illuminate\Database\Eloquent\Builder — add custom query scopes globally
  • Illuminate\Http\Request — add convenience methods for extracting data
  • Illuminate\Http\Response / JsonResponse — add response formatting helpers
  • Illuminate\Support\Str / Stringable — add custom string transforms
  • Illuminate\Routing\Router — add custom routing methods
  • Illuminate\Filesystem\Filesystem — add file operation helpers

That's basically your entire application's surface area.

Pro Tip: The Builder Macro That Saved a Sprint ⚡

As a Technical Lead, I've learned that query patterns repeated across models are a code smell. A pattern that saved us in a real project was a Builder macro for soft-deleted audit queries:

Builder::macro('withoutTestData', function () {
    return $this->where('is_test', false);
});

// Now every single query can use it
Order::withoutTestData()->where('status', 'completed')->get();
User::withoutTestData()->recent()->get();

Before this, devs kept forgetting to add ->where('is_test', false). After this? It's a first-class method with IDE autocomplete support (more on that in a sec).

Organising Macros: Don't Dump Everything in AppServiceProvider 🗂️

When I first discovered macros I made the classic mistake — shoved 30 of them into AppServiceProvider::boot(). It became a garbage dump.

The clean approach: dedicated macro service providers.

// app/Providers/CollectionMacroServiceProvider.php
class CollectionMacroServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Collection::macro('toAssoc', ...);
        Collection::macro('toProductOptions', ...);
        Collection::macro('paginateArray', ...);
    }
}

// app/Providers/RequestMacroServiceProvider.php
class RequestMacroServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Request::macro('bearerUser', function () {
            return auth()->user() ?? abort(401);
        });
    }
}

Register them in config/app.php providers array. Now your macros are organised, testable, and won't make the next developer cry.

IDE Support: The @mixin Trick 🧠

"But Anuragh, my IDE shows red squiggles everywhere!" — every developer who just discovered macros.

Fix it with a helper file for your IDE:

// ide-helpers/CollectionMacros.php (not autoloaded in production)
/**
 * @mixin \Illuminate\Support\Collection
 */
class CollectionMacros
{
    public function toAssoc(): Collection {}
    public function toProductOptions(): Collection {}
}

Or better, use the laravel-ide-helper package — it generates these stubs automatically. Your team will thank you.

Bonus Tips 🎁

Tip 1: Closures vs. invokable classes

For complex macros, extract them:

// Cleaner for multi-line logic
Collection::macro('toProductOptions', new ToProductOptionsMacro());

Tip 2: Check before you define

if (!Collection::hasMacro('toAssoc')) {
    Collection::macro('toAssoc', fn () => ...);
}

Useful when packages also add macros and you want to avoid conflicts.

Tip 3: Macros can call $this

Inside a macro closure, $this refers to the instance. So $this->map(), $this->filter() — all the regular methods are available. You're writing real methods, just registered dynamically.

When NOT to Use Macros 🚫

Macros are great, but they're not a silver bullet:

  • Don't use them for complex business logic that deserves its own class
  • Don't add macros for one-off operations — just write the code inline
  • Don't name them things that might conflict with future Laravel additions (prefix your macro names in packages!)

The TL;DR 🚀

Laravel Macros let you add your own methods to Collection, Builder, Request, and other core classes. Define once, use everywhere. No helper function graveyards, no repeated transformations, no "where did this come from?" moments at 2am.

Register them in dedicated MacroServiceProvider classes. Document them with IDE helper stubs. Test them like any other unit.

A pattern that saved us in a real project — repeatedly — and once you start thinking in macros, you'll wonder how you ever lived without them.

Got a macro you swear by? Share it on LinkedIn — I'm always collecting new ones.

Want more Laravel deep dives? Give this blog a star on GitHub.

Now go extend the framework. Responsibly. 🐒⚡

← Back to all posts