Now, my static generator has gone through three complete rewrites over the years. When I started out I dreamt of open sourcing it and it becoming something "big", but now I hope no one will ever use it! Over the years I've come to realise I made a lot of things very complicated for no real reason. For example: I wanted to manage everything with YAML — big mistake. You can take a look at it yourself, this is part of my site's configuration:

/:
    template: blog/overview.twig
    variables:
        title: Blog
        overviewTitle: programming
        posts: src/content/blog.yaml
        meta:
            description: "A blog about modern PHP, the web, and programming in general. Follow my newsletter and YouTube channel as well."
    config:
        order:
            variable: posts
            field: date
            direction: desc

/blog/{id}:
  template: blog/detail.twig
  variables:
    overviewTitle: programming
    post: src/content/blog.yaml
    meta:
      description: "A blog about modern PHP, the web, and programming in general. Follow my newsletter and YouTube channel as well."
  config:
    collection:
      variable: post
      parameter: id
    next: true
    meta: true

And this is how I add blog posts (in another YAML file):

a-simple-approach-to-static-generation:
  date: 2024-08-30
  title: A simple approach to static site generation
  content: src/content/blog/2024-08-30-a-simple-approach-to-static-generation.md
  disableAds: true

timeline-taxi-chapter-07:
  date: 2024-08-24
  title: "Timeline Taxi: chapter 7"
  content: src/content/taxi/taxi-07.md
  next: timeline-taxi-chapter-01
  disableAds: true

extends-vs-implements:
  date: 2024-08-21
  title: Extend or implement
  content: src/content/blog/2024-08-18-extends-vs-implements.md
  disableAds: true

There's so much overhead converting YAML config into something that generates a website, and it's really not worth it. Especially when you realise I need a non-static version for local development. So I actually parse this YAML into a routable application as well 🤢.

Three years ago, I realised that this approach was doing more harm than good, and I tried refactoring stitcher to Laravel: instead of a YAML file, I'd make simple controllers, and somehow generate static pages from those. In other words, I'd use my controllers as "configuration", which had the benefit my content being accessible within a non-static context as well for local development — the controllers were already there.

I actually got pretty far twice, but gave up on it twice as well. It was never a high-stakes project since the original still worked, and I guess other things got in the way.

However, yesterday, I was working on the Tempest docs website, and realised it could use a static version as well. Why would I need to boot the framework everytime when all I need is an HTML page? So I did some hacking and… well. I got it working within an hour 😅

Granted, Tempest does most of the heavy lifting, but I dare to say that my experience writing a static generator from scratch three times might have helped as well. Here's what I did.

Tempest already has controller actions — obviously — they look like this:

final readonly class HomeController
{
    #[Get('/')]
    public function home(): View
    {
        return view('home');
    }
}

Now, what if we want to generate a static version of this page? We need a way of letting Tempest know it should generate an HTML page from a controller action. That's easy enough using an attribute:

final readonly class HomeController
{
    #[StaticPage]
    #[Get('/')]
    public function home(): View
    {
        return view('home');
    }
}

Now, Tempest has a concept called discovery, so finding the actions that should be compiled into static pages isn't all that difficult:

final readonly class StaticPageDiscovery implements Discovery
{
    public function __construct(
        private StaticPageConfig $staticPageConfig,
    ) {
    }

    public function discover(ClassReflector $class): void
    {
        // Loop over all public methods
        foreach ($class->getPublicMethods() as $method) {
            // If a method has the `#[StaticPage]` attribute,
            $staticPage = $method->getAttribute(StaticPage::class);

            if (! $staticPage) {
                continue;
            }
            
            // we need to add it to our list of static pages
            $this->staticPageConfig->addHandler($staticPage, $method);
        }
    }

    // Some more boring cache stuff
}

So right away, we've got a config file with all the controller actions that should be compiled to static pages. Next, let's create the command that will generate all that content:

final readonly class StaticGenerateCommand
{
    use HasConsole;

    public function __construct(
        private Console $console,
        private StaticPageConfig $staticPageConfig,
    ) {}

    #[ConsoleCommand('static:generate')]
    public function __invoke(): void
    {
        foreach ($this->staticPageConfig->staticPages as $staticPage) {
            // …
        }

        $this->success('Done');
    }
}

Right now, nothing much is going on: we inject that static page config which was populated by our discovery class, and we inject the console as well because we want to write some output to it. Now, what should we do with each static page? It holds a reference to a controller action, which we can use to generate a response with, which we can render into HTML. We'll need to inject a couple more framework dependencies to handle the heavy lifting for us, but nothing too complicated:

#[ConsoleCommand('static:generate')]
public function __invoke(): void
{
    $publicPath = path($this->appConfig->root, 'public');
    
    foreach ($this->staticPageConfig->staticPages as $staticPage) {
        // First, we generate the URI for this static page's controller handler
        $uri = uri($staticPage->handler);
       
        // Next, we dispatch a new GET request via Tempest's router 
        $response = $this->router->dispatch(
            new GenericRequest(
                method: Method::GET,
                uri: $uri,
            ),
        );
        
        // We render the response
        $this->viewRenderer->render($response->getBody());

        // And write the HTML to a file
        $file = path($publicPath, $uri . '.html');
        file_put_contents($file, $content);
        
        $this->writeln("- <em>{$uri}</em> > <u>{$file}</u>");
    }

    $this->success('Done');
}

So that's all good, but there's an important thing missing: this approach won't work for routes that have dynamic parameters. Take for example Tempest's docs controller action:

final readonly class DocsController
{
    #[StaticPage]
    #[Get('/{category}/{slug}')]
    public function show(string $category, string $slug, ChapterRepository $chapterRepository): View
    {
        return new DocsView(
            chapterRepository: $chapterRepository,
            currentChapter: $chapterRepository->find($category, $slug),
        );
    }
}

Yeah, this won't work, since we don't need to render one page, we need to render a page for every $category and $slug variant. In other words: we need to render a page for every chapter in the docs. It might seem like a difficult problem to solve — it used to be the most difficult thing to get right when I built stitcher — but it's actually pretty trivial. Whenever we have a dynamic route, we'll need a way to specify all variations of that route — something to provide data to fill in the gaps. How about… a data provider?

So, let's make a small change: let's add an interface called DataProvider, which has one task… provide data. It's the same concept as PHPUnit's data providers, by the way, it's not too complicated. So let's refactor our docs controller like so:

final readonly class DocsController
{
    #[StaticPage(DocsDataProvider::class)]
    #[Get('/{category}/{slug}')]
    public function show(string $category, string $slug, ChapterRepository $chapterRepository): View
    {
        // …
    }
}

And implement that DocsDataProvider class next:

final readonly class DocsDataProvider implements DataProvider
{
    public function __construct(
        private ChapterRepository $chapterRepository
    ) {}

    public function provide(): Generator
    {
        foreach ($this->chapterRepository->all() as $chapter) {
            yield [
                'category' => $chapter->category,
                'slug' => $chapter->slug,
            ];
        }
    }
}

As you can see, it's not too complicated: we already have a ChapterRepository that lists all available chapters, now it's just a matter of providing the right data for every page. So with that in place, we need to make one final change to our generate command, as it needs to take this data provider into account:

#[ConsoleCommand('static:generate')]
public function __invoke(): void
{
    // …
    
    foreach ($this->staticPageConfig->staticPages as $staticPage) {
        // Retrieve the data provider via the container
        $dataProvider = $this->container->get(
            $staticPage->dataProviderClass 
            ?? GenericDataProvider::class
        );

        // Loop over all its iterations
        foreach ($dataProvider->provide() as $params) {
            // Generate the URI for this static page's controller handler
            // WITH the dynamic parameters
            $uri = uri($staticPage->handler, ...$params);
            
            // … The rest stays the same
        }
    }
}

And we're done! Now we have one controller action that generates a dynamic amount of pages, all with just a couple of lines of code. I added some null checks and prevented some edge cases — you can check out the full code here if you want to.

In hindsight, I'm really struggling to understand my train of thought for when I built stitcher: why did I make things so complicated, when all I needed was just a couple lines of code? Wisdom comes with age, right? Well, I'm happy with the results, and I believe I'm now able to finally port my blog to something that works a lot easier. All the building blocks are in place, I just need to do the refactor.

Read the previous chapter.

“Big Bertha, Hyperion-C, seize all powerup activities and hand over remote control to us, you have one minute to comply or we will shoot you down.”

The radio voice makes it pretty clear: when it comes to unauthorized launches, the USN on Mars takes things more seriously than the UN on Earth.

“Powerup 85%”

“Just a couple more minutes.” I mumble.

“Pathing complete”

“Big Bertha, Hyperion-C,” the voice comes in once again, “this is your last warning. You have 30 seconds to comply.”

“Ok doc,” I say, my eyes fixed on the dashboard, “it’s gonna be close. We can take a couple of hits, but I don’t know how long we’ll last.”

“Powerup 90%”

“Big Bertha, 10 seconds.” I ignore them.

It feels longer than ten seconds, but finally the first shot is fired. It misses — that might have been on purpose, or maybe because the ships are still pretty far out.

I open my mic channel, “USN, this is Hyperion-C, beware of full-powerup, clear the engine zone or you will be vaporized!”

Two more shots, one hits us, but there’s no other reply. The dashboard reports no critical damage.

“Powerup 95%”

“Doc, hold on tight! Remember those couple of g’s I told you about? They will be here soon.”

Another two shots, both of them hit. An alarm goes off, the shuttle has been breached. It’s sealed off from the ship so there’s no need to worry. Too bad for the shuttle though.

Another shot. The ship rumbles.

“Engine failure, continue powerup?”

“What is that?” The doctor asks — he’s glancing at the dashboard himself.

“One of the engines has been hit.” I say, not looking up as I’m frantically pressing buttons to reconfigure my engine setup.

“Now what?” He asks with a slight tone of panic in his voice.

“Don’t worry,” I say, “We can still use the other engine.” Meanwhile I’ve made the necessary changes so that we can continue powerup with one engine alone.

“Get ready, doc!”

“Powerup 100%. Initiate acceleration?”

The dashboard reports one more shot approaching, but it never hits. In an instant, I’m pressed into my seat and I find it difficult to move. I usually find the pressure that comes with full-powerup acceleration rather uncomfortable, but now feels like a relief. It’ll take an hour to reach near-lightspeed, but the USN ships are already far behind. Space in front of us is turning more and more blue, the common blueshift at ultra-high speeds. I keep close track of the engine status, if this second one fails, we’re in big trouble.

It doesn’t fail though. An hour later we’ve reached 99.995% c, and we’re back to zero g’s now that the engine has powered down.

“You ok?”, I ask as I turn away from the dashboard to the doctor.

“I think so. That was tense.”

“It’s not done yet, unfortunately,” I sigh. I waited to tell him the news until acceleration was done. We have a damaged engine, but we can accelerate to near-lightspeed and slow back down from it just fine with one. The problem is that our one working engine doesn’t have enough fuel anymore. Usually the load is balanced between two engines, and so also their fuel usage. Now that we’ve accelerated with one engine alone, it has used almost all the fuel it had. A quick checkup on fuel status tells me I need at least three injections from the damaged engine before we can slow down again.

“I hope,” I tell the doctor, “there are still three working injections in the damaged engine. Otherwise…”

“What? Otherwise what?” The doctor asks, the same panic creeping into his voice once again.

“Look, if we don’t have enough fuel, we can’t slow down.” I let those words sink in for a moment before I continue. “If we can’t slow down… Well that's the end of the story for us.” There’s no need to sugarcoat our situation.

“You mean you accelerated to near-lightspeed, without knowing whether we could ever stop again?”

“It was that or being shot by the USN, remember?” The doctor’s panic isn’t helping, it’s not like I’m at fault here. He insisted on powering up, even though I suggested taking another route. Granted, that was before one of my engines was toast, but still. “Besides,” I continue, “let’s not make a big deal out of it before we’re truly in trouble. For all we know, the damaged engine’s injections are fine. I just need to move them to the other side —”

“Hang on,” the doctor interrupts, “are you going on an EVA at near-lightspeed?” The panic in his voice has made room for skepticism.

“Yeah. Well. It’s not impossible,” I snap. “I’ve got an EVA suit made especially for it. Ok… I’ve never done it before. If I fall off… Well, I don’t need to explain to you how the ship works, because you’ll be screwed anyway if I don’t manage to transfer those injections. Maybe I should explain how deep sleep works and how to rig the system so that you could die a painless death if something were to happen.”

But the doctor shoves it aside. “Just… Fix it,” he says. The mood now definitely changed for the worse. Maybe it’ll be good not to be in each other's hair for a moment. So I sigh without saying anything else, and head downstairs.

Half an hour later I’m in my EVA suit in the frontal airlock. I know this won’t be easy. The most difficult part about doing an EVA at near-lightspeed is that space is almost empty — almost. At this speed, miniscule dust and radiation particles accumulate into what would feel like a sand storm on Earth. My suit only guarantees protection for up to 15 consecutive minutes, so as soon as the airlock door opens, I’m on the clock to inspect the damaged engine, find and detach three working injections, move them to the left outrigger of the ship, into the engine, and get back to the airlock.

I press the button. The airlock opens.

I’m immediately pushed backwards, but my boots are magnetically attached to the floor and it only takes a couple of seconds to regain my balance. I gasp when I look up and see the sparkling stripes and flashes of light. These are miniscule dust particles flying by at nearly the speed of light. Each of them leaves a light trail as thin as a hair. They aren’t visible from within the cockpit with its filtered glass, but from outside, they resemble an infinite sea of fireflies in space.

I stand in awe, but I know I’m on the clock, so I force myself forward, turn, and grab the handle on the right side of the airlock. My muscles ache pretty quickly as I pull myself forward while I’m fighting the invisible storm around me, but I manage to hold on tight and crawl towards the right outrigger. I hoist myself on top of it, turn backwards, and once again I’m stunned by an amazing view: the redshifted space behind us glows like the most magnificent sunset without any visible horizon.

I reach the broken engine and see how the injectors are directly exposed, the cover plate nowhere to be found. Most likely it ripped off after our somewhat hasty departure from Mars.Luckily all injections seem fine, it’s only the engine that was damaged, not the injectors in front of it. I sigh. We’re in luck. Granted, my ship is in bad condition with a missing cover plate and a damaged shuttle, but none of those issues are life-threatening. I grab the first injection rod, turn it clockwise and lift it out of the injector. It instantly slips out of my fingers and flies off into infinity. Ok so, just holding it doesn’t work. I only now think of magnetizing my glove. I’m lucky that that injection didn’t hit the ship. I lift up the second one, and this one holds. I magnetically attach it to my leg. Now the third, and the fourth. I’ve got three full injections and ten more minutes. Let’s go.

The magnificent light spectacle around me reflects faint stripes of light on the hull as I crawl my way onto the left outrigger. I’m sweating, my muscles burn, but we’re on the right track. This engine’s injectors are exposed as well, their cover plate ripped off. I immediately spot the ones that need to be replaced: full injection rods emit a soft dark glow, empty ones don’t. I pull out five depleted ones in total, that leaves 2 full ones. If I add the three I have with me, we’ll have just enough fuel for slowdown on one engine. One by one, I strap the empty ones to my leg and back, and replace them with new rods. I do a final check, all are firm in place. Four more minutes, time to get back.

Once again awestruck, I take a minute to stare into space when I’m back into the airlock — I did have a minute to spare after all. I should probably be happy about the successful repair, but the only thing I think of is the magnificent view I’m witnessing. I don’t want this moment to end.

Full of sweat, I strap into my seat half an hour later. “Ok doc, we’re good,” I say when I see the dashboard reporting 5 full injections in the left engine. “Maybe we should have a proper talk?”

I also made a video about it, by the way:

I've been wrestling with code that abuses inheritance for a couple of years now. Granted: I don't really like the word abuse because it sounds very heavy, and code that abuses inheritance can still work perfectly well. But I also struggle to find a better word for it. Maybe "code that doesn't fit my expectations of what inheritance should be used for". I'm frustrated with myself because I can't seem to put into words exactly why I dislike code that's intentionally designed to be extended. It happens a lot in Laravel, but I'm sure it happens in Symfony and other places as well.

"Extend from a base class", "override a method" — all in the name of "flexibility" and "configurability". It's a common pattern, but it feels so… icky to me. The practice is so common that a whole community of developers is vocally against using final, because it blocks them from accessing that flexibility inheritance is giving them.

All the while, I'm thinking "this isn't the way inheritance was meant to be used…"

Like I said, it's difficult to put into words, but I think the problem for me started when I watched Alan Kay's talk about his vision for OOP. Alan is the inventor of object-oriented programming, by the way. He describes how you can build a dog house using only a hammer, nails, planks, and just a little bit of skill. Once you've built it, you've earned the skills and know-how, and you can apply that knowledge to other projects. Next, you want to build a cathedral, using the same approach with your hammer, nails, and planks. It's a 100 times larger, but you've done this before — right? It'll only take a little longer.

This is where Alan says OOP started to derail: languages like C++ took a relatively simple concept, and started to do a bunch of things with it in a way it wasn't supposed to be used. Granted, the code works, but it's lacking in many areas. Honestly, it's a fascinating talk and I highly recommend watching it.

Back to modern OOP: we've taken a concept like inheritance, and made it almost equivalent to "an easy way of configuring and plugging into vendor code". Open source packages are designed deliberately to extend and overwrite different parts of their codebase, hoping all goes well. The sad part, to me, is that there are better solutions to solve these problems. Other ways than to rely on inheritance. There's a range of patterns that help us solve whatever issues we run into — including configuration and "plugability" of code that's out of our control. Alan talks about this as well, by the way: proper architecture is a thing.

I was thinking about inheritance, comparing it to interfaces, and I came up with a definition that somewhat makes sense to me: I want to use inheritance to reflect real-world relations; I want to use interfaces to describe technical behaviour.

A class that implements an interface doesn't necessarily describe the essence of that class, it only promises it can perform the tasks defined by that interface. It could do a lot more things, for all I know, but I don't care about that within a specific context. It's a "hey, I can do this" promise rather than "hey, I am this". Inheritance, on the other hand, conveys that a class is a subcategory of something else. To me, that kind of relation only makes sense when we're talking about real-world modelling. Or maybe it's the other way around: if we try to apply that kind of relation to technical properties, things get out of hand fairly quickly.

An example: User extends Model, for me, that's wrong: a User isn't a Model; instead it's a class that can act like a model. It's a class that makes a promise to whatever context it's being used in. AdminUser, on the other hand, should extend from User, because it reflects a real-world relationship: an AdminUser is everything a User is, and probably a bit more. So, in my mind it should be AdminUser extends User implements Model (although the implements Model already happens on the parent class and isn't necessary here).

Like I said, I suspect not many people caring so deeply about this, and I'm not sure why I care so deeply about it myself. I think this definition keeps things somewhat clear to me. It eliminates a gray zone that I find confusing to work in.

And sure, there are some technical arguments to make against my thought experiment within PHP: there's no multiple inheritance, there are no interface default methods, and you can't implement an interface via a trait. There are limitations to the language we're using.

But still, I find this mental model more comfortable than the alternative.

Read the previous chapter.

I remember growing up as a kid, following the live transmission as humans set the first foot on Mars. We had been chasing the Mars dream for multiple centuries and were finally there. A handful of centuries before that historical landing, billionaires had privatized the space sector and made it into their life's mission to be the first on Mars. They longed for something money could not buy, but none of them ever got to witness the landing. An endless chain of setbacks and disappointments had defined that space age.

I wonder how they would react, had they known they were looking in the wrong direction. Conventional propulsion was their biggest misstep. It would have never allowed humans to colonize Mars in a reasonable timeframe. The breakthrough came with the invention of antimatter pulsar engines, which could reach speeds no one thought imaginable. Suddenly the distance between Mars and Earth could be crossed within 30 days, then 25, then 20. Soon thereafter, we managed to reach near-lightspeed velocity. If the early pioneers would have had that technology available in their time, they would have been able to spend a year or two in near-lightspeed deep sleep to wake up in a new age. Instead, they died without the accomplishment they longed for, some even driven to insanity at the end of their lives.

And here I am — orbiting what used to be a desolate, dusty planet. It took almost 500 years from that first step in the Martian dust to make it into what it is today. The doctor’s looking out the cockpit window in awe. I’ve seen Mars before — a couple of times, not often, and definitely not in the stage it is today. I can relate. After a minute, maybe 5, maybe 10 — who knows — it’s back to work. We need to come up with a plan to refuel this ship. My fuel reserves are now almost empty, and getting from Mars to any other planet in a reasonable amount of time has become impossible. It needs to happen here and now.

“I suggest a couple of things.” I tell the doctor. It’s good having someone to bounce ideas off of, even if that someone has no practical experience with space travel, let alone how things work on Mars.

“First, I’ve changed our call sign. It’s one of the advantages of having an older ship: I’ve had to do several software upgrades throughout the centuries, which includes patches to its identification system. I kept the old versions as a backup though. I hotpatched the system to use my very first call sign.”

“Won’t they recognise it as an outdated call sign?” The doctor asks.

“Sure, but that’s not uncommon. There still are ships arriving occasionally in this period. Pioneers who bet everything they had on one very long near-lightspeed trip. So everyone still knows how to deal with these call signs, they are just not as convenient. It might give us a chance of not being flagged immediately.”

“Makes sense. What else?”

“There’s only one other thing I can think of: we won’t be able to refuel at any USN-owned station, that’s way too risky. But there are a handful of privately-owned stations in Martian orbit still. Not as many as I remember there to be, but we only need one. They tend to ask less questions about visitors. They are obliged to report to the USN once every month or so, which would mean trouble for us, but by then we’re already far gone. That’s the plan. What do you think?”

“Sounds… easy?”

“In theory it is easy, and no, I think this is our only option. I’ve refueled here a handful of times when the Martian reactors were still abundant and antimatter was cheaper here than on Earth. But that’s a long time ago. You better have some cash at hand, because it’s going to be expensive.”

“Don’t worry about that, I’ve got you covered.”

“So, are you ok with this plan? Anything to add?”

“Just to be sure, are there any alternatives you can think of?”

“Nope, as far as I know this is our only option.”

“Well, then I’m good to go. You’ve done this before, let’s just act normal and it’ll be fine.”

“Normal,” I say to myself and chuckle half-sarcastically. If all goes well, we should be on our way to the Oort cloud in three hours; we escaped Earth a little over a week ago because I became a wanted criminal; I’m here with a doctor who apparently discovered time travel, and I don’t even know where we’re going. So yeah, let’s act normal.

“That reminds me”, I say, “I will need those coordinates before we can engage in a full powerup. And a full powerup takes half an hour. So, whatever timing fits you best, but I’m just letting you know.”

The doctor nods. “I’ll give them when refueling is done.”

Ok, here goes.

“Mars Station Alpha 2, this is Big Bertha calling out, do you copy?”

The doctor turns to me barely holding it together. “Big Bertha?” he mouths.

“I know. I found it funny back then, I was young. Shut up.”

“Big Bertha, this is Mars Station Alpha 2, how are you today?” The reply sounds a little more cheery than usual.

“Mars Station, we’re all good here, just arrived from a pretty long trip and we’re looking for refuelment, can you help us with that?”

“Big Bertha, that shouldn’t be a problem, what kind of engine are you running?”

“Mars Station, I’ve got two separate antimatter pulsar engines, both need full refuelment.”

“Big Bertha, please proceed to gate 8, we’ll have the injections ready for you there. Please be advised that each injection will cost 50MD”

50 Mars Dollars, with a current conversion rate of one to five; it’s gonna be expensive indeed.

“Mars Station, all fine. Big Bertha proceeding to gate 8. Thank you.”

I have to do some exotic maneuvering to be able to dock at gate 8, this station is so packed that the ship needs to be spinned sideways and extend the outriggers into their near-lightspeed flight configuration, just so that we can dock without crashing into anything. The ship has become as flat as possible, meaning we now just barely fit. We need to attach with our frontal dock — the rear dock is occupied by the shuttle — which makes things more difficult as the outriggers extend most frontwards. Ideally, I’d move the shuttle to the front, but I don’t want to risk spending another half an hour maneuvering around.

But I know this ship as none other, and we dock without problems. Less than a minute later, the frontal airlock beeps, indicating that the valet wants to board. I float to the lower deck and open the gate.

“Good morning, sir. I was told you need full refuelment for both pulsar engines, correct?” He’s tapping frantically on his tablet while talking, not looking up.

“That’s right, I need 10 injections per engine.”

“Can these engines be accessed from the inside, sir?”

“I’m afraid not, you’ll need an EVA to reach them. I can help if you want.”

“Oh that’s ok sir, part of the service. This is a pretty nice ship you have!” He exclaims as he’s looking around the interior.

“Yeah it’s one of the few they made in my era, my grandfather designed it, called it Hyperion. This is Hyperion-C, the third one they made. They are very reliable, I think all nine of them are still operating fine after all these years.”

“Hyperion, good name — yet you renamed it to Big Bertha!” He says as he chuckles.

“I was young…”

“Oh believe me sir, I get you, no worries. Ok so, refuelment will take 15 minutes. I will need payment up front though.”

“Yeah, that’s no problem, hang on.” I call the doctor downstairs. “This is my travel companion, he’s the one paying today.”

“Very well, sir. That’s 20 injections in total, do you want to keep the depleted ones or can we recycle them?”

“Feel free to recycle them,” I reply.

“Perfect, that’s 1200 dollars then, you can pay here.” He holds the tablet in front of the doctor. The doctor scans his biochip, and the payment succeeds. First step done.

“We’ll see each other in an hour and a half then?”

“Perfect, see you then, sir.”

We move back up to the cockpit, sit in our chairs and watch for a couple of minutes as four technicians start their EVA. We can’t see the back of the outriggers from within the cockpit, which is where the engines are located, but we see them going back and forth carrying depleted injections.

“So, doc, a couple of pre-flight checks. After refueling, we travel to a safe takeoff position. As soon as full powerup is done, we’ll start acceleration. It’ll be fast. Really fast. The ship’s equipped with g-shields, otherwise you’d be squashed in an instant. You’ll still experience a handful of g’s though. They were barely noticeable during our acceleration to Mars, but a full powerup to near-lightspeed does carry some discomfort. Probably 3 to 4 g’s. Some people get used to it, others faint and stay unconscious during the entirety of acceleration. I could already put you in deep sleep if you want but —”

“Don’t worry about it,” the doctor interrupts, “I have had proper high-g training a year ago. I’ll be fine.”

I have to admit, the doctor doesn’t disappoint me. He is prepared. Meanwhile the technicians have already started to load the new injections, they are efficient.

“Like I told you, I’ll need those coordinates before powerup, ideally when we’re leaving here. We’re navigating the Oort cloud at near-lightspeed, so the autopilot will need some time to calculate the best path.”

“I’ll share them with you as soon as we’ve undocked.” The doctor assures me.

“Ok, next step is to explain the first days of our journey and deep sleep, you might not —”

The airlock beeps again, someone’s at the door. I float downstairs and am surprised to see the valet with two armed guards as the airlock slides open.

“Any problems?” I ask. They haven’t finished refueling yet.

“As a matter of fact, sir. There is. The payment of the gentleman traveling with you triggered a problem while processing. It turns out your client is wanted by the UN, so I’m sorry to inform you that he will have to come with us.”

The guards and valet are still standing in the docking tunnel, so I have no more than two seconds to make a decision before they enter the ship. I only need one second though. I reach to the upper right corner of the airlock where the emergency disconnect button is located. In an instant, the docking port slides shut and we disconnect from the station. There’s a loud bang and the doctor shouts my name. I rush upstairs.

“Strap in.”

“What happened?”

“Strap in!” I repeat.

The four technicians are floating in front of the ship, making haste to get back to the station. The right outrigger has hit the station, but doesn’t seem to have suffered any damage, at least as far as I can tell. I RCS to back out as fast as I can and turn around. I trust forward into higher orbit.

“What happened?” The doctor asks again when we’ve cleared the station.

“You’re wanted by the UN! That happened. Most likely there’s a USN patrol on their way to intercept us, and those will be more heavyweight than the shuttles that chased us on Earth. I’m going to prepare for full powerup, once we’ve cleared Mars.”

“Wait, they weren’t done refueling yet!”

“I know, we’ve got 14 out of 20 injections. I’m afraid your trip has been canceled.”

“No that can’t be!” The doctor exclaims, for the first time seeming to lose his calm.

“Look, we can’t make the trip you wanted to, but we can still skip a century. Let’s hope the UN will have lost interest in us by then.”

“No, you don’t understand! There’s only one chance of going to the place we’re going to, and that’s now. A hundred year delay won’t work!”

“Doc, I’m sorry, we tried, but it didn’t work out. Unless you want to spend probably the rest of your life in jail, you’ll have to let go of your plans.”

