DEV Community: Doeke Norg

Exploring Coroutines in PHP

Doeke Norg — Sat, 05 Jul 2025 09:41:22 +0000

The term "coroutine" often comes up when talking about asynchronous or non-blocking code, but what does it actually mean? In this post, we will explore coroutines as a concept and see how PHP supports them through Generators and Fibers. Whether you're building pipelines, CLI tools, or preparing to dive into concurrency, understanding coroutines is an essential first step.

What are Coroutines?

A coroutine is a function. However, where a regular function continuously runs from top to bottom until it is finished, a coroutine can pause/suspend itself and be resumed. It can return a value every time it suspends, and receive a value when it is resumed. While the coroutine is suspended and not yet finished, it will hold on to the current state it is in.

Suspend and resume

Once a coroutine is executed, it will start performing its task. During the execution, the coroutine can suspend itself, handing over control to the rest of the code. This means that the suspension of the execution can only originate inside the coroutine. It has to voluntarily release control (dare I say it should yield? Spoilers!)

After that, the fate of the coroutine is in the hands of the rest of the code. It cannot resume itself. The coroutine will have to be explicitly given control back with the instruction to resume. Until then, it waits while the rest of the code runs.

Note: The other code could continue and never call the coroutine again, leaving it in its suspended state. Once the other code finishes, the program ends. It will not have to wait for the coroutine to finish.

Return and receive values

When a coroutine suspends its execution, it can provide a value to go with that. This makes the suspension like a return statement. And because a coroutine can resume and suspend multiple times, it can return multiple values.

A coroutine can also receive a value when it is resumed. It will have this value available immediately after resuming and can act on it. This makes a coroutine bi-directional.

While returning and receiving values is possible in a coroutine, it is not required. A coroutine can just suspend its execution without doing anything else.

Hold its state

When a regular function is called, any internal parameters it creates to hold values are released from memory as soon as the function finishes. You can call a function multiple times, but the values from the first call will not be available in the function the second time it is called.

Since a coroutine is a function that can suspend and resume, values that are scoped inside the coroutine stay available while it hasn't finished. When the coroutine regains control and resumes its execution, it can still reference those variables. Only when the coroutine is finished are its internal variables released from memory.

Types of coroutines

Coroutines come in a few flavors. They can either be symmetrical or asymmetrical, and stackless or stackful.

Asymmetrical vs. Symmetrical Coroutines

When it comes to suspending its execution, as we now know, the control must be released by the coroutine. An asymmetrical coroutine can only release control back to the code that called the coroutine. A symmetrical coroutine can choose to whom it releases control, either a different coroutine or the original caller.

Let's imagine coroutines are playing a game of hot potato.

In an asymmetrical game, the main program always passes the potato to a coroutine, which can only toss it back to the caller, not to another coroutine.

In a symmetrical game, coroutines can pass the potato among themselves, deciding who goes next. The main program will start and end the game, but doesn’t have to control every pass.

Note: Even in a symmetrical coroutine situation, at some point, the control must be released back to the original calling code for the program to finish. Otherwise, it would hang indefinitely.

Stackless vs. Stackful Coroutines

Finally, there are stackless and stackful coroutines. The difference lies in where they are allowed to suspend execution.

A Stackless Coroutine can only yield control from its outermost function. While it can call other (nested) functions, it cannot suspend from within them.

A Stackful Coroutine, on the other hand, can suspend from within nested functions. It will release its control right there, and when it is resumed, it will resume from that exact location.

As a result, stackful coroutines are more flexible, since they allow suspension inside helper functions. This can reduce verbosity and keep the focus on the core logic.

How are coroutines implemented in PHP?

Now that we know the conditions that can make up a coroutine, let's see how PHP implements or facilitates coroutines.

Coroutines using Generators

The first introduction of Coroutines in PHP came with version 5.5 in the form of Generators.

Now, most developers know Generators as memory-preserving iterators. And if you haven't yet, I'd highly recommend reading my earlier post Generators over Arrays where I go into detail on how Generators can be used like this. But as we'll see, they are much more than just iterators.

As a quick reminder, here is an example of a Generator that yields a few values.

function exampleGenerator(): Generator {
    echo "Started";

    $value = 4;

    yield 1;
    yield;
    yield 3;
    yield $value;
}

$generator = exampleGenerator();

So, how is this Generator also a coroutine? Let's examine the conditions we've talked about so far.

It can pause its execution

When we call $generator = exampleGenerator(), it only returns the Generator instance. The code inside it has not yet been started. The generator will start when any function is called on it.

If we call $result = $generator->current(), for example, the first part of the code will run. It will echo Started, set the parameter of $value to 4, and then it will pause its execution and yield control back.

It can return a value

Now that the execution is paused, the generator has also returned the value of 1. We can see that when we dump the value of $result.

It can be resumed

When the generator is paused, we can do anything we want in our calling code. Send an email, write a log, sleep for a bit. But we can also resume the generator by calling $generator->next(). At this point, the generator will resume its code until it hits the next pause or yield keyword. If we call $generator->current() again, it will have a value of null, because the next yield keyword does not specify a value to be returned. It simply pauses execution.

It remembers its state

If we were to call $generator->next() two more times, it would be at the yield $value line. To prove that it has remembered its earlier state of the $value parameter, we can inspect $generator->current() and lo and behold, it will have the value 4.

Note: When using a Generator as an iterator with foreach($generator as $key => $result), internally it will also use these methods. After calling $generator->rewind() once, it will call these methods for every iteration:

$generator->valid() - to make sure it has more values

$generator->key() - to return the value to $key

$generator->current() - to return the value to $result

The body of the foreach loop runs

$generator->next() - to resume to the next yield

Here is the full code so far if you want to try it out:

function exampleGenerator(): Generator {
    echo "Started";

    $value = 4;

    yield 1;
    yield;
    yield 3;
    yield $value;
}

$generator = exampleGenerator();

$result = $generator->current();
var_dump($result); // int(1)
// Other code, send email, log, sleep...

$generator->next(); // Restart coroutine
var_dump($generator->current()); // NULL

$generator->next(); // Current value = 3
$generator->next();
var_dump($generator->current()); // int(4)

It can receive a value (?!)

Wait, what? Yes, it can. Well, our current example can't, but a Generator in general can receive a value when it resumes. To let the generator receive a value, it must be called with $generator->send($value). So, where does this value enter the coroutine? Right after the last yield. Or better yet, "before". Let me explain with an example:

function coroutine(): Generator {  
    $received = yield 'Hello from the Coroutine';  
    yield "Received: ". $received;  
}  

$coroutine = coroutine();  

$result = $coroutine->current(); 
var_dump($result); // Hello from the Coroutine

$next = $coroutine->send('Greetings from the code'); 
var_dump($next); // Received: Greetings from the code.

In this example, the Generator will be started by the current() method and immediately paused. During its suspension, the value the Generator returns will be Hello from the Coroutine.

The Generator::send() method not only sends the value, but it also instructs the Generator to resume its execution. At that point, the Generator will set the value of $received to the value it received from send() and yield it back prefixed by Received:. The result of the ->send() will therefore be: Received: Greetings from the Coroutine.

You can also use ->throw(\Throwable $exception) to throw an exception back into the Generator. It will be as if the
current yield statement were replaced by that exception.

So, to summarize, the yield keyword can be used in different ways:

yield; Suspends the execution, returns nothing
yield $value; Suspends and returns $value
$received = yield; Suspends, returns nothing, able to receive either a value to $received, or an exception
$received = yield $value; Suspends, returns $value, able to receive either a value to $received, or an exception

It is Asymmetrical and Stackless

As we've seen, the yield keyword makes a function a coroutine, because it pauses the execution and releases control. However, it can not release control to any other coroutine. This would require a yield to syntax, which doesn't exist.

While a generator can start (and consume) a different generator, this isn't technically symmetrical because it is not releasing its control. It only starts the other generator, while it also still runs itself. This makes a generator an Asymmetric Coroutine.

Finally, a generator cannot be suspended from a nested function. This is because the yield keyword inside a function will make it return a Generator. So, when you call yield in a nested function, it becomes a generator, instead of suspending the parent. This lack of call stack awareness makes the generator a Stackless Coroutine.

Coroutines using Fibers

If you are anything like me, when PHP 8.1 introduced Fibers, you might have read about them and thought "🤯 this isn't for me". And to be honest, it might very well not be. However, I think with the context of coroutines and generators, it is much easier to understand and see their use cases.

Where a Generator itself is a stackless coroutine, Fibers represent a toolbox that you can use to implement a stackful coroutine. Let's take a look at our last example, written with Fibers.

$coroutine = new Fiber(function () {  
    $received = Fiber::suspend('Hello from the Coroutine');  
    Fiber::suspend('Received: ' . $received);  
});  

$result = $coroutine->start();  
var_dump($result); // Hello from the Coroutine
$next = $coroutine->resume('Hello from the code');  
var_dump($next); // Received: Hello from the code

With Fibers, the coroutine is now wrapped inside a Fiber instance. After that, you need to explicitly start() the Fiber instance.

Note: any arguments you pass to the start() method will be provided to the callback function, just like it would when you call a generator function with arguments.

Suspending and resuming

Just like in our previous generator example, a fiber can suspend its execution. Where the generator uses more iterator function names, because it is mostly used as such, a fiber's methods are very semantic: Fiber::suspend() and $fiber->resume().

So why is ::suspend() a static method, and ->resume() a non-static method? This has to do with the call stack.
Unlike a generator, a Fiber has its own call stack. This means that suspension can happen deep within nested functions, not just at the top level. However, neither those nested functions nor the callback that starts the fiber have access to a $this variable representing the currently running instance.

This is where the static Fiber::suspend() function comes in. Because a fiber knows its call stack, Fiber::suspend can determine the closest instance it is being called in, and suspend it.

And because a coroutine can't resume itself, the instance must be resumed from the outside. This is why the instance has a public non-static method resume().

Returning and Receiving values & Exceptions

Just like a generator, a Fiber can return multiple values. Whenever you call Fiber::suspend($value), you can provide a value that will be returned. A fiber will receive any value that is provided to the $fiber->resume($value) method.

You can also resume a fiber by throwing a Throwable $exception at it. This allows the Fiber to respond to different types of communication. You can send the fiber an exception by calling $fiber->throw($exception). Inside your callback function, you should guard against this by wrapping (at least) the current Fiber::suspend() call in a try-catch block.

$coroutine = new Fiber(function () {  
    Fiber::suspend('Hello from the fiber.');  

    try {
       $received = Fiber::suspend('Give me something.');  
       Fiber::suspend(sprintf('You gave me a value of "%s": ', $received));  
    } catch (\Throwable $e) {  
       Fiber::suspend(sprintf('You gave me this exception: "%s".', $e->getMessage()));  
    }  
} );  

$hello = $coroutine->start();  
var_dump($hello); // Hello from the fiber.  

$message = $coroutine->resume('Hello from the code');  
var_dump($message); // Give me something.  

$result = $coroutine->throw( new Exception( 'Exception from the code' ) );  
var_dump($result); // You gave me this exception: "Exception from the code".

Note: While a local catch is possible, a better approach would be to wrap your entire callback function body. Because an exception is always thrown from the outside, the callback does not control the exceptions, so it should always expect them.

Nested suspension

We have seen that a Generator cannot be suspended from a nested function, as that would become a Generator itself. With Fibers, however, it is possible to have a nested function call that will suspend the current Fiber. This allows you to use helper functions, which can keep your code more DRY, more semantic, and easier to understand.

final class Logger {  
    public function warning(string $message): void {  
       echo $message;  
    }  
}  

function get_logger(): ?Logger {  
    try {  
       $logger = Fiber::suspend( 'Waiting for a logger instance...' );  

       return $logger instanceof Logger ? $logger : null;  
    } catch (Throwable) {  
       return null;  
    }  
}  

$coroutine = new Fiber(function () {  
    $message = 'I am a message that needs to be logged.';  

    $logger = get_logger();  
    $logger?->warning($message);  
});  

$message = $coroutine->start();  
var_dump($message); // Waiting for a logger instance...  

$coroutine->resume(new Logger()); // I am a message that needs to be logged.

In this example, we can see that the Fiber callback function does not explicitly suspend its execution. However, the get_logger helper function does. The code is suspended right there, and the control is handed off to the caller. When the caller resumes the coroutine with a new Logger, the coroutine also resumes right there in the nested function. It validates the input, returns the logger, and the coroutine continues. This makes the Fiber a Stackful Coroutine.

Fibers are also Asymmetrical

