Laravel Under The Hood - The Magic of Macros

Hello 👋

How often have you wished for a method that doesn't exist on collections or string helpers? You start chaining methods, only to hit a wall when one of them turns out to be missing. Honestly, it's understandable; frameworks, you know, are a one-size-fits-all thing. I found myself in this situation multiple times.

Every time, before diving into how to extend the framework, I check to see if what I want to extend is macroable or not. But what does that mean? That's exactly what we'll be exploring!

WTF Are Macros? 🍏

Let's say we have this JWT:

$jwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

And we need to extract the headers:

str($jwt)
    ->before('.')
    ->fromBase64()
    ->fromJson(); // does not exist 😞

//  BadMethodCallException  Method Illuminate\Support\Stringable::fromJson does not exist.

The fromJson() doesn't exist 😔 Sure, one could simply do:

json_decode(str($jwt)->before('.')->fromBase64());

But where's the fun in that? Plus, it is my article 🤷

So, we need a way to extend the Stringable class. There are a few ways to do this, but Laravel thought ahead, it knew that developers might want to add custom methods, so it made the class macroable, or as I like to call it, extendable.

If you inspect the Illuminate\Support\Stringable class, you'll see it uses a Macroable trait.

Let's go ahead and extend the class. In the AppServiceProvider, add the following:

<?php

namespace App\Providers;

use Illuminate\Support\Stringable;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Stringable::macro('fromJson', function (bool $associative = true) {
            return json_decode($this->value, $associative);
        });
    }
}

Now, let's rerun the code:

str($jwt)
    ->before('.')
    ->fromBase64()
    ->fromJson();

// ["alg" => "HS256", "typ" => "JWT"]

It works perfectly 🎉 But now, you might be wondering, how did this work? And what exactly is $this->value? What in the Harry Potter is going on?

Unveiling the Magic 🪄

We know that the Stringable class uses the Macroable trait, which provides the macro() method. Let's take a closer look at what it does:

// src/Illuminate/Macroable/Traits/Macroable.php

/**
 * Register a custom macro.
 *
 * @param  string  $name
 * @param  object|callable  $macro
 *
 * @param-closure-this static  $macro
 *
 * @return void
 */
public static function macro($name, $macro)
{
    static::$macros[$name] = $macro;
}

It's pretty straightforward; it just saves the callback to a static macros array. Now, if we inspect the trait further, we will find the __call method, which is triggered every time a non-existent method is called. In our case, that's fromJson(). Let's dive in:

/**
 * Dynamically handle calls to the class.
 *
 * @param  string  $method
 * @param  array  $parameters
 * @return mixed
 *
 * @throws \BadMethodCallException
 */
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) {
        $macro = $macro->bindTo($this, static::class);
    }

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

First, it checks if a macro is registered, which is the case with fromJson(), it then fetches the callback (or object) from the macros array. Now, for the magic trick; if the macro is a closure (as in our case), it calls bindTo() which essentially tells the closure that $this should refer to whatever is passed as the first argument. In this case, it is the Stringable instance, which happens to have the $value attribute.

// $this here is the stringable
// $this inside the closure is now referencing the stringable class
$macro->bindTo($this, static::class);

And this is why we can do $this->value.

We Can Do Better: Mixins 🧩

There is one more thing I want to show you! When we extend the same class a couple of times, the service provider might get messy very quickly. We can extract all our custom macros to a class called a Mixin.

Let's create a StringableMixin:

<?php

namespace App\Macros;

use Closure;

class StringableMixin
{
    public function fromJson(): Closure
    {
        return function (bool $associative = true) {
            json_decode($this->value, $associative);
        };
    }

    // Add more macros here as needed
}

Now, in AppServiceProvider, we can register this mixin:

use App\Macros\StringableMixin;
use Illuminate\Support\Stringable;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Stringable::mixin(new StringableMixin);
    }
}

And that's it! Now, we can do:

str($jwt)
    ->before('.')
    ->fromBase64()
    ->fromJson();

Which is basically the same, just a bit cleaner.

If you are curious about how this works, the mixin() method on the Macroable trait uses the reflection API. It retrieves all the public methods from the Mixin class, expects each to return a closure, and then registers the closure as a macro just like we have seen earlier.

The Poor IDE 🥲

Well, as you have seen, there is a lot of magic going on, and the IDE wouldn't know about the defined macros. If you're working within a team, other developers won't know about these macros either, which is not good. Luckily, there are tools to help you with that. A free and open-source option is the Laravel IDE helper package.

You can install the package and generate the _ide_helper.php file, and you should be good to go.

And So It Ends..

Our example is fairly simple, but you can push macros much further than this, as most of the common classes Laravel ships with are macroable. For instance, you can add a new apiResponse() macro, or anything that you feel is very common in your app's logic and is being repeated more than it should be. But don't overdo it. Macros add a new layer of complexity, and when working in a team, they could be confusing.

So, whenever you feel something is missing from your application, but not from the framework itself, use macros 🪄