“Wait, you said we’ve had 14 injections, right? That’s enough for a one-way trip, right?”

“I wanna go back, doc! I’m not going to give my life for your mission!”

“No, you don’t understand. You can get back. Ok look, I’ll tell you where we’re going, but you can already prepare the powerup?”

“I’m doing that anyway, start talking!”

“The holotype message contained coordinates somewhere in the Oort cloud. We did as much research as we could on it from Earth, and discovered a cluster of meteorites that could potentially contain tachyonium. We sent an expedition to it three years ago: two near-lightspeed capable ships that have been setting up camp within that region of space. There’s much more to tell you about them, but I’ll tell you when we’ve got more time. My mission is to join them. Both ships have antimatter reactors on board, you can refuel when we’re there!”

I take a moment to let the doctor’s words sink in.

“You have set up camp in the Oort cloud to mine meteorites?”

“We’ve been doing much more, but please, let’s hurry. Will you take me there?”

I still haven’t figured out whether to trust the doctor with my life or not. He continues without waiting for my reply. “You haven’t had any reason to distrust me! I’ve helped you every step of the way. I have every reason to want you to succeed, because if you don’t, I don’t either. Please.”

“Sure but you only need me to succeed halfway!”

“No, because we need your ship! I promise you, I’ll explain everything to you when we’re on our way, and you will get back home, please trust me.”

This seems to be one of those pivotal, life-altering moments where every choice seems to be the wrong one. I glance at Mars on the dashboard. I’ve never even set foot on it, but in this moment, with the prospect of traveling half a lightyear away, it feels as close to home as Earth. My life probably won’t be the same ever again.

I curse.

“Ok, doc, give me the coordinates.”

I'm anticipating some questions about that decision, so I wanted to write down my thoughts. I've got three reasons for setting such a strict version requirement.

# 1. The longer we wait, the bigger the break

Whether you're building a framework, a package, or work on any kind of open source code: you'll never be in the same unique position again as right when you're starting out. You have a clean slate, you can do whether you want without worrying about anyone being affected by it.

With PHP 8.4 coming, PHP will change pretty significantly, especially with property hooks. If I ever want to include property hooks in Tempest, the best time is now, because introducing them into already established interfaces is a huge breaking change. Honestly, I'm dreading the moment where I have to go through all of Tempest's interfaces, and refactor probably half of the methods there to property hooks. Nevertheless, it's better to do it now, and to do the work myself, rather than postponing it another year or two, and impacting everyone.

There won't ever be a moment as good as now to embrace PHP 8.4, it will only get more difficult the longer we wait.

# 2. Pushing the community

I've made this argument before: open source PHP maintainers have a collective responsibility to push the community forward. Upgrades aren't as scary as they used to be, and we're missing out on performance improvements, security fixes, and new syntax, all because of the fear of upgrades.

In my opinion, staying up to date with modern PHP versions is part of the job. Everyone should charge their clients for it, and do the work.

# 3. A natural filter

My last reason might seem counterintuitive at first: I'm pushing PHP 8.4 for Tempest (and 8.3 when tempest/highlight was released) to deliberately slow the adoption rate. Don't I want these projects to be successful? Sure. But I'm also limited on time. Imagine tagging the first Tempest release with 8.3 or even 8.2 support; there would probably be a lot more people trying it out, and there likely would be a much bigger inflow of bug reports. That in itself isn't bad, but I reckon a lot of people would play around with it for five minutes, run into edge cases, and then throw it away.

I'm limiting the initial audience to a smaller group, a group that — in general — makes more effort to upgrade PHP sooner and doesn't necessarily expect everything to work flawlessly in v1.

So yeah, those are my reasons. You might not agree with them, in which case I'd love to hear your thoughts! Send me an email or join the Tempest Discord!

Read the previous chapter.

“Maybe we should have a proper talk then?” The doctor suggests after we’ve settled in the cockpit where I told him the trip to Mars will take around 10 days. He did remarkably well during our escape, but it seems he got through it on pure adrenaline and needs to decompress now. His hands are shaking, but he’s holding up. He could probably use the distraction of a talk. Fair enough.

“Ah,” he says after I tell him everything that happened over the past 24 hours, “I didn’t know they had their eyes on you. Otherwise I would have warned you when we met.”

“That might have spared me a very embarrassing hour or two…” I reply.

“Ok so, I reckon you’re totally clueless about what happened these past years on Earth, right?”

“I guess so, between spending seven years away from Earth and being dragged naked into a police station, I haven’t had much time to catch up… What happened?”

“Well, ISTRA, of course. But that’s only the result of a much bigger movement. I should probably tell you a bit about my field of study first.”

“Definitely.” I lean back in my seat and stare outside into the darkness. “Go ahead.”

“12 years ago, a small anomaly was observed at night in the UK, near Sheffield. A super bright flash of light in the sky, most people assumed it was a comet of some sorts. And indeed it was: a small comet the size of a melon. It was recovered by scientists shortly after it fell. Maybe you know, maybe you don’t, but comets these days aren’t all that uncommon. We recover close to a hundred sizable ones every year in the UK alone. Most of them are tested for rare materials, and processed accordingly. The same happened with this particular comet.”

“Yeah I’ve heard of more and more comet strikes during the past couple of decades. Is it really worth the effort?”

“In some cases it is. Most comets only contain common materials, but some can be processed for gold, cobalt, platinum, and silver — in significant amounts. With today’s processing technologies, the yield is worth the effort. Now, this particular comet was different though. Long story short, it contained an unknown element, and that’s where the Sheffield Institute of Space Travel finds its origin — specifically to research this one comet.

At first, I was recruited together with a team of two other scientists to do testing on this newly found material. Interestingly enough, the more tests we did on it, the more we realized it didn’t adhere to the laws of physics as we know them. As an experiment, we heated a small sample of the comet to observe how it behaved under high temperatures. Nothing happened. The next day, we wanted to conduct the same experiment again so we recalibrated our measuring equipment and prepared for another test run. During that calibration, the equipment picked up all sorts of particle activity around the sample. We assumed this was a very delayed reaction to our previous experiment, so we noted the time and delay, reheated the sample, and came back the day after. Nothing happened. We were puzzled about this and brainstormed possible theories for these inconsistent observations. Eventually we decided to retry the same experiment later that day, with two different sets of equipment. However, when setting up the new tools, they again picked up activity from yesterday’s experiment, now with what seemed to be a longer delay. Throughout the next few days, we kept running experiments and taking measurements. The timings never lined up and for days we weren’t able to find an answer for this odd behavior.

That is, of course, until we noticed a pattern. Our measurements seemed to always occur at a random time after each experiment, but they did occur on a fixed time before the next experiment. Always one hour before we heated the sample again.

Now, this of course makes no sense. How could an experiment we were going to do, influence the measurements of a past experiment? We did more test runs, but each time we moved the sample so that we had a more accurate understanding of which observation belonged to which experiment. It turned out that the past experiment had nothing to do with it. Each observation was consistent with the position of where the sample would be next. To make sure there weren’t any biases, we’d have one team observe the readouts, while another team, those who hadn’t seen the readouts, would move the sample. Next we experimented with changing the temperature. Slight changes to it seemed to influence the delay. The more we heated the sample, the earlier its readout could be observed. Again we had a blind team moving the sample at a random point in time to prevent any biases.

All of this experimentation led to a conclusion: we believed we had discovered tachyons.”

I know enough physics to raise my eyebrows. I have heard of tachyons before— particles that travel faster than the speed of light. “So the result of each experiment was measured before the experiment was done?” I repeat, just to let those words sink in.

“Exactly.”

“So you mean the experiment went… back in time?”

“I wouldn’t put it like that, no; but we can say the experiment’s results were observed without being constrained by the natural flow of time.”

“But, I believe tachyons were proven not to exist, weren’t they?”

“Well, it was never proven they don’t exist. However, their existence would lead to paradoxes, and their behavior would be inconsistent with our current laws of physics. However, no one managed to prove without a doubt they don’t exist.”

“So we’re talking time travel stuff?”

“I would be hesitant applying the term time travel because it has so many nuances and paradoxes that would distract from proper research. Here’s an example. One experiment was about making an observation, and then deliberately placing the sample in the wrong spot, so that the observation could not have taken place — to create a paradox.”

“What happened?”

“Nothing. We weren’t able to pick up any reading. It makes sense, since we never actually put the sample in the right place. If we relied on a blind placement team once again, the readings only worked if they placed it in the spot we were observing. It seemed to be consistent.”

“So then what?”

“Well eventually we concluded that we didn’t discover tachyons.”

“Huh?”

“Tachyons were theorized centuries ago as some kind of particle that travels faster than light. In theory that could mean they would be able to send information back in time, which is what we were observing.

However, we discovered three distinct kinds of particles, all exhibiting the same behavior, albeit with subtle differences between them. So tachyons isn’t an accurate term. We’re also not sure whether the material we discovered is the source of these particles, or merely a carrier for them. On top of that, we can’t be certain whether they travel faster than the speed of light or not, because we simply cannot observe that. We can only observe a side effect that is theorized to be consistent with tachyon behavior. We did call the host material tachyonium, though. It seemed fitting.”

“What happened next?”

“Well after months of experimentation, we noticed something peculiar. We observed one of our tachyonium samples to emit what seemed to be controlled flashes of particles. What struck us the most, was that this particular sample was the so-called holotype sample: it was the first sample extracted from the meteorite that was used to determine that this was in fact an unknown element. We never touched it afterwards, let alone experiment on it. Now, all our samples were constantly measured, including the holotype. It was meant to be used as a baseline, since we never experimented on it, so it should never show activity. Safe to say, it doing so with a very distinct pattern — it grabbed our attention.

The very distinct pattern also seemed to be more deliberate than just a random occurrence, it kept repeating. It seemed as if the holotype was trying to communicate some sort of message. So we gathered the data over the course of several weeks until we noticed full repetition. We interpreted that data as binary information, and to our astonishment, it indeed included a message.”

“What — who…” I stumble for words.

“We don’t know, and we can only guess. My best guess is that future-us, or someone in the future, decided to send a message back in time via that sample. Since it’s the holotype specifically, it’s natural to assume that it was us, although we cannot confirm that.”

“What did the message say?”

“It included very helpful information about tachyonium that moved our research forward.”

“Hang on a second. So future you sent a message to past you, which influenced the situation of past you. Doesn’t that mean that future you would have never sent any information at all? Isn’t that something like the grandchild paradox?”

“The grandfather paradox, and our situation is most commonly described as the bootstrap paradox where information or an object which is needed to make time travel possible, comes into existence thanks to time travel, which causes a circular dependency, hence time travel cannot be created.

Now, I agree with you that this is paradoxical, but the fact is that it happened. We have no way of communicating with the future us, since tachyonium only allows one-way communication into the past. Future us also never disclosed any information about who or what they are so we can only guess about their motivations, though I assume they tried to limit the possibility of paradoxes as much as possible.”

“But it’s still a paradox, it cannot be.”

“Well, look at it from our reference point: we obtained information from an external party, all is fine, time just moves on with that newly acquired information. The paradox only impacts the future reference point. What happened to them after the paradox was created? Will they simply stop existing? Will there be an alternate version of the future, a branch, so to speak? We don’t know. And I don’t think we can ever know. The only thing we can observe is that the same message kept repeating over and over again even until today. So that’s an argument for the alternate future still existing somewhere.”

“Alternate — you mean like a multiverse?”

“Not really. For a multiverse you’d need multiple material copies of the same universe, I don’t believe that’s the case here. We’re only talking about time that’s alternating. That’s one dimension, not the other three. If we assume that time is an infinite dimension that we cannot perceive from our point of view, but one that’s there nevertheless; then we might have found a way to navigate a small part of that dimension using tachyonium. We’re not changing anything, we’re only experiencing one slice of that time dimension, and we’re moving through slices whenever a paradox is created. So don’t think of it as multiple universes, think of it as multiple timelines within the same physical universe.”

“Well I grant it to you doc, your story is way more interesting than mine.”

He smiles and stares out the window for a moment.

“Our stories might actually be more intertwined than you think,” he continues. “Did you notice how those shuttles after takeoff mentioned that both the ship wasn’t authorized to launch, and the pilot is a wanted criminal or something alike? Yeah I don’t think them chasing us is only about you having helped criminals with your taxi services. I believe it’s about your ship.”

“What about my ship?” I doubt it has much impact on all of this.

“See, ISTRA is what made it possible for you to be prosecuted, but ISTRA itself is one of the measurements taken to prevent our research. After three years of experimentation and research, we presented our findings to a special board of UN and USN members. They concluded that we weren’t allowed to continue it any further. On top of that, they created ISTRA to prevent us from bringing this research into the practical field.”

“How does ISTRA prevent you from doing so?”

“Simple. By discouraging or prohibiting near-lightspeed travel, we cannot get to the one place we need to be for our next breakthrough.”

“At a random spot in deep space?”

“At a very specific spot within the Oort cloud, 31000 AU away, give or take.”

I already knew we were traveling far, but it’s only right now that I realize how far. The Oort cloud… that’s huge. “What are you going to do there?”

“If you’re ok with it, I’ll keep that information to myself until we’ve left Mars and are on our way. I also won’t give you the coordinates of where we’re traveling to, until we’re ready to go for real.”

Once again, the doctor makes me feel uncomfortable. He’s asking to put a lot of trust in him. What is in it for me? I grimace as I’m reminded about my fate if I were to go back to Earth, which I seemed to have forgotten for a minute while the doctor was explaining all his science to me.

“Look,” he says, when he notices my worries, “I don’t think I’ve given you any reason to doubt my intentions. I’ve told you everything I can at this point, and I’m more than happy to provide all the financial means needed to get us refueled and on our way. Once we’re ready to go, I’ll give you access to the bank account containing your full payment — which you can check and transfer up front, if you want to. You can still abort the mission at that point if you decide you can’t trust me, but I cannot take the risk of telling you where we’re going or what I’ll do there before we’re certain we’ll get there. I hope you understand”

I nod. It makes sense, the doctor has a way of swaying my doubts the moment he addresses them.

“I’m ok doc. Thanks for being as open as you can. Give me some time to let everything sink in. I think I’ll be fine.”

“Good. Feel free to ask any questions you have. If I can answer them at this stage, I will.”

I stare out the cockpit window. The stars look fabulous. Our journey won’t even make it halfway to our nearest neighboring star. That’s how big space is. It makes me feel insignificant, but that’s not a bad thing right now. The less eyes on me, the better.

First, I gave up on most abstractions. Oh, how young-me loved them. For present-me, abstractions are becoming more and more of a rarity. I just find that 95% of problems don't need abstractions, they are better to be solved in place. I remember I reached for abstractions whenever a problem could possibly need it, instead of when I actually needed it. I don't do that anymore.

Second, I find myself liking a functional mindset more and more. It's just simpler. I find it comfortable to split data and functionality, to keep my code as flat as possible. I'm still using classes and objects and their internal state, but overall these objects are looking more and more like functions: data goes in, data comes out. That's it.

Something I'm less proud of: testing is still a struggle. I don't really understand why. I know testing makes my life easier. I know it's good in the long run. And still, there's always a barrier to cross. In part, I think it's because of the friction and overhead that comes with testing frameworks, the setup, mocking, faking data, … It's really a shame that testing doesn't come more natural to me. I force myself to do it — and it always pays off — but still…

Next, I'm using less fancy shorthands. I don't care about clever oneliners anymore. I'd prefer to write a verbose if/else statement over cramming the same functionality in one line of code. Less is not always more.

Another realisation: I can't live without static analysis anymore. I remember using Sublime for the first 2 or 3 years of my professional programming career, but I don't understand how I made that work. Have I become lazy? Too reliant on my tools? I don't think so. I think I've optimised my toolchain to serve me better over the years. Let the computer do the boring things for me, I'll focus on the things I like.

Finally, I'm still using PHP. It has its quirks, it's old, it shows, I know. And yet… it's ok, it gets the job done. In fact, I like the language much more today than a decade ago. I think the past ten years have been great for PHP.

Here's to the next ten 🍻!

Read the previous chapter.

My initial plan is to refuel in Lunar orbit at one of the Gateway stations. With fully loaded engine injectors, we’ll be able to make the one lightyear journey just fine. The distance doesn’t matter all that much: as soon as the ship is traveling at near-lightspeed, it only requires a marginal amount of energy to keep its momentum. It’s the speeding up and slowing down to and from near-lightspeed that requires most fuel. For our journey, we’ll have to do the procedure twice: once traveling to the coordinates specified by the doctor, and once traveling back to Earth. Most taxis aren’t equipped with enough fuel capacity to do two consecutive full powerups and slowdowns, which is one of the reasons the doctor is so keen on traveling with me specifically.

Unfortunately, my initial plan won’t work. If Earth spaceports are already aware of my “wanted” status, it means there’s no chance we can dock at any official Lunar Gateway station. Luckily, there are the unofficial Lunar stations, run by individual companies. Oftentimes they are involved in shady business. They now seem to be our only chance of obtaining a full refuelment. It will cost a buttload of money, and I’m not even sure we’ll be able to dock anywhere. But, we’ll have to figure it out in Lunar orbit, because right now I need to focus on docking the shuttle to my ship and prepare for powerup.

We’re currently half an hour away from our rendez-vous point, and another problem already poses itself. Several problems, actually, if you count each of them individually: three shuttles launched 10 minutes after our takeoff, and they left little doubt as to their intentions:

“Taxi LT-22 Shuttle, this is UNJ-6, we urge you to stop your ascent and return to Earth immediately. Your ship wasn’t authorized to launch, and the pilot is to be apprehended immediately. Return to Earth, or offensive measures will be taken.”

I don’t worry — at least not more than I already did — it isn’t a lost cause yet. These shuttles can only be class-B patrol shuttles, given how fast they were launched after our departure. At full acceleration, they can’t keep up with us. However, they might be able to intercept us when we’re docking, which takes about 15 minutes, 10 if I’m pressured on time; and believe me, I am. Still, 10 minutes might be just enough for them to reach an acceptable interception range, which means they could fire at us at will. I’m unsure what kind of weapons these patrol shuttles are equipped with specifically. We might be able to take a couple of hits, but I would rather not put that to the test.

So, time is of essence. If we can dock, powerup, and leave within 10 minutes, we’re good. At least until we arrive in Lunar orbit. I drive the shuttle to max speed, nearing the limit of what’s safe this close to Earth, but maybe I can gain another minute or two.

The doctor knows exactly what to do in a tense situation such as this one: to say nothing. He doesn’t even look at me, and I’m thankful for that; we’re coming in on the ship, I have a visual, and I need to concentrate. It has a pretty unique design: two outriggers extend from the main ship, the outriggers house the engines and fuel injections, while the main part has the cockpit and cargo hold. It also has two docking ports: one up front, and one at the back. We’re coming from behind, so we’ll dock with the rear port, making sure I’m perfectly centered between the outriggers so that I don’t damage them. The question is: how much do I slow down before docking — or, in other words: can I find the balance between “a bumpy, yet successful dock”, or “slamming into my spaceship and die”. I rather have the first option, so I err on the side of safety, albeit by a slim margin.

Our relative velocity is still pretty fast: 5 meters per second, but I might be able to make it work. I keep half an eye on the clock as I’m using the sticks to guide the shuttle not-so-gently towards its goal.

“Remote connection established” comes up on the shuttle’s main dashboard. I tap the screen three times in the right places without even looking at it. It makes the ship start the powerup procedure remotely. That’ll save us two more minutes. I slow down to 3 meters per second because this is just way too fast. I notice a slight twitch in my hands as I grab the sticks again, a side effect of the adrenaline surging through my veins. We’re 15 meters out. 12. 9. 7. 5. 4. 3. 2. 1.

A huge tremor. In a reflex, the doctor startles and swings his arms trying to grab hold of something. Luckily he’s strapped in tight. We didn’t dock, but bumped. Distance is 2 meters. 3. 4. I give some more power. 4. 4. 3. 2. 1. Another bump, less powerful this time.

“Docking success” I feel another surge of adrenaline as I see that message pop up on the dashboard. Good, but there’s no time to celebrate. I leave the doctor strapped in, and launch myself towards the airlock beneath the shuttle’s control panel. It opens and I make way into the ship. I can navigate my ship blindly, so I make it through the cargo bay to the cockpit in no time. “Powerup 89%” the dashboard shows. Just enough time to set the right course.

“Of course it couldn’t have been that easy,” I mumble as I check available orbital maneuvers for the Moon. The closest window requires an almost full additional orbit around Earth, which is more than enough time for the shuttles to intercept us. That won’t work. Venus would be ideal: there’s a huge community of smugglers there — Venus is a Space Pirate haven. But it’s too far. We don’t have enough fuel to make it. Mars is within reach. But Mars… I don’t want to go to Mars. There’s so much risk of getting caught by officials in Martian orbit — the United Space Nations headquarters is on Mars. There is very little room for missteps there.

“98%”

It's our only chance. Mars it is. I set the course, just in time for powerup to complete. This isn’t a full powerup, mind you. A full powerup is required for near-lightspeed travel, but we don’t need near-lightspeed to get to Mars.

“Autopilot engaged”

We’re off. Our velocity is increasing and for a moment I feel the g-forces pressuring me in my seat. It doesn’t take long before the g-shields kick in, and pressure is back to normal. We’ve escaped. Just like that. I smile, big time. I did it. At least, the first step. I look at Earth’s projection on the dashboard and can’t help but feel that familiar feeling whenever I set out on a new trip. Earth is home, but it also isn’t. From Earth’s perspective, I’ve spent way more time on this ship than over there. But from my point of view, even though she changes with every trip, and even though it’s hard to resettle time and time again; she is home.

“See you soon”, I say to myself as the globe grows smaller and smaller. I startle from my thoughts as I remember: I need to get the doctor.

Whether you plan on using Tempest or not, whether you plan on writing your own framework one day or not, I think you'll find what comes next interesting and inspiring!

# Setting the scene

First, let's talk about the core characteristics of this ORM. It's important to understand the challenges I ran into later on. First, I find static analysis important — really important. That's why I want typed properties to be the core of Tempest's design.

I prefer to start with the end goal — the user-facing code — in mind, so I drafted something like this as a Tempest model class:

class Book
{
    public function __construct(
        public string $title,
        public DateTimeImmutable|null $publishedAt,
        public Author $author,
        /** @var Chapter[] $chapters */
        public array $chapters,
    ) {}
}

Note how we're not doing any manual relationship configuration. In fact, it's one of the key characteristics of Tempest to be smart enough to reduce as much config as possible. The Author type of the $author property is enough to determine that this is a belongs to relation, the /** @var Chapter[] $chapters */ docblock on $chapters is enough to know this is a has many relation. Yes, I know docblocks suck. Let's hope PHP gets typed arrays one day. Why a docblock and not an attribute? Well we need the docblock anyway if we want proper type analysis on the property — my core requirement — so it would only make people's lives more difficult if they had to add an attribute on top of a docblock:

/** @var Chapter[] $chapters */ // Meh
#[HasMany(Chapter::class)] // Even more meh
public array $chapters,

Another important design decision in Tempest is that model classes aren't directly tied to the database. You can load model classes from a database if you want to, but they could also be persisted to a JSON file, a Redis store, XML, whatever you can think of. Granted: your average app will persist most of its models to a database, so there is a trait in Tempest to help you with that:

class Book implements Model
{
    use IsModel;
    
    public function __construct(
        public string $title,
        public DateTimeImmutable|null $publishedAt,
        public Author $author,
        /** @var Chapter[] $chapters */
        public array $chapters,
    ) {}
}

(Note to self: I still have to rename the interface and trait to DatabaseModel)

Anyway, those are models. Let's talk about lazy loading next.

# Lazy loading

Let's say you retrieve a book from the database (this find() method is provided by that IsDatabaseModel trait):

$book = Book::find($id);

By default, it won't load relations like $author and $chapters. Think about it: in this example it wouldn't be a biggy to load two relations, but what happens if each $chapter has a backreference to the book? And each $author has an array of its books as well? Or, what if an author has a relation to a $publisher, which has a list of all books published, … will you always load all relations? No, that wouldn't be very performant, and even if it would be performant enough, it would need a lot of — wasted — memory. That's why, by default, Tempest doesn't load relations. In case you need a relation to be loaded, you'll have to specifically say so:

$book = Book::query()->with('author')->find($id);

This is no different from what Laravel does by the way: it also doesn't load relations up front unless you specifically tell the framework to do so (this mechanism is called "eager loading"). However, Tempest goes one step further. If you happen to access a relation that's not loaded, Tempest won't load it for you behind the scenes. Instead, it will throw an error:

$book = Book::find($id);

$book->author; // MissingRelation

This is different from Laravel, and a very deliberate decision. In Laravel, Eloquent will lazily load missing relations for you by default. So if the relation isn't currently loaded, Laravel will perform an additional query on the fly to retrieve it for you. This again doesn't seem like a big deal in an isolated example, but let's say we're looping over an array of books instead:

<div :foreach="$this->books as $book">
    {{ $book->title }} by {{ $book->author->name }}
</div>

Sidenote: the syntax you're seeing here is part of my work in progress view engine for Tempest — yes, I'm also writing a view engine besides an ORM.

Back to the problem with lazy loading: if we didn't load $author up front, lazy loading would perform a separate query for every book in the array. This is the infamous n+1 problem, and it's one of the most common performance issues in Laravel. I can't remember how many hours I spent chasing and fixing n+1 issues in Laravel applications. It often had impact production app performance by seconds, and often required hours of debugging and fixing. Remember that, in real life, model schemes are much more complex than a simple belongs to relation, which means that solving n+1 issues is often more complex than to "eagerly load everything", which would lead to serious memory issues in some cases. It really is a time sink.

Now, Laravel has addressed this issue in part a year or two ago: you can now disable lazy loading manually. By default, Laravel still lazily loads everything, but good for them acknowledging the issue and providing an easy way of disabling it. By doing so, you're getting forced to think about these problems up front, instead of trying to fix them when they pop up.

I'm not here to dis Laravel by the way; I love Laravel, and I totally understand the decision to make lazy loading the default. Starting from scratch though, I have a opportunity to rethink the pain points I experienced with Laravel, and so I decided on another approach: lazy loading is off by default, but you can turn it on manually for specific properties. It looks like this:

#[Lazy] public Author $author,

Personally, I like these defaults better: nothing is lazily loaded, unless you specifically say so. It does require a programmer to micromanage which relations are loaded up front — true — but let me tell you, the same happens in Laravel as soon as you have an app whose model scheme is somewhat larger than two or three belongs to relations. I just did a quick search in the codebase of RFC Vote, built with Laravel. It's not even a big app, and we're already manually loading relations in ten different places to prevent n+1 issues.

return Rfc::query()
    ->with(['arguments', 'yesArguments', 'noArguments'])
    // …
    ->get();

So, that's the theory. How do you make this work in PHP? That's where things get fascinating.

# Just a tiny bit of hacking

Back to our initial example, the Book model:

class Book implements Model
{
    use IsModel;
    
    public function __construct(
        public string $title,
        public DateTimeImmutable|null $publishedAt,
        public Author $author,
        /** @var Chapter[] $chapters */
        public array $chapters,
    ) {}
}

Let's say we build and perform a query to select all relevant fields (everything besides the relations). We retrieve that data as an array, and map that array onto the object. This is what such an object would look like after that mapping has been done:

Book {
    title: 'Timeline Taxi',
    publishedAt: null,
    author: uninitialized,
    chapters: uninitialized, 
}

The interesting parts here are the unitialized properties: typed properties that haven't been initialized yet. We didn't load relations, so we didn't initialize those properties. Don't worry if you don't know how to do that in PHP — we'll come back to it.