It would be cool if it all came full circle, and I told you that Fibers were also symmetrical. But unfortunately, that's not the case. Just like the yield keyword, the Fiber::suspend() method does not allow for suspending to a specific coroutine. It, too, can only release control to the caller, making the use of Fibers an Asymmetric Coroutine.

Just like in a Generator, calling start() or resume() on a different coroutine does not pause the current one. Here is a quick example that proves that:

$a = new Fiber(function (Fiber $b) use (&$a) {  
    echo "starting B\n";  
    $b->start($a);  
});  
$b = new Fiber(function (Fiber $a) {  
    echo "Resuming A\n";  
    $a->resume(); // FiberError: Cannot resume a fiber that is not suspended  
});  

$a->start($b);

In this example, $a starts $b, and in turn, $b wants to resume $a. But because there was no handoff of control and suspension, $a is still running, resulting in an exception.

However, just because Fibers aren’t symmetrical doesn’t mean they’re useless or no better than Generators. Their stackful nature and added expressiveness make them a powerful tool in their own right.

Comparing Generators and Fibers

Now that we've explored both, let's compare Generators and Fibers side by side to see how they differ.

Capability	Generator	Fibers
Suspend / Resume	✅ `yield`, `->next()`	✅ `Fiber::suspend()`, `->resume()`
Return Values	✅ via `yield $value`	✅ via `Fiber::suspend($value)`
Receive Values	✅ via `->send($value)`	✅ via `->resume($value)`
Exception Handling	✅ via `->throw($exception)`	✅ via `->throw($exception)`
Symmetrical	❌ Always resumes to original caller	❌ Always resumes to original caller
Stackful	❌ Cannot suspend in nested functions	✅ Can suspend from within nested functions
Iterator Integration	✅ Implements `Iterator` (great for `foreach`)	❌ Not iterable — requires manual handling

What are Coroutines useful for in PHP?

The ability to pause code execution, have bidirectional I/O, and retain its current state makes coroutines a good candidate for various use cases. Let's have a look at some possibilities.

State processing

Because coroutines can retain their state between invocations, they are useful as state machines, chatbots, pipelines, and command-line (CLI) tools.

Let's look at a simple command-line tool that asks some questions to produce a final output.

$cli = (function () {
    $state = [];
    $state['name'] = yield 'What is your name?';
    $state['age'] = yield 'How old are you?';

    return $state;
})();

$cli->rewind();
while ($cli->valid()) {
    $prompt = $cli->current();
    echo $prompt . "\n";
    $input = trim(fgets(STDIN));
    $cli->send($input);
}

$result = $cli->getReturn();

// Display the collected information
echo "\nCollected information:\n";
echo "Name: " . $result['name'] . "\n";
echo "Age: " . $result['age'] . "\n";

In this example, the Generator will return a few questions. We display every question and use fgets(STDIN) to input an answer. This answer will be sent back to the generator, and it will proceed to the next question. When the Generator finishes, we return the recorded state. We can use ->getReturn() to get that value from the generator.

Note: You can only use getReturn on a Generator or Fiber that has finished. Otherwise, it will throw an exception.

Lazy iteration

Being able to return multiple values is what makes coroutines great at being lazy iterators. Because the data it returns does not need to exist before the iteration starts, it can save a lot of memory. In PHP, generators are perfect for this kind of job, since they implement the Iterator interface and plug right into foreach loops. If you’re curious to see this in action, check out my post on Generators over arrays.

Cooperative Multitasking (Concurrency)

Concurrency is a concept of multiple tasks running at the same time. This can be achieved through parallelism, where tasks run on separate threads simultaneously, or through cooperative multitasking, where tasks take turns running by explicitly yielding control.

Note: Because coroutines simply yield their control, you need a manager that determines which coroutine runs next. This is often implemented with something called an Event Loop, which will manage and schedule coroutines based on I/O events and timers. Out of the box, PHP does not provide this, but there are various projects like Revolt and ReactPHP that do. We will touch on them in a different post.

Imagine a chef preparing a meal. Instead of cooking the entire dish and cleaning everything afterward, the chef alternates between cooking steps and quick cleaning tasks. While both routes would have the same result, alternating makes for a cleaner work environment.

Here is what that could look like in code, using Fibers.

$cooking = new Fiber(function (array $steps): Meal {  
    Fiber::suspend('Ready to cook.');  
    foreach ($steps as $step) {  
        // Perform step.  
        Fiber::suspend($step . " finished");  
    }

    return new Meal();
});  

$cleaning = new Fiber(function () {
    Fiber::suspend('Waiting for something to clean.');  

    while (true) {
        // Cleaning.
        Fiber::suspend('Finished cleaning');
    }
});

$cooking->start(['chopping', 'mixing', 'cooking', 'plating']); // Ready to cook.
$cleaning->start(); // Waiting for something to clean.

// Alternate between cooking and cleaning.
while (!$cooking->isTerminated()) {
    printf("[Cooking] %s\n", $cooking->resume());
    printf("[Cleaning] %s\n", $cleaning->resume());
}

$meal = $cooking->getReturn();

And this could happen in code, too. Code uses memory, which can routinely be freed up to keep memory usage low. Especially when you are processing a lot of data, this constant switching between processing and cleaning can drastically improve your code's efficiency.

Where cooperative multitasking really shines is when you combine it with background processing. Instead of waiting for a function to finish its computation, you could allow the calling code to perform other tasks, while in the background the computation is finished. Then the function could pick up where it left off at a later moment, when the computation is completed.

TL;DR (but scrolled here anyway)

Coroutines are functions that can pause and resume execution while retaining internal state.
PHP supports coroutines through Generators (asymmetric, stackless) and Fibers (asymmetric, stackful).
Use Generators for iteration and memory efficiency.
Use Fibers for cooperative multitasking and nested suspension.
Real-world applications include CLI tools, state machines, and async workflows.

Coming Up: Coroutines in Practice

Now that we've explored what coroutines are and how PHP supports them through Generators and Fibers, the next step is putting them to work. In a next post, we’ll dive into concurrency in PHP, exploring event loops like Revolt, coroutine schedulers, and async libraries like ReactPHP. We’ll see how coroutines fit into the bigger picture of building responsive, non-blocking PHP applications.

Reading bundle configuration inside Symfony Compiler Passes

Doeke Norg — Thu, 04 May 2023 15:29:20 +0000

When creating a Symfony bundle, you'll often want to use a custom Configuration to configure, or even add, various services during the compilation of the service container. Symfony provides this option by implementing an Extension. While an Extension provides a lot of options to do so, a big configuration can easily create a massive extension class that does way too much.

An alternative to this approach is using Compiler Passes to split up all the logic into separate steps. A big drawback however is that by default these compiler passes don't have access to the final compiled configuration.

To get around this problem, an often used solution is to store (parts of) the configuration in a temporary transient parameter on the service container. Because the compiler pass has access to (a copy) of the container, you can read that parameter and remove it from the container before compiling is completed.

Although this is a viable option, the use of these temporary values always seemed a bit off to me; plus the developer must be very conscious of removing the values afterwards. Let's look at a great alternative option of providing this configuration to the compiler passes.

Injecting the extension into the compiler passes

Because the Extension is the location where the configurations of that bundle are aggregated and combined, it should serve as the only trustworthy source for the configuration. That means we should only retrieve the configuration from the extension class.

As luck would have it; you initialize and add a compiler pass in the build() method on the bundle class. This class also has access to the extension, by use of the getContainerExtension() method. That means we can inject the
extension into our compiler pass like this:

use Symfony\Component\HttpKernel\Bundle\Bundle;

final class MyEpicBundle extends Bundle
{
    public function build(ContainerBuilder $container): void  
    {  
        $extension = $this->getContainerExtension();

        if ($extension instanceof MyEpicExtension) {
            $container->addCompilerPass(new MyEpicCompilerPass($extension));
        }
    }
}

To accept the extension in the compiler pass, we need to make sure to receive it as its first argument:

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

final class MyEpicCompilerPass implements CompilerPassInterface
{  
    public function __construct(private MyEpicExtension $extension)  
    {
    }

    public function process(ContainerBuilder $container): void  
    {  
        // ... We want our configuration here.
    }
}

Retrieving the configuration from the extension

An extension has to implement a load() method that receives all provided configurations (e.g. from the project or other bundles that need to configure this bundle), as well as a copy of the container. To compile all these configurations into a final configuration array you can either use a Processor, or use the Extension::processConfiguration() method if you extend the base Extension.

In either case, you will probably want to avoid processing the configuration multiple times; so let's add a micro cache that contains the compiled configuration, and retrieves only that.

use Symfony\Component\DependencyInjection\Extension\Extension;

final class MyEpicExtension extends Extension
{
    private array $config;

    public function load(array $configs, ContainerBuilder $contaienr): void
    {
        $loader = new YamlFileLoader($container, new FileLocator(__DIR__ . '/../../config'));
        $loader->load('services.yaml');  

        $this->compileConfig($configs);
    }

    /**
     * Compiles and stores the configuration once.
     */
    private function compileConfig(array $configs): void  
    {  
        $configuration = new Configuration(); // This is our bundle's configuration class.
        $this->config ??= $this->processConfiguration($configuration, $configs);  
    }  

    /**  
     * Retrieves the configuration for the bundle.
     */
    public function getConfig(): array  
    {  
        return $this->config ?? [];  
    }
}

Now we are able to retrieve the entire bundle configuration in our Compiler Pass by calling the getConfig() method on the extension.

// MyEpicCompilerPass.php
public function process(ContainerBuilder $container): void  
{  
    $config = $this->extension->getConfig();

    // ...
}

The compiling of the extension configurations is actually done in a compiler pass. This is called the Merge Pass and is the first compiler pass to be processed. Because of this, once our custom compiler pass reads the configuration of off the extension, we can be sure it is already compiled, cached and ready for use.

That's it

As I said; there are alternative ways of using configuration inside a compiler pass. And a compiler pass might not even be necessary in some cases. A small configuration could very well be processed inside the bundle extension. Like always "it depends"; but this too is a nice thing to have in your tool belt.

I hope you enjoyed reading this post! If so, please leave a 👍 reaction or a 💬 comment and consider subscribing to my newsletter! You can also follow me on 🐦 twitter for more content and the occasional tip.

How the PHP Middleware Pattern works and can easily be applied

Doeke Norg — Wed, 04 May 2022 05:24:58 +0000

In this post we'll be looking at Middleware in PHP. This pattern is most common in the handling of requests and responses. But the Middleware Pattern can also be applied in various other places. We'll look into what middleware is, how middleware works, when middleware can be useful and what an alternative to middleware might be.

Note: The middleware pattern is not part of the patterns introduced by the
Gang of Four, but I personally still view it as a pattern, as it can be applied in various situations.

What is Middleware?

Middleware in PHP is a layer of actions / callables that are wrapped around a piece of core logic in an application. These middlewares provide the ability to change either the input or the output of this logic. So they "live" between the input and the output, right in the middle.

While these short explanations are obviously very easy to follow and click instantly, let me illustrate this with a small example:

$input = [];
$output = $this->action($input);

In this example, a Middleware layer is able to:

change $input before it is injected into $this->action()
change $output after it was returned by $this->action()

Let's look at how it does this.

How middleware works

The Middleware layer consists of a stack of middleware callables. These can be either a simple Closure, an invokable class or a method on a class.

Each one of the middleware callables is wrapped around the core action. Alright, I'll say it; it's like an onion, or a present with multiple layers of wrapping paper. The input gets injected into the first middleware (or most outer layer). The middleware can do something with the input, and then pass that (changed) input along to the next middleware, and the next, and the next, until it reaches the final action (the core). By this time, the input maybe changed a little or a lot.

Then the core action is executed and returns its output to the last middleware, which returns its output back to the previous middleware, all the way back to the first middleware. On its way back, every middleware can now change the output before it gets returned.

Before we look at some examples, let's first explore the different types of middleware.

Types of middleware

While the concept of middleware is pretty much the same between them, there are actually two common types of middleware: Single Pass Middleware & Double Pass Middleware.

Single Pass middleware

The most common type of middleware is Single Pass Middleware. With this type every middleware callable receives two parameters:

the input (e.g. a request, message, DTO or scalar value)
A callable to invoke the next middleware in the chain, that also receives a single parameter: the input.

Note: In some conventions the callable parameter is called $next to indicate the invocation of the next middleware.

This type of middleware can change the input and forward that modified version to the next middleware. To affect the output; it will first call the next middleware and retrieve its output. It can then modify that output and return this instead.

Here is a small example middleware to illustrate the full behavior.

function ($input, $next) {
  // Receive the input and change it.
  $input = $this->changeInput($input);

  // Call the next middleware or final action with the changed input, and receive the output.
  $output = $next($input); 

  // Change the output, and return it to the previous middleware or final consumer.
  return $this->changeOutput($output);
}

Double Pass Middleware

The second type of middleware is Double Pass Middleware. With this type every middleware also receives a default output object as a parameter. So the "double" part refers to the middleware passing along both the input and an output to the next middleware / final action.

Why is this useful? In the Single Pass type a middleware must either:

Create the required output object when short-circuiting (not calling $next but returning a different result).
Call the $next middleware(s) to retrieve an output object, and change that.

Depending on the type of output, it can be cumbersome or even undesirable to make the middleware depend on a service or factory to create that output type. And it can be just as undesirable to call (and possibly instantiate) every other middleware and final action, only to discard everything they do; and change the output object completely.

So with the Double Pass a default output object is created beforehand and passed around. This way the middleware already has an output object of the correct type it can use when it wants to short-circuit.

Here is another small example to illustrate the full behavior.

function ($input, $output, $next) {
  // Quickly return the output object, instead of passing it along.
  if ($this->hasSomeReason($input)) {
    return $output;
  }

  // Call the next middleware and return that output instead of the default output.
    return $next($input, $output); 
}

Now we know what a middleware callable looks like, but how can we wrap all these middlewares on top of an action?

A simple middleware implementation

Let's dive into some code, and create a very basic Single Pass middleware implementation. In this example we will prepend & append some value to a string (re-)using a single middleware class.

Note: There are many ways a middleware implementation can be built. This example isn't very optimized, and there is lots of room for improvement. But this example is really to demonstrate the inner workings of middleware as clear as possible.

As we've seen, we first need a core action (or function) to wrap our middleware around. Our action will simply receive
and return a string.

$action = fn(string $input): string => $input;

Now we'll create an invokable middleware class that we can use multiple times with a different value to prepend and append.

class ValueMiddleware
{
    public function __construct(string $value) {}

    public function __invoke(string $input, callable $next): string
    {
        // Prepend value to the input.
        $output = $next($this->value . $input);

        // Append value to the output.
        return $output . $this->value;
    }
}

The middleware class is instantiated with a $value. This instance will be our middleware callable, since it is an invokable class. Let's create 3 of them:

$middlewares = [
    new ValueMiddleware('1'),
    new ValueMiddleware('2'),
    new ValueMiddleware('3'),
];

Now we'll add all of these middlewares as a layer around our $action, and then we'll examine the code.

foreach ($middlewares as $middleware) {
    $action = fn(string $input): string => $middleware($input, $action);
}

Let's look at what is happening in this loop.

At first the $action closure is our simple callback which returns the $input.
In the first loop $action is overwritten with a new closure that also receives the $input (just like the initial action). When this closure is executed, it will call the first middleware, and provide that input, as well as our initial $action. So inside that middleware $next is now the original action.
In the second and third loop $action is overwritten again, but in this middleware the $next callable is not the original action, but the closure we set at the previous iteration.

Note: As we can see, $next never directly refers to a middleware. It can't, because the middleware method signature expects 2 parameters, while $next only receives one; the input. $next is always a callable which is responsible for calling the next middleware. So this can also be a method on a middleware handler that contains and keeps track of a list of (applied) middlewares.

And that's it. Our middleware implementation is complete. All we need to do now is run the $action with a value, and check out the response.

echo $action('value');

The result of this will of course be: 123value123... wait what? Did you expect 123value321? That would make the whole onion thing make more sense, right? But it is actually correct.

The middleware that prepends and appends 1 is applied first, but is then wrapped with 2, which in turn is wrapped by 3. So middleware 3 is the first to prepend 3 on the input, but it is also the last middleware to append that value. It's a bit of a mind-bender, but when we check out the $input and return for every middleware we end up with this list:

Middleware	$input	return
Middleware 3	value	123value123
Middleware 2	3value	123value12
Middleware 1	23value	123value1
Core-action	123value	123value

Working our way down the $input list, and back up the return list, we can see what stages the value passes through in this entire middleware flow.

Tip: If you want the order of middlewares to be outside-in, where the top of the list is the first one to be called, you should array_reverse the array, or use a Last-In-First-Out (LIFO) iterator like a Stack.

Request and Response middleware

One of the most common places you'll find middleware being used is within a framework that transforms a Request object into a Response object. PSR-15: HTTP Server Request Handlers in the PHP Standard Recommendation (PSR), is a recommendation on how a (PSR-7) Request object should be handled and turned into a Response object. This recommendation also contains the Psr\Http\Server\MiddlewareInterface. This interface favors the use of a process method on a middleware class, but the principle is the same. It receives an input (the Request object), modifies it, and passes it along to RequestHandler which will trigger the next middleware or final action.

Tip: Laminas' Mezzio is a minimal PSR-7 middleware Framework which provides a set of PSR-15 middlewares. And while most frameworks that work with PSR-7 and PSR-15 use Single Pass Middleware (since that
is what PSR-15 recommends) it also provides a Double Pass Middleware Decorator, so those will also work with these PSRs.

Learn more about decorators and proxies

Examples of Request and Response middlewares

Middlewares can be used to perform all kinds of actions and checks during a request, so the main action (controller) can focus on the task at hand. Let's look at a few examples of middleware that can be useful.

Cross-site request forgery (CSRF) validation middleware

To prevent a CSRF attack a framework can choose to add a certain validation to a request. This validation need to happen before the main action is triggered. In this case a middleware can examine the request object. If it deems the request valid, it can pass it along to the next handler. But if the validation fails, the middleware can immediately short-circuit the request, and return a 403 Forbidden response.

Multi-tenant middleware

Some applications allow for multi-tenancy, which basically means the same source code is used for different customers; e.g. by hooking up a separate database / source per customer. A middleware can inspect the request and figure out (for instance by checking the request URL) what database should be selected, or which customer should be loaded. It can even attach that Customer entity (if one exists) to the Request object, so the core action can read the proper information off the request object, instead of having to figure out the correct customer itself.

Exception handling middleware

Another great type of middleware is the handling of exceptions. If this middleware is applied as the outermost middleware it can wrap the entire request to response flow in a try-catch block. If an exception is thrown, this middleware can log the exception and then return a properly configured response object which contains information about the exception.

Other real world examples of middleware

While middleware is most common in the handling of requests and responses, there are other use cases. Here are a some examples:

Symfony Messenger middleware

The Queue handler of Symfony symfony/messenger uses middleware to manipulate the Message when it is sent to the queue, and when it is read from the queue and handled by the MessageHandler.

One example of these is the router_context middleware. Because messages are (mostly) handled asynchronous, the original Request is not available. This middleware stores the original Request state (things like the host and HTTP port) when it is sent to the queue and restores this when the Message is handled, so the handler can use this context to build up things like absolute URLs.

Guzzle middleware

While also somewhat in the realm of Request and Response; the Guzzle HTTP Client also supports the use of middleware. These again allow you to change the request and response to and from the HTTP request. This implementation works a bit different, but still revolves around a callback that triggers the next middleware / action.

Alternative to middleware

Like we've seen, middleware essentially allows us to change input and output respectively before and after a core action, within a single function / callable. So a great alternative to middleware would be to provide event hooks before and after the core action. With these events you can change the input before it hits the core action, and maybe even return early. And afterwards you can change the output.

Both of these options work quite well. For instance Laravel uses middleware around their Request and Response flow, while Symfony uses the Events approach.

Note: If you want to learn more about events, you can check out my (quite lengthy) blog post on Event Dispatching.

Thanks for reading

When using middleware you can easily create a separation of concerns within your code. Every middleware has a tiny job to do. It can easily be tested; and the core action can focus on what it does best, without worrying about any possible edge cases or side effects. And while it currently mostly revolves around (PSR-7) Request and Response objects, the pattern can be used widely. Do you have other ideas where this pattern can be useful? Let me know!

Using callbacks to prevent code duplication

Doeke Norg — Mon, 11 Apr 2022 11:57:25 +0000

Sometimes it can be useful to use a callback function or other callable to prevent a bunch of code duplication.

Let's say you have an event subscriber that encrypts and decrypts data in the life cycle of an entity. When the entity is stored, some data will be encrypted; and when the entity is loaded, the data will be decrypted.

Here is a maybe somewhat contrived but minimal example of this:

final class EncryptionSubscriber
{
    public function __construct(private CryptographerInterface $cryptographer) { }

    private function getEncryptedProperties(Entity $entity): array {
        // some code to detect the encrypted properties of the entity.
        return ['encrypted'];
    }

    public function onSave(Event $event): void {
        $entity = $event->getEntity();

        foreach ($this->getEncryptedProperties($entity) as $property) {
            $value = $entity->getValue($property);
            $entity->setValue($property, $this->cryptographer->encrypt($value));
        }
    }

    public function onLoad(Event $event): void {
        $entity = $event->getEntity();

        foreach ($this->getEncryptedProperties($entity) as $property) {
            $value = $entity->getValue($property);
            $entity->setValue($property, $this->cryptographer->decrypt($value));
        }
    }
}

While this isn't that bad, the onSave and onLoad are practically the same method; only the content of setValue() is different. And to be honest, with two tiny functions like these; I might not bother. But it often happens that three or even more methods are the same. Or the functions are way more elaborate; while they still only differ by a tiny thing.

Extracting a `callback` helper

A solution to this duplication can be to extract one helper method that contains all the logic once. But at the point where the logic is different we call a callable which is injected. The original onSave and onLoad will then defer to that helper method, and provide the callable to handle the specific difference.

final class EncryptionSubscriber
{
    // ...

    public function onSave(Event $event): void
    {
        $this->processEvent($event, fn($value) => $this->cryptographer->encrypt($value));
    }

    public function onLoad(Event $event): void
    {
        $this->processEvent($event, fn($value) => $this->cryptographer->decrypt($value));
    }

    private function processEvent(Event $event, callable $callback): void
    {
        $entity = $event->getEntity();
        foreach ($this->getEncryptedProperties($entity) as $property) {
            $value = $entity->getValue($property);
            $entity->setValue($property, $callback($value)); // [tl! highlight]
        }
    }
}

As you can see, we added a processEvent() method that also receives a callable $callback. This callback is executed with the current value instead of the previous encrypt or decrypt calls. This makes the entire method a very generic implementation. Only the specific difference is handled by the callback.

If the callback needs more context to do its job, that can be added as additional parameters on the $callback() call.

While the onSave and onLoad still have some necessary duplication; the amount is way less and the difference is easier to spot. And with the help of some shorthand fn it's very readable.

Thoughts and comments?

Like I said, there is a time and place for things like this. If the duplication is minimal; you might not need to bother with it. But I think it's a nice tool to know. Do you have other nice examples where this would be useful? Please share it with the rest of us. And if you have any other comments, drop them below.

Heaps explained in PHP | Quick access to the highest or lowest value of a dataset

Doeke Norg — Mon, 27 Dec 2021 11:41:34 +0000

In this article we'll explore the world of Heaps, the data structure. Because some knowledge of Trees is useful I highly suggest you read my Trees and Tree Traversal in PHP article before diving into this one.

I did my best to provide some visual aid for Heaps, because it can be hard to visualize some steps. If you have trouble understanding the concept through this blog post, I suggest you also watch the videos linked at the end of the post.

What is a Heap?

A Heap is a data structure. So it is a way of how data is organized and how it can be accessed in an efficient way. There are many types of data structures, like: (Doubly) Linked Lists, Graphs, Stacks, Queues, Arrays and HashMaps. Each of these data types can be used for various use cases; but some are more performant than others in certain situations.

🎄 A Heap is a Binary Tree

The data structure of a Heap is a Binary Tree. Starting with a Root-node, every node has a maximum of two children; left & right. But there are two rules these trees have to follow.

Heap rule #1: The parent node has a lower value (MinHeap) or a higher value (MaxHeap) than its children

There are two types of heaps: a MinHeap and a MaxHeap. The difference between these are the order in which the nodes are placed inside the Tree.

The children of a node in a MinHeap have a higher value then their parent, while the children of a node in a MaxHeap will have a lower value then their parent. If there are two identical values, a node can have a child with the same value. This behavior flows all the way down the Tree.

Note: The naming of the heaps refers to the value of the top, or Root-node, of the Tree. This means the top of a MinHeap will always be the lowest value (min) of the nodes, and in a MaxHeap it will be the highest value (max).

Heap rule #2: A Heap is a Complete Binary Tree

There are 5 types of Binary Trees:

Full Binary Trees: every node has zero ór two children; but never one
Perfect Binary Trees: every node has exactly two children
Balanced Binary Trees: the left and right sub-branch of a node never vary by more than one node
Degenerate Binary Trees: every node has a single child, essentially making it like a single line list
Complete Binary Tree: every row of the Tree is filled from left to right, without leaving gaps between nodes.

So in a Complete Binary Tree, and thus also a Heap, it is not possible to have a node with only a right child-node. But it ís possible to have one with only a left child node.

🔨 Creating a Heap

Enough theory; let's look at an example of a Heap.

Note: In this example we'll use numbers (integers) that represent the values. But that's mostly for simplicity's sake. These values can be strings, objects, whatever you want; as long as you can compare them and figure out which is the lesser or greater of the two.

Let's say we have a list of values. I'll put it in a PHP array to make it look pretty:

$values = [2, 18, 36, 5, 2, 0, -5, 72];

We'll make this list into a MaxHeap. Remember; in this case the highest value goes at the Root-node, making the values decrease every level of the tree. So in this case our Root-node will be 72.

This root-node will have two children. Those values will be 36 and 18, because those the next highest two values. The position of these values doesn't really matter at this point, they can both be either left or right.

Both of these values can have 2 children; so lets find the next 4 values in declining order from the list: 5, 2,2 and 0. Again there exact position doesn't matter, because they are all lower then 18 and 36.

And our final remaining number -5 will be the last child; the most left value on the lowest level of the tree. This makes our Complete Binary Tree complete.

So this is the MaxHeap we created:

The last node

The node that is the most right node (filled from the left) at the bottom of a Complete Binary Tree is called the last node. In our example this is -5. We'll come back to this node when we start extracting nodes.

At this point you might be thinking: this feels like cheating. And yes, I know; we cheated a bit by sorting the integers in our head from largest to smallest first, and then filling out the Heap from left to right. But that is actually the fastest way of creating a MaxHeap. However, what if we didn't know the values up front, or if they came in a random order? How would we fill out this MaxHeap?

Adding values to an empty Heap

So now let's create a Heap without sorting the numbers beforehand. In this case it would be a more iterative process:

We add the first value to the heap (in our case 2). This will become our root-node by default.
We insert the second value (18) at the first available location (left child).
We compare this value to its parent (the Root-node in this case). If it is bigger that the parent, swap them; otherwise go back to step 2 for the next value. (we need to swap)
Repeat step 3 until there are no other parents to swap with (there are no other parents)

After this we go back to step 2 and insert the next value: 36 (In our case the right child of the Root-node). We compare it to its parent. It is bigger, so we swap. 36 is now the root with 2 and 18 as its children.

Note: This swapping of values with a parent to put the values in the correct spot is referred to as sifting up.

The next value to add will be 5. Again, we insert it at the first available location in the Tree (step 2). In this case the left child of 2. We compare it to its parent and swap (step 3), because 5 is bigger than 2. We repeat step 3, but this parent (36) is bigger, so we are done. Next!

Boring! - Ok, let's stop this explanation here. I think you get the point. If you really want a more in-depth visualization; I've added some useful links at the end of this article including a video explanation.

Extracting a value from a Heap

We've seen how you can add a value to the Heap By injecting it, and then sifting it up. But how can you extract a value? It isn't as simple as removing the node, because that might cut the Tree in half. Take the Root-node for instance. On a Heap it's very likely you want to extract that value. But simply removing it will create two new Trees.

To avoid this Tree splitting, we need to replace (or swap) the Root-node with the last node. In a heap the last node can always be removed from a Tree, without corrupting it, because the Tree is already sorted.

However, when we swap the Root-node with the last node, and extract it, the Tree will no longer be a Heap at that point, because the wrong value will be at the top. So we need to turn this Tree into a Heap again, starting with the Root-node. This process is not as lengthy as turning an entire unsorted Tree into a Heap, because most of the Tree is already in the correct order.

Note: The transforming of a Binary Tree into a Heap, is known as to Heapify.

Instead of sifting the Root-node up, we need to sift the Root-node down. In this case we need to compare the node to both its children, and swap it with the largest of the two. And keep repeating it, until the node is in its correct position. At this point the Tree is once again a Heap.

Creating a Heap in PHP

Creating a Heap is made easy in PHP by using the abstract SplHeap class. It contains all methods of an Iterator as well as a few helper methods that are specific to a Heap:

extract() - Removes and returns the Root-node from the Heap, and reorders the Heap with a new Root node.
insert($value) - Adds a new value to the Heap and reorders it.
top() - Only returns the current Root node value; it does not change the cursor of the iterator or remove the node.
isCorrupted() - Returns whether the current Heap is in a corrupted state (this happens when the compare() function throws an exception).
recoverFromCorruption() - resets the corrupted state of the heap and allows for further use.

And then there is also abstract protected function compare($value1, $value2): int. This function is used inside the Heap algorithm to determine how it should order two values / nodes.

PHP also provides a SplMinHeap and a SplMaxHeap class that are concrete implementations of the SplHeap. These classes have an implemented compare() method. Both classes essentially use the spaceship operator to compare the values.

protected function compare($value1, $value2): int {
    // SplMaxHeap
    return $value1 <=> $value2;

    // SplMinHeap
    return $value2 <=> $value1;
}

Knowing all this we can create a MaxHeap from our $values array like this:

$heap = new \SplMaxHeap();
foreach($values as $value) {
    $heap->insert($value);
}

We saw that SplHeap is also an Iterator, so we can foreach over the Heap and have it yield its values in a decreasing order.

foreach($heap as $value){
    var_dump($value);
}
// int(72), int(36), int(18), int(5), int(2), int(2), int(0), int(-5)

Note: Iterating over the Heap will essentially call extract() for every value. This means that those values are gone from the heap. If you call ::rewind() on the Heap, this will not return those values. Using ::current() or ::top() will return the current top value without removing it. When you call ::next() however, this will again extract the current value.

Creating a custom MaxHeap in PHP

When using a MaxHeap to sort a list of objects it is possible the value of those objects is calculated through a function. In that case the regular SplMaxHeap will (probably) not work, but you can create your own MaxHeap by extending splHeap.

Imagine having a shop with product represented by a Product class. It can store a physical weight in different units of measurements; like pounds (lbs) and grams (g). To put these in a MaxHeap, it needs to be able to compare those different types of measurements. A (very simple) implementation could look like this:

class Product
{
    public function __construct(public $name, public string $weight_type, public int $weight_amount) {}
}

class ProductMaxHeap extends \SplHeap
{
    protected function compare($value1, $value2): int
    {
        return $this->asGrams($value1) <=> $this->asGrams($value2);
    }

    private function asGrams(Product $product): int|float
    {
        if ($product->weight_type === 'grams') {
            return $product->weight_amount;
        }

        if ($product->weight_type === 'pounds') {
            return $product->weight_amount * 453.59237;
        }

        throw new InvalidArgumentException('Product has unknown weight type.');
    }
}

In this example we convert the weight amount of pounds into grams in order to compare the values accordingly.

Tip: Whenever dealing with types like these, make sure to use constants that represent that type (like public const WEIGHT_TYPE_GRAMS = 'grams';) or use Enums when using PHP 8.1 or higher. This provides autocompletion in IDE's and prevents typo's like gram instead of grams.

Array Index Algorithm for Heaps

Remember how Heaps are Complete Binary Trees? This is actually a very helpful characteristic of a Heap. If we give every node in the tree a 0-based index key, and moved from top to bottom, left to right, we can actually quite simply figure out what the keys of the children of a specific node are. So we can store a heap as an array.

$heap_as_array = [ // Keys added for visual aid
    0 => 72,
    1 = 36,
    2 => 18,
    3 => 5,
    4 => 2,
    5 => 2, 
    6 => 0, 
    7 => -5,
];

Assuming $i represents the current node's key, the algorithm to figure out the left child of that node is: ($i * 2) + 1, and for the right child it is: ($i * 2) + 2.

Let's try that out. We want the values for the left and right child of 36. Its key is 1. So the left key is (1 * 2) + 1 = 3, and the right key is (1 * 2) + 2 = 4. Which are respectively the nodes: 5 and 2. Which in turn matches our Heap.

We can also do the reverse and find out the parent of the current node. The algorithm for that is: (int) ($i -1) / 2. For the right child of 36 (index: 4) that would be: (4 - 1) / 2) = 1.5. The int of 1.5 = 1. And key 1 is indeed the parent node: 36.

Heapify an 0-based array

Because a Complete Binary Tree can be stored as a 0-based array; we can also see any 0-based array as a Complete Binary Tree. How is this helpful? Because it's very easy and efficient to turn any existing Complete Binary Tree into a Heap.

When we want to convert a Complete Binary Tree into a Heap, we only have to sort half of it. Because the sorting is done by swapping two nodes, the other half of the Tree will automatically also end up in their correct position.

Note: Since we are working with a 0-based array, swapping means we can just switch the index of these values.

You can try this out yourself:

Draw a Complete Binary Tree from the provided array 2, 18, 36, 5, 2, 0, -5, 72
Start at the half of the array: 5
Sift it down by swapping it with the largest of its children and repeat this until it has no children to swap with (It only has one child: 72)
Now work your way back by applying step 3 on every element before 5 (So the next will be 36)

If done correctly, you end up with a Tree like this:

         72
       /    \
     18       36
    /  \     /  \
   5    2   0   -5
 /
2

As you can see, by only sifting down half the array, the other half of the Heap automatically ended up in a correct position.

🤷 When are Heaps useful?

Because there are many types of data structures, there are also many ways to solve a problem. Sometimes a simple array is all you need. But Heaps have their time to shine.

Direct access to the highest (or lowest) value

A MaxHeap (or MinHeap) has direct access to the highest (or lowest) value of the dataset. So whenever you are working with large datasets for which you need the maximum (or minimum) value; a Heap is a safe bet. As you've seen we only need to sort half the dataset in order to figure out the minimum or maximum value. Which is pretty fast.

Working with a lot of inserts and removals

When inserting a new value into a dataset, a Heap is more efficient because it only performs (relatively) a few comparisons to end up in the right spot. In the worst case scenario an array would need to perform a comparison for every value it has. Because a Heap is a binary tree, the worst case would need exponentially fewer comparisons. Making it a more efficient.

Sorting arrays

An array can be sorted by using a MaxHeap in a process known as HeapSort.
Because a MaxHeap continuously has the highest value at the top, you can extract that value and place it at it to the beginning of an array. By adding the next value, and the next, and the next, at the beginning of the array, it ends up sorted from lowest to highest.

Note: Although this technically qualifies as HeapSort this isn't the most efficient way. We'll cover HeapSort more in-depth in an upcoming post where we'll make it more efficient.

Priority Queues

While also a topic for a future blog post, queues are essentially a First-In First-Out system that adds new values at the end of a list, and extracts values from the start of the list.

A variant on this is where you use a MaxHeap that contains a priority value for a certain object. When adding this object to the Heap, it will end up higher or lower depending on its priority. This type of queue is called a Priority Queue.

Fun fact: Did you know the letters ueue in Queue are not silent, but are actually just waiting their turn? - I'll let myself out; sorry.

Because this is such a frequently used case for MaxHeaps, PHP actually provides a SplPriorityQueue based on a MaxHeap.

Instead of updating your object to contain a priority, you can insert the object with a priority.

$queue = new SplPriorityQueue();

$queue->insert('task 1', 1);
$queue->insert('task 2', 3);
$queue->insert('task 3', 2);

var_dump($queue->extract()); // string(6) "task 2"

And because we only need to partially sort a Heap find the highest priority, this too is a lot more efficient that sorting an array-queue after every insertion.

Real world example

A very nice real world example of a Heap implemented with a PHP array can be found in the revolt/event-loop package.

In this example they implemented a queue of callbacks based on an expiry time. Whenever the expiry time has passed, the callback will be extracted. So this is an example of a Priority Queue, but it's based on a MinHeap instead of a MaxHeap; because the lowest expiry time has to be on top.

Alternative for the Standard PHP Library (SPL)

As u/sproingie pointed out on Reddit The SPL data structures are not great. They are a great jumping of point in getting started with other data structures. But if you want / need more performance you could install the Data Structures extension. While it has a Priority Queue, there is no generic Heap implementation. But you might be able to build this yourself using the DS\Vector class.

🔗 Useful links

Thanks for reading

Like I stated at the beginning of the post; Trees and Heaps are very visual things and not everything is as easily explained with a bunch of text. I do hope after reading this post you understand the gist of it. If you have any questions please leave a comment.