Now, because of how PHP works, uninitialized properties don't throw any errors after constructing an object. In other words, you can perfectly construct an object with uninitialized properties. PHP will only check and throw errors on uninitialized properties when you try to read them. It's perfectly fine to build an object via reflection without calling its constructor (we'll come back to that).

This means we can keep the relation's type itself clean (remember that core requirement?) We don't need to make its type nullable or provide another kind of "special value" for relations. If PHP didn't have an uninitialized property state, we'd have to resort to doing something like this to mark relations as optional:

class Book implements Model
{
    use IsModel;
    
    public function __construct(
        // Allow a union on a special "missing relation" type:
        public Relation|Author $author,

        // Making the relation nullable would be an option as well:
        /** @var Chapter[] $chapters */
        public ?array $chapters,
    ) {}
}

Now I don't know about you, but I like to write as little code as possible, especially if the framework can do the work for me. On top of that, I like to keep my type definitions clean, and not make them unions or nullable just because of a technical requirement. That's why I like embracing the uninitialized state.

Sidenote about that: once again I wish we had generics in PHP, in which case we could probably do something like this:

public function __construct(
    public BelongsTo<Author> $author,

    public HasMany<Chapter> $chapters,
)

Anyway, that's just me dreaming out loud, it'll probably never happen.

So, what's next? We need a way to execute some checks when a user tries to access this uninitialized property. Easy enough, right? PHP has a magic method, __get() that will trigger every time you access a non-existing property on an object. That should be easy, right?

trait IsModel
{
    public function __get(string $name): mixed
    {
        $property = new ReflectionProperty($this, $name);

        // If this property is allowed to lazy load, load it 
        if (attribute(Lazy::class)->in($property)->exists()) {
            $this->load($name);

            return $property->getValue($this);
        }

        // Otherwise, throw an exception
        throw new MissingRelation($this, $name);
    }
}

Well… nope. That doesn't work. Wanna know why? Trying to access an uninitialized property on a class doesn't trigger __get()! Why — you wonder? Because the property we're trying to access does in fact exist, it simply isn't initialized yet. So instead of triggering __get(), PHP will throw an error:

Fatal error: Uncaught Error: Typed property Book::$author 
must not be accessed before initialization

You didn't think it was gonna be so easy, did you? This is PHP, after all 😅 Now, luckily, there is a way around this! This is PHP, after all. 😎

To explain the workaround though, I'll need to first explain how model objects are created. I already mentioned they are constructed without triggering the constructor. That's done via reflection. Let's assume we have this array of items — the result of our initial SELECT query:

[
    'title' => 'Timeline Taxi',
    'publishedAt' => null,
]

Tempest has a class ArrayToObjectMapper, which knows how to transform this data into an object (it can also do this with nested properties, etc, but let's keep it simple for this example). From the outside, it looks something like this:

$book = map($query)->to(Book::class);

Now, this is what happens behind the scenes: the mapper will create an object of Book, without calling its constructor, it will then loop over all public properties, and it will set those property values to what's present in the input array (the $query data):

final readonly class ArrayToObjectMapper implements Mapper
{
    // …

    public function map(mixed $from, mixed $to): object
    {
        $reflection = new ReflectionClass($to);
        
        $object = $reflection->newInstanceWithoutConstructor();
        
        foreach ($class->getProperties(ReflectionProperty::IS_PUBLIC) as $property) {
            if (! array_key_exists($property->getName(), $from)) {
                continue;
            }
            
            $property->setValue($object, $from[$property->getName()]);
        }
    }
}

Now, this is a simplification of what's really happening, but it's enough to understand how we're going to hack PHP <insert delirious laugh here>!

I might be overhyping it a bit though, since it's just one line of code. Remember that we want __get() to trigger on properties that aren't initialized. In other words, we want __get() to trigger on properties that didn't have a value present in the $from array.

Turns out you can do exactly that, even for properties that aren't initialized, by manually unsetting the property, like so:

public function map(mixed $from, mixed $to): object
{
    $reflection = new ReflectionClass($to);
    
    $object = $reflection->newInstanceWithoutConstructor();
    
    foreach ($class->getProperties(ReflectionProperty::IS_PUBLIC) as $property) {
        if (! array_key_exists($property->getName(), $from)) {
            unset($object->{$property->getName()});
            
            continue;
        }
        
        $property->setValue($object, $from[$property->getName()]);
    }
}

Indeed, by unsetting a property, even though it was never initialized, and even though it exists in the class definition, will make PHP think it doesn't exist, and trigger __get()! 🎉

This makes it so that we can use typed properties (promoted or not, both will work), without having to make them nullable or anything else. Tempest will be able to hook into unloaded properties via __get(), which means we can add support for lazy loading, and we can throw proper errors whenever a user accesses a property that wasn't loaded.

Beautiful, isn't it? Of course, it would be much easier if there was a magic method that hooked into uninitialized property access; but that, we don't have. Luckily PHP wouldn't be PHP if there wasn't some obscure workaround for it, and that's exactly what we've done!

That's about all I wanted to share today. Next up my list is supporting eager loads — basically always loading a relation, even if you didn't specify it manually. Shouldn't be difficult though.

By the way, I just read through the lazy objects RFC, which might make all of this much easier in PHP 8.4!

Leave your thoughts in the comments down below! Oh and, if you're wondering about that book title I used in the examples, you can read about it here: https://stitcher.io/blog/timeline-taxi-chapter-01.

Let's see: I'm currently improving Tempest's ORM, which means nothing more than "generating the right queries (text processing), and mapping the data unto objects".

I while ago, I wrote a code highlighter. It's basically the definition of text processing. I also built a console framework, which is nothing more than processing an incoming command (which is text), and generating the appropriate output (which is text). Routing? Processing an HTTP request (text), map its data to a controller, and eventually return text again. Building a template engine? Text processing.

Especially with programming languages like PHP, within a web context; 99% of things we're doing is processing text and moving data from one point to another. I like that realization, because it means I can boil down what seem to be the hardest problems, into relatively simple pieces. I wanted to share that with you, maybe you have some additional thoughts? You can leave a comment to let me know!

Read the previous chapter.

“Jonathan Russel speaking,” the voice on the other end of the phone says.

“Is your offer still standing?” I ask him directly. He doesn’t need any other explanation.

“Of course, did you change your mind?”

“Can you meet me in an hour in Yokohama spaceport?”

“Sure can.”

“I’ll meet you at gate A44, that’s within the non-commercial section. I’ll see you there.”

I hang up. On my walk of shame back to the hotel, I decided there was no way I’d spend two years in prison. So the only option left is to do what I usually do: fix Earth problems by leaving Earth. Sure, half a lightyear back and forth is a little bit over the top, but there’s no way I can find another client on such short notice who’s willing to pay what doctor Russel pays. And I will need the money a hundred years from now. It’s not ideal, but it’s way better than two years in prison and being broke afterwards.

I pick up the phone again and dial the other number.

“This is Wakato.”

“Wakato, hi. There’s a change of plan, I need to leave as soon as possible, don’t ask any questions, I’ll explain later. How’s the ship?”

“Post-flight maintenance has been done, everything’s checked, sir. Refueling is scheduled within two days. Apart from that I’m looking into the kitchen upgrades you mentioned.”

“Yeah, we’ll have to scratch those upgrades I’m afraid. Can you prepare the shuttle and load it with enough rations?”

“I can sir, but can I ask what’s going on?”

“I’ll tell you when I’m at the spaceport, I’ll be there in less than an hour.”

“Sir, do you want me to ration the shuttle within the hour?” Wakato asks, surprised.

“If possible, yes.”

“That’ll be difficult —”

I interrupt him: “Can you do it?”

He pauses for a second.

“I can, sir.”

“I’ll see you in an hour.”

I hang up and make my bag. I don’t know how much freedom is involved in “having a week to get things in order”, so I’m not sure if I’ll even make it to the spaceport. I figure the faster I go, the better.

I rush out of the hotel, get a cab, and make it race to the spaceport. My bag in hand I run past the travel gates into the non-commercial section. I’m fifteen minutes early, so I don’t expect doctor Russel to have arrived yet, but there he stands, in front of gate A44.

In surprise, I blurt out “you’re fast!”

“I’m not fast, I’m prepared.” he replies.

“Hang on. Do you know what's going on?”

Now he looks at me, surprised. “I’m not sure what you mean? You called me, so here I am. I just meant that I didn’t need to pack anything, I had everything already in order. What happened then?”

I shake my head. “Later, we need to hurry.”

“Well I’m not that much in a hurry, I’m sorry if I gave you the impression I was. A couple of days of preparation time would have been fine.”

“Obviously I am in a hurry. I’ll tell you later. Let’s get to the shuttle. Do you have everything you need with you?”

He points towards two large bags in front of the gate. “Is there enough room for those?”

“That should work.”

I lead the doctor through gate A44, straight onto the shuttle fields. Wakato’s there, frantically directing two technicians who are rationing the shuttle.

“Sir!” he exclaims when he sees me. “Are you ok?”

“Wakato, I’m glad to see you! Let’s talk in a minute. This is doctor Russel, he’ll be my next client. Could you load his bags into the hold while I set him up in the shuttle?”

Wakato has a confused look, but smiles and takes the doctor’s bags without any questions. I lead the doctor into the shuttle, and set him up in the main passenger’s seat.

“Are you ok waiting here for a couple of minutes? I need to check some final things with my valet.”

I exit the shuttle and pull Wakato aside. I tell him what happened in the police station only a couple of hours ago. He looks at me in disbelief.

“I’m so sorry sir, if I had known that gentleman inquiring about you last year was a cop, I would have never told him anything!”

“Don’t worry about it, Wakato, even if you hadn’t told them anything, they would still know when I returned based on the public flight records. There’s nothing you could have done to prevent this. How’s the fuel situation? I know we can’t do a full powerup right now, but can I make it into Lunar orbit?”

“Yes, that should work perfectly. You can even reach Mars, but going any further would be too risky.”

I nod. Lunar orbit should do.

“I have to say, sir, I should have told you about ISTRA right upon your arrival, but I know you like a couple of days off before getting up to speed, and I figured it wouldn’t be this time pressing…”

“I don’t think it would have made a difference, Wakato. Those people knew I was here as soon as I contacted Earth upon my return. I’m surprised they weren’t here to meet me right on the spaceport. Probably because I made a last-minute change to my landing schedule.”

“So… you’re leaving for a hundred years then?”

“I’m afraid so. I’m lucky this client was here in the right place and time. No room for me to get picky, I'm afraid.”

“That means then…”

“I’m afraid so, Wakato San. I’m afraid so.”

We look at each other for a moment in silence. I extend my hand and shake his.

“Thank you for all your help these past decades. You’ve been the best valet I’ve ever worked with. You know I mean that.”

He bows. I bow in reply.

“Well, no more time to waste. I hope we manage to take off, otherwise we might see each other again in half an hour.”

The technicians have just finished loading the rations, and I make it back into the shuttle. Doctor Russel is waiting patiently and smiles when he sees me again.

“Everything ok?” he asks.

“Everything will be ok.” I reply. “I’ll tell you all about it once we’re on our way, but now we need to lift off.” I sit in the pilot seat, and perform all preflight checks in silence.

“Yokohama, Tower, this is Taxi LT-22, come in.”

“Taxi LT-22, this is Yokohama, Tower, we copy you.”

“Requesting permission for stationary departure, currently standing at gate A44, destination orbit lane A44, section D.”

“Copy, stand by.”

Silence as my heart throbs in my throat.

“Taxi LT-22, this is Yokohama, Tower. Permission not granted, I repeat: permission for stationary departure not granted.”

I curse. I usually don’t, but today I do. I look at the doctor’s puzzled face.

“Yokohama, Tower, copy that, permission not granted. Can you tell me the reason?”

“Taxi LT-22, your shuttle has been flagged for government inspection and is not allowed to leave the spaceport until further notice.”

I curse again. I turn to the doctor.

“So, doc. I need to tell you something.” I give him the short version of what happened. He listens patiently, without interruptions. When I’m done, I wait for him to reply.

“So, to be clear.” He replies. “My mission is absolutely crucial, not just for theoretical science, it will have a huge impact on the future of space travel in general. I came here looking for you, since you’re the only pilot we could find after two years of searching who’s able to make this journey. You noticed I came here immediately after you called me, that’s because I’ve been ready to go at any given moment for a while now.”

He pauses, as if he’s thinking about the best way to phrase this.

“Look, I’ve given everything for this research the past five years. It’s my life’s work, and I don’t care about the consequences in this current time. If I want this research to succeed, I need to gap half that lightyear. So, as far as I’m concerned, I’m fine to do whatever it takes to get there.”

I look at him in silence. If I’m doing this, I’m taking a huge bet on someone who’s practically a random stranger. I haven’t had the time to properly vet him as I usually do with my clients. I haven’t had the time to properly overthink the consequences of bridging a hundred Earth years. I don’t even know how he’ll be able to pay me a hundred years from now. But what’s the alternative? Prison and being broke afterwards.

I curse, one last time.

“Yokohama, Tower, be advised, proceeding with unauthorized stationary takeoff from gate A44. Please make way.”

“Taxi LT-22, permission not granted, I repeat, permission NOT granted.”

I hear a faint siren in the distance, but it’s quickly overturned by the sound of the engines.

“Hold on, doc.”

Read the previous chapter.

Doctor Jonathan Russel from the Sheffield Institute of Space Travel stands out indeed, dressed in a typical brown English raincoat, a hat, a small bag in one hand, and an umbrella — an umbrella of all things — in the other.

“Where did you think you’d travel to?” I ask him with a sarcastic smile.

“Oh it was raining in the UK when I boarded the plane, I had almost no time to prepare, so here I am.”

The doctor smiles and I have to admit, he seems like a genuinely pleasant person at first sight.

“Would you like to sit, have a drink perhaps?” He proposes as he holds a chair for me. The hotel’s lounge is crowded, noisy even. I don’t like it here.

But we sit down, I order my usual, the doctor orders coffee, which I find odd for an Englishman.

“It’s been a long flight,” he tells me when I ask about it.

“So, how about we skip the smalltalk?” He continues.

I think I like this man.

“On the phone I told you I’m a doctor at the Sheffield Institute of Space Travel. Have you heard of it?”

I shake my head.

“Naturally,” he continues. “The institute was founded five years ago, so it makes sense that you haven’t heard of it, I believe you were still traveling back then.”

I nod. This doctor seems to know a lot of things about me…

“We’re concerned with the theoretical and practical study of space travel and everything related to it. I particularly, am working on a study about possible ways of dealing with time dilation — a concept you’re fairly familiar with, I reckon; given that you’ve made it into your job.“

I nod without interrupting.

“Now, part of my study involves a practical test, flying to a specific point in space, and back. I’m looking for a pilot.”

Well that’s all still pretty vague if you ask me, I’m still not sure what the doctor actually does, and why is he talking to me? There are plenty of UK taxi pilots. No need to come to me.

“Look, I just came back from a trip, and plan to stay for a year or two. If you want to, we can schedule a trip two years from now, but I’m sure you’ll find other taxis that are available to leave earlier.”

“Well, here’s the problem. No other taxi pilot wants to take me.”

“Well that’s not a good way to sell yourself, doc!” I exclaim as I lay back in my chair and sip my glass.

“Oh it’s nothing bad though, it’s just that… See, this place I want to travel to is — well — it’s far.”

“How far?”

“Slightly more than half a lightyear away.”

I whistle as I sit up straight again, my glass still in my hand but I’m not sipping it anymore. “Yeah that’s not gonna happen, doc! That’s what — more than a year of travel time back and forth, so a hundred years of Earth Time. No way any pilot wants to make such an investment.”

“I was told you do long trips though, longer than usual trips.“

“I do,” I hesitate to say while I’m thinking about how to end this conversation — no way I’m going to travel that far — “but not a hundred Earth years! 30, 40 years, maybe? The longest trip I ever did was 43 years. But let me tell you: that was no fun coming back. No way I’m doing a hundred!”

“What if I told you that price wouldn’t be a problem? And, sure, such a big time gap is huge, but you’ve now bridged, what, 500 years in total?”

“453,” I correct him.

He’s quick with his reply: “Well in total that’s significantly more than a hundred!”

“How do you know so much about me? And what kind of price are we talking about when you say it isn’t a problem?” Ok, I can’t help being a little bit intrigued.

“Four times your normal rate. But I’m allowed to bargain up to six times, so let’s just say six.”

The doctor’s smart. He ignored my first question and distracted me with a huge pile of money instead. I look at him in silence for a moment.

“No, I won’t do it,” I conclude after a moment and intense staring from the doctor’s side. “There’s too much risk, half a light year, that’s — that’s huge, it’s too much.”

The doctor looks at me, disappointed, but I can also see a level of understanding in his eyes.

“So,” he says after having thought it over for a while, “if you find yourself doubting that decision in the coming days, would you be so kind as to give me a call? You can reach this number,” and he slips me a business card of some sorts.

“I’m pretty sure I won’t,” I say as I grab the card and slide it into a pocket, soon to be forgotten. I get up, shake his hand, and leave him at the bar. Time for my bath. I make it up to make room, undress — again — as I refill the bath, I slide into the hot water, and close my eyes. Bliss.

A while later — I’m not sure how much later — I’m woken from my slumber by a loud knock on the door. I can hear someone shout my name in the distance. I hear a loud bang as I sit up half confused, and two seconds later the bathroom door swings open. Two cops grab me from the bathtub. They don’t care about me being naked, they grab a towel, wrap it around my waste, and drag me down the hallway. In total bewilderment, I just let it happen.

It’s only when I’m sitting in the cop’s car that I get a chance to gather my thoughts. “Hey!” I shout towards the cops in the front of the car, “what’s going on?” My wrists hurt, I was handcuffed right before I was pushed into the car. The cops ignore me.

“Hey!” I shout again. No answer. I kick the seat in front of me. No answer. I kick it again, not expecting an answer but simply out of anger. I’m driven to what I suppose is the police station, though I’m not familiar enough with Yokohama to be sure. It looks boring and official. It could be a police station.

The cops lead me down the hallway — dressed only with a towel around my waste, mind you. Somewhere along the hallway, they stop at a random door, open it, and lead me in. They remove my handcuffs as I sit down on one of the two chairs in the room. “What is going on?” I demand once more. No answer. They both exit the room and the lock clicks shut.

I look around. What is this place? Is this an interrogation room? I’ve only seen them in detective series. It looks like an interrogation room. With the two chairs, the table in between, the mirror glass. Yeah, this is an interrogation room. “Hey!” I shout again, but there’s only silence. It probably takes no more than ten minutes — but it feels like an hour — when suddenly the door clicks and swings open. I look startled as a tiny man walks in. He smiles faintly, puts down a huge stack of papers on the table, and sits in front of me.

“Do you have any idea why you’re here?” He asks without introducing himself.

“No”, I snap, “who are you?”

“You’re a taxi pilot, is that correct?” The man continues and ignores my question.

“I am, who are you?”

“Are you aware of the International Space Travel Regulations Act of ‘91?” He continues, flipping through some of the papers without looking up.

“‘91? That’s what? Three years ago? No, I was traveling back then. I just arrived back and haven’t had a chance to catch up with everything. Who are you?” I ask once more. “What am I doing here?”

Still, he ignores my question.

“I figured.” He mumbles. “The International Space Travel Regulations Act — ISTRA — was signed by all UN countries three years ago. It details all regulations concerning space travel, including providing taxi services to convicted or suspected criminals. Something you aren’t unfamiliar with, are you?”

He looks up now, I stare at him. He seems to enjoy this moment.

“The interesting part about this law is that it acts retroactively up to 300 years.”

He pauses for dramatic tension. I decide to not give him the satisfaction and continue to stare with a puzzled gaze. Not receiving the hoped reaction, he sighs, then continues.

“So, you’ve been doing a lot of traveling, haven’t you?”

“I do.”

“Well, let me cut to the chase” he seems to have already lost his patience. ”You were reprimanded for many of your taxi travels, including the most recent one with a certain individual called mr. Tunaki. You’ve had a trial and,”

“Hang on,” I say, “a trial?”

“Like I said, a trial, a little over a year ago. We actually tried to contact you via your valet but it seems that you were unavailable at that time. Section C of ISTRA mentions that after three failed attempts at communication with a suspect, we’re allowed to charge that person in absens — that’s Latin — meaning there’s an immediate trial. If, during that trial, said suspect still isn’t able to provide any rebuttal, the charges are automatically accepted.”

The cop stops reading from what I assume is a printout of section C of the so-called “International Space Travel Regulations Act”. He looks at me. I can’t say anything.

“Anyway,” he concludes, “you’ve been convicted on all accounts. Since you weren’t available at the time of sentencing you’ve received a suspended sentence, as well as a fine. This last one will be automatically collected from your bank account now that you have been informed about the sentence. Any questions?”

I look at him in disbelief.

“Well,” I stammer, “why did you abduct me out butt naked from my hotel room?” It’s the only reasonable question I can come up with, I’m still processing the rest.

“Sure. ISTRA section C also outlines the procedure for dealing with absent suspects or convicts upon their resurfacing. They are to be informed immediately, or as soon as possible, about their current situation. This is of course meant to protect the rights of each suspect, or, in your case, convict.” He smiles when he says “convict”.

“So what, a fine?”

“Yes, well, the fine was set on, let me check, 1.2 million Earth Dollars, since you’re an Earth Dollar Bank client, we can automatically collect this charge from your account, which will happen as soon as you leave this office.”

“But, you can’t do that!” I shout. I want to stand up but realize just in time that my towel might drop… so I stay seated.

“As a matter of fact, sir, I can, and I have. The charge has already been prepared and will be automatically deducted once you leave this office.”

I can’t say anything. 1.2 million is almost the whole of my capital. But the cop doesn’t stop there.

“As to your suspended sentence, you’ll still have to serve it. The judge ordered, let me check, 2 years in prison. We won’t arrest you right now, because we want to allow you to get your business in order before serving your sentence. You have a week where you’re not allowed to leave the city, your passport has been invalidated, and together with the fine charge, all access to your bank account will be blocked until you’ve served your sentence. You’re to report next week, Monday, at 7 AM in Yokohama General Prison. If you fail to report there on time, you’ll be arrested and your sentence will automatically be prolonged by a year. At least, that’s what the judge’s order says. Any questions?”

I just stare into nothingness. Less than an hour ago, I was having a bath, now I’m a convicted criminal. I’m out of money and I’ll have to serve two years in prison.

“No? Ok, then you’re free to go, until next week, of course.”

The cop smiles, stands up, walks to the door and unlocks it with some kind of wristband sensor. Another cop walks in, drags me up — I’m just in time to grab my towel — and leads me out. I’m handed a folder of papers while walking out, my file with all necessary information, and that’s it. I’m on the street in front of the police office. In a towel.

$numbers = [1, 2, 3, 4, 5, 6];

$firstMatch = array_find(
    array: $numbers, 
    callback: fn (int $number) => $number % 2 === 0
);

To start off with, I want to make a note on naming conventions: in Laravel, the function that returns the first element from an array that matches a callback is called Collection::first() instead of find. This might cause some confusion for people expecting array_find() to return all elements that match the callback's condition.

The decision for array_find() over array_first() isn't all that weird though: lots of languages implement a method to find the first matching element from an array, and those functions are always called find. Just to name two examples: JavaScript and Rust.

If you need a way to get multiple elements from the array based on a callback, then the array_filter() function is what you're looking for.

$numbers = [1, 2, 3, 4, 5, 6];

$allMatches = array_filter(
    array: $numbers, 
    callback: fn (int $number) => $number % 2 === 0
);

Another important thing to note is that array_find(), as well as the three other functions (we'll look at those later in this post), they accept both the value and key as arguments in the callback function:

$firstMatch = array_find(
    array: $array, 
    callback: fn (mixed $value, int|string $key) => /* … */
);

By the way, you can read with me through the RFC to learn about all the details:

# array_find_key

Besides array_find(), there's now also a function called array_find_key(). It does exactly the same, but returns the key instead of the value of the matched element:

$numbers = [1, 2, 3, 4, 5, 6];

$firstMatchedKey = array_find_key(
    array: $numbers, 
    callback: fn (int $number) => $number % 2 === 0
);

# array_any and array_all

Finally, there are two related functions added, these two will return a boolean instead of a value. array_any() will return true if at least one element within the array matches a callback's condition, while array_all() will return true, only if all elements match the callback's condition:

$numbers = [1, 2, 3, 4, 5, 6];

// True: at least one element is dividable by 2
array_any(
    array: $numbers,
    callback: fn (int $number) => $number % 2 === 0
);

// False: not all elements are dividable by 2
array_all(
    array: $numbers,
    callback: fn (int $number) => $number % 2 === 0
);

// True: all elements are smaller than 10
array_all(
    array: $numbers,
    callback: fn (int $number) => $number < 10
);

# Property hooks RFC

One of the biggest changes in modern-PHP history: the ability to define property hooks, eliminating the need for a lot of boilerplate code.

class BookViewModel
{
    public function __construct(
        private array $authors,
    ) {}

    public string $credits {
        get {
            return implode(', ', array_map(
                fn (Author $author) => $author->name, 
                $this->authors,
            ));
        }
    }
    
    public Author $mainAuthor {
        set (Author $mainAuthor) {
            $this->authors[] = $mainAuthor;
            $this->mainAuthor = $mainAuthor;
        }
        
        get => $this->mainAuthor;
    }
}

The goal of property hooks is to remove a lot of getters and setters, by allowing each property to define its own get and set hooks. Hooks are optional, and you don't have to add both of them on a specific property. For example, a property with only a get hook is virtual property.

There is a lot to say about property hooks, and I plan to write a followup post on them soon, so make sure to subscribe if you want to know when that one is done. One final thing I'd like to mention — probably what I'm most hyped about: property hooks can be defined in interfaces!

interface HasAuthors
{
    public string $credits { get; }
    public Author $mainAuthor { get; set; }
}

# new without parentheses RFC

As if property hooks alone wasn't enough, PHP 8.4 has another feature that will save so much boilerplate code: you don't have to wrap new invocations within parenthesis anymore to be able to chain methods on them. So instead of doing this:

$name = (new ReflectionClass($objectOrClass))->getShortName();

You can now do this:

$name = new ReflectionClass($objectOrClass)->getShortName();

I don't know about you, but I write a lot of code like this, and so I'm super happy that we're finally getting rid of those brackets. It doesn't only work for methods, by the way. You can also chain properties, static methods, constants — whatever you want. You can read all about this new feature in this dedicated post.

# JIT changes RFC

PHP 8.4 changes the way the JIT is enabled. Previously, you had to set opcache.jit_buffer_size to 0 in order to disable the JIT, but now you can disable it like so:

opcache.jit=disable
opcache.jit_buffer_size=64m

The only way users can be affected by this change is if they did specify a opcache.jit_buffer_size but no opcache.jit. In that case, you'll have to add opcache.jit=tracing to enable the JIT again.

Finally, there have also been some improvements to the JIT which makes it run faster in some cases, and use less memory.

# Implicit nullable types deprecation

PHP had this weird behaviour where a typed variable with a default null value would be made nullable automatically:

function save(Book $book = null) {}

// Deprecated: Implicitly marking parameter $book as nullable is deprecated,
// the explicit nullable type must be used instead

This behaviour is now deprecated and will be removed in PHP 9. The solution is to make Book explicitly nullable:

function save(?Book $book = null) {}

# New HTML5 support RFC

PHP 8.4 adds a \Dom\HTMLDocument class which is able to parse HTML5 code properly. The old \DOMDocument class is still available for backwards compatibility.

$doc = \Dom\HTMLDocument::createFromString($contents);

You can read all about the new HTML 5 parser here.

# array_find RFC

There's a pretty simple new function added in PHP 8.4, one of those functions that you have to wonder about "hang on, wasn't that available yet?" I guess most developers have grown used to third party collection classes, although I think having array_find() natively in PHP is pretty nice.

The naming might be a bit confusing though, because what this function does is it takes an array and callback, and will return the first element for which the callback returns true:

$firstMatch = array_find(
    $posts, 
    function (Post $post) {
        return strlen($post->title) > 5; 
    }
);

There are also some variations of this function called array_find_key(), array_any() and array_all(), you can read all about them here.

PHP 8.4 is still in the development phase, so there's of course more to come. I'll update this post over time, so make sure to subscribe if you want to be kept in the loop.

If you want something to watch next, make sure to check out my latest video as well:

So, yeah, classic PHP — right 😅? Well, we can laugh all we want, but let's take a moment to highlight new features that — albeit late — fix these quirks: PHP 8.4 is adding an HTML 5 compliant parser! In this post I'll go through the highlights of this new parser, and you can read with me through the whole RFC as well:

# Backwards compatible

One of the core requirements for this new parser is that it should be fully backwards compatible. That's why internals have chosen to make a completely new class — within a new namespace — to house the new HTML 5 parser. The old \DOMDocument class is left (mostly) alone. The only change in the old implementation is that \DOMDocument now extends the abstract \Dom\Document class, which is also the parent for the new, HTML 5 compliant implementation: \Dom\HTMLDocument.

If you want to use PHP's new HTML 5 parser, that's the one you need:

// HTML 5 compliant
$dom = \Dom\HTMLDocument::createFromString($html); 

While the old version is still available as usual:

// HTML 4-ish support
$oldDom = new \DOMDocument(); 
$oldDom->loadHTML($html);

# Constructing DOMs

One key difference you'll spot immediately is that the new implementation relies on static constructors instead of calling methods on the newly created object afterward. The new HTMLDocument class has three named constructors available:

HTMLDocument::createEmpty();
HTMLDocument::createFromFile($path);
HTMLDocument::createFromString($html);

These are their full signatures:

public static function createEmpty(string $encoding = "UTF-8"): HTMLDocument;
public static function createFromFile(string $path, int $options = 0, ?string $override_encoding = null): HTMLDocument;
public static function createFromString(string $source, int $options = 0, ?string $override_encoding = null): HTMLDocument;

For the $options variable, these options are available:

• LIBXML_HTML_NOIMPLIED
• LIBXML_COMPACT
• LIBXML_NOERROR
• \Dom\NO_DEFAULT_NS

The $override_encoding variable is used to override the implicit encoding detection routines as determined by the HTML parser spec. This can be useful when the document is downloaded manually.

# DOM Objects

Note that using the new implementation will result in other types of value objects to be created as well. For example, instead of \DOMNode, you'll get \DOM\Node; instead of \DOMElement, you'll get \DOM\Element, etc. The RFC originally aimed to keep these objects the same between the old and new implementation, but there turned out to be too many differences. You can read all about them here.

Albeit a bit late, I think this is a very nice addition to PHP. I definitely have some usecases for it! What are your thoughts? You can leave them in the comments down below!

A throbbing pain wakes me up as it shoots from my lower arm up to my shoulder. My first instinct is to reach for whatever’s hurting my arm, but I recover fast enough to know that I shouldn’t. It’s been centuries since the invention of deep sleep, yet we still need pain stimuli to wake from it. Why no one has bothered to come up with a better way than shooting electrochoques through an arm is beyond me. I turn right, mr. Tunaki is still strapped in firmly, deep asleep. Just the way I left him. I turn to the dashboard in front of me, both our vitals are good. Speed is nominal, 0.99995% c. We’re three days worth of travel time out from Earth. All is good. I remove the probe from my arm as I stare into the blueshifted space in front of me. Just the way I left it.

Mr. Tunaki gets another day of deep sleep before waking up. He doesn’t enjoy his pain shock either, but he’s a little more verbal about it. He reaches to his right arm and starts pulling on the probe — I need to pin his left hand to ensure he doesn’t rip his arteries. I’m serious: these probes make a mess when you pull them out uncontrolled. I once had a client who ripped it off as soon as he awoke and it took me three days of cleaning afterwards. Well, it took the valet three days of cleaning, no way I’m doing that myself. But I know the drill: secure their hands, let them curse, let them shout, lull them like a baby. “I understand it’s painful sir, I know it’s confusing. It’ll only take a minute. You’re doing good. You’re doing great, sir.”

The thought of almost being home helps mr. Tunaki to calm down. His crimes expired two Earth years ago, but we figured we would take some margin just to be sure. After all, it’s only a week of travel time for us, so why not? “Two more days,” I tell him as I hand him a bag of dried spinach pasta. 500 years of space travel and we’re still eating the same kind of boring food we’d eat back then. To be fair, I suspect there will be ships with more luxurious life support systems by now. I think I heard they were making significant progress in that area over the past decades. I might need to look into some upgrades. An updated kitchen would be nice. Luckily, mr. Tunaki doesn’t mind the food quality. He gobbles up his bag as if it’s the best meal he ever had. That’s what over 20 days of deep sleep does with a person — it transforms rubbish space food into a feast.

“Earth, Ground, this is Taxi LT-22, do you copy?”

“Taxi LT-22, this is Earth, Ground, we copy. Welcome back.”

“Earth, how are things down there? Everything’s still the way I left it?”

“Taxi LT-22, everything’s still good here, how was your trip?”

“All good, Earth, thanks. Glad to be back!. Can you send us our parking procedures? We’ll arrive in about two hours.”

“Taxi LT-22, copy, stand by.”

“Taxi LT-22, you can park in orbit lane A44, section B. You can shuttle down from there to Singapore spaceport.”

“Earth, Ground, thank you. Would there be any chance to shuttle down to Yokohama spaceport instead? I’ve got a client who’s from that region.”

“Taxi LT-22, copy, stand by.”

“Taxi LT-22, you can park in orbit lane A44, section D, and shuttle down to Yokohama spaceport instead.”

“Earth, Ground, lane A44, section D, shuttle down to Yokohama; copy that.”

“Taxi LT-22, your parking documents have been sent over. If you need anything else, let us know.”

“Earth, Ground, copy that; thank you, have a nice day.”

With a parking spot secured, I check up on Earth’s — and my personal — financial situation. In theory, the Earth Dollar should be pretty stable, but being away for years on end always has risks. It’s looking good though. Mr. Tunaki’s payment is already there as well. Perfect. There’s about two years of pure luxury waiting for me; and that is if I take into account the upgrades I want to do to my ship. I’ll have to talk to my valet about it. I hope Wakato is still working at Yokohama spaceport, that would be nice.

We park in lane A44, section D, and prepare for separation. I help mr. Tunaki into the shuttle, strap him in, and take place in the pilot seat. “This is the bumpy part of the ride,” I warn him. “There’s a bag underneath your seat if you need it.“

He needed it.

We arrive at Yokohama spaceport without any other problems, although mr. Tunaki vomited part of his spinach pasta outside the bag, onto his lap and, more importantly, onto the chair. “Don’t worry about it,” I lie, “this happens almost always.” Meanwhile I’m worrying about the poor valet who will need to clean up the mess. It stinks.

We make a soft landing on one of the spaceport runways and we taxi to gate A44. I power down the shuttle’s engine, and look who’s there!

“Wakato! Konnichiwa!” I exclaim in my best Japanese as I crouch out of the shuttle. “It’s great to see you!”

“Sir! It’s great to see you!” Wakato replies, “Did you have a good trip?”

“All fine. You don’t seem to have aged at all.”

“Oh but I did, and I’m noticing it more and more,” Wakato laughs. “I’m actually retiring next year.”

“Oh that’s too bad… you’re one of the best valets I’ve ever worked with, I mean that.”

“There’s a new guy here now, I’m training him to be my replacement. He’s pretty good, I think you’ll like him. “

“Ah well… we’ll see. Hey about the shuttle, my client wasn’t able to find the bag in time… So there’s some cleaning up to do. I’ve also ordered a refueling shipment. I checked fuel prices when I arrived and they seemed very favorable, so I just ordered a full refueling. Apart from that, it’s the standard maintenance tasks that need to be done, you know the drill, I’ve sent you the full report.”

“I’ll have all of it taken care of, sir!”

“Oh, could you look into whether we can upgrade the ship’s kitchen? I’m really sick of having to eat bagged food.”

“I’ll look into it and send you the available options, sir.”

“Thank you, Wakato San!”

“Sir, if you don’t mind. There was a gentleman asking about you a while ago. I told him you were still on your journey, but maybe you could get in touch with him once you’re back. It was a bit strange sir, the gentleman didn’t want to say why he needed you and didn’t want to leave any contact details.”

“Don’t worry about it,” I tell Wakato, “this happens to me multiple times. Potential clients want to get a hold of me as soon as possible, especially those with shady things going on in their lives.” I whisper the “shady” part because mr. Tunaki is unloading his bags from the hold, and can probably hear me if I speak too loud. “I’m sure he’ll be in touch again,” I continue, “if he hasn’t already found another pilot. In any case, I plan on staying for a year or two, so either he will have to wait, or find someone else. But thanks for letting me know!”

I grab my bag from the shuttle’s hold, shake mr. Tunaki’s hand, and wish him well. Who knows what he’ll do, but he’s not my problem anymore. I walk towards the spaceport exit hall, board the ferry, and am walking into the crowd ten minutes later. The city center is busy — too busy to my liking — but I make it to the hotel without any problems. I’ll stay here for a day or two to relax, then I’ll start to plan. Even though seven years is a relatively short period of time, it takes a significant amount of work and planning to get everything back into order. “Part of the job,” I mumble to myself as I sigh and open the hotel door.

It’s a nice room, it looks out on the spaceport floating on the bay in the distance. I hope Wakato can do something about that kitchen… I pour a drink from the minibar, and prepare a bath. Oh how I’m looking forward to a bath. I undress, drop all my clothes in the middle of the room. But right when I’m ready to step into the bath, the hotel phone rings. I sigh — again. My guess is that it’s Wakato with news about the kitchen, that’s fast; so I run to the phone and pick it up.

“Hello?”

I’m greeted by an unfamiliar voice.

“Yes, speaking,” I reply, “who is this?” Maybe it’s that client Wakato was talking about. I don’t really feel like meeting anyone right now…

“I’m sorry to disturb you, sir,” the voice replies, “I’m doctor Jonathan Russel, from the Sheffield Institute of Space Travel. I need to speak to you very urgently. I —”

“I’m sorry,” I interrupt, “mister, doctor, I just returned from a long trip, and I’m really not interested in whatever you wanna talk about. So thank you for your interest but —”

“Oh but sir,” the doctor says, “your valet told me this would really interest you.”

So it is probably that guy Wakato was talking about. Well, if he deemed it important enough to pass my private coordinates to a random stranger, then maybe I should check it out. I’ll admit, I am a little intrigued by what doctor Jonathan Russel from the Sheffield Institute of Space Travel wants to talk about.

“Ok,” I say, “you have five minutes.”

“I actually think it would be better to talk face to face,” the doctor replied.

I roll my eyes, whatever interest I had is quickly dissipating. “Look, I don’t feel like going out, maybe we should schedule an appointment somewhere in the coming week then.”

“Oh, no worries, sir, I’m in the lobby of your hotel. I can come right up if that’s ok for you.”

Suddenly I feel worried about the intentions of this doctor, he’s already in my hotel? But my curiosity gets the upper hand.

“I’ll come down,” I finally say, “I’ll meet you in the lobby. How will I recognise you?”

“Oh I’ll recognise you sir, but I’m basically the one person who’s dressed wrong for the occasion. You can’t miss me.” He chuckles as he says it.

“Ok,” I sigh out loud, “I’ll be there in five.”

Or, in other words, you can get rid of these two brackets:

(new ReflectionClass($className))->getShortName();

It seems like such a small change, but I write this kind of code so often, and it's so nice that I won't have to think about wrapping stuff in brackets again. Roman phrased it like this:

Every time I find myself typing new MyClass() and then returning back and adding those parentheses. It would be good to reduce this friction and make PHP coding flow smoother.

Exactly! It's these small things that have a huge impact on a daily basis. I love it! In this post, I'm going share some of the details of this new feature, and you can read with me through the whole RFC as well:

# Methods, properties, and more

Thanks to this new feature, you can chain much more than just methods on newly created objects: methods, properties, static methods and properties, you can use even array access or invoke the newly created class directly:

new MyClass()::CONSTANT;
new MyClass()::$staticProperty;
new MyClass()::staticMethod();
new MyClass()->property;
new MyClass()->method();
new MyClass()();
new MyClass(['value'])[0];

Granted, something like new MyClass()() looks a bit weird, it might just require some time to get used to, we'll see.

# Also for dynamic and anonymous classes

The same syntax can be used on dynamic class names: class names that are resolved via a variable or via function calls:

$className = MyClass::class;

new $className()->property;
new (trim(' MyClass '))->method();

As well as on anonymous classes:

new class () { /* … */ }->method();

While I think shorter isn't always better, it's good to have this functionality available, just in case.

# Constructor brackets are required

There's one caveat to this feature: the new class instantiation needs to be called with constructor brackets, even if no constructor parameters are passed:

// This is valid PHP if MyClass has an empty constructor
$class = new MyClass; 

new MyClass->method() // This isn't valid

new MyClass()->method() // But this is

The reason for this requirement is that without the constructor brackets, the PHP parser wouldn't be able to properly determine whether it's a new class instantiation or not. The RFC explains this behaviour more in depth in order to avoid any ambiguities.

# Anonymous classes are the exception

The previous limitation however isn't present for anonymous classes, because their constructor brackets come before the class' body:

new class { /* … */ }->method();
new class () { /* … */ }->method();

Both are valid.

Despite a couple of minor gotchas, I'd say this is a super nice addition to PHP, a small feature, but one with a big impact. Leave your thoughts about it in the comment section down below (I've added comments on this blog!), and don't forget to subscribe to my mailing list if you want to be kept in the loop!

Ok sure, luck had something to do with it, but the most crucial factor was actually a single blog post. One post, now more than 7 years ago, is what triggered a chain of events that led me to where I'm at today. I oftentimes remind myself of this blog post, and I think it would make an inspiring story to share with you as well.

So, back to 2017. I was working at your average web agency. One of my hobby side projects during that time was to build a static site generator in PHP. I needed a test subject, so I made a small blog to try it out. Eventually I lost interest in the static site generator idea, but the blog stayed. I'm still using that static generator to power what you're reading right now, but I would never want anyone else to use it.

Anyway, I wrote the occasional blog post, and one day I stumbled upon a video on Laracasts. It was titled "Visual Debt" — and boy, did I disagree with everything said in it.

So I reached for the only platform I had: write a reaction post about it. A couple of weeks later and I checked up on my analytics — I occasionally did so to see how many people were reading my stuff, mostly to boost my ego a little bit. That one post apparently had thousands of views — much more than any of the other posts I had written up until that point. What happened was that someone I never heard of shared my post on his newsletter, which apparently had a huge following, and it spread from there.

That someone was Freek. I checked out his website, which led me to his company's website, which made me realise there was this small agency called Spatie 30 kilometers from my home. Apparently, they were looking to hire a PHP developer. I had been close to burning out on my current job for months by this time, but I never have had the courage to start a new job search. However, this company really sparked my interest.

So I sent them a casual mail. I attached my CV, but most importantly, I attached my GitHub account. I was invited for an introductory meeting a week later. It went well, and I was surprised to learn that I didn't have to do any technical tests. They already knew my blog, they knew my GitHub, they knew me.

I woke up the next morning, finding an email from Freek in my inbox: "We really liked meeting you, and we'd like to invite you for a second meeting." A couple of months later, I started working at Spatie. I had an amazing 5 years there, met a lot of cool people within the community (offline and online), which is also how I met Roman, my current colleague at JetBrains. We were attending PHP Benelux, where I gave an unconf talk. It was about — believe it or not — that one blog post I wrote as a reaction to the Visual Debt video.

I kept in touch with Roman, and one day we started talking about an open position for a DA at JetBrains. He had been following my blog and YouTube content and thought I'd be a good fit. And so, here were are.

Had it not been for that one video about Visual Debt, I doubt I'd be where I am today. So, in a way, all of this is thanks to Jeffrey Way, the creator of that video. By the way, besides that one video about Visual Debt, I agree with almost everything Jeffrey does at Laracasts, so you definitely should check him out if you haven't heard of him.

Of course, I also have to thank myself for writing — I guess? I simply wrote whatever I wanted to write back then, I didn't have a content plan, I didn't have a strategy. I kept writing, and apparently it worked out pretty well.

I've never been a planner or a big strategist, let alone a skilled marketeer. I usually go where the flow takes me. I try to do whatever I like to do. That definitely makes me a bad businessman and I doubt I'll ever be able to count myself as one of the successful independent entrepreneurs. But I don't feel much ambition to be that. I just write some stuff and focus on the things I like to do, and it's leading me to great places anyway.

I'm going through a period of reflection these days, and it's showing me a lot of stuff I need to work on. But I'm also reminded about a lot of good stuff I'm thankful for. I figured I'd share those parts as well, because I think it could inspire a handful of people. Working on whatever makes you happy is a valid strategy. Not driven by money or fame, but just because you want to. Put that work out there in public. Not because you want to reach specific goals or numbers, but just because you can.

If you want to, you should.

PS: I've added comments to my blog, so you can leave your thoughts on this page now directly! I'd love to read your thoughts as well.

Keep in mind note that I'm working with the data available. That means that these charts are not a 100% accurate representation of the PHP community as a whole, but they are an accurate representation of one of the most prominent parts of PHP: the packagist ecosystem.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

# Usage Statistics

As usual, we start by looking at the percentage of PHP versions being used today, note that I've omitted all versions that don't have more than 1% usage:

Visualizing this data looks like this:

Evolution of version usage

An additional data point I wanted to look into this time, is to compare the growth of each PHP version the first half year after its release.

What's interesting is that the PHP 7.* versions seem to have had a faster adoption rate compared to PHP 8.* releases. From a personal point of view, I also feel less need to immediately update to newer PHP versions, especially since they didn't offer that many exciting features the past two years. I wonder if the adoption rate for PHP 8.4 will be higher or lower, especially since it has some very nice features (like property hooks).

Let's take one more look at version evolution across time, you can spot the slowed down adoption rate in this chart as well::

All time evolution

# Required versions

Next, I used Nikita's popular package analyzer to download the 1000 most popular composer packages. I use a script that scans these packages to determine their minimum required version. Here are the results:

There are two important notes to make here.

1. This tables shows the minimum required version. That means that packages with a minimal version of, for example, 8.0, could also support PHP 8.1, PHP 8.2, and PHP 8.3.
2. If you count the numbers, you'll notice there are some differences between each year. Not every package lists a valid version string.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

Instead of comparing absolute numbers, it's best to plot this data into a chart for a relative comparison, so that we can see changes over time:

Minimal PHP requirement over time

We see the first four packages requiring PHP 8.3 as their minimal version this month, however there is a huge difference compared to PHP 8.2 and PHP 8.1, which had 94 and 125 packages using them as their minimum version respectively. Granted, PHP 8.3 has been a rather boring release, with quite a lot of deprecations as well, but I didn't expect the difference to be so big. We'll see how and if this trend continues in the next year with PHP 8.4.

Once again, I'd like to remind open source authors about the responsibility we collectively hold to move the PHP ecosystem forward. Bumping minimum requirements is a good thing to do, and should — in my opinion — but done more and faster. Feel free to disagree and share your thoughts via email or in the comments below this post.

My first realisation was that one of the biggest factors preventing me from leaving Twitter was FOMO — fear of missing out. The fear that I won't be up-to-date with what's happening in the PHP community anymore. The fear that I won't be relevant anymore. After my blog post and email last week though, lots of people reacted, which made me realise that FOMO is a thing, but more importantly that I shouldn't have that fear in the first place. That's where my second realisation comes in.

I learned about the spotlight effect: "the psychological phenomenon by which people tend to believe they are being noticed more than they really are". I think the same effect can be applied on communities of people. Having been in the Twitter bubble, I started to believe that it was a crucial part of being involved in the PHP community. However, given the amount of people who told me they have left Twitter long ago, and oftentimes social media in general; I can't help but conclude that Twitter isn't as representative as I liked to think.

That's the spotlight effect in action: Twitter has been my most important communication channel for years, so naturally, I got biased towards it. Most likely though, it only represents a vocal minority, a small subsection of the PHP community. The thing with vocal minorities is that they stand out much more compared to silent majorities, and trick us into thinking that those majorities don't exist, or that they aren't as relevant compared to our own bubble, our own comfort zone.

This is no one's fault, no one's doing this on purpose. But coming to this realisation makes me much more chill about leaving Twitter. I probably won't miss out on as much as I thought I would. My plan forward is to rely on RSS and email as my primary channels of communication. We'll see how it goes. On a personal level I can say that I haven't missed Twitter this past week, and the need to check up on it is subsiding.

Overall I had a good week, I finally managed to write down a couple of chapters for a scifi novel I've been wanted to write. I'm 9000 words in, and it's been such a great project to work on, just because I want and can. I hope you don't mind if I share some more updates about it with you in the future. Do let me know if you really don't want to hear anything about it though, I'll keep your feedback in mind.

Finally, if you mailed me and I haven't replied personally to your answer on my previous post yet: I do plan on replying to all mails, I just have been AFK a lot these days :)

That's the amount of times I instinctively wrote "twitter.com" in Chrome's URL bar today. Five times I saw the login screen instead of my home feed, and five times I was reminded about the decision I made last night. Even while writing this, I have the urge to quickly cmd+tab into chrome, go to Twitter and check up on… I don't even know what.

I'm not allowing myself to do that anymore; yesterday evening I decided I'd log off of Twitter, hopefully for good.

Yesterday in general was a weird day. I visited the doctor, talked about burnout, she wrote me off work for a couple of weeks, and gave me one task: try to get my thoughts back in order. There are many factors in play, and I don't feel the need to share all of them with the world wide web. The "full picture" also doesn't matter for what I do want to share: that realisation I had yesterday evening, lying awake, trying to make sense of it all. "The bucket's full", the doctor had told me, "nothing will fit anymore. You'll have to make some changes."

I'm not a total mess by the way. I caught this early (thanks to my wife), and I'm dealing with it, and I'll get it fixed. However, yesterday it was clear to me that in order to do so, I needed to get rid of one specific thing. It's definitely not the only culprit, but yes, Twitter has had an effect on the downwards spiral I'm experiencing.

Now, my job involves being online, a lot. I'm a developer advocate so people need to know me, and I need to know them. I've always thought to be very lucky or blessed having been able to turn what I used to do as my hobby, into my full time job. I get to create, I get to interact with like-minded people, I get to build meaningful relationships. Naturally, having to be involved with the PHP community, Twitter was one of the hot spots for me.

I used to use Twitter as a place to meet new people, to discover interesting ideas. PHP developers shared projects, opinions, blog posts, videos, and it was a great platform for discovery on the web.

But, obviously, Twitter has changed. People might still be tweeting about those things, they just don't reach me anymore. Twitter's goal has shifted into keeping people on the platform, while I need exactly the opposite. My home feed these days is filled with indie SaaS developers, content- and course creator guru's, thought leaders, self-proclaimed SEO-experts, and people trying to sell me whatever they are making. It has grown into an alienating, artificial "positive-vibes" feedback loop. The Algorithm™ is serving a different kind of content these days, forcing more and more people to make that kind of content, rinse and repeat.

And you know what? It works. I can't stop scrolling. After ten minutes I suddenly think: what am I doing here? I close the tab. Ten minutes later I've somehow ended up scrolling that same feed again — I don't even remember how I got there.

By pure coincidence, while I'm writing this post, a great blog post suddenly popped into my feed (RSS feed, that is, not Twitter), it talks about the same topic:

Like many, I bought into the software hustle culture, spurred by Twitter and loads of success stories by indie hackers who seem to be able to fart money before I've even had my first coffee.

From my point of view, the worst part is that this content doesn't really make me happy. It doesn't really inspire. It doesn't really make me a better person. Of course, everyone wants me to think that their content and their tweets are different and valuable, but in the end they bring little to no value. That might be different for others, but for me, it simply doesn't work anymore. I'm sick of it. Twitter's Algorithm™ has had such a negative impact on my happiness, my self-worth, and my motivation, that I can't continue to mindlessly scroll.

So I decided to log off. I'll have to think about how I can still do my job without Twitter. I might go on a blocking and mute spree once I start work again, trying to clean my home feed. On the other hand, given how much Twitter changed over the past years, I'm not at all convinced it offers enough value for what I'm trying to do anyway. We'll see… People who still want to reach me or be kept up to date about what I'm doing can always mail me if they want to.

They can be registered manually like so:

$container->singleton(
    Highlighter::class, 
    new Highlighter(new LightTerminalTheme()), 
    tag: 'cli',
);

Or you could use an initializer:

#[Singleton(tag: 'web')]
final readonly class WebHighlighterInitializer implements Initializer
{
    public function initialize(Container $container): Highlighter
    {
        return new Highlighter(new CssTheme());
    }
}

And you can retrieve a specific tagged singleton like so:

$container->get(Highlighter::class, tag: 'cli');

Or by using the #[Tag] attribute for autowired dependencies:

class HttpExceptionHandler implements ExceptionHandler
{
    public function __construct(
        #[Tag('web')] private Highlighter $highlighter,
    ) {}
}

Ok but, singletons should be… singletons, right? How can you have multiple singletons for the same class? And what about tight coupling between abstracts and implementations?

Well that's why I'm writing this blog post.

# Let's work through it

In order to understand the usefulness of tagged singletons, I'll have to make sure we're on the same page about a couple of things regarding dependency injection: the pattern itself, the container, autowiring, singletons, and finally the topic of "object identity".

It's a multi-layered answer, but I hope it'll be an interesting read — I definitely found it an interesting topic to write about.

# Dependency Injection

Let's start from the beginning: what is dependency injection? Here's the definition from Wikipedia:

dependency injection is a programming technique in which an object or function receives other objects or functions that it requires, as opposed to creating them internally. Dependency injection aims to separate the concerns of constructing objects and using them, leading to loosely coupled programs

Note that this definition says nothing about how dependencies are injected. The pattern is about the fact the dependencies are passed from the outside into an object.

Following that definition, this is an example of dependency injection:

$object = new HttpExceptionHandler(
    highlighter: new Highlighter(
        theme: new CssTheme(),
    ),
);

In this example, HttpExceptionHandler has a dependency on Highlighter, which has a dependency on CssTheme. We've manually constructed all dependencies needed, but it's still dependency injection.

As a side note; I like to think of dependencies as more than only objects, a dependency could be a scalar value as well — which is extremely useful for injecting config values, but that's a story for another time.

So: dependency injection is about injecting dependencies from the outside into a class, so that that class doesn't have to worry about constructing and managing those dependencies by itself.

# The container

Next is the container, which is what most people think about when they say "dependency injection". The container is no more than a tool to make dependency injection more convenient. A container could be as simple as this, a class that's essentially a key/value store of dependency definitions:

class Container
{
    private array $definition;
    
    public function register(string $key, Closure $definition): self
    {
        $this->instances[$key] = $definition;
        
        return $this;
    }
    
    public function get(string $key): mixed
    {
        $definition = $this->instances[$key] ?? throw new UnknownDependency();
        
        return $definition($this);
    }
}

Setting up the container would look something like this:

$container = (new Container())
    ->register('cssTheme', fn (Container $container) => new CssTheme)
    ->register('highlighter', fn (Container $container) => new Highlighter($container->get('cssTheme')))
    ->register('httpExceptionHandler', fn (Container $container) => new HttpExceptionHandler($container->get('highlighter')));

$container->get('httpExceptionHandler');

Now, this isn't how most real-life containers work; and that's for good reasons: this is a rather inconvenient way of managing dependencies. I deliberately wrote it like this though to clarify how a container, in its core, is a key/value store of definition functions. You can register objects in it, and you can get objects from it.

A slightly more convenient way to register objects is by not specifying textual keys, but instead using the class name of the object:

class Container
{
    private array $instances;
    
    public function register(string $className, Closure $definition): self
    {
        $this->instances[$instance::class] = $definition;
        
        return $this;
    }
    
    // …
}

That way, you don't have to come up with textual IDs for every dependency you want to register, you can simply use its class name:

$container = (new Container())
    ->register(CssTheme::class, fn (Container $container) => new CssTheme)
    ->register(Highlighter::class, fn (Container $container) => new Highlighter($container->get(CssTheme::class)))
    ->register(HttpExceptionHandler::class, fn (Container $container) => new HttpExceptionHandler($container->get(Highlighter::class)));

Even more convenient: you could infer the class name from the closure's definition with just a little bit of reflection on the definition's return type:

class Container
{
    private array $instances;
    
    public function register(Closure $definition): self
    {
        $reflection = new ReflectionFunction($definition);
        
        $this->instances[$reflection->getReturnType()->getName()] = $definition;
        
        return $this;
    }
    
    // …
}

Which leads to even less work!

$container = (new Container())
    ->register(fn (Container $container): CssTheme => new CssTheme)
    ->register(fn (Container $container): Highlighter => new Highlighter($container->get(CssTheme::class)))
    ->register(fn (Container $container): HttpExceptionHandler => new HttpExceptionHandler($container->get(Highlighter::class)));

Remember, our main goal is developer experience at this point. We'd probably cache the final or "compiled" key/value store for production, so why not use a little reflection to make our lives easier?

In the end though, the only thing we're doing is figuring out which key to use for which dependency. Most containers happen to use the class name because it's convenient, but it could be anything you'd like. It's just a key.

# Autowiring

Speaking of convenience, real dependency containers do a lot more than just keeping track of keys and values. Autowiring is probably one of the container's biggest advantages. Autowiring is a mechanism that allows the container to come up with definitions for dependencies itself, instead of needing each definition to be manually defined. You can still define definitions for specific cases if you need to, but only for the cases where autowiring isn't smart enough.

Essentially, you'd write this:

$container->get(HttpExceptionHandler::class);

And the container would use reflection to find the right dependencies:

class Container
{
    // …
    
    public function get(string $key): mixed
    {
        $definition = $this->instances[$key] 
            ?? $this->autowire($key);
        
        return $definition($this);
    }
    
    private function autowire(string $class): Closure
    {
        $constructor = (new ReflectionClass($class))->getConstructor();
        
        $dependencies = [];
        
        foreach ($constructor->getParameters() as $parameter) {
            $dependencies[$parameter->getName()] = $this->get($parameter->getType()->getName());
        }
        
        // The autowire definition is created on the fly
        return fn () => new $class(...$dependencies);
    }
}

That's autowiring: adding convenience for developers, so that they don't have to specify every definition manually. The reason the container can do autowiring, is because we've agreed to use class names as dependency keys, and those class names happen to be available within object constructors as well:

final readonly class HttpExceptionHandler
{
    // Highlighter is both the parameter's type,
    // but also the dependency's key:
    
    public function __construct(
        private Highlighter $highlighter,
    ) {}
}

You don't need to use class names, by the way. You could make a container that only uses manual defined dependency IDs like in the very first example, and use attributes to handle autowiring:

final readonly class HttpExceptionHandler
{
    public function __construct(
         #[Autowire('highlighter')] private Highlighter $highlighter,
    ) {}
}

But honestly, using the class name works and requires less typing. So why bother?

# Singletons

Well, we do sometimes bother, which is why I added tagged singletons in Tempest, but we're getting ahead of ourselves. Let's first discuss singletons on their own. Singletons are a special kind of dependencies: as soon as the container has constructed a singleton, it will be cached, and that cached version is used whenever the same class is requested again.

A simplistic implementation could look something like this:

class Container
{
    // …

    private array $singletons;
    
    // Registering the singleton is very similar
    // to registering normal definitions
    public function singleton(Closure $definition): self
    {
        $reflection = new ReflectionFunction($definition);
        
        $this->singletons[$reflection->getReturnType()->getName()] = $definition;
        
        return $this;
    }
    
    // We need to have some additions in our get method
    public function get(string $className): mixed
    {
        // If there's a singleton definition
        if ($singleton = ($this->singletons[$className] ?? null)) {
        
            // We'll check whether it's still in its definition form
            if ($singleton instanceof Closure) {
            
                // If so, we'll execute the definition once,
                // and store its result (the singleton object)
                $this->singletons[$className] = $singleton($this);
            }
            
            // Finally we'll return the singleton object itself
            return $this->singletons[$className];
        }
        
        // If there's no singleton,
        // we'll just resolve the dependency as normal
        $definition = $this->instances[$className] 
            ?? $this->autowire($className);
        
        return $definition($this);
    }
}

Singletons can be super useful in cases where constructing objects take time, like for example objects that represent over-the-wire connections to external services, or when a dependency is used in many places throughout your codebase, in which case it might be better to have one shared instance of it, instead of numerous copies of the same class.

The highlighter example falls in the latter category: it's used all over the place, including loops, so I'd rather have one instance of it, instead of possibly hundreds.

So, now that we know about the container, autowiring, and singletons, we can finally discuss tagged singletons.

# Tagged singletons

In essence, tagged singletons are no different from normal singletons, they just don't use the class name as their identifier. The reason is simple: binding singletons to class names can sometimes be limiting.

Take our highlighter example: I actually need two singleton instances of it: one for highlighting code on the web, and one for highlighting code in the console. And I actually sometimes need both of them, within the same request or command invocation. Going into the details of why would lead us too far, but I'm fairly certain that everyone who has ever worked on a larger codebase has a similar example: you need two single instances of the same class, slightly configured differently.

One solution people come up with is to have dedicated interfaces for each responsibility. These interfaces don't do anything, they are only there to help the container figure out which class to provide:

interface CliHighlighter extends Highlighter {}
 
interface WebHighlighter extends Highlighter {} 

People then provide custom implementations for these interfaces, wrapping the original highlighter object:

final readonly class GenericCliHighlighter implements CliHighlighter
{
    private Highlighter $highlighter;
    
    public function __construct()
    {
        $this->highlighter = new Highlighter(new LightTerminalTheme());
    }
    
    public function parse(string $content): string
    {
        return $this->highlighter->parse($content);
    }
}

final readonly class GenericWebHighlighter implements WebHighlighter
{
    private Highlighter $highlighter;
    
    public function __construct()
    {
        $this->highlighter = new Highlighter(new CssTheme());
    }
    
    public function parse(string $content): string
    {
        return $this->highlighter->parse($content);
    }
}

In some cases you'd need to extend the parent class instead of using an interface if the code you're integrating with has chosen inheritance over composition, but it would look quite similar: a lot of code, just to make sure the container understands what we want.

Let's say we don't have two variations of our singleton, but five. What about the overhead then? Remember how the container's task was to make our lives easier? Now we find ourselves making our lives more difficult, just because the container isn't smart enough.

Ok, what about an alternative? We could have a factory class, something like this:

final readonly class HighlighterFactory
{
    public function make(string $key): Highlighter
    {
        return match($key) {
            'cli' => new Highlighter(new LightTerminalTheme()),
            'web' => new Highlighter(new CssTheme()),
        };
    }
}

Well… this "solution" is basically extracting part of the responsibility from the container, because it's falling short. It should be the container's task to know how to construct objects, but apparently it doesn't know how to do so in all cases. And thus we provide a custom factory — a mini-container in disguise — to "solve" our problem.

Oh, by the way, have you spotted how this factory doesn't support singletons? Should we implement it? Making it even more a mini-container?

final class HighlighterFactory
{
    private static ?Highlighter $cli = null;
    private static ?Highlighter $web = null;
    
    public function make(string $key): Highlighter
    {
        return match($key) {
            'cli' => self::$cli ??= new Highlighter(new LightTerminalTheme()),
            'web' => self::$web ??= new Highlighter(new CssTheme()),
        };
    }
}

I think you see what I'm getting at, right? Either solutions are truly suboptimal. Remember that we have to write this code for every dependency that needs singleton variations. All because our container lacks.

Ok so, tagged singletons solve this problem. The only thing they do is to optionally define another identifier for a singleton:

$container->singleton(
    Highlighter::class, 
    new Highlighter(new LightTerminalTheme()), 
    tag: 'cli',
);

The identifier of this singleton would be Highlighter#cli (technically it would be the FQCN of Highlighter, but you get the point). Apart from that, you have two ways to specify the tag when requesting a dependency, either when manually resolving a dependency from the container:

$container->get(Highlighter::class, tag: 'cli');

Or by using the #[Tag] attribute while autowiring:

class HttpExceptionHandler implements ExceptionHandler
{
    public function __construct(
        #[Tag('web')] private Highlighter $highlighter,
    ) {}
}

In short, tagged singletons give a programmer control over the dependency's identifier, only when needed. It's the next logical step in making our lives more convenient, which is all the container is about.

# But this is wrong!

I'll list some of the counterarguments I got, and try to defend my case as well as possible.

There can only be one singleton per class! — Well this statement actually mixes two ideas together. The singleton pattern indeed describes one instance per class. However, this isn't necessarily what the container is doing. A more apt name would be cached dependencies, but unfortunately we've gotten so used to the term "singleton", which is now causing confusion.

Also, thanks to modern containers, we've gotten used to the class name being the dependency key, which causes the misconception that the class name can be the only viable dependency key. I hope this blogpost has giving you some food for thought and will allow you to challenge any preconceptions.

Tagged singletons tie a concrete implementation to an abstract! — True. By introducing a tag, we request one specific instance from the container. We're doing micromanagement and not programming to abstractions or interfaces anymore. This isn't any different from the two solutions others proposed though. Creating empty interfaces or subclasses just to please the container is equally concrete. It's not because we slammed the keyword interface in front of it that it suddenly is the perfect design. The factory solution is exactly the same: you request a very specific implementation. The only difference with tagged singletons is that there is more code to write in both other solutions, and more places to fail.

The reality is, sometimes we need a very specific thing. Adding layers of abstraction just to be able to say you're programming "the right way" — well, it isn't "the right way".

# In closing

I had a lot of fun writing this post, and I hope you enjoyed reading it, even if you disagreed with some parts. I'd love to further talk about it, so feel free to come say hi on the Tempest Discord, and subscribe to my mailing list to be kept into the loop about future content.

Absolutely!

There are very good reasons to be excited about PHP these days. Today, I want to share some of the things I'm most excited about this year for PHP.

# Continuous evolution

When Nikita left over two years ago — Nikita being the main contributor and driver for PHP, he went to work on LLVM — I'll admit I was scared for PHP's future:

I'm a little worried now that Nikita has stepped down. He's definitely not the only person capable of working on PHP's core, but he did a tremendous amount of work these past years with PHP 8.0 and 8.1. I don't think 2022 will be the most mind blowing year for PHP, but rather a year of adding stability.

Looking back, I think that fear wasn't needed. The PHP Foundation has grown into a well-established community, with now 10 developers being paid to work on PHP core. Two major features being worked on at the moment come to mind: property hooks — which I'm hopeful for will pass once it comes to voting; and a rework of Pecl — PHP's extension manager.

Of course, I still got a sliver of hope when it comes to generics, which the Foundation is/was also looking into. I do think that the only viable way forward is runtime-ignored generics though, time will tell whether the Foundation will be able to cultivate a new mindset or not.

# FrankenPHP

One of the cool things happening in PHP land today is a project called FrankenPHP. It's been in the works for a year or two — if I remember correctly, and it's getting some real traction these days.

FrankenPHP is an app server for PHP, written in Go, that gives existing PHP apps a major performance boost, and it's super easy to get started with. It also supports compiling PHP projects as standalone binaries, worker mode for long-lived applications, is three times faster than PHP-FPM, HTTP/2 and HTTP/3 support, and more.

Recently, we've seen support for FrankenPHP for Laravel and Symfony. So it's growing into something big.

# Laravel

I think it's fair to say at this point that Laravel's marketing strategy is working well. Laravel itself — the open source framework — is by far the most popular one within the PHP community; but they've also managed to create an ecosystem of products built with and for Laravel, to build a sustainable business. Just recently, Laravel hired 6 new people, from a COO to BizOps to engineers; and Taylor mentioned that "serious business is underway".

Modern businesses are growing and embracing PHP, which is great to see.

One of the things I embraced last year was Laravel Livewire, a tool that allows you to write interactive apps, without any JavaScript. I did some tinkering with it, and had a lot of fun making a game:

# Discovering PHP

What I found especially heartwarming to see is how people outside the PHP community are re-discovering PHP. There have been a number of examples of people coming from the JavaScript world, suddenly realising Laravel is a thing, and a good thing; and there are people like ThePrimeagen on YouTube who were pleasantly surprised by PHP:

# Composer and Packagist

The PHP ecosystem keeps growing as well: there's a continuous growth in packages, indicating an active ecosystem.

On top of that, Packagist recently crossed the one hundred billion downloads milestone. That's a doubling in two years time! We're now at 105 134 384 876, and that number keeps growing.

I think it's fair to say: PHP is not dead!

Right now, tempest/highlight counts 109 pattern classes, a handful of them representing a collection of patterns such as keywords or operators. Take, for example, the NewObjectPattern that matches PHP class names when they are used to create a new object:

final readonly class NewObjectPattern implements Pattern
{
    use IsPattern;

    public function getPattern(): string
    {
        return 'new (?<match>[\w]+)';
    }

    public function getTokenType(): TokenType
    {
        return TokenType::TYPE;
    }
}

With 109 patterns (and that number is still growing), the question arises: how to test them? I could write individual tests for all of them, which is what I started out with. That grew into a mess pretty quickly though, so I created a trait called TestsPatterns which has this method:

public function assertMatches(
    Pattern $pattern,
    string $content,
    string|array|null $expected,
): void {
    $matches = $pattern->match($content);

    if (is_string($expected)) {
        $expected = [$expected];
    }

    if ($expected === null) {
        $this->assertCount(
            expectedCount: 0,
            haystack: $matches['match'],
            message: sprintf(
                "Expected there to be no matches at all in %s, but there were: %s",
                $pattern::class,
                var_export($matches['match'], true),
            )
        );

        return;
    }

    foreach ($expected as $key => $expectedValue) {
        $this->assertSame(
            expected: $expectedValue,
            actual: $matches['match'][$key][0],
            message: sprintf(
                "Pattern in %s did not match %s, found %s instead.",
                $pattern::class,
                var_export($expectedValue, true),
                var_export($matches['match'][$key][0], true),
            ),
        );
    }
}

This trait can be used like so:

class NewObjectPatternTest extends TestCase
{
    use TestsPatterns;

    public function test_pattern()
    {
        $this->assertMatches(
            pattern: new NewObjectPattern(),
            content: 'new Foo()',
            expected: 'Foo',
        );

        $this->assertMatches(
            pattern: new NewObjectPattern(),
            content: '(new Foo)',
            expected: 'Foo',
        );
    }
}

This trait significantly reduced the amount of code I had to write: it takes a Pattern object, and checks whether a given input returns a matching output.

Good enough? Well, not so fast. Writing tests this way for 109 patterns actually gets pretty boring, pretty fast. I believe that to write a thorough test suite, writing tests need to be as frictionless as possible, otherwise people (me) will just skip writing tests in the long run.

So, I wondered: "can I reduce this friction even more?"

Data providers came to mind: what if I made one class that contained all my test cases, and only needed to provide the data?

It would look something like this:

final class PatternsTest extends TestCase
{
    use TestsPatterns;

    #[Test]
    #[DataProvider('patterns')]
    public function test_patterns_with_attribute(Pattern $pattern, string $input, string $output)
    {
        $this->assertMatches(
            pattern: $pattern,
            content: $input,
            expected: $output,
        );
    }

    public static function patterns(): array
    {
        return [
            [new NewObjectPattern(), 'new Foo()', 'Foo'],     
            [new NewObjectPattern(), '(new Foo)', 'Foo'],     
            [new NewObjectPattern(), 'new Foo', 'Foo'],     
            
            // …
        ];   
    }
}

Now there is even less duplicated setup code to write! However, there is a glaring problem: this approach scales poorly. Can you imagine having all pattern tests in one test file? Luckily, PhpStorm allows to run a single data provider entry, and is able to tell you which specific data provider entry failed, so there is some fine-grained control:

But still… hundreds, potentially thousands, of tests in the same file doesn't seem like an approach that would work in the long run.

Data providers gave me another idea though. What if there's one "main test" that's responsible for testing all patterns, but what if its data provider entries were aggregated from separate files?

What if…

What if I kept patterns and their specific tests together? Would that be possible?

Definitely! How about using attributes on the pattern class itself?

#[PatternTest(input: 'new Foo()', output: 'Foo')]
#[PatternTest(input: '(new Foo)', output: 'Foo')]
#[PatternTest(input: 'new Foo', output: 'Foo')]
final readonly class NewObjectPattern implements Pattern
{
    use IsPattern;

    public function getPattern(): string
    {
        return 'new (?<match>[\w]+)';
    }

    public function getTokenType(): TokenType
    {
        return TokenType::TYPE;
    }
}

With these attributes in place, I could now rewrite my data provider method like so:

public static function patterns(): Generator
{
    $patternFiles = glob(__DIR__ . '/../src/Languages/*/Patterns/**.php');

    foreach ($patternFiles as $patternFile) {
        $className = str_replace(
            search: [__DIR__ . '/../src/', '/', '.php'],
            replace: ['Tempest\\Highlight\\', '\\', ''],
            subject: $patternFile,
        );

        $reflectionClass = new ReflectionClass($className);

        $attributes = $reflectionClass->getAttributes(PatternTest::class);

        foreach ($attributes as $attribute) {
            /** @var PatternTest $patternTest */
            $patternTest = $attribute->newInstance();

            yield [$reflectionClass->newInstance(), $patternTest];
        }
    }
}

Let me quickly run you through what happens. First, the data provider scans all classes in the right directories:

$patternFiles = glob(__DIR__ . '/../src/Languages/*/Patterns/**.php');

Next, it gathers one of more PatternTest attributes from these classes:

$reflectionClass = new ReflectionClass($className);

$attributes = $reflectionClass->getAttributes(PatternTest::class);

Finally, each of those attributes is used to generate a test:

foreach ($attributes as $attribute) {
    /** @var PatternTest $patternTest */
    $patternTest = $attribute->newInstance();

    yield [$reflectionClass->newInstance(), $patternTest];
}

And… that's it! In this case, I find this approach to be very handy: whenever I create a new pattern class, the first thing I do is add a couple of pattern tests to it so that I have an example to look at. There's also no need to worry about performance overhead: the whole testsuite for tempest/highlight runs in 50ms.

The only downside to this approach is that you cannot run a specific pattern test on its own, without having first run the whole testsuite. PhpStorm is able to run data provider entries individually when they are listed within the data provider method, but filling that array dynamically of course prevents PhpStorm from detecting that.

You can rerun specific pattern tests when they failed, and I find that adding a good error message helps you to quickly find the problem:

I'll acknowledge that this is indeed a minor downside to this approach. However, I find that for this specific use case, I'm saving lots of time, and I've removed the majority of friction while testing tempest/highlight. In the end, for me, it's a win.

Let's explain how tempest/highlight works by implementing a new language — Blade is a good candidate. It looks something like this:

@if(! empty($items))
    <div class="container">
        Items: {{ count($items) }}.
    </div>
@endslot

In order to build such a new language, you need to understand three concepts of how code is highlighted: patterns, injections, and languages.

# 1. Patterns

A pattern represents part of code that should be highlighted. A pattern can target a single keyword like return or class, or it could be any part of code, like for example a comment: /* this is a comment */ or an attribute: #[Get(uri: '/')].

Each pattern is represented by a simple class that provides a regex pattern, and a TokenType. The regex pattern is used to match relevant content to this specific pattern, while the TokenType is an enum value that will determine how that specific pattern is colored.

Here's an example of a simple pattern to match the namespace of a PHP file:

use Tempest\Highlight\IsPattern;
use Tempest\Highlight\Pattern;
use Tempest\Highlight\Tokens\TokenType;

final readonly class NamespacePattern implements Pattern
{
    use IsPattern;

    public function getPattern(): string
    {
        return 'namespace (?<match>[\w\\\\]+)';
    }

    public function getTokenType(): TokenType
    {
        return TokenType::TYPE;
    }
}

Note that each pattern must include a regex capture group that's named match. The content that matched within this group will be highlighted.

For example, this regex namespace (?<match>[\w\\\\]+) says that every line starting with namespace should be taken into account, but only the part within the named group (?<match>…) will actually be colored. In practice that means that the namespace name matching [\w\\\\]+, will be colored.

Yes, you'll need some basic knowledge of regex. Head over to https://regexr.com/ if you need help, or take a look at the existing patterns in this repository.

In summary:

• Pattern classes provide a regex pattern that matches parts of code.
• Those regexes should contain a group named match, which is written like so (?<match>…), this group represents the code that will actually be highlighted.
• Finally, a pattern provides a TokenType, which is used to determine the highlight style for the specific match.

# 2. Injections

Once you've understood patterns, the next step is to understand injections. Injections are used to highlight different languages within one code block. For example: HTML could contain CSS, which should be styled properly as well.

An injection will tell the highlighter that it should treat a block of code as a different language. For example:

<div>
    <x-slot name="styles">
        <style>
            body {
                background-color: red;
            }
        </style>
    </x-slot>
</div>

Everything within <style></style> tags should be treated as CSS. That's done by injection classes:

use Tempest\Highlight\Highlighter;
use Tempest\Highlight\Injection;
use Tempest\Highlight\IsInjection;

final readonly class CssInjection implements Injection
{
    use IsInjection;

    public function getPattern(): string
    {
        return '<style>(?<match>(.|\n)*)<\/style>';
    }

    public function parseContent(string $content, Highlighter $highlighter): string
    {
        return $highlighter->parse($content, 'css');
    }
}

Just like patterns, an injection must provide a pattern. This pattern, for example, will match anything between style tags: <style>(?<match>(.|\n)*)<\/style>.

The second step in providing an injection is to parse the matched content into another language. That's what the parseContent() method is for. In this case, we'll get all code between the style tags that was matched with the named (?<match>…) group, and parse that content as CSS instead of whatever language we're currently dealing with.

In summary:

• Injections provide a regex that matches a blob of code of language A, while in language B.
• Just like patterns, injection regexes should contain a group named match, which is written like so: (?<match>…).
• Finally, an injection will use the highlighter to parse its matched content into another language.

# 3. Languages

The last concept to understand: languages are classes that bring patterns and injections together. Take a look at the HtmlLanguage, for example:

class HtmlLanguage extends BaseLanguage
{
    public function getInjections(): array
    {
        return [
            ...parent::getInjections(),
            new PhpInjection(),
            new PhpShortEchoInjection(),
            new CssInjection(),
            new CssAttributeInjection(),
        ];
    }

    public function getPatterns(): array
    {
        return [
            ...parent::getPatterns(),
            new OpenTagPattern(),
            new CloseTagPattern(),
            new TagAttributePattern(),
            new HtmlCommentPattern(),
        ];
    }
}

This HtmlLanguage class specifies the following things:

• PHP can be injected within HTML, both with the short echo tag <?= and longer <?php tags
• CSS can be injected as well, JavaScript support is still work in progress
• There are a bunch of patterns to highlight HTML tags properly

On top of that, it extends from BaseLanguage. This is a language class that adds a bunch of cross-language injections, such as blurs and highlights. Your language doesn't need to extend from BaseLanguage and could implement Language directly if you want to.

With these three concepts in place, let's bring everything together to explain how you can add your own languages.

# Adding custom languages

So we're adding Blade support. We could create a new language class and start from scratch, but it'd probably be easier to extend an existing language, HtmlLanguage is probably the best. Let create a new BladeLanguage class that extends from HtmlLanguage:

class BladeLanguage extends HtmlLanguage
{
    public function getInjections(): array
    {
        return [
            ...parent::getInjections(),
        ];
    }

    public function getPatterns(): array
    {
        return [
            ...parent::getPatterns(),
        ];
    }
}

With this class in place, we can start adding our own patterns and injections. Let's start with adding a pattern that matches all Blade keywords, which are always prepended with the @ sign. Let's add it:

final readonly class BladeKeywordPattern implements Pattern
{
    use IsPattern;

    public function getPattern(): string
    {
        return '(?<match>\@[\w]+)\b';
    }

    public function getTokenType(): TokenType
    {
        return TokenType::KEYWORD;
    }
}

And register it in our BladeLanguage class:

    public function getPatterns(): array
    {
        return [
            ...parent::getPatterns(),
            new BladeKeywordPattern(),
        ];
    }

Next, there are a couple of places within Blade where you can write PHP code: within the @php keyword, as well as within keyword brackets: @if (count(…)). Let's write two injections for that:

final readonly class BladePhpInjection implements Injection
{
    use IsInjection;

    public function getPattern(): string
    {
        return '\@php(?<match>(.|\n)*?)\@endphp';
    }

    public function parseContent(string $content, Highlighter $highlighter): string
    {
        return $highlighter->parse($content, 'php');
    }
}

final readonly class BladeKeywordInjection implements Injection
{
    use IsInjection;

    public function getPattern(): string
    {
        return '(\@[\w]+)\s?\((?<match>.*)\)';
    }

    public function parseContent(string $content, Highlighter $highlighter): string
    {
        return $highlighter->parse($content, 'php');
    }
}

Let's add these to our BladeLanguage class as well:

    public function getInjections(): array
    {
        return [
            ...parent::getInjections(),
            new BladePhpInjection(),
            new BladeKeywordInjection(),
        ];
    }

Next, you can write {{ … }} and {!! … !!} to echo output. Whatever is between these brackets is also considered PHP, so, one more injection:

final readonly class BladeEchoInjection implements Injection
{
    use IsInjection;

    public function getPattern(): string
    {
        return '({{|{!!)(?<match>.*)(}}|!!})';
    }

    public function parseContent(string $content, Highlighter $highlighter): string
    {
        return $highlighter->parse($content, 'php');
    }
}

And, finally, you can write Blade comments like so: {{-- --}}, this can be a simple pattern:

final readonly class BladeCommentPattern implements Pattern
{
    use IsPattern;

    public function getPattern(): string
    {
        return '(?<match>\{\{\-\-(.|\n)*?\-\-\}\})';
    }

    public function getTokenType(): TokenType
    {
        return TokenType::COMMENT;
    }
}

With all of that in place, the only thing left to do is to add our language to the highlighter:

$highlighter->addLanguage('blade', new BladeLanguage());

And we're done! Blade support with just a handful of patterns and injections!

I think that the ability to extend from other languages and language injections are both really powerful to be able to quickly build new languages. Of course, you're free to send pull requests with support for additional languages as well! Take a look at the package's tests to learn how to write tests for patterns and injections.

Huh. Isn't there a better way to do syntax highlighting for that?

He was talking about code blocks for the upcoming Tempest docs site. I must say I wasn't surprised by his question, although I had hoped he wouldn't ask it.

I wrote code blocks like so:

public function store(<hljs type>BookRequest</hljs> $request)

That's right, I manually add and parse special "highlight" tokens in them. Take a look at, for example, the source of my latest what new in PHP 8.3 post. Lots of hljs tags everywhere.

Of course, I don't do this without reason. I used highlight.js for years, and found it increasingly frustrating that it didn't render code blocks correctly — especially modern PHP syntax. Maybe three or four years ago, I switched to highlight.php, a PHP port of highlight.js. It wasn't any better than highlight.js, but at least it did its rendering server-side, which is always a good thing.

The major benefit of server-side rendering, was that I was able to add a small parser on top of it. With it, I could control my code block's styling when it didn't work exactly right. Hello hljs tags!

Maybe it's just me, but I really cannot stand wrongly highlighted code blocks, so I was willing to do whatever it takes to get it right. Even if it meant manual work for every single code block I'd write. It's one of these things I got used to over time though, and I didn't really question it anymore. Shortly after adding my custom syntax, I added keyboard shortcuts to wrap selected text in hljs tokens, so it wasn't even that much a bother — to me, at least.

However, when I started drafting the Tempest docs, I knew deep down that this solution wouldn't work long-term. Tempest — and that includes its documentation — is an open source project. If one of the goals is for people to contribute, then I can't expect them to learn a quirky syntax I came up with a couple of years ago.

So, yes, Aidan's right to ask this question.

Isn't there a better way to do syntax highlighting for that?

"No problem", I told him, "I'll find a replacement!" Originally I had other plans that day, but I imagined it wouldn't be so hard to switch to another highlighter. It's a couple of years later, surely there will be a better solution now.

Right?

First, I looked at highlight.js again. It was still rendering PHP code as if it was PHP 7.4. Stuff like attributes, function names, and some types weren't highlighted at all. Unacceptable.

Next, I looked at Torchlight. As far as I knew, it's a "highlighter as a service" (it's also a game I used to play, but that's irrelevant). Torchlight was created a year or two ago, and I heard pretty good things of it. I believe the Laravel docs uses it.

I had high hopes for Torchlight. They had a free plan for open source projects, so let's go!!

Unfortunately, one small issue: it only works in Laravel projects. Torchlight requires Laravel facades to be booted in order to work. That would mean manually booting up Laravel in a project that's not using Laravel at all. On top of that, Torchlight makes API requests, so I figured it wouldn't be the most performant solution anyway. The way I write content is by doing lots of refreshes, and I need changes to be instantly visible. So, Torchlight was out.

Next on my list was Shiki, which has a PHP wrapper. Shiki supports TextMate grammar, which is used for syntax highlighting in many editors. In general, it's much more accurate than something like highlight.js, and you can run it server-side. Nice!

Remember what I said about performance though? Yeah… Shiki is slow. Like, super slow. It took more than 10 seconds to render the Controllers docs page, which only includes a handful of code blocks.

Sure, one "solution" to that is caching, but when I'm writing, I want things to appear instantly. Even with caching, you'd still look at 1-2 second page refreshes when you're making changes to code blocks, which — to me — is unacceptable.

At this point I was becoming frustrated. Surely it can't be that there is no proper solution to syntax highlighting that satisfies these three requirements??

• Fast enough so that page load times are tolerable without caching during development.
• Server-side rendered, it's just text after all; why would you bother all clients to do more work while the server could do it once?
• Support proper PHP syntax, or at least provide an easy way to add new syntax outside the package's core, so that new PHP syntax (or other languages) will have support immediately when people need it.

"HOW HARD CAN IT BE?" — I asked Aidan in frustration, ready to give up. "We'll stick with my quirky syntax, and I'll manually add hljs tags afterward whenever people send PRs. Good enough."

But Aidan wasn't ready to let go:

I’m very determined to find a solution to this syntax highlighting problem though.

With these words of "encouragement", I decided to consider one final option. Let's write something myself. It's just syntax highlighting — "how hard can it be?" If I wasn't able to get something working in a couple of hours, I could still abandon the idea.

"Working on it", I told Aidan.

What happened during the next two days is hard to describe, but you probably recognise the feeling nevertheless: being so deep into "the zone" and determined to solve a problem that everything else must give way.

It took a couple of iterations, some dreaming about it during the night — I tend to dream about code when I'm deep into a project, nothing to worry about. But yesterday morning, everything fell into place.

This is what I sent Aidan at 6:57 AM:

Ok Aidan, I need you to keep calm. Ok?

EVERYTHING WORKS 😱😱😱😱😱😱😱😱

Ok, not everything worked, but all important things did:

• Server-side rendered highlights
• Fast enough to handle stuff without any caching
• Accurate syntax highlighting
• An easy API to add new languages
• Language injection support, so that you can combine multiple languages within one codeblock (it's actually pretty neat)

And so… I'd like to present, a code highlighter that doesn't suck: tempest/highlight.

Ok, it still sucks a bit, because I still need to add more languages, and there will probably be some inaccuracies within the languages I already added (PHP, HTML, CSS, and Blade). But: the foundation is there, and it works. I'm actually already using it on the Tempest docs site, because why not?

I'm now going to switch this blog over as well, though I will keep the backwards compatibility option for now, because I don't want to be bothered with updating hundreds of past blog posts.

So, if you're in need for a code highlighter that doesn't suck, feel free to check out tempest/highlight! Also, if you're looking for an open source project to contribute to: I more than welcome PRs! (The README gives you more info on how to get started.)

PS: give it a star as well while you're there 😉

PPS: here's a code block rendered with the new highlighter:

final readonly class BookController
{
    #[Get(uri: '/books/{book}')]
    public function show(Book $book, User $user): View
    {
        return view('Front/books/detail.view.php',
            book: $book,
            user: $user,
        );
    }
}

PPPS: here's a vlog showing the initial implementation of this package:

Half a year ago, I wrote this:

Ok, so, I've started working on something — probably the biggest project I've worked on in a while — and I'm having a blast. I'm building… A framework 😳

If you haven't heard of that framework before — it's called Tempest — you could check out me building the foundations of it during several livestreams.

I had a break working on Tempest for a couple of months because of other projects, but recently I started diving into it again. I've actually used it to build a small website, and let me tell you: I really enjoyed it.

That probably shouldn't come as a surprise since I built it the way I like to build things. But still, I was very happy seeing all pieces fit together so perfectly. Granted: there is a lot more fine-tuning to do, but I do think there's some potential here.

To be clear: Tempest doesn't aim to replace any frameworks like Laravel or Symfony; but for getting smaller PHP websites up and running? I feel like there's a lot of potential for a small and modern framework.

I especially like how Tempest gets out of your way. There's no need for config files or any setup, Tempest understands your code. I'm not kidding, it works really well.

So, I'd say go check out a very pre-alpha version of what undoubtedly will become something great in the future: https://github.com/tempestphp/tempest-framework.

# On a personal note

Much to my frustration, I've been sick since mid-December. Nothing serious, just a very annoying cough that doesn't want to go away. I've seen my doctor numerous times, a specialist, I'm using an inhaler, nasal spray, tried antacids, nothing seems to work. I actually have had the same issue for multiple years now: periods of coughing without any clear reason or solution.

Like I said, it's not too serious, just an annoying cough that doesn't want to go away, though it is very limiting when trying to record videos or audio. The more I talk, the worse it gets, so proper recording sessions aren't really an option right now. That three-minute video about Tempest I linked a couple paragraphs ago took waaaaay too much time and editing to get all the coughs out…

That's why I've been rather quiet on PHP Annotated, and why I've mostly focussed on writing content for PhpStorm lately. Last week, the first post in a series about JetBrains' AI Assistant for Unit Testing went live, and I've got a couple more scheduled soon.

I really hope my coughing gets over soon, and I really hope we'll find a proper solution. I've got another doctor's appointment scheduled next week and hope new medication will have a better impact.

Anyway, I mainly wanted to share this with you in case people were wondering why PHP Annotated is so quiet lately. I really want to get back into it a soon as possible though!

That's it for today's newsletter, do check out Tempest and give it a star while you're there 😉

Until next time

Brent

PS: I feel real inspired to livestream today. I'm still coughing, but I hope I'll manage. Come say hi:

Keep in mind note that I'm working with the data available. That means that these charts are not a 100% accurate representation of the PHP community as a whole, but they are an accurate representation of one of the most prominent parts of PHP: the packagist ecosystem.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

# Usage Statistics

Let's start with the percentage of PHP versions being used today, and compare it to the previous three editions, note that I've omitted all versions that don't have more than 1% usage:

Visualizing this data looks like this:

Evolution of version usage

There seems to be a slightly faster adoption of PHP 8.3 compared to PHP 8.2: 6.4% of projects are using PHP 8.3 within the first two months of its release, for PHP 8.2 it was 4.7%.

Furthermore, the PHP 7.* share continues to shrink — a good thing given that support for the 7.* series ended more than a year ago. Right now PHP 8.1 is the oldest supported version, only receiving security updates until November 25 this year. I can't help it, I keep saying the same thing over and over again, it's important update your PHP installations!

Moving on to the all-time overview chart, here you can see the evolution of version usage across time:

All time evolution

New in PHP 8.3

# Required versions

Next, I used Nikita's popular package analyzer to download the 1000 most popular composer packages. I use a script that scans these packages to determine their minimum required version. Here are the results:

There are two important notes to make here.

1. This tables shows the minimum required version. That means that packages with a minimal version of, for example, 8.0, could also support PHP 8.1, PHP 8.2, and PHP 8.3.
2. If you count the numbers, you'll notice there are some differences between each year. Not every package lists a valid version string.

Instead of comparing absolute numbers, it's best to plot this data into a chart for a relative comparison, so that we can see changes over time:

Minimal PHP requirement over time

Talking about progression, I'd like to remind open source maintainers about the power and responsibility they hold. Imagine if all modern open source packages only supported PHP versions that were actively worked on. My suspicion is that many more projects would be encouraged to update faster; eventually leading to a healthier, more performant, and more secure ecosystem. Open source maintainers yield quite a lot of power in this regard.

Also keep in mind that forcing a new minimal PHP requirement doesn't automatically block older projects from using your code: outdated projects can still download older versions of your packages, so there's really no good argument not to do it from a package maintainer's point of view.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

That's all data I have to share for this edition of PHP's version stats. You can always reach me via email if you want to share your thoughts or have questions.

You can probably relate. That moment when you were writing code because you wanted to, no, because you desired to. No deadlines, no pressure. Only that feeling of power, being able to create something from nothing with code. It could be something as simple as an HTML web page, a program on your calculator to — hmm — cheat on your maths exam, or hacking something together for a game you're playing.

For me, at least, those are some of the examples that resonate.

I'm writing this as a reminder to myself and whoever needs to hear it: don't forget that time when your programming passion sparked. You're older now, you've got other things to do, you have responsibilities now. You might never experience the same amount of joy compared to that first year of programming, behind the computer in the living room while your siblings were playing, making lots of noise and distracting you.

But you can still find passion projects. Keep an open mind. Write a game, a website, a book, whatever. Not because you must, not to impress your social media following, not to make a living out of it — but because you can, because it gives you joy.

I've always assumed this mentality existed mostly thanks to "being online", and that when it came to face-to-face interactions, people would be more forgiving towards each other.

Apparently, that assumption is wrong 😅

Last week, I went to SymfonyCon, and a year ago I went to Laracon. It turns out people are as harsh towards the other community in real life as they are online.

I'm baffled by this sentiment. There's no denying that people are building successful things with Symfony, just like there's no denying people are building successful things with Laravel. Why does anyone feel the need to convince me or others that their choice is superior? Why do we feel the need to pick sides? Why does it matter that someone else uses another solution to the same problem, if they manage to solve that problem equally well? Why do we feel the need to identify so strongly with a framework, that we need to dismiss the other?

I don't know.

Maybe we should say that more often: "I don't know", especially when it comes to the other side, and give them the benefit of the doubt.

What are your thoughts? Have you had the same experience? Maybe completely the opposite? Let me know!

PS: there were also a bunch of nice people at both SymfonyCon and Laracon, maybe that's good to mention as well 😁

Two weeks ago, I had a chat with my colleague Roman about how PHP is evolving: we both want to get a better understanding of how the community feels about RFCs. While technically, the internals mailing list is open to everyone, I know only a very small group of PHP developers who actually participate. So we decided to build a small app that could help us and the community to lower the bar for participation.

Its temporary name is "RFC Vote" — but please share your ideas if you have better names! It's a small project that allows everyone to vote for RFCs. The most interesting part though is how you vote: if you vote directly, you must give argumentation to explain why you voted yes or no. On top of that: everyone can vote for existing arguments individually. Say someone already shared the same reasons as you for voting yes or no, then you can simply vote for that argument, instead of writing something on your own — argument votes are added to the total result as well.

We hope that by using this vote mechanic, we'll get better insights into why people vote the way they do, and not just if people would like a feature or not. And, maybe — we can even inspire internal developers to take a look at the community results, before casting their own vote for upcoming RFCs.

Here's an except from our about page:

This project is dedicated to providing a platform for the PHP community to express their thoughts and feelings about the proposals for the PHP language in an easier way.

Our main goal is to visualize the diverse opinions and arguments surrounding PHP's proposed features, making it easier to understand the benefits and downsides of each proposal. By doing so, we hope to foster a greater understanding of how PHP developers feel about these changes.

While official voting on RFCs is limited to internal qualified developers and a specific group of contributors, RFC Vote offers a space for everyone in the PHP community to share their voice. Your votes and comments won't directly influence the official PHP RFC outcomes, but they can serve as valuable insights for those involved in the decision-making process.

In addition to casting a vote, you are encouraged to share your reasoning behind your choices on each RFC. By explaining why you voted yes or no, we can collectively gain better insights into the popularity or concerns associated with an RFC. This collaborative approach allows us to learn from one another and contributes to a more informed and connected PHP community.

So, next thing I knew, I was programming like a madman, did some livestreams to show off the progress, and got help from 9 other developers.

After two weeks, we're nearing a "version 1", and so I wanted to share it with you as well. Maybe you have some ideas, questions, or just want to take a look? Well, the site is already live here: https://rfc.stitcher.io/, and you can check out the code on GitHub.

Let me know your thoughts!

Oh, by the way, I'll be doing another live stream at 11 CEST today (less than 2 hours from when this post was published), so you might want to tune in? I'll see you there!

# Readonly amendments RFC

This RFC proposed two changes, only one was accepted: being able to reinitialize readonly properties while cloning. That might sound like a very big deal, but this RFC only addresses a very specific (but important) edge case: overwriting property values within __clone(), in order to allow deep cloning readonly properties.

readonly class Post
{
    public function __construct(
        public DateTime $createdAt,
    ) {}
    
    public function __clone()
    {
        $this->createdAt = new DateTime(); 
        // This is allowed,
        // even though `createdAt` is a readonly property.
    }
}

You can read an in-depth post about this RFC and some sidenotes here.

# Typed class constants RFC

You can now typehint class constants:

class Foo
{
    const string BAR = 'baz'; 
} 

# #[Override] attribute RFC

The new #[Override] attribute is used to show a programmer's intent. It basically says "I know this method is overriding a parent method. If that would ever change, please let me know".

Here's an example:

abstract class Parent
{
    public function methodWithDefaultImplementation(): int
    {
        return 1;
    }
}

final class Child extends Parent
{
    #[Override]
    public function methodWithDefaultImplementation(): int
    {
        return 2; // The overridden method
    }
} 

Now, let's imagine at one point the parent method changes its method name:

abstract class Parent
{
    public function methodWithNewImplementation(): int
    {
        return 1;
    }
}

Thanks to the #[Override] attribute, PHP will be able to detect that Child::methodWithDefaultImplementation() doesn't override anything anymore, and it will throw an error.

You can read more about the #[Override] attribute here.

# Negative indices in arrays breaking

If you have an empty array, add an item with a negative index, and then add another item, that second item would always start at index 0:

$array = [];

$array[-5] = 'a';
$array[] = 'b';

var_export($array);

//array (
//  -5 => 'a',
//  0 => 'b',
//)

Starting from PHP 8.3, the next item will be added at index -4:

//array (
//  -5 => 'a',
//  -4 => 'b',
//)

# Anonymous readonly classes UPGRADING

Previously, you weren't able to mark anonymous classes as readonly. That's fixed in PHP 8.3:

$class = new readonly class {
    public function __construct(
        public string $foo = 'bar',
    ) {}
};

# The new json_validate() function RFC

Previously, the only way to validate whether a string was valid JSON, was to decode it and detect whether any errors were thrown. This new json_validate() function is beneficial if you only need to know whether the input is valid JSON, since it uses less memory compared to decoding the string.

json_validate(string $json, int $depth = 512, int $flags = 0): bool

# Randomizer additions RFC

PHP 8.2 added the new Randomizer class. This update brings some small additions:

Randomizer::getBytesFromString(string $string, int $length): string

This method allows you to generate a string with a given length that consists of randomly selected bytes from a given string.

Randomizer::getFloat(
    float $min,
    float $max,
    IntervalBoundary $boundary = IntervalBoundary::ClosedOpen
): float

getFloat() returns a float between $min and $max. You can define whether $min and $max should be included thanks to the IntervalBoundary enum. Closed means the value is included, while Open means excluded.

Randomizer::nextFloat(): float {}

Finally, nextFloat() is a shorthand for getFloat(0, 1, IntervalBoundary::ClosedOpen), in other words: it'll give you a random float between 0 and 1, where 1 is excluded.

# Dynamic class constant fetch RFC

PHP 8.3 allows you to fetch constants with a more dynamic syntax:

class Foo 
{
    const BAR = 'bar';
}

$name = 'BAR';
 
// Instead of this:
constant(Foo::class . '::' . $name);

// You can now do this:
Foo::{$name};

# More Appropriate Date/Time Exceptions RFC breaking

In many cases, PHP would simply throw an Exception or Error object; or emit a warning or error when something went wrong in dealing with dates and times. This RFC goes through all those edge cases and adds proper, dedicated exceptions for them.

We now have exceptions like DateMalformedIntervalStringException, DateInvalidOperationException, and DateRangeError.

In general, these additions won't break any code, since these newly added exceptions and errors subclass the generic Exception and Error classes. However, there are three small breaking changes that come with this RFC:

• The Epoch doesn't fit in a PHP integer now returns a new DateRangeError instead of a generic ValueError, which it does not subclass. This is only an issue for 32-bit platforms.
• The Only non-special relative time specifications are supported for subtraction warning with DateTime::sub() and date_sub() becomes a new DateInvalidOperationException.
• The Unknown or bad format (%s) at position %d (%c): %s and String '%s' contains non-relative elements warnings that are created while parsing wrong/broken DateInterval strings will now throw a new DateMalformedIntervalStringException when used with the OO interface, instead of showing a warning and returning false.

# Improved unserialize() error handling RFC

unserialize() will now always emit a E_WARNING when running into problems instead of sometimes an E_NOTICE.

This RFC also proposed adding more exceptions when running unserialize(), but that part didn't get accepted.

# Changes to the range() function breaking

From the changelog:

• A TypeError is now thrown when passing objects, resources, or arrays as the boundary inputs
• A more descriptive ValueError is thrown when passing 0 for $step
• A ValueError is now thrown when using a negative $step for increasing ranges
• If $step is a float that can be interpreted as an int, it is now done so
• A ValueError is now thrown if any argument is infinity or NAN
• An E_WARNING is now emitted if $start or $end is the empty string. The value continues to be cast to the value 0.
• An E_WARNING is now emitted if $start or $end has more than one byte, only if it is a non-numeric string.
• An E_WARNING is now emitted if $start or $end is cast to an integer because the other boundary input is a number. (e.g. range(5, 'z');)
• An E_WARNING is now emitted if $step is a float when trying to generate a range of characters, except if both boundary inputs are numeric strings (e.g. range('5', '9', 0.5); does not produce a warning)
• range() now produce a list of characters if one of the boundary inputs is a string digit instead of casting the other input to int (e.g. range('5', 'z');)

# Traits and static properties breaking

From the changelog:

Uses of traits with static properties will now redeclare static properties inherited from the parent class. This will create a separate static property storage for the current class. This is analogous to adding the static property to the class directly without traits.

# Stack overflow detection PR

PHP 8.3 adds two new ini directives called zend.max_allowed_stack_size and zend.reserved_stack_size. Programs that are close to overflowing the call stack may now throw an Error when using more than the difference between zend.max_allowed_stack_size and zend.reserved_stack_size.

The benefit of this feature is that stack-overflow-induced segmentation faults won't result in segfaults anymore, making debugging a lot easier.

The default for zend.max_allowed_stack_size is 0, meaning PHP will automatically determine a value. You can also provide -1 to indicate there isn't a limit, or a specific number of bytes. The zend.reserved_stack_size directive is used to determine the "buffer zone", so that PHP is able to still throw an error instead of actually running out of memory. The value here should be a number of bytes, but PHP will determine a reasonable default for you, so you don't necessarily need to set it, unless you're running into edge cases for specific programs.

On a final note, for fibers, the existing fiber.stack_size directive is used as the max allowed stack size.

zend.max_allowed_stack_size=128K

# New mb_str_pad function RFC

From the RFC:

In PHP, various string functions are available in two variants: one for byte strings and another for multibyte strings. However, a notable absence among the multibyte string functions is a mbstring equivalent of str_pad(). The str_pad() function lacks multibyte character support, causing issues when working with languages that utilize multibyte encodings like UTF-8. This RFC proposes the addition of such a function to PHP, which we will call mb_str_pad().

The function looks like this:

function mb_str_pad(
    string $string, 
    int $length, 
    string $pad_string = " ", 
    int $pad_type = STR_PAD_RIGHT, 
    ?string $encoding = null,
): string {}

# Magic method closures and named arguments PR

Let's say you have a class that supports magic methods:

class Test {
    public function __call($name, $args) 
    {
        var_dump($name, $args);
    }
    
    public static function __callStatic($name, $args) {
        var_dump($name, $args);
    }
}

PHP 8.3 allows you to create closures from those methods, and then pass named arguments to those closures. That wasn't possible before.

$test = new Test();

$closure = $test->magic(...);

$closure(a: 'hello', b: 'world'); 

# Invariant constant visibility breaking

Previously, visibility for constants weren't checked when implementing an interface. PHP 8.3 fixes this bug, but it might lead to code breaking in some places if you weren't aware of this behaviour.

interface I {
    public const FOO = 'foo';
}

class C implements I {
    private const FOO = 'foo';
}

# The small deprecations RFC rfc

As is usual with every release, there's a single RFC that adds a bunch of small deprecations. Keep in mind that deprecations are no errors, and these are generally a good thing for the language to move forward. These are the deprecations that passed, you can read more details about them in the RFC:

• Deprecate passing negative $widths to mb_strimwidth()
• Deprecate and remove the NumberFormatter::TYPE_CURRENCY constant
• Deprecate and remove the broken pre-PHP 7.1 Mt19937 implementation (MT_RAND_PHP)
• Deprecate and remove calling ldap_connect() with 2 parameters $host and $port
• Deprecate remains of string evaluated code assertions

# Small, but notable changes

Not every change in PHP passes the RFC process. In fact, the majority of changes include maintenance and bugfixing, and don't require an RFC. All of these changes are listed in the UPGRADING document. I'll list some of the most prominent ones, but you should definitely read throughout the whole list if you want to know about the tiniest details.

• When using FFI, C functions that have a return type of void now return null instead of returning FFI\CData:void
• posix_getrlimit() now takes an optional $res parameter to allow fetching a single resource limit.
• gc_status() has four new fields: running, protected, full, and buffer_size.
• class_alias() now supports creating an alias of an internal class.
• mysqli_poll() now raises a ValueError when the read nor error arguments are passed.
• array_pad() is now only limited by the maximum number of elements an array can have. Before, it was only possible to add at most 1048576 elements at a time.
• New posix functions: posix_sysconf(), posix_pathconf(), posix_fpathconf(), and posix_eaccess()
• Executing proc_get_status() multiple times will now always return the right value on posix systems.
• opcache.consistency_checks ini directive was removed
• Improved array_sum() and array_product()

That's it for now, but this list will grow over time. If you want to stay up to date, you can subscribe to my newsletter, follow me on Twitter, or subscribe to my RSS feed.

They are, of course, right, but only half. Let's talk about object relations.

You can think of the classic class/interface relation as an Is A relation: you can say Item Is A Purchasable Item, or, in technical terms: class Item implements Purchasable.

I don't think there's any disagreement here amongst developers, this is the classic definition of an interface. It allows us to write code that works with all types of purchasables, without worrying which concrete implementation we're dealing with.

function createPayment(Purchasable $purchasable): Payment
{
    $price = $purchasable->getPrice();
    
    // …
}

This is where people who argue against interface default methods stop. If this is the only way you're using interfaces, then yes, you're right: interface default methods aren't necessary.

However, there is another way interfaces are used. And mind you: I'm not saying "there is another way interfaces can be used", no, I'm saying this is happening in modern PHP code, today, in many projects.

Here goes. Interfaces can be used to model an Acts As relation — I have a perfect example, thanks to Larry.

Here's the so called LoggerInterface, part of PSR-3:

interface LoggerInterface
{
    public function emergency(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function alert(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function critical(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function error(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function warning(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function notice(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function info(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function debug(
        string|\Stringable $message, 
        array $context = []
    ): void;

    public function log(
        $level, 
        string|\Stringable $message, 
        array $context = []
    ): void;
}

As you can see, most methods are essentially shortcuts for the log method: they are convenience methods so that you don't have to manually provide a logging level. It's a great design choice to include in the interface, as it forces all implementations to have better accessibility.

However, let's be honest, no one is ever going to need a logger with a different implementation of debug or info or any of the other shorthands. These methods will always look the same:

public function debug(
    string|\Stringable $message, 
    array $context = []
): void
{
    $this->log(LogLevel::DEBUG, $message, $context);
}

In essence, this LoggerInterface is not only describing an Is A relation — if that were the case we'd only need the log method. No, it also describes an Acts As relation: a concrete logger implementation can Act As as proper logger, including the convenience methods associated with it. FileLogger Acts As LoggerInterface, Monolog Acts As LoggerInterface.

It all boils down to the question: is this a valid way of writing and using interfaces? I would say, yes.

I'd encourage you to take a close look at your own projects, and be totally honest for a moment: are any of your interfaces describing an Acts As relationship? If they do, then you cannot make the case against interface default methods.

As always, it's important to note that I'm working with the data available to us. That means that these charts are not a 100% accurate representation of the PHP community as a whole, but they are an accurate representation of one of the most prominent parts of PHP: the packagist ecosystem.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

# Usage Statistics

Let's start with the percentage of PHP versions being used today, and compare it to the previous three editions, note that I've omitted all versions that don't have more than 1% usage:

Visualizing this data looks like this:

Evolution of version usage

It's important to know which PHP versions are currently still supported: PHP 8.2 and PHP 8.1 are still receiving updates. PHP 8.0 is still getting security updates until the end of November, this year. That means that PHP 7.4 and below don't receive any updates more, and should be considered end of life.

In total, that's around 30% of packagist downloads by outdated and insecure version of PHP. At the beginning of this year, that number was closer to 40%, meaning we see a steady decline — a good thing!

New in PHP 8.3

Moving on to the all-time overview chart, here you can see the evolution of version usage across time:

All time evolution

It seems that PHP 8.1 saw the biggest growth over time since PHP 7.4 and PHP 5.5. PHP 8.2, in comparison, seems to make a slower start. It's also interesting to note a relative high percentage of PHP 8.1 two years in a row. Granted, PHP 8.1 was a pretty solid release with features like enums and readonly properties. It'll be interesting to see how this graph evolves next year, when PHP 8.1 moves in security fixes only mode.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

# Required versions

Next, I used Nikita's popular package analyzer to download the 1000 most popular composer packages. I wrote a script that scans these packages to determine their minimum required version. Here are the results:

There are two important notes to make here.

1. This tables shows the minimum required version. That means that packages with a minimal version of, for example, 8.0, could also support PHP 8.1 or and PHP 8.2.
2. If you count the numbers, you'll notice there are some differences between each year. Not every package lists a valid version string.

Instead of comparing absolute numbers, it's best to plot this data into a chart for a relative comparison, so that we can see changes over time:

Minimal PHP requirement over time

There seems to be a pretty big leap in PHP 8.0 and PHP 8.1 being the minimal versions — a good thing. After all, the open source community plays a big part in pushing the community forward by increasing their minimal required version.

That's all data I have to share for this edition of PHP's version stats. You can always reach me via email if you want to share your thoughts or have questions. You can also subscribe to my newsletter if you want to receive updates about this blog in the future.

Marking a method with the #[Override] attributes signifies that you know this method is overriding a parent method. So the only thing it does, is show intent.

Why does that matter? You already know you're overriding a method, don't you? Well, let's imagine these two classes:

abstract class Parent
{
    public function methodWithDefaultImplementation(): int
    {
        return 1;
    }
}

final class Child extends Parent
{
    #[Override]
    public function methodWithDefaultImplementation(): int
    {
        return 2; // The overridden method
    }
} 

Now, let's imagine at one point the parent method changes its method name:

abstract class Parent
{
    public function methodWithNewImplementation(): int
    {
        return 1;
    }
}

Before the #[Override] attribute, there was no way of knowing that Child::methodWithDefaultImplementation() doesn't override the renamed method anymore, which could lead to unforeseen bugs.

Thanks to #[Override] though, PHP now knows something is wrong, thanks to that attribute. It basically says "I know this method should override a parent method. If that would ever change, please let me know".

# Some thoughts

What strikes me most about this RFC, is how irrelevant it could be. Once again we're adding runtime checks for something that could be determined by static analysers.

I don't want to repeat every argument I made in the past, so I'll just link to my previous thoughts on the topic, and summarise: we're missing out. PHP internals should either come with an official spec for static analysers, or with a first-party static analyser. Why? Because so much more would be possible, and it would drive PHP forward tremendously.

Anyway, it seems like many people have tried to make the same argument about this RFC in particular on the Internals mailing list, to no avail.

I don't mind this feature, although I'll probably never use it myself (I use an IDE that prevents me from making these kinds of mistakes, I don't need PHP's runtime to double-check it for me). What I am sad about, is how the PHP community is divided between the static-analysis and non-static-analysis camps, and I don't know if there will ever be someone who'll be able to unify and steer the language into a next decade of progression.

It was a beautifully complex, abstract class that integrated with Doctrine (the ORM that I was using back then). It had every possible CRUD operation you could think of — not just for entities, but also for child- and has many relations; there were automatic overviews, filtering, pagination, validation, data persistence, routing, and whatnot.

And the only thing I had to do was to create a new controller, extend from my amazing CRUDController™, provide an entity class, and be done.

class TimesheetController extends CRUDController
{
    public function getEntity(): string
    {
        return Timesheet::class;
    }
}

Such a blast!

Except, of course: exceptions started to emerge. Not the programming kind, but the business kind. Some controllers had to do some things a little differently. It was small things at first: different URL schemes, different kinds of validation; but soon, things grew more and more complex: support for nested entities or complex filtering, to name a few.

And young me? I just kept going. Adding the proverbial knobs and pulls to my abstract class (which was growing into a set of classes by now).

In the end, I created a monster; and — ironically — it had taken more time than if I had simply copied code between controllers over and over again. On top of that: I was leaving the startup, and no one really understood how more than 50 controllers actually worked.

You might assume I understood, but let me be clear: I didn't really know how much of it worked anymore.

Yes, I had failed to see the proper solution: a class generator — so that I didn't have to manually copy code again. It actually existed back then, I simply didn't know about it, no one told me about it, and I wasn't smart enough to question myself once I started going down a certain path.

It's such a classic example, many of you probably recognise it. I wouldn't say my coding skills were bad, by the way. No, I didn't question myself enough, I lacked self-reflection and wasn't able to critically look at my own ideas.

I wish I could show you The CRUDController™'s source code; but I don't have access to it anymore, unfortunately. Luckily, the memory still exists. And it's a memory I remind myself of very often when I'm going down the path of abstractions and complications. It's often enough to hold me back and look for better solutions.

So, how do we go from plain PHP to a map like this? It all starts with noise.

# Noise generation

Let's imagine we have grid of 150 by 100 pixels. Each pixel makes up a point of our map.

$pixels = [];

for($x = 0; $x < 150; $x++) {
    for($y = 0; $y < 100; $y++) {
        $pixels[$x][$y] = drawPixel($x, $y, 0); 
    }
}

For now, the drawPixel function will generate a div per pixel, which can be laid out on a CSS grid. We can refactor to use canvas later, but being able to use CSS's built-in grid saves a lot of time.

function drawPixel(int $x, int $y): string
{
    return <<<HTML
    <div style="--x: {$x}; --y: {$y};"></div>
    HTML;
}

This is the template file:

<style>
    :root {
        --pixel-size: 9px;
        --pixel-gap: 1px;
        --pixel-color: #000;
    }

    .map {
        display: grid;
        grid-template-columns: repeat({{ count($pixels) }}, var(--pixel-size));
        grid-auto-rows: var(--pixel-size);
        grid-gap: var(--pixel-gap);
    }

    .map > div {
        width: var(--pixel-size);
        height: 100%;
        grid-area: var(--y) / var(--x) / var(--y) / var(--x);
        background-color: var(--pixel-color);
    }
</style>

<div class="map">
    @foreach($pixels as $x => $row)
        @foreach($row as $y => $pixel)
            {!! $pixel !!}
        @endforeach
    @endforeach
</div>

This is the result:

By the way, I will get rid of the gaps between pixels, I only added them to show that these are indeed separate grid cells.

Let's play around with our grid. We'll start by assigning a value between 0 and 1 for each individual pixel. We'll use a class called Noise that takes a pixel's point (X/Y coordinates), and returns a value for that point. First, we'll return a random value.

final readonly class Noise
{
    public function __construct(
        private int $seed,
    ) {}
    
    public function generate(Point $point): float
    {
        return rand(1, 100) / 100;
    }
}

// …

drawPixel($x, $y, $noise->generate($x, $y)); 

Here's the result:

Relying on randomness won't get us very far though. We want a given seed to generate the same map over and over again. So instead of randomness, let's write a hash function: a function that, for any given point and seed, will generate the same value over and over again. You could make it as simple as multiplying the seed with the x and y coordinates, and turning that into a fraction:

public function generate(Point $point): float
{
    $hash = $this->seed * $point->x * $point->y;
    
    return floatval('0.' . $hash);
}

The result, however, doesn't seem random enough. Remember that we want to generate a world map: we want some randomness, but also some cohesion. So our hash function will need to be a bit more complex.

Let's try an existing hash function that we don't need to invent ourselves. We probably want a performant one, since we're generating a hash for thousands of pixels. PHP has support for xxHash, which is an "extremely fast hashing algorithm". Let's give it a try.

private function hash(Point $point): float
{
    $hash = bin2hex(
        hash(
            algo: 'xxh32',
            data: $this->seed * $point->x * $point->y,
        )
    );

    $hash = floatval('0.' . $hash);

    return $hash;
}

This noise looks promising: it's quite random, but always yields the same result for a given seed. But going from this to a cohesive world map still seems like a leap. Let's change our hash function, so that it'll return the same color within a square of 10 pixels:

private function hash(Point $point): float
{
    $baseX = ceil($point->x / 10);
    $baseY = ceil($point->y / 10);

    $hash = bin2hex(
        hash(
            algo: 'xxh32',
            data: $this->seed * $baseX * $baseY,
        )
    );

    $hash = floatval('0.' . $hash);

    return sqrt($hash);
}

Here's the result:

Oh, by the way: I take the square root of the hash, just to increase all values a little bit. That'll be useful in the future, but not necessary. Without the square root, the map looks like this:

Let's imagine something for a second. Let's say all pixels with a value higher than 0.6 are considered land, and all pixels with a lower value are considered water. Let's make some changes to our drawPixel method to reflect that behaviour:

function drawPixel(int $x, int $y, float $value): string
{
    $hexFromNoise = hex($value);
    
    $color = match(true) {
        $noise < 0.6 => "#0000{$hexFromNoise}", // blue
        default => "#00{$hexFromNoise}00", // green
    };
    
    return <<<HTML
    <div style="--x: {$x}; --y: {$y}; --pixel-color: {$color}"></div>
    HTML;
}

By the way, that hex function converts a value between 0 and 1 to a two-digit hexadecimal. It looks like this:

function hex(float $value): string
{
    if ($value > 1.0) {
        $value = 1.0;
    }

    $hex = dechex((int) ($value * 255));

    if (strlen($hex) < 2) {
        $hex = "0" . $hex;
    }

    return $hex;
}

The result is looking a lot more like a map already:

Ok, pretty nice! But these sharp edges don't really look realistic. Can we find a way to make transitions between the edges more smooth?

# Lerp

Time for some maths. Let's say we have two values: 0.34 and 0.78. We want to know the value exactly in the middle between these two. How do we do that?

Well, there's a simple mathematical formula for that. It's called "Linear Interpolation" — "LERP" for short:

function lerp(float $a, float $b, float $fraction): float
{
    return $a + $fraction * ($b - $a);
}

lerp(0.34, 0.78, 0.5); // 0.56

So, given a number $a (0.34), a number $b (0.78), and a fraction (0.5, also known as: "half"); we get 0.56 — the number exactly in the middle between 0.34 and 0.78.

Thanks to the fraction part in our lerp formula, we can determine the value at any place between these points, not just the middle:

lerp(0.34, 0.78, 0.25); // 0.45

Ok, so why is this important? Well, we can use our lerp function to smooth edges! Let go back to our noise pattern and explain:

Let's say that, instead of coloring each pixel in this grid, we only color a pixel when it's exactly on a 10x10 lattice. In other words: when its x and y coordinates are divisible by 10.

final readonly class Noise
{
    public function generate(Point $x): float
    {
        if ($point->x % 10 === 0 && $point->y % 10 === 0) {
            return $this->hash($point);
        } else {
            return 0.0;
        }
    }

    // …
}

Here's the lattice:

Let's imagine that these pixels are the $a and $b boundaries we pass into our lerp function. For any given pixel, it's trivial to determine these surrounding "fixed" points (they are on a fixed 10x10 grid) and we can also calculate the pixel's relative distance to those points. We can use the hash of these fixed points and the distance from any pixel to these points as input values for our lerp function. The result will be a value that's somewhere between the values of our two edge points — in other words: a smooth transition.

First, we'll use our lerp function on the y-axis (whenever x is divisible by 10). We'll determine the relative top and bottom points on our "lattice", calculate the distance between our current point and the top point, and then we'll use our lerp function to determine the right value between the top and bottom point, with that distance fraction:

if ($point->x % 10 === 0 && $point->y % 10 === 0) {
    $noise = $this->hash($point);
} elseif ($point->x % 10 === 0) {
    $topPoint = new Point(
        x: $point->x,
        y: (floor($point->y / 10) * 10), 
        // The closest point divisible by 10, above our current pixel
    );

    $bottomPoint = new Point(
        x: $point->x, 
        y: (ceil($point->y / 10) * 10) 
        // The closest point divisible by 10, below our current pixel
    );

    $noise = lerp(
        // The hash value (or color) of that top point:
        a: $this->hash($topPoint),
        
        // The hash value (or color) of that bottom point:
        b: $this->hash($bottomPoint),
        
        // The distance between our current point and the top point
        // — the fraction
        fraction: ($point->y - $topPoint->y) / ($bottomPoint->y - $topPoint->y),
    );
}

Here's the result, you can already see the smooth transition within the lines:

Next, let's add the same functionality in the other direction, when y is divisible by 10:

if ($point->x % 10 === 0 && $point->y % 10 === 0) {
    // …
} elseif ($point->x % 10 === 0) {
    // …
} elseif ($point->y % 10 === 0) {
    $leftPoint = new Point(
        x: (floor($point->x / 10) * 10),
        y: $point->y,
    );

    $rightPoint = new Point(
        x: (ceil($point->x / 10) * 10),
        y: $point->y,
    );

    $noise = lerp(
        $this->hash($leftPoint),
        $this->hash($rightPoint),
        ($point->x - $leftPoint->x) / ($rightPoint->x - $leftPoint->x),
    );
}

No surprises:

Finally, for the remainder of the pixels, we won't be able to do a simple lerp function (which only works in one dimension). We'll have to use Bilinear Interpolation: we'll first make two lerp values for both x-axes, and then one final lerp value for the y-axis. We'll also need four edge points instead of two, because these pixels aren't aligned with our lattice.

if ($point->x % 10 === 0 && $point->y % 10 === 0) {
    // …
} elseif ($point->x % 10 === 0) {
    // …
} elseif ($point->y % 10 === 0) {
    // …
} else {
    $topLeftPoint = new Point(
        x: (floor($point->x / 10) * 10),
        y: (floor($point->y / 10) * 10),
    );

    $topRightPoint = new Point(
        x: (ceil($point->x / 10) * 10),
        y: (floor($point->y / 10) * 10),
    );

    $bottomLeftPoint = new Point(
        x: (floor($point->x / 10) * 10),
        y: (ceil($point->y / 10) * 10)
    );

    $bottomRightPoint = new Point(
        x: (ceil($point->x / 10) * 10),
        y: (ceil($point->y / 10) * 10)
    );

    $a = lerp(
        $this->hash($topLeftPoint),
        $this->hash($topRightPoint),
        ($point->x - $topLeftPoint->x) / ($topRightPoint->x - $topLeftPoint->x),
    );

    $b = lerp(
        $this->hash($bottomLeftPoint),
        $this->hash($bottomRightPoint),
        ($point->x - $bottomLeftPoint->x) / ($bottomRightPoint->x - $bottomLeftPoint->x),
    );

    $noise = lerp(
        $a,
        $b,
        ($point->y - $topLeftPoint->y) / ($bottomLeftPoint->y - $topLeftPoint->y),
    );
}

Note that there's some repetition in our code that we could get rid of. But I prefer explicitly making all four edge points for clarity. Take a look at the result though:

This looks much smoother! Let's apply our colours:

Hm. You can probably see where we're going, but I still think these lines are far too… rough. Luckily, there are two more tricks we can apply! First, instead of using a plain lerp function, we can apply a so-called "shaping function" to our fraction. With this shaping function, we can manipulate our fraction before passing it to the lerp function. By default, our fraction will have a linear value — it's the distance from any given point to the starting edge:

But by applying a function to our fraction, we can manipulate it so that the values closer to the edges are even more smooth.

We could use whatever function we'd want. For our case I'll use a shaping function called smoothstep, which smooths edges.

function smooth(float $a, float $b, float $fraction): float
{
    $smoothstep = function (float $fraction): float {
        $v1 = $fraction * $fraction;
        $v2 = 1.0  - (1.0 - $fraction) * (1.0 -$fraction);

        return lerp($v1, $v2, $fraction);
    };

    return lerp($a, $b, $smoothstep($fraction));
}

The difference is subtle, but it's a little bit better.

The second trick is to apply a new layer of noise. This one shouldn't be as random as our first one though. We'll use a simple circular pattern, and apply it as a height map on our existing noise. The further a pixel is from the center, the smaller its value:

private function circularNoise(int $totalWidth, int $totalHeight, Point $point): float
{
    $middleX = $totalWidth / 2;
    $middleY = $totalHeight / 2;

    $distanceFromMiddle = sqrt(
        pow(($point->x - $middleX), 2)
        + pow(($point->y - $middleY), 2)
    );

    $maxDistanceFromMiddle = sqrt(
        pow(($totalWidth - $middleX), 2)
        + pow(($totalHeight - $middleY), 2)
    );

    return 1 - ($distanceFromMiddle / $maxDistanceFromMiddle) + 0.3;
}

This is the pattern on its own:

And now we combine this pattern with our existing noise, which is as easy as multiplying them:

final readonly class Noise
{
    public function __construct(
        private int $seed,
    ) {}
    
    public function generate(Point $point): float
    {
        return $this->baseNoise($point) 
             * $this->circularNoise($point);
    }
}

Here's the result:

This looks a lot better! Thanks to our circular pattern, the middle portion of our map is raised, while the outer portions are lowered. It creates a neat island look. Let's try out some seeds to see the difference between them:

Pretty nice! But we're far from done: we'll want to add different areas on our map: forests, plains, mountains, vegetation, …. Simply using a match in our drawPixel method won't suffice anymore.

# Improved drawing

Let's make an interface Biome, which will determine our pixel color, and can determine what kind of vegetation should be added. We'll also represent pixels as a proper value object.

interface Biome
{
    public function getPixelColor(Pixel $pixel): string;
}

Let's add seas and plains first.

final readonly class SeaBiome implements Biome
{
    public function getPixelColor(Pixel $pixel): string
    {
        $base = $pixel->value;

        while ($base < 0.25) {
            $base += 0.01;
        }

        $r = hex($base / 3);
        $g = hex($base / 3);
        $b = hex($base);

        return "#{$r}{$g}{$b}";
    }
}

final readonly class PlainsBiome implements Biome
{
    public function getPixelColor(Pixel $pixel): string
    {
        $g = hex($pixel->value);
        $b = hex($pixel->value / 4);

        return "#00{$g}{$b}";
    }
}

Depending on a pixel's biome, we'll use its noise to generate a different kind of color. In our drawPixel function, we can now make some changes:

function drawPixel(Pixel $pixel): string
{
    $biome = BiomeFactory::for($pixel);
    
    $color = $biome->getPixelColor($pixel);
    
    return <<<HTML
    <div style="
        --x: {$x}; 
        --y: {$y};
        --pixel-color: {$color};
    "></div>
    HTML;
}

For now, our BiomeFactory will only take a pixel's value into account to determine the biome. We could add other conditions later.

final readonly class BiomeFactory
{
    public static function for(Pixel $pixel): Biome
    {
        return match(true) {
            $pixel->value < 0.6 => new SeaBiome(),
            default => new PlainsBiome(),
        };
    }
}

It still works:

Let's go ahead and add all biomes now:

final readonly class BiomeFactory
{
    public static function make(Pixel $pixel): Biome
    {
        return match(true) {
            $pixel->value < 0.4 => new SeaBiome(),
            $pixel->value >= 0.4 && $pixel->value < 0.44 => new BeachBiome(),
            $pixel->value >= 0.6 && $pixel->value < 0.8 => new ForestBiome(),
            $pixel->value >= 0.8 => new MountainBiome(),
            default => new PlainsBiome(),
        };
    }
}

Note that I also decided to change the sea level: from 0.6 to 0.4, so the map looks a bit different now. Take a look:

Not bad, right? But this is far from a finished game — in fact, this is only the very first step: we'll need a way of interacting with this map, we'll need to define some form of gameplay. Maybe you remember the intro? I mentioned resource gathering. I imagine this game to be some kind of cookie-clicker style game: the more resources you gather, the more you can advance in the tech tree, the more resources you can gather, …

Anyway, I've done a lot more work on this game already: I actually started this project as an experiment to explore the limits of Laravel Livewire, so interactivity and gameplay were the primary focus. I've explained the basic concepts already on my YouTube channel in two videos. I'm also working on a third video where I discuss how I added interaction to this particular game board, as well as the problems I ran in to (there are a bunch of caveats I haven't mentioned yet in this blog post).

So, if you want to follow along, make sure to subscribe on YouTube — I hope to make the third and final video of this series soon. Alternatively, you can subscribe to my mailing list, where I'll send you an update as well.

In the meantime, you can watch the first two parts of this series; and don't forget to subscribe!

I do want to write about the underlying mindset of these kinds of posts, and of the people upvoting — that mindset of calling something "harmful". I can understand that someone doesn't like a framework, an ecosystem, the community or some individuals of that community. But calling something "harmful"? As if it's proven that Laravel hurts? Hurts what exactly? The PHP community? PHP's reputation? Laravel's competing frameworks? A programmer's "best practices"?

For what it's worth, I'd say that Laravel has done mostly good to the PHP community: it seems that a lot of people are able to make a living thanks to it; it seems that Laravel is widely known and praised within the programming community; in what way could it be considered "harmful"?

"It creates unmaintainable projects and doesn't teach best practices" — people say.

The argument of "best practices" baffles me. What defines a "best practice"? Aren't "best practices" meant to help you in building successful software? And hasn't Laravel proven to be able to do exactly that: build successful software? Shouldn't our assumptions of what defines a "best practice" be redefined if the most popular PHP framework doesn't seem to fit those assumptions?

Unmaintainable? To what extent? There are huge projects running Laravel in production — they have been for years? Some people will point towards failed Laravel projects, trying to prove their point. Well, let me show you success stories. Now what? Let me show you some failed Symfony projects. Who's right? Who's wrong?

This kind of mindset isn't uncommon in the programming world: we're used to doing things a certain way, and we're comfortable doing so. Whenever something comes along that doesn't fit our way of doing things, we experience friction. However, instead of questioning ourselves, too often do we point towards the thing that's causing friction, blaming it for everything that's wrong in the world. The safety of the internet makes it even more profound: we can write whatever we want with little to no consequences.

I would say that the inability to self-reflect, to adapt, and to question ourselves, is probably way more harmful than Laravel will ever be.

It looks like someone combined a horse with a giraffe, and kept adding stuff until they met the requirement of "being able to survive in the desert". Who came up with that? Don't get me wrong: camels do work, so they must have gotten something right. But honestly, the finishing touches are far from ideal:

PHP is like a camel: there's little to say when it comes to beauty or elegance, but it does seem to survive many harsh conditions. So, who am I to judge? Coincidentally, PHP was originally inspired by PERL, whose logo is a camel; so maybe there is a deeper connection still? But let's not go too deep down the camel rabbit hole; instead, let's talk about how programming languages are designed.

PHP is one of those programming languages that's not backed by a big company or a group of people whose job it is to work on it. PHP is mostly driven by a group of volunteers. A year ago, we got the PHP Foundation which employs a handful of developers to work on the language, but it's not like they have any ownership. They have to submit their ideas, and are at the mercy of "PHP Internals" to decide what goes in the language, and what not.

So about that group of volunteers: PHP Internals are a group of people who discuss and vote on what gets added into the language. Part of that group consists of core developers, and then there are some prominent PHP community members, release managers, past contributors, docs maintainers, and probably a bunch of other people. We're talking somewhere around 200 members — probably, but there aren't any public numbers, as far as I know.

That group is the perfect example of a committee: they all come together to decide on how PHP should evolve next. They don't have a unified plan or vision, but all of them bring their own agenda. While a core programmer might favor cleaning up PHP's internal code (even when it brings some breaking changes), a prominent community member might push forward ideas that help with the development of a PHP framework or package.

This phenomenon — designing a language with such a large group — is called "design by committee". At first glance, it might sound like a very democratic approach to software design where everyone can pitch an idea, and if enough people vote for it, it gets added. However, because there's such a large diversity of opinions, a committee rarely achieves excellence.

Say you want to add a feature in PHP that benefits you — a prominent framework developer. Then you'll have to convince enough people to vote for it. First, you request Internals to share their comments on your idea — an RFC (request for comments). Naturally, you'll make compromises, trying to get as many people on your side as possible before voting starts. On top of that: people can lobby others to influence their vote and, in the end, the result. Suddenly you're playing a game of politics, instead of proper software design.

And so, design by committee often leads to average results at best; or (in many cases) no result, because people couldn't find consensus. Camels were probably designed by a committee as well. Sure, they work, but they are far from excellence and full of compromise.

The alternative to design by committee is called "design by dictator" or having a "benevolent dictator for life". It might sound rather negative at first, but hear me out. A benevolent dictator (or group of benevolent dictators) don't want to push their own agenda; they want the best for their product. It's their product — they have full ownership. And exactly because it is their product, they will listen to "the masses". Because, their product is nothing, without their people.

In the end though, a dictator will make decisions, even when those decisions aren't agreed upon within the community as a whole. There's much less need for compromise, and so, more room for excellence.

Maybe you are skeptical of the idea? Well, don't take my word for it, there are quite a lot of open source projects applying this technique. You might even recognise a couple:

• Rust
• Laravel
• Ruby
• Linux
• Ruby on Rails
• Ubuntu
• Vue.js
• And more

I think it's fair to say that all of these projects are a huge success. I believe much of their success comes from that one person in charge, leading the way, having a clear vision. These leaders still listen to their audience, and they often allow for voting on features. But, in the end, there's one person carrying the ownership. There's one leader to look up to.

When people trust a benevolent dictator, much more becomes possible than when they settle with a committee.

PHP will never change its leadership model; the committee would have to give up its power which, of course, they don't want to. I think this is one of the reasons I'm excited about the idea of a superset for PHP: it could be an independent project, led by one person or a company, regardless of what the committee wants. If that person or company gained my trust, I would be fine with them make the decisions to move the language forward, rather than settling with average.

Let's take a look!

In an ideal world, we'd be able to clone classes with readonly properties, based on a user-defined set of values. The so called clone with syntax (which doesn't exist):

readonly class Post
{
    public function __construct(
        public string $title,
        public string $author,
        public DateTime $createdAt,
    ) {}
}

$post = new Post(
    title: 'Hello World',
    // …
);

 // This isn't possible!
$updatedPost = clone $post with {
    title: 'Another One!',
};

Reading the title of the current RFC: "Readonly properties can be reinitialized during cloning" — you might think something like clone with this is now possible. However… it isn't. The RFC allows only allows for one specific operation: to overwrite readonly values in the magic __clone method:

readonly class Post
{
    public function __construct(
        public string $title,
        public string $author,
        public DateTime $createdAt,
    ) {}
    
    public function __clone()
    {
        $this->createdAt = new DateTime(); 
        // This is allowed,
        // even though `createdAt` is a readonly property.
    }
}

Is this useful? It is! Say you want to clone objects with nested objects — a.k.a. making "deep clones"; then this RFC allows you to clone those nested objects as well, and overwrite them in your newly created clone — even when they are readonly properties.

readonly class Post
{
    public function __clone()
    {
        $this->createdAt = clone $this->createdAt; 
        // Creates a new DateTime object,
        // instead of reusing the reference
    }
}

Without this RFC, you'd be able to clone $post, but it would still hold a reference to the original $createdAt object. Say you'd make changes to that object (which is possible since readonly only prevents the property assigned from changing, not from its inner values being changed):

$post = new Post(/* … */);

$otherPost = clone $post;

$post->createdAt->add(new DateInterval('P1D'));

$otherPost->createdAt === $post->createdAt; // true :(

Then you'd end up with the $createdAt date changed on both objects!

Thanks to this RFC, we can make real clones, with all their nested properties cloned as well, even when these properties are readonly:

$post = new Post(/* … */);

$otherPost = clone $post;

$post->createdAt->add(new DateInterval('P1D'));

$otherPost->createdAt === $post->createdAt; // false :)

# On a personal note

I think it's good that PHP 8.3 makes it possible deep cloning readonly properties. However, I have mixed feelings about this implementation. Imagine for a second that clone with existed in PHP, then all of the above would have been unnecessary. Take a look:

// Again, this isn't possible!
$updatedPost = clone $post with { 
    createdAt: clone $post->createdAt,
};

Now imagine that clone with gets added in PHP 8.4 — pure speculation, of course. It means we'd have two ways of doing the same thing in PHP. I don't know about you, but I don't like it when languages or frameworks offer several ways of doing the same thing. As far as I'm concerned, that's suboptimal language design at best.

This is, of course, assuming that clone with would be able to automatically map values to properties without the need of manually implementing mapping logic in __clone. I'm also assuming that clone with can deal with property visibility: only able to change public properties from the outside, but able to change protected and private properties when used inside a class.

Awhile ago, I wrote about how PHP internals seem to be divided, one group comes up with one solution, while another group wants to take another approach. To me, it's a clear drawback of designing by committee.

Full disclosure — the RFC mentions clone with as a future scope:

None of the envisioned ideas for the future collide with the proposals in this RFC. They could thus be considered separately later on.

But I tend to disagree with this statement, at least assuming that clone with would work without having to implement any userland code. If we'd follow the trend of this current RFC, I could imagine someone suggesting to add clone with only as a way to pass data into __clone, and have users deal with it themselves:

readonly class Post
{
    public function __clone(...$properties)
    {
        foreach ($properties as $name => $value) {
            $this->$name = $value;
        }
    }
}

However, I really hope this isn't the way clone with gets implemented; because you'd have to add a __clone implementation on every readonly class.

So, assuming the best case where clone with gets added, and where it is able to automatically map values; then the functionality of this current RFC gets voided, and makes it so that we have two ways of doing the same thing. It will confuse users because it faces them with yet another a decision when coding. I think PHP has grown confusing enough as is, and I'd like to see that change.

On the other hand, I do want to mention that I don't oppose this RFC on its own. I think Nicolas and Máté did a great job coming up with a solid solution to a real-life problem.

PS: in case someone wants to make the argument for the current RFC because you only need to implement __clone once per object and not worry about it on call-site anymore. There's one very important details missing from these examples in isolation: deep copying doesn't happen with a simple clone call. Most of the time, packages like deep-copy are used, and thus, the potential overhead that comes with my clone with example is already taken care off by those packages and don't bother end users.

Today I want to thank Kinsta in particular for stepping in and helping out! They've committed to a generous monthly sponsorship, which is getting me closer to achieving that break-even goal.

If you haven't heard of Kinsta before, they are a cloud platform targeted towards companies and dev teams to help them ship and manage their web projects. What I like about companies like Kinsta is that they are always on the lookout for helping out the community members like they did with my sponsor issue. They contacted me out of the blue saying they wanted to help, which I really appreciate!

So big thanks to Kinsta for helping me work on stitcher.io in my free time!

For example, you can use it to comment out individual keywords and statements like final or implements X:

/-final class Foo /-implements Bar

But you could also use the /-- variant to comment out a whole section based on its scope:

/--public function fromInterface(int $i): int {
    return $i + 1;
}

It's just a small thing, but when I saw it, it immediately clicked. Especially in a language like PHP where "dump and die debugging" is the de-facto standard, it would be nice to have a slightly shorter and more convenient way to comment out code.

/-final class Foo /-implements Bar
{
    public /-readonly string $prop;
    
    /--public function fromInterface(int $i): int {
        return $i + 1;
    }
}

New in PHP 8.3

I’ve been laughed at and ridiculed. But don’t worry, I won’t give in. I will keep using a light colour scheme.

I know I’m a minority, and people do ask me why I keep using light colours schemes. Well, I’ve got three reasons to do so, and I think they make a pretty good point for everyone to switch.

First, people have been doing research into text readability. Studies show that our eyes can more easily distinguish a dark foreground from a light background, than the other way around. I will leave some links in the footnotes if you want to read about it. I find it a compelling first reason for light colour schemes: they are easier to read.

Second: the majority of websites and UIs are still made with a light colour scheme first, so switching between dark code and light applications becomes tiring after a while, especially if you’re doing it day in, day out. Granted, more and more applications support dark mode, but then we’re back to reason one: they are more difficult to read.

Third, and this is probably the thing most people think about: there’s this misconception that “light colour schemes” hurt your eyes, especially in dark rooms. Let me tell you: sitting in an all dark room programming isn’t good for your eyes anyways, regardless of the colour scheme you’re using. If you feel that a light colour scheme hurts your eyes, it might be better to lower the brightness of your screen and make sure your room is properly lit because — a dark theme isn’t the solution.

When I first learned about the real arguments for light colour schemes, I couldn’t do anything else but to use them. I’ve got decades to go in front of a screen, and I really need to do all I can to make it as easy as possible for my eyes.

Here’s my challenge: use a light colour scheme for a week, but do it in a properly lit room, and with proper screen brightness. Come back here after a week, and let me know your thoughts.

I know it looks strange the first time you see it, but hear me out for a minute: I am a code folder.

class TwitterSyncCommand extends Command
{
    protected $signature = 'twitter:sync {--clean}';

    /** @var \Illuminate\Database\Eloquent\Collection<Mute> */
    private Collection $mutes;

    public function handle(Twitter $twitter) { /* … */ }

    public function syncFromList(Twitter $twitter): void { /* … */ }

    public function syncFromSearch(Twitter $twitter): void { /* … */ }

    private function storeTweets(array $tweets, TweetFeedType $feedType): void { /* … */ }

    private function shouldBeRejected(Tweet $tweet): ?RejectionReason { /* … */ }
}

I hide most of my code, most of the time. I have keyboard shortcuts to easily show and hide blocks of code; and when I open a file, all method and function bodies are collapsed by default.

The reason? I’m not a superhuman speed reader that understands dozens of lines of code at one glance. And… I also don’t have a two-metre-high screen.

I just can’t read and understand all of this — you know?

class TwitterSyncCommand extends Command
{
    protected $signature = 'twitter:sync {--clean}';

    /** @var \Illuminate\Database\Eloquent\Collection<Mute> */
    private Collection $mutes;

    public function handle(Twitter $twitter)
    {
        $this->mutes = Mute::query()->select('text')->get();

        if ($this->option('clean')) {
            $this->error('Truncating tweets!');

            Tweet::truncate();
        }

        $this->syncFromSearch($twitter);

        $this->syncFromList($twitter);

        $this->info('Done');
    }

    public function syncFromList(Twitter $twitter): void
    {
        do {
            $lastTweet = Tweet::query()
                ->where('feed_type', TweetFeedType::LIST)
                ->orderByDesc('tweet_id')
                ->first();

            $tweets = $twitter->request('lists/statuses.json', 'GET', [
                'list_id' => config('services.twitter.list_id'),
                'since_id' => $lastTweet?->tweet_id,
                'count' => 200,
                'tweet_mode' => 'extended',
            ]);

            $count = count($tweets);

            if ($count === 0) {
                $this->comment('No more new tweets');
            } else {
                $this->comment("Syncing {$count} tweets from list");

                $this->storeTweets($tweets, TweetFeedType::LIST);
            }
        } while ($tweets !== []);
    }

    public function syncFromSearch(Twitter $twitter): void
    {
        do {
            $lastTweet = Tweet::query()
                ->where('feed_type', TweetFeedType::SEARCH)
                ->orderByDesc('tweet_id')
                ->first();

            $tweets = $twitter->request('/search/tweets.json', 'GET', [
                'q' => 'phpstorm',
                'since_id' => $lastTweet?->tweet_id,
                'count' => 200,
                'tweet_mode' => 'extended',
            ])->statuses;

            $count = count($tweets);

            if ($count === 0) {
                $this->comment('No more new tweets');
            } else {
                $this->comment("Syncing {$count} tweets from search");

                $this->storeTweets($tweets, TweetFeedType::SEARCH);
            }
        } while ($tweets !== []);
    }

    private function storeTweets(array $tweets, TweetFeedType $feedType): void
    {
        foreach ($tweets as $tweet) {
            $subject = $tweet->retweeted_status ?? $tweet;

            $tweet = Tweet::updateOrCreate([
                'tweet_id' => $tweet->id,
            ], [
                'state' => TweetState::PENDING,
                'feed_type' => $feedType,
                'text' => $subject->full_text ,
                'user_name' => $subject->user->screen_name,
                'retweeted_by_user_name' => isset($tweet->retweeted_status)
                    /** @phpstan-ignore-next-line  */
                    ? $tweet->user->screen_name
                    : null,
                'created_at' => Carbon::make($subject->created_at),
                'payload' => json_encode($tweet),
            ]);

            if ($reason = $this->shouldBeRejected($tweet)) {
                $tweet->update([
                    'state' => TweetState::REJECTED,
                    'rejection_reason' => $reason->message,
                ]);
            }

            (new ParseTweetText)($tweet);
        }
    }

    private function shouldBeRejected(Tweet $tweet): ?RejectionReason
    {
        if ($tweet->isRetweet() && $tweet->feed_type === TweetFeedType::SEARCH) {
            return RejectionReason::retweetedFromSearch();
        }

        // Reject tweets containing a specific word
        foreach ($this->mutes as $mute) {
            if ($tweet->containsPhrase($mute->text)) {
                return RejectionReason::mute($mute->text);
            }
        }

        // Reject replies
        if ($tweet->getPayload()->in_reply_to_status_id) {
            return RejectionReason::isReply();
        }

        // Reject mentions
        if (str_starts_with($tweet->text, '@')) {
            return RejectionReason::isMention();
        }

        // Reject non-english tweets
        $language = $tweet->getPayload()->lang;

        if ($language !== 'en') {
            return RejectionReason::otherLanguage($language);
        }

        return null;
    }
}

I feel overwhelmed looking at all that code, especially when I’m searching for one specific method.

Now, when I create a new file, it’s all fine, it’s a blank slate, and I’ve got control. But code grows rapidly, and real life projects more often than not include work in existing files instead of blank slates. So I really need a way to reduce cognitive load, I can’t “take it all in at once”. And that’s why I’ve grown to like code folding so much.

Give yourself a week to get used to it. Configure your IDE to automatically fold method bodies and functions, and assign proper key bindings to show and hide blocks. I promise you, you’ll like it.

I'm suspicious of acronyms because there's always someone, somewhere, making compromises to make them work. Whether it is by omitting equally (or more) important elements because they don't fit the acronym; whether less important elements are included to make it work; or whether names are changed, their meaning obfuscated, so that they'd fit perfectly.

Acronyms are of course a great choice to market your ideas because, well, people tend to remember them. SOLID is the perfect example.

I like to think of my code as a book. Not just any book, I think of it as a precious, beautifully designed work of art. Something I want to WANT to read. You know why? Because programming is so much more about reading and understanding code, than it is about writing.

I would say that “writing code” is only the lesser part of my programming life. So naturally, I have much to gain by making the “reading part” as pleasant as possible.

So, let's work from an example:

final class CodeController
{
    public function __construct(private MarkdownConverter $markdown) {}

    public function __invoke(string $slug)
    {
        $code = $this->markdown->convert(file_get_contents(__DIR__ . "/code/{$slug}.md"))->getContent();

        return view('code', [
            'code' => $code,
        ]);
    }
}

First things first, I choose a large font. My brain can only read so many characters per second, so I don’t need to try and fit as much code as possible on screen, at all times.

final class CodeController
{
    public function __construct(private MarkdownConverter $markdown) {}

    public function __invoke(string $slug)
    {
        $code = $this->markdown->convert(file_get_contents(__DIR__ . "/code/{$slug}.md"))->getContent();

        return view('code', [
            'code' => $code,
        ]);
    }
}

I choose a font that’s pleasant to read, modern fonts suit me better than the ones that originated back in the 80s or 90s.

final class CodeController
{
    public function __construct(private MarkdownConverter $markdown) {}

    public function __invoke(string $slug)
    {
        $code = $this->markdown->convert(file_get_contents(__DIR__ . "/code/{$slug}.md"))->getContent();

        return view('code', [
            'code' => $code,
        ]);
    }
}

I increase the line height, because it gives my code some room to breathe, and makes it even easier to read.

final class CodeController
{
    public function __construct(private MarkdownConverter $markdown) {}

    public function __invoke(string $slug)
    {
        $code = $this->markdown->convert(file_get_contents(__DIR__ . "/code/{$slug}.md"))->getContent();

        return view('code', [
            'code' => $code,
        ]);
    }
}

Finally, I make sure that my code isn’t too wide. The less I need to move my eyes from left to right, the easier it is.

final class CodeController
{
    public function __construct(
        private MarkdownConverter $markdown,
    ) {}

    public function __invoke(string $slug)
    {
        $path = file_get_contents(__DIR__ . "/code/{$slug}.md");
        
        $code = $this->markdown
            ->convert($path)
            ->getContent();

        return view('code', [
            'code' => $code,
        ]);
    }
}

Looking at typography guidelines, the maximum advised length is somewhere between 60 and 80 characters. I think somewhere between 80 and 100 works well, because code also includes lots of tabs.

Have you considered typography when programming? Give it a try, it’ll make a lasting impression.

# Levenshtein

"Levenshtein" is the name of an algorithm to determine the difference — aka "distance" — between two strings. The name comes — unsurprisingly — from its inventor: Vladimir Levenshtein.

It's a pretty cool function to determine how similar two related words or phrases are. For example: passing in "PHP is awesome" twice, will result in a "distance" of 0:

levenshtein("PHP is awesome", "PHP is awesome"); // 0

However, passing in two different phrases will result in a larger distance:

levenshtein("Dark colour schemes", "are awesome"); // 13

Unsurprisingly, given how incompatible above two statements are 😉

# Easter dates

PHP has — believe it or not — a built-in function to determine the date of Easter for any given year. Given that Easter's date is determined by "the first Sunday after the full Moon that occurs on or after the spring equinox", I'm in awe of PHP being able to calculate it for me.

Or maybe it simply is hard coded?

date('Y-m-d', easter_date(2023)); // 2023-04-08

# Forks

Did you know PHP can be async? CLI versions of PHP have access to the pcntl functions, including the pcntl_fork function. This function is basically a wrapper for creating process forks, allowing one PHP process to spawn and manage several!

Here's a simple example using sockets to create an async child process in PHP:

function async(Process $process): Process {
    socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $sockets);
    [$parentSocket, $childSocket] = $sockets;

    if (($pid = pcntl_fork()) == 0) {
        socket_close($childSocket);
        socket_write($parentSocket, serialize($process->execute()));
        socket_close($parentSocket);
        exit;
    }

    socket_close($parentSocket);

    return $process
        ->setStartTime(time())
        ->setPid($pid)
        ->setSocket($childSocket);
}

I actually wrote a little package that wraps everything in an easy-to-use API: spatie/async.

# Metaphone?

Similar to levenshtein, methaphone can generate a phonetic representation of a given string:

metaphone("Light color schemes!"); // LFTKLRSXMS
metaphone("Light colour schemes!"); // LFTKLRSXMS

# Built-in DNS

PHP understands DNS, apparently. It has a built-in function called dns_get_record, which does as its name implies: it gets a DNS record.

dns_get_record("stitcher.io");

{
    ["host"] => "stitcher.io"
    ["class"] => "IN"
    ["ttl"] => 539
    ["type"] => "NS"
    ["target"] => "ns1.ichtushosting.com"
}

// …

New in PHP 8.3

# Recursive array merging

I mainly wanted to include array_merge_recursive because, for a long time, I misunderstood what it did. I used to think you'd have to use it for merging multidimensional arrays, but that's not true!

It might be better to let past-me explain it but, in summary, it works like this:

$first = [
    'key' => 'original'
];

$second = [
    'key' => 'override'
];

array_merge_recursive($first, $second);

{
    ["key"] => {
        "original",
        "override",
    }
}

# Mail

PHP has a mail function. A function to send mail. I wouldn't use it, but it's there:

mail(
    string $to,
    string $subject,
    string $message,
    array|string $additional_headers = [],
    string $additional_params = ""
): bool

# DL

Apparently, there's a function in PHP that allows you to dynamically load extensions, while your script is running!

if (! extension_loaded('sqlite')) {
    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        dl('php_sqlite.dll');
    } else {
        dl('sqlite.so');
    }
}

# Blob… I mean glob

glob is a seriously awesome function: it finds pathnames according to a pattern. It's pretty easy to explain, but it's oh so useful:

glob(__DIR__ . '/content/blog/*.md');
glob(__DIR__ . '/content/*/*.md');

{
    /path/to/content/blog/foo.md,
    /path/to/content/other/bar.md,
    …
}

# Sun info

Finally, PHP not only knows about Easter, it also knows about when the sun rises and sets, for any given date! It also requires a longitude and latitude, which of course makes sense because the sunrise and sunset times depend on your location:

date_sun_info(
    timestamp: strtotime('2023-01-27'), 
    latitude: 50.278809, 
    longitude: 4.286095,
)

{
  ["sunrise"] => 1674804140
  ["sunset"] => 1674836923
  ["transit"] => 1674820532
  ["civil_twilight_begin"] => 1674802111
  ["civil_twilight_end"] => 1674838952
  ["nautical_twilight_begin"] => 1674799738
  ["nautical_twilight_end"] => 1674841325
  ["astronomical_twilight_begin"] => 1674797441
  ["astronomical_twilight_end"] => 1674843622
}

What's your favourite PHP function? Let me know on Twitter!

This is a curly bracket, or brace: {.

It’s rarely used as a punctuation mark, but it is one of the most used symbols in programming languages, where they are used to group code and create scopes. It’s also one of the more debated topics when it comes to code styles.

The question is simple: should an opening brace go on a new line or not? You might think: it’s all personal preference; but I would say: it’s not.

Take a look at this code snippet:

public function __construct(string $publicDirectory, string $configurationFile, PageParser $pageParser, PageRenderer $pageRenderer) {
    // ...
}

It’s a constructor that takes a couple of arguments. So what's wrong with this code? Well first of all, you probably have to scroll sideways to read it. That's a bad thing. Scrolling requires an extra interaction with your code. You'll have to consciously search for information about the arguments of this method. That time distracts you from focusing on the application code.

Second, if you're into web development, you probably know that people don't read text, they scan. Usually from left to right and top to bottom. This is especially true for websites, but the same goes for reading code. Putting important information to the right makes it more difficult to find.

In case of this argument list, all arguments are equally important; yet a lot of useful information is pushed to that right, blurry side, where our focus isn’t by default.

So how do we pull useful information more to the left?

public function __construct(string $publicDirectory,
                            string $configurationFile,
                            PageParser $pageParser,
                            PageRenderer $pageRenderer) {
    // ...
}

This could be the first solution you think about. But it doesn't really scale. As soon as you're refactoring a method name, the alignment breaks. Say we want to make this a static constructor instead of a normal one.

public static function create(string $publicDirectory,
                            string $configurationFile,
                            PageParser $pageParser,
                            PageRenderer $pageRenderer) {
    // ...
}

See the alignment breaking?

Another issue is that arguments are still pushed rather far to the right; so let's take a look at another approach.

public function __construct(
    string $publicDirectory, string $configurationFile,
    PageParser $pageParser, PageRenderer $pageRenderer) {
    // ...
}

The advantage here is that our alignment issue is solved. However, how will you decide how many arguments should go on one line? Will you make some styling guidelines about this? How will you enforce them? This example has four arguments, but what if it had three or five?

public function __construct(
    string $publicDirectory, string $configurationFile, 
    string $cachePath, PageParser $pageParser, 
    PageRenderer $pageRenderer) {
    // ...
}

Consistency is key. If we can find a consistent rule, we don't have to think about it anymore. And like I said before, if we don't have to think about it, there's room in our heads for more important things.

So let's continue our search for consistency.

public function __construct(
    string $publicDirectory,
    string $configurationFile,
    PageParser $pageParser,
    PageRenderer $pageRenderer) {
    $this->publicDirectory = rtrim($publicDirectory, '/');
    $this->configurationFile = $configurationFile;
    $this->pageParser = $pageParser;
    $this->pageRenderer = $pageRenderer;
}

By giving each argument its own line, we solve all our problems. But we also created a new one: it's now more difficult to distinguish between the argument list and the method body.

I can illustrate it for you. Let's replace all characters in this code with X's:

XXXXXX XXXXXXXX __XXXXXXXXX(
    XXXXXX XXXXXXXXXXXXXXXX,
    XXXXXX XXXXXXXXXXXXXXXXXX,
    XXXXXXXXXX XXXXXXXXXXX,
    XXXXXXXXXXXX XXXXXXXXXXXXX) {
    XXXXXXXXXXXXXXXXXXXXXX = XXXXXXXXXXXXXXXXXXXXXXXXXXXX;
    XXXXXXXXXXXXXXXXXXXXXXXX = XXXXXXXXXXXXXXXXXX;
    XXXXXXXXXXXXXXXXX = XXXXXXXXXXX;
    XXXXXXXXXXXXXXXXXXX = XXXXXXXXXXXXX;
}

Can you see how difficult it becomes to spot where the argument list ends and the method body starts?

You might say "there's still the curly bracket on the right indicating the end". But that’s not where our focus is! We want to keep the important information to the left. How do we solve it? It turns out there is one true place where to put your curly brackets:

XXXXXX XXXXXXXX __XXXXXXXXX(
    XXXXXX XXXXXXXXXXXXXXXX,
    XXXXXX XXXXXXXXXXXXXXXXXX,
    XXXXXXXXXX XXXXXXXXXXX,
    XXXXXXXXXXXX XXXXXXXXXXXXX
) {
    XXXXXXXXXXXXXXXXXXXXXX = XXXXXXXXXXXXXXXXXXXXXXXXXXXX;
    XXXXXXXXXXXXXXXXXXXXXXXX = XXXXXXXXXXXXXXXXXX;
    XXXXXXXXXXXXXXXXX = XXXXXXXXXXX;
    XXXXXXXXXXXXXXXXXXX = XXXXXXXXXXXXX;
}

On a new line. Placing curly brackets on new lines gives our code space to breathe. It creates a visual boundary between argument lists and method bodies, it helps us to focus on things that matter.

public function __construct(
    string $publicDirectory,
    string $configurationFile,
    PageParser $pageParser,
    PageRenderer $pageRenderer
) {
    $this->publicDirectory = rtrim($publicDirectory, '/');
    $this->configurationFile = $configurationFile;
    $this->pageParser = $pageParser;
    $this->pageRenderer = $pageRenderer;
}

I work on stitcher.io and my newsletters solely in my free time. I used to have a large company sponsoring me for two years, but that partnership has ended. I'm now looking into other ways to get stitcher.io to break even again, and one of the options is to try out GitHub sponsors. If you're a regular reader and if my content helps you, I kindly want to ask you to consider sponsoring me on GitHub.

Finally, if you're a company looking into dedicated ad placements on my blog or newsletters, you can contact me via email.

# Backstory

I've been working on stitcher.io as a hobby project for over five years now, and I've been enjoying it tremendously. In the beginning, stitcher.io was just a static blog that I hosted on a cheap $5 digital ocean droplet (in fact, my previous employer provided it for free, thanks Spatie!).

Over time though, costs began to grow. I got a long-term sponsor contract, meaning I had a couple of hundred euros extra monthly income. It also meant I was now legally required to start a side business in my name, which of course, increased my monthly costs: paying an accountant, social security fees, paying taxes on that newly created income, …

I also started sending out a regular newsletter, meaning I had to upscale my cheap droplet, had to deal with mailing providers, etc. I managed to always break even thanks to that long-term sponsor contract, but I always knew that if they decided to pull the plug, I'd have to search for other solutions. I am still running carbon ads, but honestly, they earn too little to rely on: $50 a month on average.

So here we are: I've got a monthly cost of around 250 euros for hosting, mailing, accounting, and software, which doesn't take into account any yearly or biyearly costs such as social security costs, taxes, domain names, and of course all the time I spend on it.

Now, to be clear: I don't want to turn my blog and newsletters into a profitable business. And I will keep working on it regardless of whether it's making any profit. Though, it would be nice to be able to break even again. I also did consider other ways to finance this project, like, for example, by writing a new book, but I have to admit that my family situation right now (2 kids, a third is on the way) doesn't permit such a time investment in something that I don't know will work.

So, long story short: stitcher.io right now is making a loss, I'm fine with it, but I would like to see it break even. I feel a bit awkward writing about it, but on the other hand: lots of other people do it, so I figured I'd give it a chance. If you benefit from my work and want to help out on a one-time or recurring basis, you can check out my GitHub Sponsors page. If you're a company looking into dedicated ad placements on my blog or newsletters, you can contact me via email.

Thanks!

Do you want to know something dangerous?

Habits.

Not the kind where you practise long and hard to make something a habit. No, I’m talking about the kind where you’ve taught yourself something without noticing. The kind of habit that has been “there” for years, but you can’t remember how it came to be.

I’m not impeccable myself. I have several such habits, and I even have a couple that I know are wrong and should be changed.

For example: I use spaces instead of tabs for indentation.

We could talk about preference all day, but in the end we should ask: what are the rational arguments for tabs and spaces?

For tabs, there’s one big argument: accessibility. First and foremost, the size of a tab is configurable, it doesn’t have to be a fixed width of x spaces. Say there are two visually impaired people working on the same codebase. One person has to use a really large font size, so their tab length should be shorter than the default; and the other one prefers much larger tabs on a very wide monitor so that the difference between nested levels of code is more clear. Just like colour schemes or fonts, each developer can choose what style fits them best.

On top of that: blind people also code. They often use braille displays. These displays show a fixed number of characters, and every space wastes one. Say you’ve got 4 spaces per indentation level, and want to read something that’s nested 3 levels deep; then we’re talking about 12 braille characters being wasted on an already limited display. Compare that to only three when you’d use tabs.

But let’s not jump to early conclusions and look at the rational arguments for using spaces as well: Someone decided it would be the best. That’s it. “Consistency” is often coined as an argument because different editors might show different tab lengths, and some programmers… don’t like that?

A huge part of the programming community — including myself — has gotten used to spaces. Not because there are any good arguments for them, but because it has grown into a habit — a habit so big that popular code styles force users to write spaces, without any good reason.

So maybe we should rethink that habit? I would say that accessibility and writing more inclusive code is a very good argument. But unfortunately, as we all know: breaking habits is hard.

It's a language that has seen an astonishing transformation over the course of almost three decades. Even within the last 10 years, PHP has transformed in ways we couldn't imagine.

Every year, I write a post about the current state of PHP, where I look back and forward. Let's begin!

# The PHP Foundation

I usually start these posts with a summary of the latest PHP version, but this time I want focus on the PHP Foundation first. It's been a little over a year since the foundation was created: a collective of 10 volunteers and 6 developers being paid to work on PHP, the language.

Last year, I wrote this:

I'm a little worried now that Nikita has stepped down. He's definitely not the only person capable of working on PHP's core, but he did a tremendous amount of work these past years with PHP 8.0 and 8.1. I hope the PHP Foundation will be up to speed soon and that there are enough core developers who have time to work on PHP next year. PHP 8.2 is already in development, although there aren't many RFCs drafted yet.

I don't think 2022 will be the most mind blowing year for PHP, but rather a year of adding stability. Nothing wrong with that.

I think it's fair to say that the Foundation has delivered. They recently published their 2022 report, and it shows some pretty impressive numbers:

• In total, $580,000 was raised in 2022
• The Foundation pays 6 developers to work on PHP
• Foundation members made almost half of all commits in php-src
• They created 8 new RFCs, only one of those RFCs didn't make it

I think the Foundation is one of the best things to happen to PHP in a long time, and I hope they'll be able to improve the language even more in 2023. If you're working at a company that uses PHP, I'd highly recommend you consider donating.

# PHP 8.2

Moving on to PHP 8.2. It's generally regarded as a smaller release, but nevertheless it has a bunch of nice features. Just to name a couple:

Readonly classes:

readonly class PostData
{
    public function __construct(
        public string $title,
        public string $author,
        public string $body,
        public DateTimeImmutable $createdAt,
        public PostState $state,
    ) {}
}

A brand new randomizer:

$rng = $is_production
    ? new Random\Engine\Secure()
    : new Random\Engine\Mt19937(1234);
 
$randomizer = new Random\Randomizer($rng);

$randomizer->shuffleString('foobar');

Standalone null, true and false:

function alwaysFalse(): false
{
    return false;
}

Disjunctive normal form types:

function generateSlug((HasTitle&HasId)|null $post) 
{ /* … */ }

Redacted parameters:

function connect(
    string $user,
    #[\SensitiveParameter] string $password
) {
    // …
}

And more.

It's kind of crazy to realise how much PHP has evolved over the years. I made a little video comparison that clearly shows the difference:

# The ecosystem

Just like every year, I should mention Packagist, PHP's package manager: it now lists 361,000 packages; 60,000 more than last year:

One impressive number is the total amount of installations. Last year I mentioned this:

Oh, by the way, just recently Packagist passed the milestone of having handled over more than 50 billion installs. Congrats Packagist!

I just checked, and we're now at 74,492,061,634 installs. That's an increase of 24 billion installs in one year, 2 billion installs per month. All of that to say: the PHP ecosystem is growing a lot.

Twice a year, I publish my version stats post. In these posts, I analyze PHP version usage across the community based on Packagist's data. I wanted to share a graph from that post again: the timeline between 2013 and now, showing the per-version usage history.

While it's great to see PHP 8.* usage rise steeply, there's also a big chunk of people still stuck on older, slow and insecure PHP versions. My hope for 2023 is to see those old version numbers decline even more rapidly. I wrote it like this in my version stats post:

This data beautifully visualizes the division within the PHP community: one part is keeping up with modern PHP, while another one stays helplessly behind.

Speaking of upgrades, I want to mention one tool in particular: Rector. Rector is a free automation tool that helps upgrade your PHP codebase. All it takes is a tiny amount of configuration, and it'll do a huge amount of work for you.

I recently used it to update my community-driven content aggregator, Aggregate to PHP 8.2, and it was really fun and easy to use.

When, after publishing my version stats post, several people told me they hadn't updated yet and were stuck on PHP 7.*, I asked them why. They told me it was simply too much manual work. Interestingly enough, no one had even tried to use tools like Rector to help them…

I firmly believe that a "programming language" is so much more than a compiler: it's the tools and ecosystem that play an equal part in defining that "programming language", and I really think lots of people, projects and businesses would benefit if they looked into using automation tools like Rector.

Since I'm talking about the ecosystem, I can't go without mentioning PHP's two largest frameworks: Laravel and Symfony.

Over the past years, Laravel has grown tremendously. They now employ 8 full time developers to work on the framework and its ecosystem. On top of that, JetBrains' dev survey reports that 67% of PHP developers work with Laravel.

While Symfony as a framework might be less popular compared to Laravel these days, it's still one of the most mature and stable frameworks within the PHP community. It's more often used for enterprise app development, but its standalone components are popular throughout the whole PHP ecosystem — Laravel also has a couple of dependencies on Symfony components. No surprise that more than a handful of Symfony packages make it into Packagist's top package list.

I should also mention WordPress. I'll be honest, I have a love/hate relationship with it. As a user, WordPress is great. It's so easy to install and use, and I think it has earned every bit of its popularity over the years. As a developer though, WordPress makes me sad. The inability to stay up to date with modern and safe PHP versions casts a shadow on the whole PHP community.

Right now, WordPress only has beta support for PHP 8.0. Now, to be clear: PHP 8.0 was released in 2020, and is now end of life, three years later — and WordPress doesn't yet support it…

Of course, there are reasons for not properly supporting newer PHP versions. Up to you to decide whether they are good or not. My personal opinion is that the decision to hold on to backwards compatibility as much as WordPress does is mostly business driven: a big part of WordPress is the commercial part, and a big part of their customer base is running old PHP versions. It's a vicious circle where both parties are holding each other back and, by extent, hold back the PHP community as a whole.

On the other hand, we should recognise the fact that not many software projects are able to stay as popular and relevant as WordPress after almost 20 years, so maybe their strategy about backwards compatibility is the right one?

# Superset

Finally, I can't help but mention my long-term dream for PHP. I write about it, I speak about it, and I hope that one day it'll become true: a superset of PHP, with proper IDE and static analyser support.

There are a bunch of reasons why I want it to happen, you can read and hear about them if you want to; but I really hope it'll become a reality. I doubt we'll get to see a widely accepted and supported superset in 2023, but some baby steps are already being made. I'm definitely keeping a close eye on PXP, which might take things in the right direction.

With all of that being said, I hope that you'll enjoy 2023! And just in case you're new here: I'm Brent, developer advocate at JetBrains, I write and vlog about PHP; and I'd really appreciate it if you checked out the YouTube channel I've been working on lately. Take a look, and maybe consider subscribing? Thanks!

If you're not into videos but still want to follow me, you can join 15k newsletter subscribers instead, I hope to see you there!

As always, it's important to note that I'm working with the data available to us. That means that these charts are not a 100% accurate representation of the PHP community as a whole, but they are an accurate representation of one of the most prominent parts of PHP: the packagist ecosystem.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

# Usage Statistics

Let's start with the percentage of PHP versions being used today, and compare it to the previous three editions, note that I've omitted all versions that don't have more than 1% usage:

Visualizing this data looks like this:

Evolution of version usage

We can see a decent growth for PHP 8.* versions, I think that's great news! It's also great to see PHP 8.0 usage already declining: PHP 8.0 went into security fixes only mode at the end of last year, and I hope to see its usage decline a lot more this year. Keep in mind that PHP 8.0 will reach end of life on November 26, 2023. So it's crucial that projects start preparing to upgrade in the coming months.

PHP 7.4 reached end of life last year, so at the same time it's worrying that more than 25% of projects are still using it! Let's hope to see this number decline soon.

This data beautifully visualizes the division within the PHP community: one part is keeping up with modern PHP, while another one stays helplessly behind. I know there are many reasons to stay behind — often driven by business requirements and constraints — but it's crucial to realise that a lot of PHP projects are in fact running insecure and slow versions in production because of it.

New in PHP 8.3

Moving on to the all-time overview chart, here you can see the evolution of version usage across time:

All time evolution

Like I said: the decline of 7.4 is going too slow to my liking. Compare it to the much steeper decline of PHP 5.5 back in 2015 when PHP 7.0 was released: I would have liked to see the same happen with PHP 7.4 and have people move to PHP 8.0, but unfortunately that's not the case.

I feel like I'm repeating myself every year, but I really hope that people upgrade their projects sooner in the future. I'm curious to learn how this part of the PHP community can be helped. I feel that tools like Rector to automate upgrades have so much potential, if only people started using it.

# Required versions

Next, I used Nikita's popular package analyzer to download the 1000 most popular composer packages. I used a little script to get their minimum required version. Here are the results:

There are two important notes to make here.

1. This tables shows the minimum required version. It makes sense that none of the 1000 packages already supports PHP 8.2, since it's been only here for a month.
2. If you count the numbers, you'll notice there are some differences between each year. Not every package lists a version, so not all 1000 packages can be parsed.

Instead of comparing absolute numbers, it's best to plot this data into a chart for a relative comparison, so that we can see changes over time:

Minimal PHP requirement over time

You can see there's a slight increase in PHP 7.* requirements. It's a good evolution, but still very slow compared to how fast PHP is moving forward.

In my opinion, package authors should push more to require only supported PHP versions. I think it's the only way for PHP to keep moving forward at a decent rate, and for the community to keep up. On top of that: yearly upgrades are much easier to do than to stay on, for example, PHP 7.4 and try to make the jump directly to PHP 8.2.

This blog post was sponsored by Private Packagist - the private Composer repository from the creators and maintainers of Composer & Packagist.

In closing, if you take one thing away from this post, I hope it's that it's time to upgrade to at least PHP 8.1, preferably PHP 8.2. It's not as difficult as you might think, and it's definitely worth your time.

What are your thoughts on these stats? Are you using PHP 8.2? Let me know your thoughts on Twitter and subscribe to my newsletter if you want to be kept up-to-date about these posts!