I hope you enjoyed reading this article! If so, please leave a ❤️ or a 🦄 and consider subscribing! I write posts on PHP almost every week. You can also follow me on twitter for more content and the occasional tip. If you want to be the first to read my next blog; consider subscribing to my newsletter.

The Visitor Pattern in PHP

Doeke Norg — Fri, 12 Nov 2021 06:19:17 +0000

The Visitor Pattern isn't used often. This is because there are few situations in which it is applicable or even makes sense. However, it's a nice pattern to know and to have in your tool belt when the time comes. Let's look at how this pattern can be applied in a PHP environment.

🛑 The problem

Like a few other patterns, the Visitor Pattern tries to solve the problem of adding functionality to an entity without changing it (much...). In addition to this very generic problem, it provides a way of adding the functionality to multiple similar entities, which can't be completely handled in the same way.

So let's make the problem a bit more practical. Imagine you have two entities: Book and Document. And for both of these entities we want to know how many pages there are. Our Document has a public function getPageCount(): int which returns the number of pages, while the Book consists of an array of Chapter entities, which also have this function.

class Document
{
    public function __construct(private int $page_count) {}

    public function getPageCount(): int
    {
        return $this->page_count;
    }
}

class Chapter extends Document
{
    // Chapter specific code 
}

class Book
{
    public function getChapters(): array
    {
        return [
            new Chapter(5),
            new Chapter(7),
            new Chapter(2),
        ];
    }
}

To streamline the process of returning the page count for either of these entity types, we create a PageCountDumper. A (somewhat naive) implementation of this could look like this:

class PageCountDumper
{
    public function handle($entity)
    {
        if ($entity instanceof Document) {
            var_dump($entity->getPageCount());
        } elseif ($entity instanceof Book) {
            $count = 0;

            foreach ($entity->getChapters() as $chapter) {
                $count += $chapter->getPageCount();
            }

            var_dump($count);
        } else {
            throw new \InvalidArgumentException('PaperCalculator can not handle the provided type.');
        }
    }
}

And we can call it like this:

$document = new Document(20);
$book = new Book();

$dumper = new PageCountDumper();

$dumper->handle($document); // int(20)
$dumper->handle($book); // int(14)

This PageCountDumper has a handle() function that can handle both the Book and the Document entity, and will var_dump the proper page count for both. There are however a few things that stand out:

Because there is no shared interface or abstraction between Document and Book, the handle() function receives a mixed $entity and contains the logic for either situation. When adding on more entities, this type checking will pile on and can become quite cumbersome and unreadable.
We throw an exception when the entity type is unknown to avoid improper use.

We can do better!

👋 The Visitor Pattern Solution

So the Visitor Pattern provides a solution for this particular problem. It will remove the need for the instanceOf type checks, while keeping the reference to the entity type intact. And it will remove the need to explicitly throw an exception. Let's see how the Visitor pattern tackles these issues.

Entity specific functions

First off, to remove the instanceOf checks, it requires a method for every possible entity type. For convention's sake, we'll call these methods: visitBook(Book $book) and visitDocument(Document $document). And because we are creating a Visitor let's rename the calculator to: PageCountVisitor.

class PageCountVisitor
{
    public function visitBook(Book $book)
    {
        $count = 0;

        foreach ($book->getChapters() as $chapter) {
            $count += $chapter->getPageCount();
        }

        var_dump($count);
    }

    public function visitDocument(Document $document)
    {
        var_dump($document->getPageCount());
    }
}

By implementing separate methods, with type-hinted arguments, we've removed the need for the instanceOf checks. And because we can only call these methods with the appropriate type, there is no need to throw an exception. PHP would already do so when we provide an invalid argument.

If there is another entity in the future that needs its pages to be counted, let's say a Report, we can add a pubilc function visitReport(Report $report) and implement that logic separately.

But, you might be thinking: This isn't better. I still need to know what type my entity is in order to call the correct method!. And you would be correct. But hold on, this refactoring is only half of the visitor pattern.

Accepting a visitor

Remember when I said the entities the visitor works on should not be changed much? Yeah, well; there is one change that is needed on every entity to make the Visitor Pattern work. But only one, and this will make it accept any visitor, and therefore add any (future) functionality.

To avoid the instanceOf check, there is only one context in which we can be sure the entity is of a certain type: within the entity itself. Only when we are inside a (non-static) method of a class, we know for certain that $this is an instance of that type. That is why the Visitor Pattern uses a technique called Double Dispatch, in which the entity calls the correct function on the visitor, while providing itself as the argument.

To implement this double dispatch we need a generic method that receives the visitor, and relays the call to the correct method on the visitor. By convention this method is called: accept(). This method will receive the visitor as its argument. In order to accept other visitors in the future, we first extract a VisitorInterface.

interface VisitorInterface
{
    public function visitBook(Book $book);

    public function visitDocument(Document $document);
}

class PageCountVisitor implements VisitorInterface
{
    // Make sure the visitor implements the interface
}

Then we create a VisitableInterface and apply it on Book and Document.

interface VisitableInterface
{
    public function accept(VisitorInterface $visitor);
}

class Book implements VisitableInterface
{
    // ...
    public function accept(VisitorInterface $visitor)
    {
        $visitor->visitBook($this);
    }
}

class Document implements VisitableInterface
{
    // ...
    public function accept(VisitorInterface $visitor)
    {
        $visitor->visitDocument($this);
    }
}

Here you can see the double dispatch in action. The Book class calls the visitBook() method on the visitor and Document calls visitDocument(). Both are providing themselves as the parameter. Because of this minor change to the entity we can now apply all kinds of different visitors that provide a certain functionality for every entity.

To use the visitor on the entities we need to adjust our calling code like this:

$document = new Document(20);
$book = new Book();

$visitor = new PageCountVisitor();

$document->accept($visitor); // int(20)
$book->accept($visitor); // int(14)

With all the pieces now in place, we are free to create more visitors that implement the VisitorInterface and can perform a certain feature for both Book and Document. A WordCountVisitor for example.

note: I'm well aware what this is a contrived example, and that in this case it would be way easier to implement a Countable interface a make use of the count() function. This example is merely for demonstration purposes, and to make it easier to understand. However, when stacking on more and more actions, a class would need more and more interfaces. So please keep in mind that this would be a beneficial pattern when multiple actions are required, and possibly even new actions in the future.

Pros & cons

Like many other patterns, the Visitor Pattern isn't the one pattern to rule them all. There are multiple solutions to different problems. The Visitor Pattern is just that; a possible solution to a specific problem. Let's look at some reasons you might use it, and some reasons you might not.

✔️ Pros

You can add functionality to any entity by implementing the VisitableInterface once. This makes the entity more extendable.
By adding visitors the functionality you enforce separation of concern.
The entity is in control whether the visitor is accepted. You can omit the relay and cut the double dispatch.
The individual visitors are easier to test.

❌ Cons

The double dispatch can be confusing and make the code harder to understand.
The accept() and visit...() methods usually don't return anything, so you need to keep records on the visitor itself.
All Visitors need every method on the VisitorInterface while it might not have an implementation for it.

Real world examples

Realistically, you aren't likely to find this pattern much in the wild. However, it is a common practice in combination with Trees and Tree Traversal.

If you are unfamiliar with Trees & Tree Traversal, you can check out my previous blog on that.

When traversing a Tree, you are iterating over a continuous stream of Nodes. We can perform an action for every node in that Tree. This is called visiting... coincidence? These nodes are usually just an entity holding a value. Instead of adding a bunch of methods to these nodes; it's actually a nice way of adding different features to these otherwise dumb entities.

Some tree implementations I've seen actually have A PreOderVisitor and a PostOrderVisistor. These will then return an array of nodes in that order. While that is a perfectly acceptable visitor, I believe a Visitor should not dictate the order in which it is applied to the tree. For some features it might not even matter what the traversal order is, while in some cases it might.

In my Trees & Tree Traversal post I gave the example of a document inside a tree structure. When traversing that tree in PreOrder you get a logical flow of the document; starting at the cover page. Some visitors we might want to build for that tree are:

RenderPdfVisitor which could render every node as a PDF file.
TableOfContentsVisitor which could create a table of contents with the correct page numbering.
CombinePdfVisitor which could combine every previously rendered PDF into a single PDF document.

And basically every example from that blog post can be build as a visitor.

Thanks for reading

Like I said, the Visitor Pattern isn't very common, but it's nice to have up your sleeve. Do you have any experience with this pattern? Please let me know in the comments. I'm curious to hear what you think of it.

Trees and Tree Traversal in PHP

Doeke Norg — Mon, 18 Oct 2021 07:04:07 +0000

In this post I want to introduce you to Tree structures. What they are, how you can use them, and in which situation they can be helpful.

Please note that this is a basic introduction, and by no means the entire story. I might even be wrong somewhere, and if you believe I've screwed up: let me know in the comments or send me a DM.

🌳 What is a Tree?

To answer this question, we first have to look at Graphs. In Graph theory a Graph is a (visual) structure of data points (or Nodes) that are in some way related to each other. This relation can, for example, be a parent with a child or siblings. The relation between these Nodes is shown by a line / vertex (or edge). Within a "normal" Graph these relationships can be all over the place. Every node can be connected to another or even multiple nodes. Edges can zigzag everywhere.

So what is a Tree? It is a subset of a Graph that only allows any two nodes to be connected by one path, rather than unlimited paths.

Graph vs. Tree

For example; If we have a Parent node with 2 child nodes: Child 1 and Child 2, a Graph would allow these relations:

Parent <-> Child 1
Parent <-> Child 2
Child 1 <-> Child 2

This is also called a cyclic graph because it has a cycle in it (multiple nodes are connected to the same nodes creating cycles in the representation).

Note: Graphs don't have to be cyclic, but they can be.

A Tree on the other hand would only allow something like these relations:

Parent <-> Child 1
Parent <-> Child 2

or:

Parent <-> Child 1
Child 1 <-> Child 2

Because a picture is worth a thousand words; lets look a (simple) Graph vs. a Tree.

Notice that in the Tree each pair of nodes is only connected by one edge, Therefore there can never be any cycles. That's why Trees are acyclic graphs.

What elements make up a tree?

As we can see in the image above, a Tree always has a single Node at the top. This called the Root Node.

A Node can have a value, but is not forced to. It also may or may not have any child nodes. If a node does not have any children it is called a Leaf 🍃 .

Any node can have multiple children, but some Trees only allow a maximum amount of children per node. These are called N-ary Trees, in which N stands for the maximum amount of children per node. Probably the most famous of these Tree types is the Binary Tree which allows only 2 child nodes; left and right.

There is a lot more to tell about a Tree structures, but for a basic understanding; this should be enough. Let's move on to some action!

🚶 Traversing a Tree

Trees are nice as a visual representation, but you can also walk the complete structure of a Tree and use the data of every node. When we Traverse a Tree we visit every node in the Tree once. And visiting is just a fancy word for: "preforming an action on". This action can be anything you want: print it, save it or change it. Whatever you want to do to a node, you get one visit per node per traversal.

There are lots of ways to traverse a Tree. You can Zig-zag, pick a random order; but there are 2 broad spectrum types of Tree Traversal: Depth-First & Breadth-First.

↙️ Depth-First Tree Traversal

A Depth-First Tree Traversal is an algorithm of traversing a Tree, by picking a specific branch; and keep moving downward into that branch until it reaches the end. Only then will It go back up to find another branch.

Within the realm of Depth-First Tree Traversal there are several types of traversal; three of wich are the most common: PreOrder, InOrder and PostOrder.

These algorithms are recursive; meaning they will start again on the child nodes, and their child nodes, and so on.

In every upcoming example we will be returning the value of every node from the following Binary Tree.

A PHP representation of this tree can look like this:

$root = [
    'value' => 4,
    'children' => [
        [
            'value' => 2,
            'children' => [
                ['value' => 1],
                ['value' => 3],
            ],
        ],
        [
            'value' => 6,
            'children' => [
                ['value' => 5],
                ['value' => 7],
            ],
        ],
    ],
];

// Helper function to visualize the visiting of a node.
function visit(array $node): int
{
    return $node['value'];
}

PreOrder Traversal (node, left (to), right)

When traversing a Tree we start at the Root Node and then apply the algorithm.

In the PreOrder algorithm a node will be visited first, and then it's children from left to right. This process is recursive; meaning it will start again on its children, and so on.

The output of this Traversal will therefore be: 4, 2, 1, 3, 6, 5, 7.

First we visit 4, and then move on to its first (left) child, and apply the same algorithm again. So from that point we first visit 2, and then go to its first (left) child, and apply the algorithm again. When we reach 1 we hit a Leaf. It has no children, and therefore no output for a left or a right node. We've hit the maximum depth of this branch.

So now we backtrack to previous node 2 and finish its algorithm. We go right: 3. This node is also a Leaf. So we backtrack to the previous node: 2. This is now finished; so we backtrack even further to 4. We go right and visit: 6 and the algorithm repeats: Go left: 5; backtrack and go right: 7.

Example code

A PHP implementation of the PreOrder traversal can look like this:

function preOrder(array $node)
{
    // First we visit the node itself.
    $output[] = visit($node);

    // Then apply the algorithm to every child from left -> right.
    foreach ($node['children'] ?? [] as $child) {
        $output[] = preOrder($child);
    }

    return implode(', ', $output);
}

echo preOrder($root); // 4, 2, 1, 3, 6, 5, 7

InOrder Traversal (left, node, right)

The algorithm for an InOrder Traversal makes most sense on a Binary tree. This is because we first go left, then visit the node itself and then go right. If we had 3 children we'd need to make a choice what to do with the middle node; befóre or áfter the node itself.

Running this algorithm would produce the following output: 1,2,3,4,5,6,7.

Because this algorithm first visits the left node, we traverse all the way down until we hit the lowest left node 1. Because it has no children, we can't go left anymore. Therefore, we visit the node itself. We can't go right either; so we backtrack to the previous node: 2. This has now exhausted its complete left branch, so we visit the node itself. Then we go to the right node and repeat the algorithm..., etc.

Example code

A PHP implementation of the InOrder traversal can look like this:

function inOrder(array $node)
{
    // We extract a possible left and right node for clarity.
    $left = $node['children'][0] ?? null;
    $right = $node['children'][1] ?? null;

    // We'll apply the algorithm on the left node first.
    if ($left) {
        $output[] = inOrder($left);
    }

    // Now we visit the node itself.
    $output[] = visit($node);

    // And apply the algorithm on the right node.
    if ($right) {
        $output[] = inOrder($right);
    }

    return implode(', ', $output);
}

echo inOrder($root); // 1, 2, 3, 4, 5, 6, 7

The name InOrder is (most likely) based on the fact that it visits every node in ascending order. But this only works for a so-called Sorted Binary Tree. In this type of tree, every left child is less than the node itself, and the right side is more than the node itself. Just like in our example tree.

PostOrder Traversal (left (to), right, node)

In the PostOrder Traversal we visit the children from a node first (from left to right) and then the node itself. Because of the recursion of this algorithm the output will be: 1,3,2,5,7,6,4.

Since we already had two (exhausting) walk-throughs of the other algorithms, and this one is almost the same process as **PreOrder, I'll let you try this one out on your own.

Example code

A PHP implementation of the PostOrder traversal can look like this:

function postOrder(array $node)
{
    // First we'll apply the algorithm on every child from left -> right.
    foreach ($node['children'] ?? [] as $child) {
        $output[] = postOrder($child);
    }

    // Then we visit the node itself.
    $output[] = visit($node);

    return implode(', ', $output);
}

echo postOrder($root); // 1, 3, 2, 5, 7, 6, 4

↔️ Breadth-First Tree Traversal

In a Breadth-First Tree Traversal we start at the Root Node, and then visit the children. But unlike the Depth-First approach, this algorithm is not applied recursively; but more linear. It goes level by level, and therefore it's also called LevelOrder. This algorithm is usually used when the depth of a Tree is unknown or even dynamic.

LevelOrder Tree Traversal

The algorithm for LevelOrder is pretty much the same as PreOrder, but because it is Breadth-First we actually visit the child nodes before visiting the next level of child nodes. So first it will visit the root 4, then its children: 2 and 6, then the children of 2 and 6, etc.

To put this into perspective, the output of a LevelOrder traversal would be: 4,2,6,1,3,5,7. Every level is visited before moving on to the next level.

To implement this behavior you can use a Queue. This is a simple list or array that we append every child node to when a node is visited. You start by adding the Root Node to the queue, and then start a recursive function on the queue which visits the first Node of the queue; adds its children to the queue and then starts over; until the entire queue is empty.

Example code

A PHP implementation of LevelOrder traversal can look like this:

function levelOrder(array $queue, array $output = [])
{
    // If the queue is empty, return the output.
    if (count($queue) === 0) {
        return implode(', ', $output);
    }

    // Take the first item from the queue and visit it.
    $node = array_shift($queue);
    $output[] = visit($node);

    // Add any children to the queue.
    foreach ($node['children'] ?? [] as $child) {
        $queue[] = $child;
    }

    // Repeat the algorithm with the rest of the queue.
    return levelOrder($queue, $output);
}

// Put the root on the queue.
$queue = [$root];
echo levelOrder($queue); // 4, 2, 6, 1, 3, 5, 7

🤔 What can Tree Traversal be used for?

If you're anything like me, you like learning stuff like this; but also want / need a practical reason to use it. So let's explore that a bit further.

Note: You absolutely do not NEED a tree for this example. Just like most things in life, you can choose to use it; if you feel like it.

Example: Building a document

Let's say we have a Content Management System (CMS) to create a hierarchy of chapters for a document (or book). It has the following parts:

A cover page (C)
A table of contents (TOC)
Chapters 1 - 3 with various (nested) sub-chapters

Since there is nesting and a hierarchy, your CMS probably already has a tree-like structure. So let's embrace that and put it all in a Tree like this:

Since a Tree needs a Root Node we'll pick the cover page. Its child nodes will be the Table of contents, and every main chapter. The main chapters all have child sub-chapters.

Rendering the complete document (PreOrder)

If we want to combine every part into a single logical flowing document we can visit the nodes using the PreOrder Traversal. Why? Because we first visit the node itself, and then visit its children from left to right with a Depth-First algorithm. This means the output will be C, TOC, 1, 1.1, 1.2, 1.3, 2, 2.1, 2.2, 3, 3.1.

Another common task to use PreOrder for is cloning a tree. Since we visit every node in the correct order you can completely clone every node, and set the correct parent (because it already exists).

Removing a page from the Tree (PostOrder)

Let's say we don't need the main chapter 2, but we do need its children 2.1 and 2.2 (and their possible (grand-) children). If we were to use the PreOrder traversal, we would visit the main node first. If we were to remove that node; you'd lose al the sub-children as well. To prevent this we can use the PostOrder Traversal. Since this essentially works bottom-up we can move 2.1 and 2.2 up a level (by updating the parent), and then safely remove chapter 2.

Example: Indexing a website (LevelOrder)

For this example we are going to index a website. Our Root Node is the homepage of the website. Because we don't know how many links we are going to encounter, we also can't know what the depth of the Tree is going to be. In these cases it's better to use a Breadth-First traversal. Because this traverses a Tree level-by-level; we can stop the process if it goes to deep. We can set a maximum depth. A Depth-First approach can possibly send you down a very deep branch before it ever comes up again. Not ideal.

When we start at the Root Node, we visit (aka index) it. Then we find every (internal) link on the page and add those pages to the queue; and repeat the process, until the queue is empty.

To prevent a possible infinite loop, because a link can be on multiple pages & linked back to those pages, you need to keep track of every node that has been visited, and only add it to the queue if it hasn't been visited yet.

🔗 Useful links

📺 If you want to learn more about Graphs and Tree Traversal I can recommend Back to Back SWE on YouTube.
📤 PHP has some helper classes working with Data Structures. For example this SplQueue you can use to implement Breadth-First Traversal.

Thanks for reading

While this article isn't very PHP related; I think it's good to have a basic understanding of the tree principe and the traversal algorithms. You never know in what situation you end up needing this.

Adapter Pattern vs. Bridge Pattern

Doeke Norg — Mon, 04 Oct 2021 07:05:29 +0000

The Adapter pattern and the Bridge Pattern have brought along a lot of confusion. In this post we're going to look at what they are, what their differences are & where they might be similar.

🔌 Adapter Pattern

The Adapter Pattern tries to solve the problem of making two (or more) incompatible classes compatible, by using an intermediate class that implements a predefined interface.

- Wait what? Let's try this again!

The problem

Imagine a single Feed that wants to display the latest topics from multiple sources, like: Reddit & Hacker News. For these sources we have two API clients: RedditApi and HackerNewsApi. Both return a list of topics, but their APIs are not the same.

class RedditApi {
    public function fetchTopicItems(): RedditFeedIterator {
        // Returns a `RedditFeedIterator` that provides `Topic` objects, that hold a `title`, `date` and `url`.
    }
}

class HackerNewsApi {
    public function getTopics(): array {
        // returns an array of ['topic_title' => '...', 'topic_date' => '...', 'topic_url' => '...']
    }
}

We don't want to make our feed know about the different implementations, because we might want to add another source in the future and that would mean adding even more code to the feed. Instead, we'll apply the Adapter Pattern.

The solution

The Adapter Pattern consists of these 4 elements:

🙋 Client: This is the class that want's to connect to multiple sources. This would be Feed in our example.
📚 Adaptee: A source the Client wants to connect to. In our example we have two: RedditApi & HackerNewsApi.
🎯 Target: An interface or contract that defines a single API the Client will connect to.
🔌 Adapter: A class that implements the Target interface and delegates to an Adaptee source and formats its output.

First let's settle on a Target interface; we'll call it TopicAdapterInterface and it will have a getTopics() method that returns an iterable of topics, where every topic is an array with title, date and url. So it can be an array of arrays, or a Generator/Iterator of arrays.

If you aren't familiar with Generators or Iterators, then please check out my Generators over arrays post.

interface TopicAdapterInterface
{
    /**
     * @return iterable Iterable of topic array ['title' => '...', 'date' => '...', 'url' => '...']
     */
    public function getTopics(): iterable;
}

Now we can create a Feed class that uses these adapters. We'll loop over every adapter, and yield their results, so we get a single continuous stream of topics as a Generator. This of course doesn't take a date into consideration, but it's enough for this example.

class Feed
{
    /**
     * @param TopicAdapterInterface[] $adapters The adapters.
     */
    public function __construct(public array $adapters) {}

    public function getAllTopics(): iterable
    {
        foreach ($this->adapters as $adapter) {
            yield from $adapter->getTopics();
        }
    }
}

So we have a Client Feed, a Target TopicAdapterInterface and two Adaptees RedditApi & HackerNewsApi. That means that we are only missing two Adapters. We'll create these first, and then we'll look at what makes them tick.

To make it a bit easier working with the Iterators, I'll be using the iterator_map() function from my doekenorg/iterator-functions package.

class RedditTopicAdapter implements TopicAdapterInterface
{
    public function __construct(public RedditApi $reddit_api) {}

    public function getTopics(): iterable
    {
        return iterator_map(
            fn (Topic $topic) => [
                'title' => $topic->getTitle(),
                'date' => $topic->getDate('Y-m-d H:i:s'),
                'url' => $topic->getUrl(),
            ],
            $this->reddit_api->fetchTopicItems(),
        );
    }
}

class HackerNewsTopicAdapter implements TopicAdapterInterface
{
    public function __construct(public HackerNewsApi $hacker_news_api) {}

    public function getTopics(): iterable
    {
        return iterator_map(
            fn (array $topic) => [
                'title' => $topic['topic_title'],
                'date' => \DateTime::createFromFormat('H:i:s Y-m-d', $topic['topic_date'])->format('Y-m-d H:i:s'),
                'url' => $topic['topic_url'],
            ],
            $this->hacker_news_api->getTopics(),
        );
    }
}

Here you can see our two adapters: RedditTopicAdapter and HackerNewsTopicAdapter. Both of these classes implement the TopicAdapterInterface and provide the required getTopics() method. They each get their own Adaptee injected as a dependency, and use this to retrieve topics and format it to the required array.

This means that our Feed can now use these adapters by injecting them in its constructor. To connect this all together it could look a little something like this:

$hacker_news_adapter = new HackerNewsAdapter(new HackerNewsApi());
$reddit_adapter = new RedditTopicAdapter(new RedditApi());
$feed = new Feed([$hacker_news_adapter, $reddit_adapter]);

foreach ($feed->getAllTopics() as $topic) {
    var_dump($topic); // arrays of [`title`, `date` and `url`]
}

Benefits of the Adapter Pattern

🔄 You can plug in an extra Adapter at a later time, without having to change he Client implementation.
🖖 Only the Adapter needs to know about the Adaptee which enforces separation of concerns.
🔬 The Client code is easily testable, because it only relies on a Target interface.
📦 When working with an IoC container you can usually get / tag all services with a specific interface, making it very easy to find and inject or auto-wire all Adapters into the Client.

Real world examples

The Adapter Pattern is one of the most used patterns, because of its extendability. It can even be extended by other packages without the original packages having to change. Here are some real world examples of this.

Cache adapters

Most frameworks have a caching system that has a single API for working with it, while providing adapters for different implementations, like: redis, memcache or a filesystem cache. Laravel calls these adapters a Store and you can find these stores in illuminate/cache. They provide the Target interface for such a store in the illuminate/contracts
repository.

Filesystem adapters

Another common thing is to write data to files. Files that may be located somewhere else, like: an FTP server, a Dropbox folder or Google Drive. One of the most used packages for writing data to files is thephpleague/flysystem. This packages provides a FilesystemAdapter interface that can have specific implementations. And because of this Target interface, others can build 3rd-party packages that provide another Filesystem; like: spatie/flysystem-dropbox by Spatie.

🔀 Bridge Pattern

The Bridge Pattern is often confused with the Adapter Pattern, and with good reasons. Let's look at what problem this pattern tries to solve and how it is different from the Adapter Pattern.

The problem

Let's say we have two editors: a MarkdownEditor and a WysiwygEditor. Both editors can read and format some file and update the source on that file. The MarkdownEditor obviously returns Markdown text, while the WysiwygEditor returns HTML.

class WysiwygEditor
{
    public function __construct(public string $file_path) {}

    protected function format(): string
    {
        return '<h1>Source</h1>'; // The formatted source.
    }

    public function read(): string
    {
        return file_get_contents($this->file_path);
    }

    public function store(): void
    {
        file_put_contents($this->file_path, $this->format());
    }
}

class MarkdownEditor
{
    public function __construct(public string $file_path) {}

    protected function format(): string
    {
        return '# Source'; // The formatted source.
    }

    public function read(): string
    {
        return file_get_contents($this->file_path);
    }

    public function store(): void
    {
        file_put_contents($this->file_path, $this->format());
    }
}

At some point in time, we need a Markdown editor and a WYSIWYG editor that can read & store files on an FTP server. We could create a new editor that extends the MarkdownEditor or WysiwygEditor and overwrites the read() and store() method. However, this will likely introduce a lot of duplicate code between the two. Instead, we'll use the Bridge Pattern.

The solution

The Bridge Pattern also consist of 4 elements:

🎨 Abstraction: An abstract base class that delegates some predefined functions to a Implementor. In our example this will be an AbstractEditor.
🧑‍🎨 Refined Abstraction: A specific implementation of the Abstraction. In our example this will be MarkdownEditor and WysiwygEditor.
🖌️ Implementor: An interface that the Abstraction uses for delegation. In our example this will be a FileSystemInterface
🖼️ Concrete Implementor: A specific implementation of the Implementor that actually does the work. In our example this will be LocalFileSystem and a FtpFileSystem.

It is at this point, I think one of the things that makes this pattern hard to grasp is this:

Unlike the Adapter Pattern, where there is an actual Adapter; the Bridge Pattern does not have a Bridge. But no worries, we'll see the thing that makes this the Bridge soon enough!

Refactoring the code

Let's refactor our example code by implementing the Bridge Pattern. We'll start by extracting the Abstraction from our two Editors.

abstract class AbstractEditor {
    public function __construct(public string $file_path) {}

    abstract protected function format(): string;

    public function read(): string
    {
        return file_get_contents($this->file_path);
    }

    public function store(): void
    {
        file_put_contents($this->file_path, $this->format());
    }
}

class WysiwygEditor extends AbstractEditor
{
    protected function format(): string
    {
        return '<h1>Source</h1>'; // The formatted source.
    }
}

class MarkdownEditor extends AbstractEditor
{
    protected function format(): string
    {
        return '# Source'; // The formatted source.
    }
}

In this refactoring we've created an AbstractEditor that now contains all the duplicate code there was between the editors, and made the editors extend this abstraction. This way the editors, or Refined Abstractions, are only focussing on what they do best: formatting the source of the file.

But remember, we still don't have a Implementor or a Refined Implementor and we really want to use multiple file systems. So let's create the Implementor and a LocalFileSystem as the first Refined Implementor. Then we'll update the AbstractEditor to use the Implementor.

interface FilesystemInterface {
    public function read(string $file_path): string;

    public function store(string $file_path, string $file_contents): void;
}

class LocalFileSystem implements FilesystemInterface {
    public function read(string $file_path): string
    {
        return file_get_contents($file_path);
    }

    public function store(string $file_path, string $file_contents): void
    {
        file_put_contents($file_path, $file_contents);
    }
}

abstract class AbstractEditor {
    public function __construct(private FilesystemInterface $filesystem, private string $file_path) {}

    abstract protected function format(): string;

    public function read(): string
    {
        return $this->filesystem->read($this->file_path);
    }

    public function store(): void
    {
        $this->filesystem->store($this->file_path, $this->format());
    }
}

So here is the "Bridge". It's the connection between the Abstraction and the Implementor. It connects one editor to one filesystem. But now the two can vary independently. We can add multiple editors that all have their own formatting, like yaml, json or csv. And all these editors can use any filesystem to read and store those files.

So now we can create a FtpFileSystem that reads and stores the formatted content on an FTP server.

class FtpFileSystem implements FilesystemInterface {
    public function read(string $file_path): string
    {
        // Imagine the ultimate FTP file reading code here.
    }

    public function store(string $file_path, string $file_contents): void
    {
        // Imagine the ultimate FTP file writing code here.
    }
}

By using the Bridge Pattern we've made it possible to make 4 different implementation combinations:

// 1. A local markdown file editor
new MardownEditor(new LocalFileSystem(), 'local-file.md')
// 2. An FTP markdown file editor
new MardownEditor(new FtpFileSystem(), 'ftp-file.md')
// 3. A local WYSIWYG file editor
new WysiwygEditor(new LocalFileSystem(), 'local-file.html')
// 4. An FTP WYSIWYG file editor
new WysiwygEditor(new FtpFileSystem(), 'ftp-file.html')

And if we were to add another AbstractEditor and another FileSystem we'd have 9 possible combination, while only adding 2 classes 🤯!

Benefits of the Bridge Pattern

As we've seen there are some benefits to using the Bridge Pattern:

💧 The code is more DRY (Don't Repeat Yourself) by extracting the Abstraction.
🧱 It is more extendable by creating two separate abstractions that can vary independently.
🔬 The individual classes are smaller and therefore easier to test and understand.

Similarities with Adapter Pattern

Another reason why some have trouble understanding the difference between the Bridge Pattern and the Adapter Pattern is that the connecting part of the "bridge" actually looks like an Adapter.

A Client could be seen as the Abstraction as that also delegates to an interface.
A Target could be seen as the Implementor as this also defines an interface to adhere to.
An Adapter could be seen as the Refined Implementor because this implements the interface and fulfills the requirements.

That last one is probably the most confusing; as a Refined Implementor can actually be an Adapter to a dependency or Adaptee, but this is not required. The Refined Implementor will often be a class on its own, while an Adapter will always delegate. But the two are indeed not mutually exclusive.

Thanks for reading

What happens when we clone?

Doeke Norg — Fri, 24 Sep 2021 16:54:54 +0000

It can sometimes be more useful to create a copy of an object and only change the relevant parts, then to completely recreate it. For example, when the object has a lot of dependencies or parameters you need to provide; while a second copy might only differ by one value.

To create such a copy you can use the clone keyword in PHP. When you make such a clone however, you are possibly not getting a full copy.

Shallow copies

When cloning a simple stdClass with a few scalar variables, a clone will be almost identical, but it will be a separate instance. So when we update a value on the second copy it will only be updated on that instance.

$object = (object) ['title' => 'Object title'];
$clone = clone $object;

var_dump($object == $clone); // true, they are equivalent
var_dump($object === $clone); // false, they not the same instance

$clone->title = 'Clone title';

var_dump($object->title === $clone->title); // false, the title are no longer identical

However, when clone copies the object it will make what is known as a Shallow copy. This means it will keep all references that object has intact. So when you have an object or reference stored on a parameter, the instance of that reference will be the same for both copies.

$title = 'Object title';
$inner = (object) [];

$object = (object) [
    'title' => &$title, // The title parameter is now a reference to $title
    'inner' => $inner,
];
$clone = clone $object;
$clone->title = 'Clone title';

var_dump($object->title); // "Clone title"
var_dump($object->inner === $clone->inner); // true, the same instance

This is important to keep in mind when working with clones. Because this could very well be annoying oversight or a very useful advantage.

Deep copies

If you need your nested objects to be a new instance as well, you need what is known as a Deep copy. This means that every reference will be a new instance of that reference as well.

To help with this you can use the magic __clone() method on the object you are cloning. This method is called on the object after the copy is made, but also before the object is returned. So you can use it to alter any parameters.

$object = new class {
    public \stdClass $inner;

    public function __construct()
    {
        $this->inner = (object) [];
    }

    public function __clone()
    {
        $this->inner = clone $this->inner;
    }
};

$clone = clone $object;

var_dump($object->inner == $clone->inner); // true, equivalent
var_dump($object->inner === $clone->inner); // false, not the same instance

In this example we updated the $inner parameter with a new copy of itself. So now we are no longer referencing the same object. This means we now have a deep copy.

Note: Did you notice we referenced $this inside the __clone() method? The context bound to that method is not the current instance, but $this is actually referring to the clone!

A clone is not constructed

Another thing to be aware of is that the __construct() method is never called when an object is cloned. Just as with unserialize() the cloned object is recreated from the state of the original object; so there is no need to call the constructor.

$object = new class
{
    public string $title;

    public function __construct()
    {
        $this->title = 'Object title';
    }
};

$object->title = 'New title';
$clone = clone $object;

var_dump($clone->title); // "New title"

As you can see, the new title on the clone is copied as well, while we might expect the cloned object to have Object title as its title.

Factories

Not calling the __construct() when cloning can be a powerful asset. It is used in a lot of factory classes to avoid possible heavy calls from being made. Imagine some heavy dependency that is created in the constructor. That same dependency can very likely be the same instance for every clone. This way the call is only made once, and then the instance is shared between every clone.

class User {
    public HeavyDependency $heavy_dependency;

    public function __construct() {
        $this->heavy_dependency = new HeavyDependency(/*...*/);
    }
}

class UserFactory {
    private User $prototype;

    public function create(): User
    {
        return clone $this->prototype ??= new User;
    }
}

In this example we create a new instance of the User class on the first UserFactory::create() call. We then return a clone of that instance. Any subsequent calls to the create() method will already have the User instance, so we only return a clone. This cloning of a single instance to copy its dependencies is also known as the Prototype Pattern.

Set private variables on a clone without `__clone()`

One final cool trick is that you can actually create a clone and then set private variables on that clone, without the use of a __clone() method. To do this you must create a method on the object class that creates the clone and returns it. Inside this method you can still update private variables of the cloned instance.

$object = new class {
    private string $title = 'Object title';

    public function getTitle(): string
    {
        return $this->title;
    }

    public function getClone(string $title): self
    {
        $clone = clone $this;
        $clone->title = $title;

        return $clone;
    }
};

$clone = $object->getClone('New title');

var_dump($clone->getTitle()); // "New title"

Contrary to popular believe, a private variable is not private to the instance but to the class of that instance 🤯. So within the context of the same class, you can reference and update any private variable on such an instance.

As you can see this is useful for creating a clone, while also updating some of its values within the same call.

Thanks for reading

Decorator Pattern vs. Proxy Pattern

Doeke Norg — Sat, 18 Sep 2021 14:09:19 +0000

There are two patterns in PHP that are very similar; The Decorator Pattern and The Proxy Pattern. Because they are so similar, you can quickly mistake one for the other. Does that matter? Maybe not, but I think it's good to know the differences when communicating about them.

Similarities between Decorators and Proxies

Both the Decorator Pattern and the Proxy Pattern revolve around the idea of wrapping an instance of an existing interface (let's call that the inner instance) with a class that implements that same interface and delegates their function calls to the same functions on their inner instance.

These patterns are very useful for adding or changing functionality of an instance without breaking encapsulation. It can also change or extend functionalities of final functions and classes. And because they usually serve one purpose they can easily be tested.

Example

interface SubscriberInterface {
    public function subscribe(string $email): void;
}

class SubscriberDecorator implements SubscriberInterface {
    private SubscriberInterface $inner_subscriber;

    public function subscribe(string $email): void {
        $this->inner_subscriber->subscribe($email);
    }
}

In this example you can see that our SubscriberDecorator implements the SubscriberInterface and it also requires some instance of the SubscriberInterface. After that it delegates the subcribe() function to the same function on that instance.

Differences between Decorators and Proxies

When it comes to naming a class a Decorator or a Proxy you have to look at its intent. What is the class actually doing with the instance it is wrapping?

Required vs. Optional dependency

You might have noticed I didn't include a __construct() method in the previous example. This was intentional, because this is where the first difference can be apparent.

A Decorator requires an instance of the interface it is wrapping, while a Proxy does not require such an instance. A Proxy can receive an instance, but is also allowed to create this instance itself. So you can create a new Proxy on its own, while a Decorator needs another instance as dependency.

// Decorator
 public function __construct(public SubscriberInterface $inner_subscriber){}

// Proxy
 public function __construct(?SubscriberInterface $inner_subscriber = null){
    $this->inner_subscriber = $inner_subscriber ?? new InnerSubscriber();
}

Additive vs. Restrictive

Decorators are additive; meaning they only add new functionality by wrapping the function call and returning the original value. It can however do anything before or after that call. You can for example log every value when a function is called or dispatch an event. Just make sure to return the original value.

Proxies are restrictive; meaning they can change the behavior of a function or even restrict calling a specific function by throwing an exception.

Tip: Both Decorators and Proxies are allowed to add any extra functions or parameters. It can therefore be wise to implement some magic __isset(), __get() and __call() methods on the Decorator or Proxy to pass these calls along to the inner instance as well.

General purpose vs. Specific purpose

Decorators serve a general purpose. It will add some functionality regardless of the instance it is wrapping. This means that multiple decorators should be able to be applied on top of one another in any random order and still produce the same result and added functionality.

Proxies serve a more specific purpose. It will mostly be used to change or append functionality to a specific instance of the interface. Proxies also aren't commonly stacked on top of one another as a single proxy is usually enough.

Tips for Decorators and Proxies

Here are a few tips you might consider when working with Decorators and Proxies.

Make a base abstraction

If you create multiple Decorators or Proxies of the same interface it can be beneficial to create an abstract class of the interface or a trait that satisfies the interface, where every function is already deferred to the function on the inner instance. If you are a package creator, you might even consider providing this implementation inside the package. This way a Decorator or Proxy can extend or use this implementation and only (re)declare the functions it needs.

Single responsibility Decorators

It might be tempting to slap on multiple features onto a Decorator, but the beauty of them is that they can be added or removed without changing the underlying code. So try to make tiny Decorators that focus on one thing and apply these on top of each other. Again, this simpleness makes them easier to test as well.

Examples

You can find a couple of nice examples of Decorators and Proxies in Symfony.

Their developer toolbar shows a lot of information regarding events and cache, for example. They log this information by decorating the current EventDispatcher with a TraceableEventDispatcher and the current cache adapter with a TraceableAdapter within the dev environment.

An example of a Proxy can be found in the DeflateMarshaller of the symfony/cache package. This Marshaller is restrictive due to its dependency on gzinflate() & gzdeflate() and its changes to the output of the inner instance.

Thanks for reading

How to use symfony/mailer without the Symfony framework

Doeke Norg — Sat, 11 Sep 2021 10:07:14 +0000

On August 19, 2021, Fabien Potencier officially announced the end of maintenance for Swiftmailer. Swiftmailer is being replaced by the symfony/mailer package.

Because of the name, you might think this package can only be used inside a Symfony project, but that's not the case. The naming only implies the package is created by Symfony. So let's take a look at this package and how we can use it inside a project without any framework.

Introducing the components

To email a recipient you need three things; a mailer service, a transporter and, (of course) a message.

Mailer

As you might expect, the symfony/mailer package provides a MailerInterface with a corresponding Mailer service. The Mailer service contains the main API and is responsible for sending the message to the appropriate receiver. The interface only has one method: send(). So the API is very basic and easy to understand. To set up the mailer service a transporter is required.

Transporter

A transporter is responsible for actually sending a message using a particular protocol. The service must implement the TransporterInterface, which also only contains a send() method. When you call the Mailer::send() method, it will delegate this request to the provided TransportInterface::send() method.

Because there are many ways a mail can be sent, there are also many transporters available. By default, this package includes the two most common transporters: sendmail and smtp. There are however many 3rd party transport services available. A full list of these services can be found on the documentation site.

Message

The most important part of sending a message is of course the message itself. Symfony Mailer uses the symfony/mime package. This package provides a few handy objects for creating messages that follow the MIME standard. One of these classes is Email, which provides a high-level API to quickly create an email message. An Email is a data object that contains the message, the recipient, and any other useful headers. This class is also Serializable.

Usage

Now that we are familiar with the underlying components, let's create a PHP program that sends an email via the sendmail protocol.

We'll create a new project by making an empty folder and running the following command inside it:

composer init -n --name symfony-mailer-test

This will create a tiny composer.json file with the following content:

{
    "name": "symfony-mailer-test",
    "require": {}
}

To use symfony/mailer inside our project, we need to require it:

composer require symfony/mailer

Now we'll create an index.php file, and require the vendor/autoload.php file.

require_once 'vendor/autoload.php';

Now we'll create the email message we want to send.

use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('sender@example.test')
    ->to('your-email@here.test')
    ->priority(Email::PRIORITY_HIGHEST)
    ->subject('My first mail using Symfony Mailer')
    ->text('This is an important message!')
    ->html('<strong>This is an important message!</strong>');

As you can see, the API for creating an Email is very verbose and easy to understand. You might have noticed we provided the content twice; as text and as HTML. When the email client used to read the mail supports HTML, it will show that version, otherwise it will fall back to the text only version.

Now that our Email is done. We can add our transport service and the mailer instance.

use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mailer\Transport\SendmailTransport;

$transport = new SendmailTransport();
$mailer = new Mailer($transport);

$mailer->send($email);

Now we should be able to send this message. We can try it out by running it from the command line.

php index.php

And there you have it. You've just sent a mail using symfony/mailer.

Using a DSN

There is one more thing I'd like to show you, and that is creating a transporter based on a DSN. If you are unfamiliar with the term, DSN stands for Data Source Name. It is a string that represents the location of a data source. This data source can be anything like a file location, a database connection, or in our case a mail transport driver.

There is no real definitive format for a DSN, other than: it is a string. Symfony however has chosen to make their DSNs mirror a URI. So this format should be pretty familiar to you. If I were to say to you for example:

Create a url based on the ftp protocol, for the doeken.org domain, with username: john and password: doe on port 21.

You would probably give me a string like this: ftp://john:doe@doeken.org:21.

In the case of a transporter DSN, the protocol is the name of the sender, so in our case: sendmail. So that would make our DSN sendmail:// This is however not a valid URI because there is no domain. To fix this, we can add a random string, but most prefer default. That means the final DSN is sendmail://default.

We can now use the Transport::fromDSN() method to automatically create the appropriate transport service.

use Symfony\Component\Mailer\Transport\Transport;

$transport = Transport::fromDsn('sendmail://default');

$transport will now still hold a SendmailTransport instance, and the sending of the mail will still work.

If you wanted to send a mail using the smtp protocol you can provide a similar DSN. I like using HELO to debug my emails. A DSN for this could be: smtp://symfony-mailer@127.0.0.1:2500.

Testing

For testing purposes symfony/mailer includes a NullTransport service. This transporter will not send any mail, but it will trigger all the appropriate events. You can create this transporter using the null://default DSN.

Events

I won't be covering events in this blog post, but this is something that symfony/mailer supports. As of version 5.3 the only event dispatcher package you can use is symfony/event-dispatcher. When 5.4 is released, and Swiftmailer will officially be retired, you can use any PSR-14 event dispatcher.

Do you want to learn more about event dispatching?
Then you should check out my in-depth post on Event Dispatching.

Documentation

If you want to learn more about the symfony/mailer package I highly recommend reading the docs. It goes into a lot of detail on the possible transport services, as well as using multiple transports at the same time, or even sending mails asynchronous by using a message queue.

I hope you enjoyed reading this article! If so, please leave a ❤️ or a 🦄 and consider subscribing! I write posts on PHP most every week.

A simple PSR-4 autoloader

Doeke Norg — Fri, 03 Sep 2021 19:27:36 +0000

Have you even used a composer.json file purely for the need of registering a PSR-4 autoloader? I have, and it always felt a little weird to require such a hunk of code for such a simple task. It adds a vendor folder and a bunch of empty files. I don't like that overhead when it's not necessary.

So here is a drop-in alternative. You can for example use this in a WordPress theme or plugin.

spl_autoload_register(function (string $class_name): void {
    // Map the namespace to the corresponding folder
    $namespace_mapping = [
        'DoekeNorg\\BlogTheme' => 'src',
    ];

    foreach ($namespace_mapping as $namespace => $directory) {
        if (
            strpos($class_name, $namespace = trim($namespace, '\\')) !== 0
            || (!$directory = realpath(__DIR__ . DIRECTORY_SEPARATOR . trim($directory, DIRECTORY_SEPARATOR)))
        ) {
            continue; // Class name doesn't match or the directory doesn't exist
        }

        // Require the file
        $class_file = $directory . str_replace([$namespace, '\\'], ['', DIRECTORY_SEPARATOR], $class_name) . '.php';
        if (file_exists($class_file)) {
            require_once $class_file;
        }
    }
});

How to use this autoloader

Save this file as autoload.php for example, and fill out the correct values for $namespace_mapping
require this file inside your bootstrap file or theme/plugin entry file

That's it. Now you can reference any class with that namespace, and the autoloader will require the correct file.

The mapping is relative to the location of the autoload.php file, so you can also do things like this:

|-- blog-theme
    |-- src
    |-- vendor
        |-- autoload.php <- the autoloader 
    |-- public
        |-- index.php <- entry file

When you require vendor/autoload.php inside public/index.php you can adjust your mapping to the following,
and the resolving will still work.

 $namespace_mapping = [
    'DoekeNorg\\BlogTheme' => '../src',
];

Couldn't you make this into a nice class?
Of course, but would that really be better?

Is it a big win over Composer?
No, a big win it is not, a small one; maybe. It's also not ment to replace Composer in any way, because that is way more optimized. It's just that for a simple plugin or theme you don't need the overhead Composer creates.

DEV Community: Doeke Norg

Exploring Coroutines in PHP

What are Coroutines?

Suspend and resume

Return and receive values

Hold its state

Types of coroutines

Asymmetrical vs. Symmetrical Coroutines

Stackless vs. Stackful Coroutines

How are coroutines implemented in PHP?

Coroutines using Generators

It can pause its execution

It can return a value

It can be resumed

It remembers its state

It can receive a value (?!)

It is Asymmetrical and Stackless

Coroutines using Fibers

Suspending and resuming

Returning and Receiving values & Exceptions

Nested suspension

Fibers are also Asymmetrical

Comparing Generators and Fibers

What are Coroutines useful for in PHP?

State processing

Lazy iteration

Cooperative Multitasking (Concurrency)

TL;DR (but scrolled here anyway)

Coming Up: Coroutines in Practice

Reading bundle configuration inside Symfony Compiler Passes

Injecting the extension into the compiler passes

Retrieving the configuration from the extension

That's it

How the PHP Middleware Pattern works and can easily be applied

What is Middleware?

How middleware works

Types of middleware

Single Pass middleware

Double Pass Middleware

A simple middleware implementation

Request and Response middleware

Examples of Request and Response middlewares

Cross-site request forgery (CSRF) validation middleware

Multi-tenant middleware

Exception handling middleware

Other real world examples of middleware

Symfony Messenger middleware

Guzzle middleware

Alternative to middleware

Thanks for reading

Using callbacks to prevent code duplication

Extracting a callback helper

Thoughts and comments?

Heaps explained in PHP | Quick access to the highest or lowest value of a dataset

What is a Heap?

🎄 A Heap is a Binary Tree

Heap rule #1: The parent node has a lower value (MinHeap) or a higher value (MaxHeap) than its children

Heap rule #2: A Heap is a Complete Binary Tree

🔨 Creating a Heap

Adding values to an empty Heap

Extracting a value from a Heap

Creating a Heap in PHP

Creating a custom MaxHeap in PHP

Array Index Algorithm for Heaps

Heapify an 0-based array

🤷 When are Heaps useful?

Direct access to the highest (or lowest) value

Working with a lot of inserts and removals

Sorting arrays

Priority Queues

Real world example

Alternative for the Standard PHP Library (SPL)

🔗 Useful links

Thanks for reading

The Visitor Pattern in PHP

🛑 The problem

👋 The Visitor Pattern Solution

Entity specific functions

Accepting a visitor

Pros & cons

Extracting a `callback` helper

Set private variables on a clone without `__clone()`