Laravel does this on purpose, it's all about convention. Consistency is probably the framework's strongest selling point.

When a new feature gets introduced to the framework it tends to feel natural because it follows the same patterns. You don't necessarily have to think about what a method might be called, or where it belongs, or even how it works. It just integrates nicely alongside the rest of your code and behaves in the way you expect.

I think that this same idea can be applied to, and ultimately shape, your application code.

I'll give you an example. Laravel has facades (tl;dr static proxies that resolve their underlying classes from the container) and those facades can be "faked" inside of tests, essentially swapping out the real instance for a testable, mocked one.

There's no reason you can't apply this same pattern to your own service classes.

If your service classes are resolved through the container, they become trivial to replace during tests. Pull out a shared interface or contract, implement that for the real service implementation and then create a "fake" version of the service class that can be used inside of your tests. That fake version could use mocks and provide useful testing helpers, or simply do nothing and be mocked itself.

Go a step further and let your testing code leak into your production code by adding a static fake() method to the real class that just swaps the bound instance in the container.

The benefit isn't just clearer tests, it's consistency. You would use a fake version of a Laravel class in your test, so why shouldn't you use a fake version of your own class?

The same logic can be applied to entry points. Jobs use a handle method, middleware uses a handle method, listeners use a handle method. The convention makes these classes predictable to write.

If you're using the action class pattern, give those classes a handle method instead of an __invoke or execute method so that they align with the rest of the framework. It becomes easy to reason about, easy to swap, and easy to compose with things like pipelines or decorators later on.

The broader idea here is to lean on the same conventions that Laravel has already established.

When your application code follows those patterns, it starts to feel like a part of the framework itself. Other developers don't necessarily need to learn your complex architecture, they can rely on what they already know about Laravel.

This might not be something that you apply to all classes in your application, but when you're introducing a service, action, or subsystem, it's worth considering.

For the longest time that felt like a stable foundation. If you could write good code and build solid software, there would always be a place for you somewhere.

Enter AI.

At first it was tab completions. Little suggestions inside of my editor that gave me a little productivity boost, not too different from a language server providing me with smart and sensible completions for variables and types. Easy to accept with a Tab, easy to ignore with an Esc. It felt incremental.

Then it stopped feeling incremental. Those small suggestions turned into entire functions, entire classes. You soon realise you're not writing every line of code and you're no longer engaging with your code in the same way. You move from construction to curation, spending more time reading, steering and second-guessing.

That's where my unease started. Unease is probably a poor choice of word because the tooling is reliable, often remarkably capable, and almost as good as you (sometimes better to be honest).

My own "anxiety" around AI wasn’t really fear of the technology itself. It was the realisation that something fundamental about the way I work was shifting. I wasn't building things up piece-by-piece in the same way anymore. I was merely an evaluation engine and guidance counsellor for a "clanker".

Once you sit with that for a while, you start to ask the hard questions.

"If this thing can write most of the code, what value do I add?"

"If I'm not the one writing the code for every solution, will I lose touch?"

And perhaps more quitely, "If this keeps improving at the same rate, where does that leave me in X years?".

I didn't really have answers for those questions immediately and that's where the "anxiety" really lingers.

It was only once I had truly integrated these tools into my day-to-day work that I started to see the obvious boundaries and form real answers.

AI generates code, but it doesn't truly understand the intent. It doesn’t always have the context to take a real problem in your system and map it to an outcome. You're the one who bridges that gap. It follows patterns and guidelines that you provide, but it doesn’t own the consequences of those choices. It can suggest a solution, but only to the problem you’ve framed.

That distinction is what matters. The responsibility of software design and software engineering hasn't moved. You're still the one deciding what to build, why it matters, and whether the solution is actually correct. Not just syntactically, but architecturally and contextually.

The AI accelerates your execution, it doesn't replace your brain and your judgment. Once that clicks, those questions start to feel a little less open-ended and existential.

To leave you with a more poetic outro:

Your value as a software engineer isn't in writing every single line of code, it's knowing which lines should exist at all.

I instead use a Bash script to deploy my sites from the terminal. I figured it could be useful for somebody else so here's my script.

#!/usr/bin/env bash

echo "Deploying..."

# You can get this from the "Deployments" page in your site settings.
FORGE_DEPLOY_URL="https://forge.laravel.com/servers/<SERVER_ID>/sites/<SITE_ID>/deploy/http?token=<TOKEN>"
FORGE_DEPLOY_COMMIT=$(git rev-parse HEAD)
FORGE_DEPLOY_MESSAGE=$(git log -1 --pretty=%B | xargs)
FORGE_DEPLOY_AUTHOR="Ryan Chandler"

curl -X POST $FORGE_DEPLOY_URL \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "forge_deploy_commit=${FORGE_DEPLOY_COMMIT}&forge_deploy_author=${FORGE_DEPLOY_AUTHOR}&forge_deploy_message=${FORGE_DEPLOY_MESSAGE}"

echo "Deployment request submitted."

The nice part is that you can still specify the Git details for the deployment!

Testing webhooks locally normally means using the Stripe CLI and that involves a couple of options to make sure it's configured correctly for your Laravel application and also proxying those webhooks to the correct endpoint.

One of the handiest scripts I used whilst working on Forge was a tiny Bash script that configures the Stripe CLI based on your .env file automatically.

#!/usr/bin/env bash

set -euo pipefail

APP_URL="$(awk -F '=' '/^APP_URL/{gsub(/"/, "", $2); print $2}' .env)"
STRIPE_SECRET="$(awk -F '=' '/^STRIPE_SECRET/{gsub(/"/, "", $2); print $2}' .env)"

stripe listen -f "$APP_URL/stripe/webhook" --api-key="$STRIPE_SECRET"

As long as you've got the awk utility on your system, you should be good to add this to your project somewhere and execute it when need be.

chmod +x ./bin/stripe.sh
./stripe.sh

Open source

Just like the last couple of years, the open source side of things has been pretty quiet. I'm still maintaining my packages and keeping them in check.

The biggest thing I worked on open source wise is definitely Phiki 2.0.

It was a complete rewrite of the internals and got everything almost perfect compared to Shiki and vscode-textmate. I'm super happy with how it turned out and glad that PHP developers are able to get super clean syntax highlighting without all of the faff that comes with JavaScript pacakges.

On a slightly more somber note, I archived the PXP project in March 2025. I spoke about how I wanted to revive the project in the last end of year review and that was the intention, but I quickly realised that a project of that size wouldn't be the best thing to work on whilst also pumping out tonnes of cool Forge stuff at Laravel.

Content Creation

Not including this post, I've written 12 blog posts for this site. Another slow year on the blog, but I'm happy with the things I've posted.

I published a few videos too on random bits and bobs, but not as many as I would've liked.

Conferences

I attended a few conferences in 2025.

• Laracon EU (Speaker)
• Laravel Live UK (Sponsor)
• Laracon US
• Laravel Live DK
• wire:live (Speaker)

They were all excellent events. It was my first year as a Laravel employee which allowed me to attend more events than I usually would which I'm super grateful for.

Work

What a year it has been. I started at Laravel in January and immediately dove straight in to work on the next-generation of Forge.

It was great to work with a team of super talented developers, designers, and project managers. The launch went about as well as it could have and we were all super proud of what we had achieved in such a small amount of time.

Looking at 2026

2026 is an interesting year. I've officially moved on from the Forge (core services) team and will be working on Cloud for the foreseeable future.

It's definitely a switch up from Forge and I can't wait to get into all of the nitty-gritty that comes with cloud platforms.

I'm sad to be leaving the Forge team but I absolutely believe that they'll continue to smash it.

I'm also working on a new SaaS product for PHP developers, specifically those of you who want to monetize your work. It's called Privato and will be launching in the next month or so.

You pay a flat monthly fee for the platform, bring your own Stripe account and Privato takes care of the rest. No fees per purchase or anything, a single monthly payment instead.

I'll keep it short this year and let you carry on with your 2026 celebrations.

Happy New Year!

Ryan

I wanted to get some things done on a plane and one of my most visited websites is laravel.com. Despite being a Laravel developer and an engineer at Laravel, there are still things that I have to lookup sometimes: validation rules, collection method names, and more.

So I decided to download the entire Laravel website to my machine so that I could serve it using a local web server. It turns out this is super easy to do with wget.

If you haven't got wget installed already, you can use brew on macOS to install it.

brew install wget

Once you've got it installed you can use the following command to download a copy of a website for offline viewing, including frontend assets and child pages.

wget --mirror --convert-links --adjust-extension --page-requisites --no-parent <url>

I only wanted the latest Laravel docs so I ran the following command:

wget --mirror --convert-links --adjust-extension --page-requisites --no-parent https://laravel.com/docs/12.x

This created a laravel.com directory in the same one as the command was run. You can then serve this directory using a local web server such as php -S localhost:8000.

If you want to wrap this up into a nice little shell command / helper, you can add the following to your .zshrc (or equivalent):

offline-copy() {
    wget --mirror --convert-links --adjust-extension --page-requisites --no-parent "$@"
}

One of the features I added was the ability to test your Turnstile integrations using a fake implementation of the Turnstile client.

it('validates data', function () {
    Turnstile::fake(); [code! focus]
});

Under the hood, the package uses a custom Facade to call methods on the Turnstile client. This facade binds to a ClientInterface implemented by the concrete Client class as well as the FakeClient class.

class Turnstile extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return ClientInterface::class;
    }
}

The concrete Client class is then bound to the ClientInterface through the service container.

$this->app->scoped(ClientInterface::class, static function (Application $app): Client {
    return new Client($app['config']->get('services.turnstile.secret'));
});

The power of the interface here is that it allows us to easily swap out the implementation with a FakeClient class when testing.

To achieve this, I added a fake() method to the Turnstile facade that calls the Facade class's static::swap() method.

class Turnstile extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return ClientInterface::class;
    }

    public static function fake(): FakeClient // [code! focus:start]
    {
        static::swap($fake = new FakeClient);

        return $fake;
    } // [code! focus:end]
}

The swap() method itself does some work under the hood to replace the resolved instance of the facade itself with the provided fake implementation, but also overwrites the binding in the service container so that any subsequent calls to the facade or any bindings to ClientInterface will return the fake implementation.

This allows us to easily stub out the Turnstile methods that are called by the package and provide clean, Laravel-esque APIs for testing.

Turnstile::fake(); // Force pass.
Turnstile::fake()->fail(); // Force fail.
Turnstile::fake()->expired(); // Force expired.

Why not give this a go in your own applications and packages? Future you will thank you for the improved developer experience and reduced boilerplate code!

npm install

npm install installs dependencies listed inside of package.json.

If the version that gets installed is different to the version found inside of your package-lock.json file, then it will update the package-lock.json with the version. This can lead to variations in different environments and unexpected version bumps as part of your changes.

It's flexible, but can be problematic. I'd only recommend using this command when installing a new package in your project.

npm ci

npm ci will install the exact version of a package from the package-lock.json file. This is great as you can guarantee that the version you have installed is the same as your main branch and the rest of your team (assuming they also use npm ci).

If the package-lock.json file is out of sync with the package.json file, the command will fail to run to be certain that it is installing the correct thing.

This command is more deterministic and I'd recommend this when setting up a new project from Git, updating your local environment and checking you've got the right dependencies, or in CI where you normally see a good performance boost compared to npm install.

When to use each

To summarise the above:

• npm install should be used when you want to install or update a package.
• npm ci should be used to install dependencies from scratch, in CI/CD pipelines and for production builds where consistency and determinism is crucial.

I like to keep my tools fairly minimalistic, but consistent. That normally means:

• A light theme
• A nice monospace font
• Breathing room between lines and the window

Ghostty's configuration system is insanely simple, especially compared to iTerm's deeply nested input fields. Here's my config and a screenshot for reference.

theme = GitHub Light Default

font-family = JetBrains Mono
font-size = 14
font-thicken = true
font-feature = -liga

adjust-cell-height = 20 

window-padding-x = 20
window-padding-y = 20

Instead of writing changes directly to the database.sqlite file, they instead get written to a separate log file first. That log file then gets merged into the main file in one go, allowing you to write without blocking reads from the database.

It's really easy to enable this mode in Laravel!

You just need to update the journal_mode configuration value for SQLite databases inside of the database.php config file, setting it to WAL.

return [

    //...
    
    'connections' => [

        'sqlite' => [
            'driver' => 'sqlite',
            'url' => env('DB_URL'),
            'database' => env('DB_DATABASE', database_path('database.sqlite')),
            'prefix' => '',
            'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
            'busy_timeout' => null,
            'journal_mode' => 'WAL',
            'synchronous' => null,
        ],

        // ...

    ],

];

When Laravel creates the SQLite database connection, it will run PRAGMA journal_mode=WAL and all of your database writes will use the separate log file instead.

Early in the software development journey we're often curious – "how does X work?", "why does Y do this specific thing?", etc. Once we start working full-time and spend less time exploring things, that aspect of software development tends to fade away. Building your own software encourages that curiosity, since you have full-control over the journey. You don't need to worry about deadlines, team dynamics, or processes. You can experiment with new languages, frameworks, patterns – whatever it is that you're curious about.

A common argument against building your own software is that reinventing the wheel is bad, that it's a waste of time. Building something that's already been built can be a deliberate way to learn. You'll figure out why things need to work the way they do, what tradeoffs exist, or where performance decisions come into play.

Building your own software also provides a tangible goal, since you're the one setting the expectations. You could build a simple to-do list application or the next Netflix, it doesn't matter. As long as it does what you need it to do, it's a success.

So start small. Build something that solves a problem you have. It doesn't need to be perfect. It doesn't need to be original. The goal isn't to ship the next big thing – it's to learn, explore and grow as a developer.

I have, and it kind of bugs me. It turns out you can add a tiny bit of CSS to your website to prevent this from happening. Better yet? The CSS is actually supported in all major browsers.

html {
    scrollbar-gutter: stable;
}

Here's a comparison between a page navigation with and without this bit of CSS.

Without scrollbar-gutter

Notice how the page shifts to the left when the scrollbar appears? Yuck!

That's caused by the scrollbar creating a fixed-width gutter which the page needs to account for when positioning and rendering.

With scrollbar-gutter

The page no longer entirely shifts to the left to account for the scrollbar's fixed-width gutter. Much better!

(Ignore the navigation shifting around in this example, that's an unrelated issue and poor markup craftsmanship on my part)

If you're not familiar with format!() or print!() macros in Rust, they're essentially the equivalent of PHP's sprintf() and printf(). The main difference between the two languages is that Rust's macros don't inherit the syntax of C's sprintf() where you have placeholders like %s, %d, etc. Instead you use {} as the placeholders and Rust will just convert the values to strings.

Here's an example of what it looks like:

fn main() {
    let name = "Ryan";

    println!("Hello, {}!", name);
}

So I've built a new package for PHP that offers the same sort of syntax – let me introduce you to f. The name f was inspired (read "stolen") from Python, where "f-strings" are used to handle interpolation and inline formatting.

You can install the package using Composer:

composer require ryangjchandler/f

It provides a global f() function that you can use to format a string.

$name = "Ryan";

echo f("Hello, {}!", $name);

That's pretty close, right? Of course, that's a really simple and silly example because you could just use regular interpolation. Here are some comparisons between f() syntax and the equivalent sprintf() syntax provided by PHP.

Referencing positional arguments

f(
    "The {1} contains {0} monkeys. That's a nice {1} full of {0} monkeys.",
    100,
    'zoo',
)

f(
    "The %2$s contains %1$d monkeys. That's a nice %2$s full of %1$d monkeys.",
    100,
    'zoo',
)

Note that F uses 0-based indexing when referencing positional arguments.

Right-justifying text

f(
    "The following number has been padded to a length of 10 – {:0>10}.",
    100,
)

// 0000000100

f(
    "The following number has been padded to a length of 10 – %'010d.",
    100,
)

// 0000000100

The sprintf() syntax here is kind of mystical. '0' is character to pad with, 10 is the length, d is the format specifier.

F's syntax on the otherhand reads slightly nicer in my opinion. Use 0 to right-justify (>) the placeholder to a length of 10.

If you wanted to left-justify the text, you'd flip the operator to < and it would just work. To left-justify with sprintf, you'd need to add a - character.

Escaping placeholders

f("I don't want the \{} placeholder to be formatted.")

f("I don't want the %%s placeholder to be formatted")

\ is the character that we're all used to using for escaping things, so it's natural to use that for F.

F supports a bunch of different placeholder formats. Here's the table of syntaxes at the time of writing this post.

Sign off

Some people prefer string concatenation. Others like using sprintf(). Me? I like the "rusty" syntax.

Check out the code on GitHub and maybe try it out in your next hobby project!

I tried a couple of things and eventually landed on the following:

use Illuminate\Console\Application;
use Symfony\Component\Console\Input\InputOption;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Application::starting(function (Application $application): void {
            $option = new InputOption(
                name: 'example',
                mode: InputOption::VALUE_REQUIRED,
                default: 'foo',
                suggestedValues: ['foo', 'bar', 'baz']
            );
            
            $application->getDefinition()->addOption($option);
        });
    }
}

Now every command that I add to my Laravel Zero application will have the --example option attached to it, allowing me to do things such as load config files from a specified location without needing to do that manually inside of each command, kind of like this:

use Illuminate\Console\Application;
use Symfony\Component\Console\Input\InputOption;
use Illuminate\Console\Events\CommandStarting;
use Illuminate\Support\Facades\Event;
use App\Contracts\UserConfiguration;
use App\Configuration\ProjectConfiguration;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        /*
         * Register the `--config` option with every single command by default.
         * 
         * Default to `./config.json`, but accept a value from the user.
         */
        Application::starting(function (Application $application): void {
            $option = new InputOption(
                name: 'config',
                mode: InputOption::VALUE_REQUIRED,
                default: './config.json',
            );
            
            $application->getDefinition()->addOption($option);
        });

        /*
         * When a command is executed, the framework dispatches a `CommandStarting` event.
         * 
         * The event includes the parsed input (arguments & options), so I can use that to
         * bind an object to the container which can be used & injected outside of the command.
         */
        Event::listen(CommandStarting::class, function (CommandStarting $event) {
            $this->app->instance(
                UserConfiguration::class,
                ProjectConfiguration::parse($event->input->getOption('config'))
            );
        });
    }
}

It's been incredibly rewarding to see the ideas behind the project excite people. I've attended various conferences over the last couple of years and have always had a couple of people ask me about the project, and the answer has always been "I'm working on it, when I've got time."

As much as I enjoy working on PXP, I've reached a point now where it simply doesn't make much sense to continue working on it. I don't have the time to give it the attention it deserves. Software projects, especially ones as ambitious as this, require consistent effort, maintenance and iteration. When you're the only one driving the effort, it becomes hard to give it all of that alongside work and life.

All of that isn't to say that I've lost interest in the ideas behind PXP. Far from it! I still believe in the potential of tools written in languages other than PHP and I'm excited by others working on similar things. There are some fantastic projects out there tackling similar problems – whether it's static analysis tools, language servers, or faster web servers. If you're looking for alternatives, I'd encourage you to check out Mago. Saif was one of the earlier contributors to my original PHP parser project in Rust and had a tonne of impact on the project. They're now working hard on Mago and can dedicate much more time to the project. Odds are I'll probably contribute to Mago myself too in the future!

Ceasing development on PXP wasn't an easy decision to make. Ideas for the project have been looming around in my mind constantly and it's super frustrating not being able to bring said ideas to life.

Who knows – maybe one day, the ideas behind PXP will resurface in another form, whether it's from myself or from likeminded developers. But for now, it's time to call it a day.

Instead of deleting the repository entirely, I've archived it under my personal GitHub account for others to reference if needed. Everything is MIT licensed, so please feel free to use some of the code from the project as long as it adheres to the licensing.

Thank you to everyone who was interested in the project, contributed along the way, and asked how it was going.

– Ryan

The goto statement lets you jump from one part of your code to another. You mark a point in the code with a label and then reference it to jump.

goto syke;
echo "You shall not pass.";

syke:
echo "Passed ya!";

That first echo is never actually executed because the goto statement is jumping over it to the syke label. Forgive me for I have sinned.

Most modern languages either completely omit the goto feature, or strongly recommend against using it. It does still have a few niche uses though.

• Exiting deeply nested loops – instead of numbered break or continue statements, you can add a label and just goto it.
• Code obfuscation – want code that's impossible to read? Drop in a bunch of goto statements and give someone a heavy headache.
• Retry mechanisms – instead of doing things with a while loop, use a goto to jump back to a specific point. This is what Laravel's own retry() helper does internally!

Why you should probably avoid it

The main reason developers shun goto is because it makes code hard to follow. Jumping around your code can turn a simple routine into a tangled spaghetti mess. IDEs and language servers do make it easier with "go to X", but you're still better off avoiding it.

Most problems goto was designed to solve are better handled with functions and loops.

So should you use it?

Unless you're writing a short blog post about it, probably not. Knowing that it exists is useful though! Why not drop it into a PR and impress (or scare) your colleagues?

Here's the problem with complexity. Many developers build solutions for problems they don't have yet. They anticipate scaling issues, edge cases, or future requirements that will likely never materialise. Instead of focusing on solving the problems at hand, they overengineer their systems, adding unnecessary layers that slow down development and introduce unnecessary cognitive overhead.

Abstractions are powerful, but overdoing it tends to make systems harder to understand and maintain. Layers upon layers of interfaces, abstract classes, factory patterns is really just glorified indirection. If a developer needs to dive neck-deep when clicking through classes to find a method implementation or definition, the abstraction has failed.

Something else that causes a lot of problems is "trend-chasing". New frameworks, libraries, and architectural styles appear all of the time. Don't get me wrong, some of them do bring real benefits to the table, but the majority of them are just hype. Adopting a microservices architecture when a monolithic approach would do, or switching to a brand-new JavaScript framework because it's trending on GitHub. You should be choosing the tools that fit your needs (which could be microservices or domain-driven design). You shouldn't be chasing the latest and greatest – give it some to grow – new doesn't always equal better.

Here's my 5 step guide to reducing unnecessary complexity.

1. Keep it simple, stupid (KISS)

Focus on solving today's problem. Don't think about the imaginary ones of the future. The simplest solution that works right now is often the best.

2. You ain't gonna need it (YAGNI)

Don't build unnecessary complexity in the name of flexibility. Adding infinite levels of abstraction for a future use-case that may never come is wasteful. Build what is needed for now and iterate when the requirements change.

3. Optimise for readability

Your code should be easy to understand, not just for you but anyone who has to maintain it. Clear, well-structured and self-explanatory code should save you from those nightmarish debugging sessions.

4. Resist the hype

Choose tools and architectures based on necessity, not popularity. Just because somebody said "X is cool", doesn't mean you should be using X. Prioritize stability and simplicity over following the latest "cool kids" thing.

5. Refactor as you go

Start simple and improve things as you go along. Avoid prematurely optimising or restructuring a system before it's absolutely necessary. Small, incremental improvements over time lead to cleaner, more manageable and easily reviewable code.

Complexity doesn't make your code more sophisticated – it makes it harder to work with.

Open-source

Quite like 2023, I've been quite quiet on the open-source front. I've continued to maintain a few packages and some Filament plugins, but I didn't really do anything too groundbreaking.

The PXP project sat there, dormant, for a few months. Admittedly, I think I was dealing with quite a bit of burnout. Even though I wanted to spend some time working on it, I just didn't have the energy.

It's quite disappointing actually because I had a major breakthrough on how I wanted the project to grow and progress, then BAM, burnout.

As we approach the end of the year though, I'm starting to find some energy and I've started to pick things back up. Having some time away from a project gives you a fresh perspective when you come back to it. At first you forget what's what and then you have a eureka moment and realise that what you were doing isn't the best.

Besides my existing packages and PXP, I did actually spend some time on a problem that I've been wanting to solve for a few years now – syntax highlighting. I've been using Shiki for ages but it always annoyed me how slow it was and how much setup was needed to get it working from PHP. So I really dug into the complexities of TextMate grammars and released Phiki, a syntax highlighter written in PHP that uses TextMate grammars and VSCode themes to produce beautifully highlighted code.

If you read a few of my blog posts, you'll see it in action. The results have been excellent and I've had quite a few people reach out to me with nothing but kind things to say about the project.

Content Creation

Not including this post, I've written 17 blog posts for this site. I used to write about all sorts but much like my open-source work, I've just not had the energy. Still, 17 posts isn't bad.

I also continued working on my Rust for PHP Developers video course. At the time of writing this, there are more than 40 videos published and I've still got a few that need to be edited and published. I'm super thankful to those who purchased the course and waited patiently for me to release the videos. Burnout was the biggest bottleneck, but I'm happy I've managed to get so many videos out for people to enjoy.

In hindsight, I regret doing the pre-order sale. I wanted to make sure that people were interested and that the time spent on the videos could be offset, but it also added a tonne of subconscious pressure. In future, I'll probably just do a typical newsletter thing for seeing if there's any interest.

Conferences

I attended a few conferences in 2024.

• Laracon EU
• Laravel Live UK (Speaker)
• Laracon US

All of them were great. It's always nice to hear people talking about things you're not 100% clued up on, but it's also nice to see people who you might only get to see once a year.

I'm looking forward to attending more conferences in 2025.

Work

Funnily enough, I wrote about burnout in 2023 and how that led to me changing jobs. I was freelancing on top of a full-time job and it was a bit too much.

As we enter 2025, I'm very excited to announce that I'll be leaving my current role and starting a new one at a very special company.

I can't wait to get started. I'll be working with some of the smartest people in the industry and honestly, I think it might be the dream job for a lot of Laravel developers.

Looking forward to 2025

I'm going to continue working on PXP. I've got some ideas that I want to experiment with, mostly aimed towards making it hyper-useful to PHP developers and removing the need to know Rust to help contribute to its success.

I want to continue working on cool things and sharing them online too. Not because there is some magical problem that "thing" is going to fix, but because I want to build something for the sake of building it.

Happy New Year!

Ryan

The front end is all styled with Tailwind so it didn't take too long, thankfully. Add a couple of dark: classes in various Blade templates and it just works. The one issue I did have was with syntax highlighted code blocks.

The light version of the site uses a light theme for syntax highlighting. It's nice and consistent with the rest of the site, so it made sense. When you switch to dark mode though, the last thing you want is your monitor or laptop screen turning into a mini floodlight as you scroll through a blog post.

To combat this I did some work in Phiki and added "multi-theme" support. This means I can syntax highlight a code block with different themes at the same time and then use some CSS to switch between the themes.

Switch between themes using the sun/moon icon button in the header and see the code block theme change!

<?php

namespace App\Console;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    /**
     * Define the application's command schedule.
     */
    protected function schedule(Schedule $schedule): void
    {
        // $schedule->command('inspire')->hourly();
    }

    /**
     * Register the commands for the application.
     */
    protected function commands(): void
    {
        $this->load(__DIR__.'/Commands');

        require base_path('routes/console.php');
    }
}

I was a big fan of this functionality in Shiki, so porting it over made a tonne of sense.

Preface

Syntax highlighting is something that we've all had to add to a site before, probably. Whether it's documentation or our personal sites, figuring out what package or service to use can be a nightmare.

I faced this problem too. Way back when my personal site used Highlight.php, a PHP port of the popular Highlight.js package. Then I tried out Shiki, a JavaScript package that uses VSCode themes and TextMate grammars to highlight code.

Highlight.php was pretty fast but it lacked contextual highlighting which made everything feel really flat. Shiki is a very good package but it's written in JavaScript, so there's a huge overhead when trying to use it from PHP.

I was frustrated with these tools so the only logical thing to do was build my own syntax highlighter in PHP.

Overview

Phiki is a syntax highlighter written in PHP that uses VSCode themes and TextMate grammar files to produce beautifully highlighted snippets of code.

Phiki is really easy to use. Install the package with Composer:

composer require phiki/phiki

And use the Phiki::codeToHtml() method to convert a string of code into a syntax highlighted piece of HTML.

use Phiki\Phiki;
use Phiki\Grammar\Grammar;
use Phiki\Theme\Theme;

$phiki = new Phiki();

echo $phiki->codeToHtml(
    code: "echo 1 + 2;",
    grammar: Grammar::Php,
    theme: Theme::GithubDark,
);

Phiki ships with a bunch of languages and themes out of the box, all of which can be found as members on the Grammar and Theme enums you see above.

Highlighting code for the terminal

If you have a scenario where you need to highlight code for the terminal, you can use the codeToTerminal() method with the same set of parameters to generate a string of text containing ANSI escape sequences for the terminal

echo $phiki->codeToTerminal(
    code: "echo 1 + 2;",
    grammar: Grammar::Php,
    theme: Theme::GithubDark,
);

CommonMark

Highlighting code blocks in Markdown files is probably the most common use case for a syntax highlighter. Phiki ships with a league/commonmark extension so you don't need to do any manual wiring.

use League\CommonMark\CommonMarkConverter;
use Phiki\CommonMark\PhikiExtension;
use Phiki\Theme\Theme;

$converter = new CommonMarkConverter();

$converter->getEnvironment()->addExtension(new PhikiExtension(Theme::GithubDark));

echo $converter->convert(<<<'MD'
    ```php
    echo "Hello, world!";
    ```
MD);

Register the extension, providing a Theme, and it all just works.

Future

I have a small list of things that I want to do before I tag a v1.0.0. Here's the rough list:

Dual themes

When a site has a light and dark mode, having different highlighting themes for each variant is quite a nice feature. It's hard to find one theme that works well for both colour schemes. The API for this would probably be something like this:

$phiki->codeToHtml(
    code: "...",
    grammar: Grammar::Php,
    theme: [
        'light' => Theme::GithubLight,
        'dark' => Theme::GithubDark,
    ],
);

The generated HTML could then use CSS variables to store various style values for each theme and a bit of CSS could be added to the site to change which CSS variables are used.

Transformers

Phiki already has a "transformer" API that lets you modify things at various stages in the highlighting process. This could in theory be used to add things like [!code focus] to focus a particular line in a block of code.

The transformer API is very rugged at the moment though and I'd like to make it as simple to use as possible. Thankfully I can make these sort of breaking changes pre-1.0.

Performance

There are a few places in the code that have sub-optimal performance. Parsing grammars, transforming RegEx patterns, etc. Finding ways to make this more performant is vital as I want Phiki to be the fastest highlighter on the market.

Pitfalls

The current version of Phiki is my 4th attempt at writing a syntax highlighter similar to Shiki in PHP. I've probably spent anywhere from 50 to 100 hours working on the idea and finally getting to a place where it works and is near-perfect, I'd say that's not bad. I've given up plenty of times before.

Despite all of this hard work, Phiki still has a bit of a problem. It's not perfect.

TextMate grammars contains a bunch of regular expressions which determine what tokens are in a file and how they should be highlighted. The TextMate editor, and subsequent vscode-textmate package, both use a RegEx engine called Oniguruma. PHP uses the PCRE2 engine.

Oniguruma is a very good RegEx engine and has support for a bunch of things. Some of those things aren't supported by PCRE2, which is the main reason why Phiki isn't perfect. In all of my testing, the main blocker is support for "variable-length lookbehinds". Here's an example:

(?<=^\S+)=

This pattern is looking for a = character, but will only match if it is preceded by the start of the line and any number of non-whitespace characters. PCRE2 doesn't support this type of lookbehind, mainly because of the performance implications. My understanding is that the architecture and design decisions in PCRE2 would make adding these sort of lookbehinds painful and the performance would be horrible.

Of the 200+ grammars that Phiki currently ships with, only 12 of them are using variable-length lookbehinds. Others were also using them but I managed to patch them out of the grammar files with some simpler and potentially less-accurate RegEx patterns.

What I'm trying to figure out now is the best way to workaround this problem. The way I see it, I've got two choices.

1. Remove these grammars from Phiki and let users add them at their own risk.
2. Write a wrapper around PCRE2 that adds support for variable-length lookbehinds, albeit with a performance penalty.

As a developer who enjoys tackling tough problems, my mind tells me that option 2 is the way to go. Effectively write a RegEx engine in pure PHP, learn some new things and eliminate the problem for good. On the other hand, the amount of time required to build said RegEx engine would be insane and probably not worth it in the long run.

I'd love to know what you think. Let me know on Twitter.

Sign off

Thanks for reading! I'd love it if you gave Phiki a go and provided some feedback on GitHub. There is still a ways to go before tagging v1.0.0, so all feedback is welcome.

One of the things that I added was the ability to embed Blade template code inside of a Markdown file, allowing me to build custom Blade components for blog posts and then add them into the Markdown directly.

I've had a few people ask me how I'm doing this so I thought I'd show you.

Markdown extensions

The league/commonmark package has an extension API that lets you register custom blocks, inline elements, and renderers. the syntax I chose for my Blade extension looks like this:

@blade
    <!-- Put my custom Blade code here. -->
@endblade

This type of extension is a Block extension, since the syntax spans multiple lines. The league/commonmark package uses an AST (abstract syntax tree) to represent the parsed Markdown code before rendering HTML, so we need to tell the package how to parse this custom Blade block.

Writing the parser

Blocks typically span multiple lines and have some sort of opening & closing syntax. In this scenario that's @blade and @endblade. Everything in between that is parsed a literal string and any Markdown is ignored.

The Markdown parser needs to know when a block should start being parsed. This is done by writing a class that implements the BlockStartParserInterface.

use League\CommonMark\Parser\Block\BlockStart;
use League\CommonMark\Parser\Block\BlockStartParserInterface;
use League\CommonMark\Parser\Cursor;
use League\CommonMark\Parser\MarkdownParserStateInterface;

class BladeStartParser implements BlockStartParserInterface
{
    const REGEX = '/^@blade/';

    public function tryStart(Cursor $cursor, MarkdownParserStateInterface $parserState): ?BlockStart
    {
        if ($cursor->isIndented()) {
            return BlockStart::none();
        }

        if (! $cursor->match(self::REGEX)) {
            return BlockStart::none();
        }

        return BlockStart::of(new BladeParser)->at($cursor);
    }
}

The sole responsibility of this class is to determine whether or not the block is present at the current position in the Markdown document. Most blocks will use a regular expression to do this, like the BladeStartParser is.

If that RegEx doesn't match, or if the cursor is indented (not at the start of the line), then there's zero-chance that the block can be found, so it returns early.

If the @blade construct is found, then the parser is told to start parsing the rest of the block using the BladeParser class.

The BladeParser class extends AbstractBlockContinueParser and is responsible for parsing the text until the end of the block is reached.

use App\CommonMark\Block\Blade;
use League\CommonMark\Parser\Block\AbstractBlockContinueParser;
use League\CommonMark\Parser\Cursor;
use League\CommonMark\Parser\Block\BlockContinueParserInterface;
use League\CommonMark\Parser\Block\BlockContinue;
use League\CommonMark\Util\ArrayCollection;

class BladeParser extends AbstractBlockContinueParser
{
    private Blade $block;

    private ArrayCollection $strings;

    public function __construct()
    {
        $this->block = new Blade();
        $this->strings = new ArrayCollection();
    }

    public function getBlock(): Blade
    {
        return $this->block;
    }

    public function addLine(string $line): void
    {
        $this->strings[] = $line;
    }

    public function closeBlock(): void
    {
        $this->block->setContent(
            ltrim(implode("\n", $this->strings->toArray()))
        );
    }

    public function tryContinue(Cursor $cursor, BlockContinueParserInterface $activeBlockParser): ?BlockContinue
    {
        if ($cursor->match('/^@endblade/')) {
            return BlockContinue::finished();
        }

        return BlockContinue::at($cursor);
    }
}

There are a few more things going on inside of this class.

The Markdown parser needs to know which block is being parsed, so a custom Blade block is being stored in a property. There's also another property that stores a list of strings.

AbstractBlockContinueParser implements a method called isContainer() which tells the parser whether or not the block can contain other Markdown elements (headings, blockquotes, etc). The default implementation returns false which is fine in this case because Blade blocks aren't interpreted as Markdown.

Instead of parsing the content of the block as Markdown, the parser will consume each line inside of the block and call the addLine() method with a string containing the lines text. It needs to be collected and stored somewhere so that it can be passed to the Blade compiler later on.

tryContinue() is continuously checking to see if the @endblade marker can be found at the start of a line, indicating whether or not the block is finished.

If it can be found then the parser is told this block is no longer being parsed. Otherwise the parser continues consuming lines.

Once the parser is done parsing the Blade block, the closeBlock() method is called and any lines of text collected are stored inside of the custom Blade block object.

namespace App\CommonMark\Block;

use League\CommonMark\Node\Block\AbstractBlock;

final class Blade extends AbstractBlock
{
    public function __construct(
        private string $content = ''
    ) {}

    public function getContent(): string
    {
        return $this->content;
    }

    public function setContent(string $content): void
    {
        $this->content = $content;
    }
}

Block classes are mostly plain objects that store information about a block. They're not responsible for rendering.

Rendering the Blade template

To actually render a block, we need to write a custom block renderer.

use App\CommonMark\Block\Blade;
use Illuminate\Support\Facades\Blade as Engine;
use League\CommonMark\Node\Node;
use League\CommonMark\Renderer\ChildNodeRendererInterface;
use League\CommonMark\Renderer\NodeRendererInterface;

class BladeRenderer implements NodeRendererInterface
{
    /**
     * @param Blade $node
     */
    public function render(Node $node, ChildNodeRendererInterface $childRenderer)
    {
        Blade::assertInstanceOf($node);

        return Engine::render($node->getContent());
    }
}

This class takes in a Node, in this case the Blade block from before, and returns a string of HTML that represents that block.

The Blade engine provides an API for compiling and rendering a string of Blade through the Blade::render() method (aliased to Engine to avoid collision with the block).

This is how the code between @blade and @endblade is compiled and eventually added to the final HTML output.

Hooking it all up

To actually tell the league/commonmark engine that there's a custom block, we need to register all of the custom classes with the engine.

In my blog, I do this by manually building an Environment object with all of the CommonMark features I need and registering a custom Extension that has my custom blocks and renderers.

$this->app->singleton(MarkdownConverter::class, static function (): MarkdownConverter {
    $environment = new Environment();

    $environment
        ->addExtension(new CommonMarkCoreExtension)
        ->addExtension(new GithubFlavoredMarkdownExtension)
        ->addExtension(new DescriptionListExtension)
        ->addExtension(new PhikiExtension(Theme::GithubDark))
        ->addExtension(new MyExtension);

    return new MarkdownConverter($environment);
});

use App\CommonMark\Block\Blade;
use App\CommonMark\Block\Parser\BladeStartParser;
use App\CommonMark\Block\Renderer\BladeRenderer;
use League\CommonMark\Environment\EnvironmentBuilderInterface;
use League\CommonMark\Extension\ExtensionInterface;

final class MyExtension implements ExtensionInterface
{
    public function register(EnvironmentBuilderInterface $environment): void
    {
        $environment
            ->addBlockStartParser(new BladeStartParser, 80)
            ->addRenderer(Blade::class, new BladeRenderer);
    }
}

This tells the engine how to parse the @blade blocks and how to render the custom Blade block node.

Using in your own apps

Implementing this manually in your own applications is probably a bit too tedious, so I've decided to pull this out into a separate package. I'm already using it on my website!

Install the package with Composer:

composer require ryangjchandler/commonmark-blade-block

Then follow the instructions on the GitHub repository to get it setup.

Sign off

Hopefully this has been insightful. The league/commonmark package is excellent and incredibly extensible – you can basically do anything you want inside of a Markdown file.

Thanks for reading, catch you next time.

The previous iteration of my site was built on top of an old Laravel application from about 4 years ago. It was still running on Laravel 10.x and had a load of old, unreachable code that I wanted to get rid of.

Now I could have gone through the steps to upgrade to Laravel 11.x and removed all of that old code, but I wanted to keep the skeleton up-to-date with the latest changes in Laravel 11.x, so I decided to start from scratch and rebuild the site as a new project.

I'll give you the basics of the new site.

It's running on Laravel 11.x and rendered completely with Blade. There's a hint of Livewire for some interactive components, but it's not on every single page. I'm using Tailwind for the styling and have purposely kept things minimal. Here's a comparison between the old and new home pages.

I found the content being on the right-hand side of a permanent sidebar annoying and the font weights felt wrong, so the new design goes back to a single column layout with everything flowing top-to-bottom.

That's probably enough on general design changes. You can browse the site yourself to see what things look like.

Content Management

All of my posts are written in Markdown. It's mostly CommonMark-flavoured, with a few custom additions.

The previous iteration of my site actually had a Filament panel with a MarkdownEditor where I could manage everything, but I've decided to get rid of it completely. I'm much more comfortable writing Markdown inside of my text editor, so the Filament panel felt pointless.

All of the content is stored on-disk in Markdown files and I use my Orbit package to create Eloquent models from the files. This means that I can fetch content from disk the same way that I would from a regular database.

In terms of custom Markdown features, I've actually only got two right now.

Blade blocks

I've added support for Blade to my Markdown files. This means that I can do the following:

@blade
    <!-- Put my custom Blade code here. -->
@endblade

I purposely chose something that resembles a Blade directive since it doesn't interfere with any other syntax in a Markdown and is easy to spot when scanning a file. I'm actually using this to do the little image grid above.

@blade
<x-typography.image-grid>
    <x-typography.figure :src="Vite::asset('...')" />
    <x-typography.figure :src="Vite::asset('...')" />
</x-typography.image-grid>
@endblade

The benefit to this approach is that I can literally embed anything I want here. I can use Vite to get image paths, build a custom Alpine.js component for a blog post, etc.

Aside blocks

Another custom block that I've added is the "aside" block. This literally generates an aside element where I can place additional content that isn't necessarily required reading for a blog post.

The super cool thing is that on larger screens (Tailwind xl and above), I can place them in the left and right gutter, a bit like the one you should see just to the right of this paragraph.

Here's the syntax for that:

>> This block will float to the right of the page, inside of the gutter.

and if I want one on the left, I just reverse the opening sequence of characters.

<< This one should show up on the left side of the screen.
<<
<< Inline elements are supported, such as **bold**, _italic_ and `code snippets`.

When I want these "aside" blocks to have a little bit of context, I can append the opening sequence of characters with an identifier and use CSS to style the block differently.

>>[danger] This one has a little heading and some special colours.

Syntax Highlighting

In the past I've used Shiki, via the spatie/laravel-markdown package and Torchlight, to perform syntax highlighting on code blocks.

If you're not familiar with Shiki, it's a syntax highlighter written in JavaScript that uses TextMate grammars and Visual Studio Code themes to syntax highlight code snippets. It's the same technology (under the hood) that powers Visual Studio Code itself.

This is a powerful tool because any languages that has VSCode support, out of the box or through an extension, can be highlighted by Shiki. The one downside to Shiki and tools that use it, such as the ones mentioned above, is that you need a way of executing that JavaScript from PHP.

laravel-markdown will shell out to a Node script and return the highlighted code and Torchlight does it all for you on a remote server so you need to call it through an API. This comes with some noticeable overhead, especially when you're writing a blog post and viewing changes live in the browser.

To make this more of a seamless experience, I actually wrote my own syntax highlighter in PHP called Phiki. As you can tell from the name, it's "Shiki for PHP".

It uses TextMate grammars and VSCode themes to syntax highlight code, but does it all with PHP instead of relying on a JavaScript package. This makes it much faster to execute and removes any need for caching or memoization.

The generated, highlighted code is pretty much perfect for most languages. Here's an example of some PHP code highlighted with Phiki.

<?php

namespace App\Console;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    /**
     * Define the application's command schedule.
     */
    protected function schedule(Schedule $schedule): void
    {
        // $schedule->command('inspire')->hourly();
    }

    /**
     * Register the commands for the application.
     */
    protected function commands(): void
    {
        $this->load(__DIR__.'/Commands');

        require base_path('routes/console.php');
    }
}

Phiki adds a data-language attribute to the generated HTML which lets you hook up a "language tag" to your code blocks. That's what you see in the top-right corner of the code block above.

I said that it's perfect for "most languages" and there's a reason for that. Shiki, or more specifically TextMate and vscode-textmate, use the Oniguruma engine to handle RegEx matching. PHP uses the PCRE2 engine and that means there are some compatibility issues with patterns used in TextMate grammars.

Most things can be translated, or "lowered", into PCRE-compatible equivalents. This eliminates quite a few issues and differences between the two engines.

The main problem holding Phiki back right now is the fact that Oniguruma supports "variable-length lookbehinds", but PCRE2 doesn't. The first way to resolve this would be manually patching grammars that use this RegEx feature, but that requires a solid understanding of the grammar itself and intended output. I've done this for quite a few grammars, but it's not the smoothest.

My current idea is building a layer on top of PHP's preg_* functions that implements a very small RegEx engine to handle these incompatible patterns. In 99% of cases, Phiki can use PHP's regular RegEx functions. If it comes across a pattern that throws up a problem then it can defer to the slower, but more powerful, custom RegEx engine.

I'm still reading up on how RegEx engines work, so don't expect to see that fully implemented anytime soon. Do expect some blog posts as I build the engine though, as I think it'll be pretty interesting to read about.

Social images

My old site used a third-party service to generate Open Graph images on-demand. This was overkill and honestly £7 not worth spending, so my new site generates them ahead of time using Puppeteer on my machine.

Here's what they look like:

I just have a single Artisan command that loops through posts and pages, calls out to Puppeteer and then stores the image so I can commit to GitHub and deploy. It's free and actually quite fast.

Sign off

Thanks for reading if you made it this far. I like reading about how websites are built and what happens behind the scenes, hopefully you enjoyed this too.

Personal sites are never fully complete. I treat mine like a playground / testing ground for ideas and that's why I wanted to wipe the slate clean. Give myself a solid foundation for future ideas.

This project is purely for fun – I don't intend to release this as an officially supported tool. If you've read some of my more recent blog posts, you can probably tell I'm in my "programming is fun, right?" phase.

So, the first thing that I need to do is get a command-line application running. The most popular CLI framework in the Rust world is clap, so I'm going to use that because who in this world would want to roll their own argparse in 2024?

Important detail upfront – this project is going to be a monorepo. I'm going to use Cargo's workspace feature which lets me separate out logic into separate packages so I can pull in various bits and pieces when I need them.

[workspace]
members = [
    "crs"
]
resolver = "2"

That's all it takes to create a monorepo of different packages. Nifty!

The crs package is going to be the main binary for the project, so that's where I'm going to start building out the command-line interface.

Installing clap is as simple as running a single command.

cargo add clap --package crs --features derive

The --features flag lets me enable conditionally compiled code from the clap package. In this case, I want to use the fancy wancy #[derive()] macro that it provides to write nice fluent command definitions.

To actually define the arguments, I need to create a struct with some fields and add a single #[derive()] attribute.

use clap::{Parser, Subcommand};

#[derive(Parser)]
struct Arguments {
    #[clap(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    Require(RequireCommand),
}

#[derive(Parser)]
struct RequireCommand {
    package: String,
}

fn main() {
    let args = Arguments::parse();

    match &args.command {
        Command::Require(cmd) => {
            println!("require {}", cmd.package);
        },
    }
}

So now, if I were to run the project in the terminal:

cargo run --package crs -- require hello

I'll get something like this in the output:

$> cargo run --package crs -- require hello
require hello

The magic is all in the #[derive(Parser)] and #[derive(Subcommand)] macros. Rust macros are absolute wizardry.

In this case, those macros are looking at the struct or enum and implementing magical methods that handle parsing the arguments.

That can be seen in the call to Arguments::parse(). That static method is being implemented by #[derive(Parser)].

Cool stuff done. Boring stuff now – code organisation. I don't want to write everything inside of a giant match block.

My personal preference is a new cmd module that exports a function for each command, e.g. cmd/require.rs would look like this.

use crate::RequireCommand;

pub fn require(cmd: &RequireCommand) {

}

This is a nice pattern in my opinion. Keeps the commands in separate files and everything related to a command can be co-located.

There we have it. A basic command-line application in Rust, setup in less than 5 minutes. Not bad!

The next post is going to be focused on making HTTP requests. That's a pretty essential part of building the require command.

In this post, I'm going to explain how composer require works at a very high level and then start to implement the foundations of my own require command.

How Composer requires packages

So what happens when you run composer require? I'm glad you asked!

Let's say you want to install one of my (excellent) packages. You'd run a command similar to this.

composer require ryangjchandler/blade-cache-directive

The first important thing that happens is Composer tries to determine the "requirements" for the package you're attempting to install. This process involves figuring out whether the package actually exists in Composer's package repository, and if it does, which version is best to install in your project,

After it has figured those things out, it sends the necessary information over to an Installer class which handles actually downloading the package from the correct place, as well as installing any dependencies of the package you're trying to install.

That's a somewhat recursive process since dependencies of a package might also have dependencies, so that happens for each package that needs to be downloaded and installed.

Eventually it will have a list of all packages that need to be installed and where the packages need to be downloaded from.

The package files are downloaded (normally as a ZIP or a "tarball"), extracted into the vendor directory, the autoloader is regenerated and any Composer scripts are executed.

Downloading files from a URL in Rust

It's going to take a few more posts before I get into the nitty gritty of installing real packages. I just want to focus on download a file, specifically an archive file, and extracting it into a directory somewhere.

To do this, I'm first going to need an HTTP client. There are many options in the Rust world, but only a few are truly feature complete in my opinion. My personal choice is a package called reqwest.

I'm going to create a new package in the monorepo for this called crs-downloader.

cargo init crs-downloader --lib

To install the reqwest package, I'll also use Cargo.

cargo add reqwest --package crs-downloader --features blocking

I'm not writing asynchronous code, so I want to enable the blocking features which lets me run synchronous HTTP requests. At some point in the future, I'll introduce async stuff, but I'm keeping it simple for now.

This new crate is going to be responsible for downloading a single archive from a given URL, then returning a value that represents where that file has been downloaded to on disk.

I'll start by creating a new struct called Downloader.

use reqwest::blocking::Client;

pub struct Downloader {
    client: Client,
}

impl Downloader {
    pub fn new() -> Result<Self, DownloadError> {
        Ok(Self {
            client: Client::builder().build().map_err(|_| DownloadError::FailedToCreateClient)?,
        })
    }
}

#[derive(Debug, Clone)]
pub enum DownloadError {
    FailedToCreateClient,
}

The only piece of state that the Downloader has is an HTTP client. Instead of creating a new Client for each request, I can just make a single one and everything will be a little bit faster.

Cool, so how can something be downloaded from a given URL? I'll need a method, say download. That will take a single parameter url.

An HTTP request needs to be made to that url, then the data that is returned needs to be written to a specific place on the disk. I'm going to store things in a temporary directory so that it doesn't clutter a user directory.

Making that HTTP request is very simple with reqwest.

impl Downloader {
    // ...

    pub fn download(&self, url: &str) -> Result<DownloadedFile, DownloadError> {
        let response = match self.client.get(url).send() {
            Ok(response) => response,
            Err(_) => return Err(DownloadError::FailedToDownloadFile(url.to_string())),
        };

        todo!()
    }
}

Using the Client on the Downloader, I can make a GET request to the url and grab the response.

The .send() method returns a Result, meaning a value or an error. If something goes wrong during the request, I can return a simple DownloadError. There's no information in here apart from the url that was being requested – again, keeping things simple for now.

To store the downloaded data on disk I need to store it inside of a folder somewhere. Rust has a standard function for finding the "temporary directory" of a machine, but I want some more helpers. I'm going to use the tempfile package to help me a little.

cargo add tempfile --package crs-downloader

This package provides a TempDir type that will create a temporary directory, and upon destruction of the TempDir value, delete that folder from the disk. This means the value needs to be "owned" by something. I'll opt to store it inside of the Downloader.

pub struct Downloader {
    client: Client,
    tempdir: TempDir,
}

impl Downloader {
    pub fn new() -> Result<Self, DownloadError> {
        Ok(Self {
            client: Client::builder().build().map_err(|_| DownloadError::FailedToCreateClient)?,
            tempdir: TempDir::new().map_err(|_| DownloadError::FailedToCreateTemporaryDirectory)?,
        })
    }
}

As long as the Downloader is kept "alive" in the application, the files that are downloaded will be available on disk.

Taking the data from the response and storing it inside of a file is pretty straightforward too.

impl Downloader {
    // ...

    pub fn download(&self, url: &str) -> Result<DownloadedFile, DownloadError> {
        // ...

        let path = self.tempdir.path().join(
            slugify_url(url)
        );

        let mut file = File::create(&path).map_err(|_| DownloadError::FailedToCreateDestinationFile(path.to_string_lossy().to_string()))?;
        let text = response.text().map_err(|_| DownloadError::FailedToReadBytesFromResponse(url.to_string()))?;

        copy(&mut text.as_bytes(), &mut file)
            .map_err(|_| DownloadError::FailedToCopyBytesToFile(url.to_string(), path.to_string_lossy().to_string()))?;

        Ok(DownloadedFile { path })
    }
}

The code looks kind of crowded, but there's manual error-handling going on all over the place. I could introduce some casting magic, but I'm keeping things simple.

I've written all of this code without any tests so far. Now for rapid development, that's maybe not a bad thing, but I do want to make sure that this actually works.

#[cfg(test)]
mod tests {
    use super::Downloader;

    #[test]
    fn it_can_download_a_file() {
        let downloader = Downloader::new().unwrap();
        let downloaded_file = downloader.download("https://www.rust-lang.org/logos/rust-logo-512x512.png").unwrap();

        assert!(downloaded_file.path.exists());
    }
}

This is a very simple test to make sure that the downloader can actually download a file. Hardcoding a URL feels like it might cause issues in the future if that URL goes missing, but it'll do for now.

I also want a test that ensures the temporary directory and the files are tidied up too.

#[test]
fn it_tidies_up_after_itself() {
    let downloader = Downloader::new().unwrap();
    let downloaded_file = downloader.download("https://www.rust-lang.org/logos/rust-logo-512x512.png").unwrap();

    assert!(downloaded_file.path.exists());

    drop(downloader);
    
    assert!(!downloaded_file.path.exists());
}

running 2 tests
test tests::it_can_download_a_file ... ok
test tests::it_tidies_up_after_itself ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.14s

Perfect! Both tests are passing and I can now download files and store them somewhere on disk.

In the next part of the series I'll start implementing the actual package resolving stuff. That will include using the real Packagist API to grab information about a package, where it can be downloaded and more.

This post is going to focus on interacting with the Packagist API to retrieve information about a given package.

To grab information about a package from Packagist, you can use a public API endpoint as below.

https://repo.packagist.org/p2/ryangjchandler/blade-cache-directive.json

This returns some minified JSON that contains information about the Composer package. Things like the name, require, autoload, etc.

In order to grab this information from the project, I need to make an HTTP request to the endpoint. Like the previous episodes, I'm going to abstract this out into a new package in the workspace. I'm also going to add the reqwest package to I can make HTTP requests.

cargo init crs-package-metadata --lib
cargo add reqwest --package crs-package-metadata --features blocking

Serialising and deserialising JSON in Rust is fairly straightforward. There's a package called serde that lets you use macros on various structures that represent the structure of the JSON.

cargo add serde --package crs-package-metadata --features derive
cargo add serde_json --package crs-package-metadata

This lets me write a struct to represent the information returned from the Packagist API and deserialise a string of JSON into an instance of the struct.

The actual structure of the JSON is something like this:

{
    "packages": {
        "[vendor]/[package]": [
            {
                "name": "[vendor]/[package]",
                "description": "[description]",
                "version": "[version1]",
                // ...
            },
            {
                "version": "[version2]",
                // ...
            }
            // ...
        ]
    },
    "minified": "composer/2.0"
}

I don't care about the minified key, since I know it's being minified. The packages key contains a single object with a single key (the name of the package). That key contains an array of objects that hold all of the information for a set of versions of the package.

The JSON is minified, which means that any keys that are common between the various versions of a package are omitted. Composer themselves have a package composer/metadata-minifier that can be used in PHP to expand the minified versions, but since I'm writing Rust, I don't have the luxury of using existing code.

That's not a big problem right now since I don't need all of that information. I only care about the following things:

• The source of a version.
• The distributable artefacts (dist).
• The raw version of the package.
• The version_normalized field.

#[derive(Debug, Deserialize)]
pub struct PackageMetadata {
    versions: Vec<PackageVersionMetadata>,
}

#[derive(Debug, Deserialize)]
pub struct PackageVersionMetadata {
    version: String,
    version_normalized: String,
    dist: PackageDistMetadata,
    source: PackageSourceMetadata,
}

#[derive(Debug, Deserialize)]
pub struct PackageDistMetadata {
    url: String,
    r#type: String,
    shasum: String,
    reference: String,
}

#[derive(Debug, Deserialize)]
pub struct PackageSourceMetadata {
    url: String,
    r#type: String,
    reference: String
}

With the rough structure defined, I can start to write the deserialisation logic.

impl PackageMetadata {
    pub fn for_package(package: &str) -> Result<Self, PackageMetadataError> {
        let url = format!("https://repo.packagist.org/p2/{package}.json");
        let response = get(&url).map_err(|_| PackageMetadataError::FailedToFetchPackageMetadata(package.to_string()))?;

        // If the package was not found, return an error.
        if response.status() == StatusCode::NOT_FOUND {
            return Err(PackageMetadataError::PackageNotFound(package.to_string()));
        }

        // Grab the raw JSON from the response.
        let json = response.text().map_err(|_| PackageMetadataError::FailedToReadPackageMetadata(package.to_string()))?;

        // Convert the raw JSON into an untyped JSON value.
        let metadata: Value = serde_json::from_str(&json).map_err(|_| PackageMetadataError::FailedToParsePackageMetadata(package.to_string()))?;
        let versions = metadata["packages"][package].clone();

        Ok(PackageMetadata {
            versions: serde_json::from_value(versions).map_err(|_| PackageMetadataError::FailedToParsePackageMetadata(package.to_string()))?
        })
    }
}

The serde_json API is really nice I think. Rust has support for operator overloading through the trait system, so you can access keys inside of an object in a similar way to JavaScript.

The code above does a bit of manual handling to grab the array of version objects. Since the serde macros rely on things being defined at compile-time, you have to do some trickery to make it read from nested keys that have variable names. In this case, that would be the package name being used as the key.

It's not impossible to do, but I find it much nicer to take the explicit route of grabbing that value from the JSON manually and then deserialising it further into the typed PackageVersionMetadata instances.

Time to write some tests. Thankfully, I know for a fact that at least one of my packages will be available at this endpoint. So I can use that as my test case.

#[cfg(test)]
mod tests {
    use super::PackageMetadata;

    #[test]
    fn it_can_fetch_metadata_for_a_package() {
        let metadata_result = PackageMetadata::for_package("ryangjchandler/blade-cache-directive");

        assert!(metadata_result.is_ok());

        let metadata = metadata_result.unwrap();

        assert!(!metadata.versions.is_empty());
        assert!(metadata.versions.iter().any(|version| version.version == "v1.0.0".to_string()));
    }

    #[test]
    fn it_returns_an_error_when_a_package_is_not_found() {
        let metadata = PackageMetadata::for_package("ryangjchandler/this-package-does-not-exist");

        assert!(metadata.is_err());
    }
}

More progress. Nice.

The next post in the series is going to focus on parsing out semantic version strings into nice little VersionConstraint values that will let me easily test a specific version against a constraint.

Until next time.

• You choose a Blade template to render.
• The engine uses a series of regular expressions to parse and compile the template.
• The engine produces a plain PHP file and writes it to disk (so that it's cached for future renders).
• The PHP file is included and output buffers are used to capture the generated HTML.

The most interesting step in the process is that RegEx patterns are used to extract various things from the template and generate the appropriate PHP code. Other template engines use a more traditional tokeniser and parser to process templates, but since Blade is more or less just syntax sugar over regular PHP code, it can do things in a much simpler manner.

What this does mean is that you're basically always dealing with arbitrary strings that might contain plain ol' PHP code.

Custom Directives

It's possible to write your own Blade directives. This lets you hide a lot of boilerplate code inside of a directive and simplify your Blade templates.

Blade::directive('example', function (string $expression) {
    // Logic goes here.
});

Something that catches a lot of new Laravel developers out is the fact that custom directives only receive a single argument to the callback function.

Let's say our the @example() directive here is designed to accept 2 arguments:

@example('Hello, ', 'Ryan')

A less-experienced Laravel developer might expect the callback function to receive two arguments, corresponding to the two arguments we passed through to the actual directive.

That's not the case though. Instead, we receive a string containing the literal text from the Blade template.

Blade::directive('example', function (string $expression) {
    assert($expression === "'Hello, ', 'Ryan'");
});

So instead of writing regular PHP code inside of the callback and returning a value, we actually instead want to return a string of PHP code. That PHP code will then be inserted into the generated template in place of the original directive.

Blade::directive("example", function (string $expression) {
    return "<?php echo implode(' ', [{$expression}]); ?>";
});

There are packages out there that extend Laravel to support the more logical "receive the real arguments inside of the callback" approach, but the fact that we have a string here means we can do some fun and creative things.

Named arguments

Custom Blade directives quite often provide a wrapper around a regular PHP function. PHP 8.0 introduced the concept of "named arguments", allowing you to pass arguments to a function out-of-order and instead provide the name of the argument instead.

function hello(string $name, string $greeting = "Hello, ")
{
    return $greeting . $name;
}

hello(greeting: "Greetings, ", name: "Ryan");

If we wrap this hello() function inside of a Blade directive, we can actually still use named arguments!

Blade::directive("hello", function (string $expression) {
    return "<?php echo hello({$expression}); ?>";
});

@hello(greeting: "Greetings,", name: "Ryan")

Since the text between the parentheses is just being inserted inside of our expression, the named arguments are passed along verbatim to the underlying hello() function.

Pretty cool!

Magic Variables

Most Laravel developers have probably used "magic variables" in their projects before. The two most common examples are probably the $loop variable available inside of @foreach blocks, and the $message variable inside of an @error block.

Laravel ships with an @auth directive that lets you conditionally do stuff based on whether a user is logged in or not. This is cool, but I want to ship my own @auth directive that injects the current user into the block of code as a $user variable.

Fun fact – you can actually override Laravel's own directives with custom ones, since the Blade compiler checks for custom ones first. I don't recommend doing this though – all of this code is purely for educational and demonstration purposes!

Blade::directive("auth", function (string $expression) {
    $guard = $expression ?: "()";

    return "<?php if (auth()->guard{$guard}->check()): ?>" .
        '<?php $user = auth()->user(); ?>';
});

Blade::directive("endauth", function () {
    return '<?php unset($user); ?>' . "<?php endif; ?>";
});

The code above returns multiple statements for each directive. Starting and ending the if block, and also creating and unsetting the magical $user variable.

This code isn't 100% sound, please do not do this in your own apps.

The fact that we can compile directives into any arbitrary PHP code opens up some cool opportunities for things. I've even developed a couple of packages that take advantage of this for caching blocks of Blade code and even creating inline partials!

• blade-cache-directive
• blade-capture-directive

Domain Specific Languages

Another way that we can take advantage of the stringy nature of Blade directives is by writing our own domain-specific languages inside of a Blade directive.

Lots of server-side template engines have the concept of "filters". Here's an example from Twig:

{{ names | join(',') | lower }}

So names is a variable that gets passed to the join() function. The output of join(',') is then sent through to lower and the result of that operation is then output in the template.

What if we wanted to do the same but in a Blade directive, perhaps something like this:

@filter($names | join(',') | lower)

The first step is going to be parsing out the stuff inside of the directive. To get all of the different filters and the variable, we can split the expression by the | tokens, removing any excess whitespace around each part.

$parts = array_map(trim(...), explode("|", $expression));

To keep things simple, we'll assume that the first part is always a valid PHP expression.

$subject = $parts[0];
$filters = array_slice($parts, 1);

Each of the filters will map to a Closure that accepts the current value of $subject, as well as any arguments we pass to the filter. We'll need somewhere to store those callback functions.

Warning: The code you're about to see contains magic.

class Filters
{
    protected array $filters = [];

    public function __construct(protected mixed $subject)
    {
        $this->addFilter("join", function (array $subject, string $glue = "") {
            return implode($glue, $subject);
        });

        $this->addFilter("lower", function (string $subject) {
            return strtolower($subject);
        });
    }

    public function addFilter(string $name, Closure $callback): void
    {
        $this->filters[$name] = $callback;
    }

    public function get(): mixed
    {
        return $this->subject;
    }

    public function __call(string $name, array $args)
    {
        if (!isset($this->filters[$name])) {
            throw new Exception("Unrecognised filter [{$name}].");
        }

        $this->subject = $this->filters[$name]($this->subject, ...$args);

        return $this;
    }

    public function __get(string $name)
    {
        return $this->{$name}();
    }
}

Each filter is registered with the class upon instantiation. To actually invoke a filter, you either call a non-existent method on the class or access a non-existent property.

The Blade directive then needs to translate the string of filters into a series of method calls on a Filters object.

return sprintf(
        <<<'PHP'
<?php echo (new \App\Filters(%s))
    ->%s
    ->get(); ?>
PHP
    ,
    $subject,
    implode("\n    ->", $filters)
);

The $subject is passed to the constructor, then each of the filters is chained onto the object as a method or property. That triggers the __call() or __get() method on the object which runs the filter over $subject.

Then at the very end, the ->get() method is called to retrieve the final value and output in the rendered template.

I warned you, here lies magic.

So the Blade example above would be converted into something like this:

echo (new \App\Filters($names))
    ->join(',')
    ->lower
    ->get();

Passing ['Ryan', 'Jane', 'John'] through this set of filters would produce ryan,jane,john.

This is some seriously weird and wacky stuff – something you'll probably never want to use in a real application – but it's cool to mess around with regardless.

Perhaps you'll take some of these ideas away and build some cool Blade directives of your own for fun and magical purposes.

For those of you who don't know, SQLite is like a dynamically-typed language. There's no restrictions on what you can and can't store inside of a column.

That means if you have a INTEGER column in your database table, there's nothing stopping you from storing a string inside of it.

That is where strict tables come into play. You can enable "strict mode" when creating your table by appending the strict keyword to the table definition.

CREATE TABLE users (
  id      INTEGER PRIMARY KEY,
  name    TEXT,
  email   TEXT,
  age     REAL
) strict;

Now any inserts will be type checked, preventing invalid types of data being inserted into your columns.

.import

Ever needed to import a CSV file into your database but didn't want to bother writing an import script to do it? SQLite has got you covered!

If you open your database in the SQLite command-line interface, you can use the .import command to import a CSV file directly into a database table.

.import --csv /Users/ryan/Downloads/users.csv users

This will import the users.csv file into the users table.

Extensions

Lots of database engines have some sort of extension API that lets you add new functionality to the database without hand-rolling stuff.

SQLite is no exception to this. All you need to do is find the extension you want to use and download the object file for your operating system.

If you don't want to mess around with downloading files, there's an excellent package manager called sqlpkg that takes care of the boring stuff: https://github.com/nalgeon/sqlpkg-cli.

If you're using the command-line interface for SQLite, you can load the extension using the .load command.

.load /Users/ryan/Downloads/uuid
select uuid4();

If you want to find an extension to do something, try searching through sqlpkg.org!

Bytecode!?

Most SQL engines convert your SQL statements into some sort of internal representation. It's normally a tree of nodes that describe what you're doing and the SQL engine uses the tree to perform operations.

SQLite is actually different in this regard. Instead of using a tree to process your statements, it instead converts everything into a flatter sequence of instructions, bytecodes.

This is very similar to how interpreted programming languages like PHP, JavaScript, Ruby etc are executed.

You can inspect the bytecode that is generated by prepending EXPLAIN to your SQL statements in the command-line interface!

explain select * from users;

addr  opcode         p1    p2    p3    p4             p5  comment
----  -------------  ----  ----  ----  -------------  --  -------------
0     Init           0     8     0                    0   Start at 8
1     OpenRead       0     2     0     2              0   root=2 iDb=0; users
2     Rewind         0     7     0                    0
3       Rowid          0     1     0                    0   r[1]=users.rowid
4       Column         0     1     2                    0   r[2]= cursor 0 column 1
5       ResultRow      1     2     0                    0   output=r[1..2]
6     Next           0     3     0                    1
7     Halt           0     0     0                    0
8     Transaction    0     0     1     0              1   usesStmtJournal=0
9     Goto           0     1     0                    0

But here's something that has always bothered me – adding a new font to an existing <link /> tag. You either need to reselect your existing fonts in Bunny's web interface or merge the two generated URLs manually.

So I've built a new package for Laravel to solve this problem and make things a whole lot simpler.

GitHub: https://github.com/ryangjchandler/laravel-bunny-fonts

You can install the package via Composer:

composer require ryangjchandler/laravel-bunny-fonts

After installing the package, you have access to a nice "builder" API for registering your Bunny Fonts and rendering the necessary HTML tags.

Inside of a ServiceProvider, you can do the following:

use RyanChandler\BunnyFonts\Facades\BunnyFonts;
use RyanChandler\BunnyFonts\FontFamily;

BunnyFonts::add(FontFamily::Inter, [400, 500, 700]);

Then inside of a Blade template, you can use a Blade component or directive to render the relevant HTML.

<x-bunny-fonts />
<!-- or -->
@bunnyFonts()

Sets

I sometimes use different fonts in different places within the same Laravel application. Instead of loading all of the fonts all of the time, you can create different "font sets".

BunnyFonts::set('shop')
    ->add(FontFamily::Inter, [400, 500, 700]);

Then inside of the relevant Blade template:

<x-bunny-fonts set="shop" />
<!-- or -->
@bunnyFonts('shop')

Fun stuff

You might have noticed a FontFamily enumeration being used in the example above. This is an enum provided by the package.

Don't worry, I didn't sit there and write out all of the font families supported by Bunny. The code is actually generated ahead of time using a small script inside of the package and some data from Bunny Fonts.

If you're interested in the code, you can find it here.

The problem is Composer has a default execution timeout of 30 seconds, so when I've got a long-running process like a queue worker running from a Composer script, it times out after 30 seconds.

Thankfully, there is a way to disable the timeout on a script-by-script basis.

{
    "scripts": {
        "queue": [
            "Composer\\Config::disableProcessTimeout",
            "php artisan queue:work"
        ]
    }
}

All you need to do is turn the script into a multi-step one and add Composer\\Config::disableProcessTimeout at start of the list. Composer's default 30 second timeout will be disabled for the rest of the steps.

One of those features in Rust's powerful enumerations (enums). Yes, we have had enums in PHP since PHP 8.1, but they are more or less just glorified class constants. The only two real benefits they provide over class constants is the ability to use the name of the enum as a type and attach methods to an enum.

Rust's enums on the other hand are much more than just constants. I'd like to dig into them a little bit in this post and show you all the cool things you can do with them.

Syntax

We'll start off with the syntax. They look very similar to PHP's enums and many other languages.

enum Role {
	Superadmin,
	Admin,
	Editor,
	User
}

The only real difference here is the lack of an explicit case statement like we have in PHP.

If we want to add methods to our Role enum, we can do so using an implementation (impl) block.

impl Role {
	pub fn is_admin(&self) -> bool {
		matches!(self, Role::Admin)
	}
}

This impl syntax isn't specifically for enums – methods on structs are also written in this way.

Cool, but this is pretty basic right? There's nothing special here, it's just a plain ol' enumeration with some methods.

You're right – so let me introduce you to the magic.

Tagged Unions 101

Tagged unions, as a concept, have been around since the 1960s. Before we look at Rust's tagged unions, it's probably useful to understand what a regular union is. We'll use C as our example language.

In C, you can define a union. A union has many different fields, but the catch is that only one of those fields can be "filled" at any one time.

union Data {
	int i;
	float f;
	char str[255];
} data;

So if the Data.i field has a value, it means that Data.f and Data.str must be empty. Unions are also stored in a single memory location and the memory itself will always be big enough to store the largest field / member of the union.

Fun fact – PHP's interpreter uses a union to define the internal representation of all PHP values. It's known as a ZVal.

A tagged union is made up of two things – a tag, and a union. If we were to define one in C, we might do something like this:

typedef enum ValueType { Int, Float, String } ValueType;

typedef struct Value {
	Tag tag;
	union Data {
		int i;
		float f;
		char str[255];
	} value;
} Value;

When we construct a value, we "tag" it using one of the ValueType cases, then assign some data to one of the union fields based on the tag.

Tagged unions in languages like C and C++ aren't really considered "safe". The union isn't strictly related to the tag, so there's nothing stopping us from having a value tagged as Int and trying to access the String field.

This is where Rust takes things a step further.

Tagged Unions in Rust

Rust extends on its basic enumerations by allowing us to define fields as part of the enum member directly. Let's recreate that Value tagged union.

enum Value {
	Int(i64),
	Float(f64),
	Str(String),
}

This is known as a "tuple variant" or "tuple member". Each of our enum members / cases would be the "tag", and the values inside of those members would be part of the union.

Constructing / instantiating one of these members would then allow us to pass in a value for the field.

let int_value = Value::Int(100);

The super-safety aspects start to show when you want to access a field. The only way to access a field is by destructuring and pattern matching the value.

match int_value {
	Value::Int(value) => dbg!(value),
	_ => todo!(),
}

Tuple variants are just one of the syntaxes that we can use. We can also use the "struct variant" syntax.

enum AstNode {
	Print {
		value: AstNode,
	},
	Add {
		left: AstNode,
		right: AstNode,
	}
}

So instead of having nameless values inside of our members, we can instead give them appropriate names. This is useful if you've got more than one value in a member.

The same rules apply when we want to access a value inside of the member.

match node {
	AstNode::Print { value } => dbg!(value),
	AstNode::Add { left, right } => dbg!(left, right),
}

Usage in Rust

Rust leans heavily on tagged unions in the core of the language. There are two prime examples of this – the Option and Result types.

enum Option<T> {
	Some(T),
	None,
}

enum Result<T, E> {
	Ok(T),
	Err(E),
}

These are almost perfect usecases for tagged unions – since both enums can only have two possible members, but you can also use generics to change the type of the value stored inside of the them.

I sometimes forget the methods I need to call to make this work though, so here is a little code snippet for future me and anyone else who happens to come across this on the internet.

$request->file('upload')->storeAs('uploads', $request->file('upload')->getClientOriginalName())

function random(items) {
	return items[Math.floor(Math.random() * items.length)]
}

How it works

Math.random() generates a random float between 0 and 1. The generated float is always less than 1, so when we multiply it by the length of the array, it's always going to be less than items.length.

Since the result of this operation is a floating-point number and arrays are integer-based, we can use Math.floor() to round that number down.

This approach guarantees that the generated index is always in the range 0..items.length and will never produce an invalid index.

They were initially introduced by the predecessor to Google Analytics named "Urchin", hence the name. Since their introduction, near enough all analytics software provides support for breaking down traffic results by these tags.

As somebody who has only recently started learning more about SEO and improving my analysis of web traffic, I thought it might be useful for others to breakdown each of the "tags" and how they're intended to be used.

There are 5 main UTM tags available:

• utm_source
• utm_medium
• utm_campaign
• utm_content
• utm_term

Let's take a look at each of them and how they're supposed to be used.

Source

The utm_source tag is used to determine which site or origin provided the traffic. If you post a link on Twitter, you might set the tag to twitter and then use this to breakdown conversions inside of your analytics tool.

Medium

The purpose of the utm_medium tag is to distinguish between the generic type of marketing medium, e.g. social media, email, affiliates, etc.

This tag allows you to analyse traffic as a broader level – rather than looking at specific social media sites, you can instead see how much traffic originates from all social media sites.

Campaign

The utm_campaign tag lets you give distinct names to each of your marketing pushes & campaigns, so that you can compare performance across multiple campaigns.

For example, you might run a marketing campaign and realise that email marketing is performing badly (using the utm_medium and utm_source tags). After making some changes to your marketing material, you want to re-market the same URLs and compare their performance.

If you give each campaign a different utm_campaign source, you can do the comparison and reporting quite easily inside of most mainstream analytics tools.

Content

If you have multiple CTAs on a single page, you can use the utm_content tag to describe which CTA or link was used.

For example you have 2 "Buy" buttons on a page – one of them is green, one of them is black. If you add utm_content=green-buy and utm_content=black-buy, you can compare the conversion rates and traffic from each button and do some rudimentary A/B testing.

Term

This one is normally optional. You'll only really want to use it when you run paid ads that rely on keyword terms.

When you run one of these paid keyword ads, you can place the keywords inside of the utm_term tag and compare the performance between different keywords to see how people are landing on your page.

Building URLs with UTM tags

It's pretty tedious manually adding UTM tags to URLs, especially when the URLs are longer and you lose track of where you were.

To help with this, I've built a little tool that is available on this website to help generate URLs with UTM tags! Head over to the UTM Tag Builder page and start building out UTM-tagged URLs.

@ryangjchandler/alpine-clipboard

I'll start the list off with a biased choice. This is a package that I built to make copying things to the clipboard super easy.

You can use the $clipboard() magic function to copy some text to the clipboard, or if you're using a button and don't want to write out the x-on:click handler yourself, you can use x-clipboard too.

The underlying browser API is Promise based, so it's also possible to do something after the text has been successfully copied.

$clipboard(text).then(() => { ... })

Overall, this is a super useful plugin and I'm glad I made it because I use it in basically all of my projects.

@marcreichel/alpine-autosize

This is another excellent plugin that I use a lot. It turns a plain ol' <textarea> into an auto-resizing one, which is great for UX.

You install the plugin, add x-autosize to the <textarea> and it just works!

<textarea x-autosize></textarea>

@ryangjchandler/alpine-tooltip

This is another one of my plugins that integrates Tippy with Alpine. It's used in a bunch of projects and the number of CDN hits is regularly above 900,000!

There's not much more to say about it really – it just makes it super easy to create tooltips without rolling the code yourself.

<button x-tooltip.raw="Saving will bust the cache automatically.">
	Save
</button>

@alpinejs/collapse

This one is an official plugin. It provides a new directive x-collapse that work in conjuction with x-show to make "revealable" or "collapsing" elements super simple.

There are browser elements like <detail> that also do this, but they don't have any transitions or animations. That's the sort of polish you want in your product, that's the sort of polish that this plugin provides.

<button type="button" x-on:click="open = !open">
	Toggle
</button>

<div x-show="open" x-collapse>
	Toggled!
</div>

They're just not to my taste and become somewhat of a visual distraction, especially when they're repeated across all rows and those rows already have a good amount of other "stuff".

Now you could go through each Resource and add ->icon(null) to the actions – but that is quite a long task. Instead, I would recommend using one of Filament's lifecycle hooks.

Filament provides a configureUsing() method on all of its components which let's you apply a set of default configuration choices on a particular component, without having to call the same chain of methods across all usages of said component.

This method can be used to remove the default icons that Filament provides. Inside of a ServiceProvider::boot() method, or even a PanelProvider::boot() method (since PanelProvider classes are just ServiceProvider classes), you can call this method and remove those icons.

EditAction::configureUsing(function (EditAction $action): void {
    $action->icon(null);
}, isImportant: true);

The isImportant named argument here ensures that the configuration callback you provide is executed after all "unimportant" configuration callbacks, as well as after the component's setUp() method is called.

This is necessary for removing these icons, since they're set inside of the EditAction::setUp() method.

Programming

In terms of the stuff that I did work on:

• Developed a couple of Filament plugins.
• Started building a static analyser and language server for PHP & PXP projects.
• Started re-writing the static analyser and language server for PHP & PXP projects in Rust.

Content Creation

I started writing a book titled Data Structures in PHP. Writing a book is waaaay harder than it seems. You don't want to be too verbose because it's boring to read, but you also don't want to be too vague because it takes away all of the value. Finding the perfect balance between the two takes time, but I got there in the end.

I originally wanted the book to be a sort of encyclopedia for all things data structures, but it turned into more of an introduction to data structures. That's not a bad thing, since there are plenty of folks who haven't really interacted with data structures in their "raw" form before.

If you're interested in the book, you can get a 15% discount using code BLOG15 – or use this link and it will be automatically applied.

Once I released my book, I felt like I had the taste for informative content creation, so I started planning a course that teaches Rust to PHP developers.

That's still not fully released, but I have been recording videos and customers who pre-order (for a heavily reduced price) can start watching the videos as they release.

If you're interested in the course, you can still pre-order and get instant access to some videos.

Conferences

Laravel Live UK

I did my first ever conference talk in June at Laravel Live UK. It was a pretty cool experience – public speaking has never really phased me, but doing it in front of people who know about the subject matter is a bit daunting, you say one thing that's wrong, you look like a fool.

Here are a couple of photos from the event:

Huge thanks to Jonty for giving me this opportunity, I really hope I can speak at Laravel Live again at the next event.

Laracon US

2023 was also the year I attended my first Laracon! I flew all the way to Nashville to see some wicked talks, meet some online friends in person and overall have a really awesome time.

Getting there was an absolute nightmare – my outbound flight from Heathrow was fine but some adverse weather conditions resulted in a cancelled connecting flight and a 7-hour layover at JFK.

Despite that, it was really really good. Very excited to see where Laracon US 2024 is and perhaps I'll apply to speak..

Personal

Moving

Back in March we sold our first house that we purchased back in 2021. It wasn't the smoothest sale and purchase... a burst water pipe at our new property prior to completion put a massive delay on the whole thing – plus some legal holdups – it took quite a while for the purchase of our new house to go through.

The new house is a bit of a project, a doer-upper if you like. I do enjoy a challenge and as we work on things I can see it all coming together and being a house that we stay in for a good few years.

Jobs

I think this year is the first year that I got somewhat close to being "burned out". For a long time I was working a full-time job and freelancing, which was a lot of work. Back in June, I stopped freelancing and changed jobs to actually start working full-time for one of my freelance clients.

It's been a nice change of pace and I've had a lot more time to work on side-projects and stuff. I do still find myself wondering what to do though – when you go from doing so much all of the time, to doing less, you find yourself lost, unsure of what to do.

That's one of the reasons I started writing a book, working on a video course and a couple of new SaaS projects.

Looking forward to 2024

The main goal for 2024 is to work on cool shit, and enjoy working on cool shit. I don't want to put pressure on certain things, but I do see myself getting PXP to a point of usability.

I want to make sure that all of my work on open-source projects and other side-projects is sustainable, so finding ways to make that happen is my other goal.

Thanks for reading, if you made it this far.

Happy New Year!

Ryan

PHP uses an INI file for all of it's configuration. It gets loaded when PHP starts up and is used to configure extensions and various PHP features.

How you locate your php.ini file all depends on what sort of access you have to your server. I'll detail a couple of different methods below.

Command-line access

If you have access to php through the command-line (inside of your terminal - maybe via SSH), you can find the php.ini file quite quickly.

1. Open your terminal locally or connected to your server via SSH.
2. Run the php --ini command.
3. Locate the path to the php.ini file in the output.

% php --ini
Configuration File (php.ini) Path: /opt/homebrew/etc/php/8.2
Loaded Configuration File:         /opt/homebrew/etc/php/8.2/php.ini
Scan for additional .ini files in: /opt/homebrew/etc/php/8.2/conf.d
Additional .ini files parsed:      /opt/homebrew/etc/php/8.2/conf.d/error_log.ini,
/opt/homebrew/etc/php/8.2/conf.d/ext-opcache.ini,
/opt/homebrew/etc/php/8.2/conf.d/php-memory-limits.ini

phpinfo()

If you can load a PHP script in the browser, you can use the phpinfo() function to output all of PHP's configuration values and find the path to the php.ini file.

Put the following snippet of code into a PHP file and load the file in your browser.

<?php
	
phpinfo();

If you open up your settings.json file inside of Visual Studio Code, you can use an experimental feature in the Tailwind extension to get autocomplete inside of $attributes->class() and @class().

{
    // ...
    "tailwindCSS.experimental.classRegex": [
        [
            "@?class\\(([^]*)\\)",
            "'([^']*)'"
        ]
    ]
}

Save this file, open up a Blade template and give it a go. You should now be able to autocomplete Tailwind classes in the following scenarios (^ indicates cursor position):

@class([
    '^'
])

{{ $attributes->class('^') }}

{{ $attributes->class([
    '^'
]) }}

First, make sure that the element that renders the error message has some sort of "marker" class or data attribute that marks it as an error message.

@error('name')
    <p class="error-message text-danger-red">
        {{ $message }}
    </p>
@enderror

Now inside of a <script> tag, you can write the following code.

Livewire.hook('commit', ({ succeed }) => {
    succeed(() => {
        setTimeout(() => {
            const firstErrorMessage = document.querySelector('.error-message')

            if (firstErrorMessage !== null) {
                firstErrorMessage.scrollIntoView({ block: 'center', inline: 'center' })
            }
        }, 0)
    })
}) 

Using Livewire's JavaScript API you can hook into the lifecycle of a request. The commit hook can be used to do something during the lifecycle of a single commit.

A callback provided to the succeed() function will be invoked once the commit has been processed by Livewire. Then on the next tick in the event loop, you can check for an error message element and scroll it into view.

If you're using Alpine, you can place this piece of code into the init() method or x-init directive and instead of calling setTimeout with a duration of 0, use the $nextTick magic method which has the same outcome.

<form x-data="{
    init() {
        Livewire.hook('commit', ({ succeed }) => {
            succeed(() => {
                this.$nextTick(() => {
                    const firstErrorMessage = document.querySelector('.error-message')

                    if (firstErrorMessage !== null) {
                        firstErrorMessage.scrollIntoView({ block: 'center', inline: 'center' })
                    }
                })
            })
        })
    }
}">

The serialised representation of data can be achieved with various formats. JSON is very common as most languages have some form of JSON encoding and decoding. You could also use XML, YAML or even a raw string of bytes.

You're probably familiar with PHP's serialize() function. This function accepts a single value and returns the serialised version as a string.

What's unique about serialisation in PHP is that it actually uses a special serialisation format to represent various types of data, including arrays and objects.

Each data type that PHP can serialise has it's own representation and notation when serialised. Let's break these down and look at what they represent.

Booleans

Booleans are very simple.

b:0;
b:1;

The type specifier for boolean values is b. That is then followed by a colon and an integer representation of the boolean itself, so false becomes 0 and true becomes 1.

Null

Serialising null produces the following.

N;

Null doesn't have any additional data to include, so it is represented by a single N character.

Integers and Floats

Serialising the value 100 with serialize() returns the following string.

i:100;

Serialised integers are represented with the character i, followed by a colon and the integer's value.

Serialising the value 100.5 has a very similar format.

d:100.5;

The only difference is that instead of an i for integer, the type specifier is d for "double".

Strings

Serialised strings carry some extra information with them. The code below is the result of serialising Hello, world.

s:12:"Hello, world";

The type specifier is s. This is then followed by a colon and the result of strlen($value). Then that is followed by another colon and the original value wrapped in double quotes.

s:[strlen(value)]:"[value]"

The reason the length of the string is important here is that is tells the piece of code unserialising how many characters or bytes it needs to process to find the string value.

It also helps in lower level languages where strings might be stored as an array of bytes. If you know how many bytes the string is, you can allocate the correct amount and avoid potential memory issues.

Arrays

Array serialisation is a little more involved, since a PHP array has keys and values. Let's first serialise an empty array [].

a:0:{}

The type specifier for an array is a. The second component in the serialised data is the length of the array. The third component is where the key and values in the array are placed.

a:[count(value)]:{...values}

To see how the values are serialised, we can serialise a simple array with 3 values [1, 2, 3].

a:3:{i:0;i:1;i:1;i:2;i:2;i:3;}

The stuff inside of the curly braces contains information about the keys and values inside of the array.

The generic formation for the values is as follows.

{key;value;key;value;key;value}

Expanding the original array into a more explicit, keyed equivalent.

[
    0 => 1,
    1 => 2,
    2 => 3,
]

We can look at each key-value pair and see that their serialised values are placed inside of the curly braces, in order.

{i:0;i:1;i:1;i:2;i:2;i:3;}
 ^0  ^1  ^1  ^2  ^2  ^3

If we changed the array slightly and used strings for the keys instead.

[
    'a' => 1,
    'b' => 2,
    'c' => 3,
]

a:3:{s:1:"a";i:1;s:1:"b";i:2;s:1:"c";i:3;}
     ^a      ^1  ^b      ^2  ^c      ^3

It's also possible to serialise nested arrays, useful for more complex structures.

a:1:{i:0;a:3:{i:0;i:1;i:1;i:2;i:2;i:3;}}

Objects

The most complex serialisation format can be seen when serialising objects.

Let's take a simple Nothing class, instantiate it and serialise it.

class Nothing
{
    // ...
}

serialise(new Nothing);

O:7:"Nothing":0:{}

The type specifier for serialised objects is O. That is followed by the length of the class name, and the class name itself wrapped in double quotes.

The number following the class name is the number of properties that the object has. The curly braces then holds the serialised properties, in a similar format to the arrays.

Taking a new class User that has 2 properties — $name and $age — we can see how property values are serialised.

class User
{
    public function __construct(
        public $name,
        public $age,
    ) {}
}

serialize(new User(
    name: "Ryan",
    age: 23
));

O:6:"User":2:{s:4:"name";s:4:"Ryan";s:3:"age";i:23;}

The User object has 2 properties, so the name for each property is serialised as a string and the serialised value comes after.

Converting this format into a simplified grammar might look something like below.

O:[strlen(value::class)]:"[value::class]":[count(properties)]:{...property}

property ::= [name];[value]

Non-public properties

The User class only has public properties, but the serialize() function can also serialise protected and private properties.

Starting with protected properties, let's write a new class SensitiveStuff that has a single protected property $password.

class SensitiveStuff
{
    public function __construct(
        protected $password,
    ) {}
}

serialize(new SensitiveStuff(
    password: 'password123'
));

O:14:"SensitiveStuff":1:{s:11:"\0*\0password";s:11:"password123";}

Everything looks very similar, but you'll notice there are some extra characters where the property name is. Instead of the property name being serialised to s:8:"password", there are 3 additional characters: \0*\0.

The \0 character is known as the "null terminator" or "null byte". The * (asterisk) is what marks this property as protected.

If we change the visibility of the property to private and re-serialise it, it will produce a slightly different value.

O:14:"SensitiveStuff":1:{s:24:"\0SensitiveStuff\0password";s:11:"password123";}

This time, the property name has been prefixed with a null byte character, the class name of the object and another null byte. This pattern represents a private property.

Resources

It's not possible to serialise resource values in PHP. When you attempt to serialise an object with a resource stored inside of a property, it will be cast to an integer and serialised as 0.

Sign off

Thanks for reading! Hopefully this has given you a bit of an introduction to how various value types are serialised in PHP.

In another post I'll write about writing your own deserialisation logic in another programming language, most likely JavaScript!

This post will focus on rendering the template and echoing out data that can be escaped with htmlspecialchars().

Before we start writing code we need to take care of the most important part of any programming project — giving the project a name. I'm going to call it Stencil.

The templates themselves will all be plain PHP. We won't be creating any special syntax like Twig or Blade, we'll focus solely on templating functionality.

We'll begin by creating the main class.

class Stencil
{
    public function __construct(
        protected string $path,
    ) {}
}

The Stencil class will need to know where the templates are located — so that gets passed in through the constructor.

To actually render our templates, we'll need a render() method.

class Stencil
{
    // ...

    public function render(string $template, array $data = []): string
    {
        // ?
    }
}

The render() method accepts the name of the template and an array of data variables that will be accessible inside of said template.

We now need to do three things:

1. Form a path to the requested template.
2. Make sure the template exists.
3. Render the template with the provided data.

class Stencil
{
    // ...

    public function render(string $template, array $data = []): string
    {
        $path = $this->path . DIRECTORY_SEPARATOR . $template . '.php';

        if (! file_exists($path)) {
            throw TemplateNotFoundException::make($template);
        }

        // ?
    }
}

The first two on the list are easy to do. Stencil will only look for .php files so forming a path is just a case of concatenating some strings. If the requested template contains any directory separators, that will handle the nesting of templates inside of directories.

If the file doesn't exist, throw a custom TemplateNotFoundException.

To cover the third point in the list, actually rendering the template, we'll want to make a new class called Template. This will house all of the methods available to the template and handle the real rendering side of things.

class Template
{
    public function __construct(
        protected string $path,
        protected array $data = [],
    ) {}

    public function render(): string
    {
        // ?
    }
}

class Stencil
{
    // ...

    public function render(string $template, array $data = []): string
    {
        $path = $this->path . DIRECTORY_SEPARATOR . $template . '.php';

        if (! file_exists($path)) {
            throw TemplateNotFoundException::make($template);
        }

        return (new Template($path, $data))->render();
    }
}

To obtain the rendered template as a string, we'll take advantage of PHP's output buffers. When you call ob_start() PHP will start to capture anything that the application attempts to output (echo, raw HTML, etc).

You can retrieve that as a string and then stop capturing the output using ob_get_clean(). A combination of these two functions and an include will let us evaluate a template file.

class Template
{
    // ...

    public function render(): string
    {
        ob_start();

        include $this->path;

        return ob_get_clean();
    }
}

This will handle rendering the template, but it doesn't do anything to let the template access those data variables stored inside of $data. PHP being the wonderful language it is provides another function called extract() that accepts an array of key value pairs.

The key for each item in the array will be used to create a new variable in the current scope using the associated value. Since include and its relatives always execute the PHP file in the current scope, the template will be able to access the extracted variables.

class Template
{
    // ...

    public function render(): string
    {
        ob_start();

        extract($this->data);

        include $this->path;

        return ob_get_clean();
    }
}

Perfect! Now we can render a template and give it access to the data variables provided. There is one thing that we haven't considered... if we wanted to create some variables inside of the render() method, our template would also be able to access those. That's not what we want!

To solve that problem, we need to wrap the extract() and include calls in an immediately-invoke closure — that way, the template will only have access to the variables inside of the closure.

class Template
{
    // ...

    public function render(): string
    {
        ob_start();

        (function () {
            extract($this->data);

            include $this->path;
        })();

        return ob_get_clean();
    }
}

The final piece of the puzzle is a method for escaping values when echoing them. Closures inherit $this which means our template will be able to call any method we define on the Template class. Let's create an e() method that accepts a value and escapes it using htmlspecialchars().

class Template
{
    // ...

    public function e(?string $value): string
    {
        return htmlspecialchar($value ?? '', ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
    }
}

And like that we have a little template engine for our PHP projects.

<h1>
    Hello, <?= $this->e($name) ?>!
</h1>

The template above can be rendered using our engine:

$stencil->render('hello', [
    'name' => 'Ryan'
]);

And will output the following HTML:

<h1>
    Hello, Ryan!
</h1>

In a future blog post we'll implement support for partials, allowing us to separate out common templates and use them in multiple places.

If you want to skip the blog post and go straight to the package, the repository is public on GitHub.

As somebody who enjoys experimenting with parsers and text processing, writing lexers has become a somewhat regular task for me. The first step in reducing boilerplate and copy-paste'd code between projects is to write a package that can handle the tedious task of tokenisation for me.

To demonstrate Lexical's functionality, I'll write a simple lexer that can handle mathematical expressions such as 1 + 2 or 4 / 5 * 6. The lexer will need to handle 4 mathematical operators (+, -, *, /) and numeric values (just integers for now).

We'll by creating a new enumeration that describes the token types.

enum TokenType
{
    case Number;
    case Add;
    case Subtract;
    case Multiply;
    case Divide;
}

Lexical provides a set of attributes that can be added to each case in the enumeration:

• Regex - accepts a single regular expression.
• Literal - accepts a string of continuous characters.
• Error - designates a specific enumeration case as the "error" type.

Adding the aforementioned attributes to TokenType looks a little something like the code below.

enum TokenType
{
    #[Regex("[0-9]+")]
    case Number;
    
    #[Literal("+")]
    case Add;
    
    #[Literal("-")]
    case Subtract;
    
    #[Literal("*")]
    case Multiply;

    #[Literal("/")]
    case Divide;
}

With the attributes in place, we can start to build a lexer using the LexicalBuilder.

$lexer = (new LexicalBuilder)
    ->readTokenTypesFrom(TokenType::class)
    ->build();

The readTokenTypesFrom() method is used to tell the builder where it should look for the various tokenising attributes. The build() method will take those attributes and return an object that implements LexerInterface, configured to look for the specified token types.

Then it's just a case of calling the tokenise() method on the lexer object.

$tokens = $lexer->tokenise('1+2'); // -> [[TokenType::Number, '1'], [TokenType::Add, '+'], [TokenType::Number, '2']]

The tokenise() method returns a list of tuples, where the first item is the "type" (TokenType in this example) and the second item is the "literal" (a string containing the matched characters).

Skipping whitespace and other patterns

The lexer currently understands 1+2 but it would fail to tokenise 1 + 2 (added whitespace). This is because by default it expects each and every possible character to fall into a pattern. If it encountered an invalid or unrecognised character in the input, it would throw an exception (by default).

The whitespace is insignificant in this case, so can be skipped safely. To do this, we need to add a new Lexer attribute to the TokenType enumeration and pass through a regular expression that matches the characters we want to skip.

The Lexer attribute is used to configure the generic behaviour of the lexer. skip is the only option in the current version.

#[Lexer(skip: "[ \t\n\f]+")]
enum TokenType
{
    // ...
}

Now the lexer will skip over any whitespace characters and successfully tokenise 1 + 2.

Error handling

When a lexer encounters an unexpected character, it will throw an UnexpectedCharacterException.

try {
    $tokens = $lexer->tokenise();
} catch (UnexpectedCharacterException $e) {
    dd($e->character, $e->position);
}

As mentioned above, there is an Error attribute that can be used to mark an enum case as the "error" type.

enum TokenType
{
    // ...

    #[Error]
    case Error;
}

Now when the input is tokenised, the unrecognised character will be consumed like other tokens and will have a type of TokenType::Error.

$tokens = $lexer->tokenise('1 % 2'); // -> [[TokenType::Number, '1'], [TokenType::Error, '%'], [TokenType::Number, '2']]

Custom Token objects

If you prefer to work with dedicated objects instead of Lexical's default tuple values for each token, you can provide a custom callback to map the matched token type and literal into a custom object.

class Token
{
    public function __construct(
        public readonly TokenType $type,
        public readonly string $literal,
    ) {}
}

$lexer = (new LexicalBuilder)
    ->readTokenTypesFrom(TokenType::class)
    ->produceTokenUsing(fn (TokenType $type, string $literal) => new Token($type, $literal))
    ->build();

$lexer->tokenise('1 + 2'); // -> [Token { type: TokenType::Number, literal: "1" }, ...]

What is a "service container"?

A service container is a PHP object that is responsible for the instatiation of other objects. You tell the container how to construct the object, then when you need an instance of it in your program, you ask for one.

What is PSR-11?

PSR-11 is a document that specifies a common interface for service containers. It also defines two Exception interfaces that a container must throw to be compliant.

The interface itself only defines two methods:

interface ContainerInterface
{
    /**
     * Finds an entry of the container by its identifier and returns it.
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @throws NotFoundExceptionInterface  No entry was found for **this** identifier.
     * @throws ContainerExceptionInterface Error while retrieving the entry.
     *
     * @return mixed Entry.
     */
    public function get(string $id);

    /**
     * Returns true if the container can return an entry for the given identifier.
     * Returns false otherwise.
     *
     * `has($id)` returning true does not mean that `get($id)` will not throw an exception.
     * It does however mean that `get($id)` will not throw a `NotFoundExceptionInterface`.
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @return bool
     */
    public function has(string $id): bool;
}

The interface is simple on purpose. By only requiring a container to have these 2 methods, it does not dictate how the services are bound to the container in the first place.

Building a minimal PSR-11 compliant container

Let's start by installing the psr/container package that provides ContainerInterface and creating our own Container class that implements that interface.

composer require psr/container

use Psr\Container\ContainerInterface;

class Container implements ContainerInterface
{
    public function get(string $id): mixed
    {
        // ?
    }

    public function has(string $id): bool
    {
        // ?
    }
}

We want to "bind" some services to the container &mdash so a suitable method name would be bind(). This method needs to accept a string $id and, for now, an object $service.

We can store the bindings in an array on the container.

class Container implements ContainerInterface
{
    protected array $bindings = [];

    public function bind(string $id, object $service): void
    {
        $this->bindings[$id] = $service;
    }
}

Now the get() and has() methods can read from $bindings.

class Container implements ContainerInterface
{
    // ...

    public function get(string $id): mixed
    {
        return $this->bindings[$id];
    }

    public function has(string $id): bool
    {
        return isset($this->bindings[$id]);
    }
}

The ContainerInterface contains a couple of DocBlock comments with @throws annotations. For the Container class to be truly PSR-11 compliant, we need to make sure that we throw an Exception that implements the NotFoundExceptionInterface interface when trying to call get() with a non-existent $id.

use Psr\Container\NotFoundExceptionInterface;
use Exception;

class ServiceNotFoundException extends Exception implements NotFoundExceptionInterface
{
    // ...
}

class Container implements ContainerInterface
{
    // ...

    public function get(string $id): mixed
    {
        if (! $this->has($id)) {
            throw new ServiceNotFoundException($id);
        }

        return $this->bindings[$id];
    }
}

PSR-11 also defines a ContainerExceptionInterface, stating that Exceptions thrown directly by the container should implement it. The NotFoundExceptionInterface already extends that interface so there's nothing else to do.

We can write some Pest tests for the Container class.

it('can be constructed', function () {
    expect(new Container)->toBeInstanceOf(Container::class);
});

it('can bind and retrieve services', function () {
    $container = new Container;
    $container->bind('container', $container);

    expect($container->has('container'))->toBeTrue();
    expect($container->get('container'))->toBeInstanceOf(Container::class)->toBe($container);
});

it('throws a ServiceNotFoundException when trying to retrieve a non-existent service', function () {
    $container = new Container;

    expect(fn () => $container->get('foo'))
        ->toThrow(ServiceNotFoundException::class);
});

And like that, we have a PSR-11 compliant service container.

In this post, I'll show you how to write your own esolang similar to Brainf*ck in PHP.

Syntax

Brainf*ck is a minimal esolang and the original implementation only consisted of 8 symbols — >, <, +, -, ., ,, [ and ]. The language operated on a single contiguous sequence of memory called a "tape". The memory itself contained 8-bit integers (bytes from 0 to 255) which allows you represent the entire range of ASCII characters.

Here's a small overview of what each symbol / operator does.

The language that we create in this post will be very similar to Brainf*ck, but we'll use sigils and tokens found in the PHP language instead (with some variation). The table below maps the Brainf*ck tokens to our own. Let's combine the words PHP and Eso and call the language "Peso".

You can treat the \ and / tokens like a while loop where the condition is $byte !== 0.

Lexer

Let's start by writing a lexer. The job of the lexer will be taking a string of Peso code and converting it into a sequence of tokens.

The best place to start is with the tokens themselves. In this case we can just use an enum to define the tokens, since we don't really care about the characters themselves.

enum Token
{
    case RightDoubleArrow;
    case LeftDoubleArrow;
    case Plus;
    case Minus;
    case Echo;
    case Dollar;
    case Backslash;
    case Slash;
}

The first step in the Lexer will be splitting the input string into separate characters.

class Lexer
{
    /** @return array<Token> */
    public function tokenise(string $input): array
    {
        $chars = str_split($input);
        $tokens = [];

        return $tokens;
    }
}

Then we need to loop over each of the characters and try to find a token. We'll do this with a traditional for loop since it will allow us to skip X iterations for multi-character tokens.

class Lexer
{
    /** @return array<Token> */
    public function tokenise(string $input): array
    {
        $chars = str_split($input);
        $tokens = [];

        for ($i = 0; $i < count($chars); $i++) {
            $char = $chars[$i];

            if ($char === '$') {
                $tokens[] = Token::Dollar;
            } elseif ($char === '\\') {
                $tokens[] = Token::Backslash;
            } elseif ($char === '/') {
                $tokens[] = Token::Slash;
            } elseif ($char === '+') {
                $tokens[] = Token::Plus;
            } elseif ($char === '-') {
                $tokens[] = Token::Minus;
            } elseif ($char === '=') {
                if ($chars[++$i] === '>') {
                    $tokens[] = Token::RightDoubleArrow;
                } else {
                    throw UnexpectedCharacterException::make($char, expected: '>');
                }
            } elseif ($char === '<') {
                if ($chars[++$i] === '=') {
                    $tokens[] = Token::LeftDoubleArrow;
                } else {
                    throw UnexpectedCharacterException::make($char, expected: '=');
                }
            } elseif (array_slice($chars, $i, 4) === ['e', 'c', 'h', 'o']) {
                $i += 3;
                $tokens[] = Token::Echo;
            } elseif (ctype_space($char)) {
                continue;
            } else {
                throw UnexpectedCharacterException::make($char);
            }
        }

        return $tokens;
    }
}

Let's also write a unit test for the Lexer class to make sure that the correct token types are being produced, as well as a test to check that the UnexpectedCharacterException is thrown when we encounter something bad.

it('produces the correct tokens', function () {
    $lexer = new Lexer;

    expect($lexer->tokenise('=> <= + - echo $ \ /'))
        ->toBe([
            Token::RightDoubleArrow,
            Token::LeftDoubleArrow,
            Token::Plus,
            Token::Minus,
            Token::Echo,
            Token::Dollar,
            Token::Backslash,
            Token::Slash
        ]);
});


it('throws an exception when encountering an unexpected character', function () {
    $lexer = new Lexer;

    expect(fn () => $lexer->tokenise('foo'))
        ->toThrow(UnexpectedCharacterException::class, 'Unexpected character f');
});

Parsing

Writing a parser for this sort of language is a little bit overkill, but it makes sense to do it now because we'll use it later on to make Peso blazingly fast.

Parsing involves looking at each of the tokens that the Lexer produces and creating a set of structured nodes that represent the operations in the program.

class Parser
{
    protected ?Token $current = null;
    
    protected ?Token $next = null;

    protected int $position = 0;

    protected array $tokens;

    public function parse(array $tokens): Program
    {
        if (count($tokens) === 0) {
            return new Program();
        }

        $this->tokens = $tokens;
        $this->current = $tokens[$this->position];
        $this->next = $tokens[$this->position + 1] ?? null;

        $nodes = [];

        while ($this->position < count($tokens)) {
            $nodes[] = $this->node();
        }

        return new Program($nodes);
    }
}

This is the boilerplate code for the Parser. It accepts an array of tokens, does some initialisations and then tries to get a Node from the current token. Most of the work is going to be done inside of the Parser::node() method.

class Parser
{
    // ...

    protected function node(): Node
    {
        if ($this->current === Token::Plus) {
            $this->next();
            return new IncrementNode;
        } elseif ($this->current === Token::Minus) {
            $this->next();
            return new DecrementNode;
        } elseif ($this->current === Token::RightDoubleArrow) {
            $this->next();
            return new MoveRightNode;
        } elseif ($this->current === Token::LeftDoubleArrow) {
            $this->next();
            return new MoveLeftNode;
        } elseif ($this->current === Token::Dollar) {
            $this->next();
            return new ReadByteNode;
        } elseif ($this->current === Token::Echo) {
            $this->next();
            return new EchoNode;
        } elseif ($this->current === Token::Backslash) {
            $this->next();

            $nodes = [];

            while ($this->current !== null && $this->current !== Token::Slash) {
                $nodes[] = $this->node();
            }

            $this->expect(Token::Slash);

            return new WhileNode($nodes);
        } else {
            throw UnexpectedTokenException::make($this->current);
        }
    }

    protected function expect(Token $token): void
    {
        if ($this->current !== $token) {
            throw UnexpectedTokenException::make($this->current);
        }

        $this->next();
    }

    protected function next(): void
    {
        $this->position++;

        $this->current = $this->next;
        $this->next = $this->tokens[$this->position + 1] ?? null;
    }
}

The Parser::node() method is recursive when it tries to parse \ / loops. It will recursively parse each of the nodes inside of the loop and store them on the WhileNode.

To make sure the Parser is working correctly, let's write a test and check each of the Node values are present.

it('can parse all nodes', function () {
    $tokens = (new Lexer)->tokenise('=> <= + - echo $ \echo/');
    $parser = new Parser;

    expect($parser->parse($tokens))
        ->toBeInstanceOf(Program::class)
        ->getNodes()
        ->sequence(
            fn (Expectation $expect) => $expect->toBeInstanceOf(MoveRightNode::class),
            fn (Expectation $expect) => $expect->toBeInstanceOf(MoveLeftNode::class),
            fn (Expectation $expect) => $expect->toBeInstanceOf(IncrementNode::class),
            fn (Expectation $expect) => $expect->toBeInstanceOf(DecrementNode::class),
            fn (Expectation $expect) => $expect->toBeInstanceOf(EchoNode::class),
            fn (Expectation $expect) => $expect->toBeInstanceOf(ReadByteNode::class),
            fn (Expectation $expect) => $expect->toBeInstanceOf(WhileNode::class)
                ->getNodes()
                ->sequence(
                    fn (Expectation $expect) => $expect->toBeInstanceOf(EchoNode::class)
                ),
        );
});

Execution

Now that we have a nice structured set of nodes we can start to execute the program. Let's start with a "simple" program that accepts 2 numbers from the input and adds them together.

$ ------------------------------------------------ => $ \ <= + => - / <= echo

Simple, right? Let me explain what the program is doing. I'll use #0, #1, etc to represent cells in the tape of memory.

We start by reading a single character of input into #0. The input itself will be a string, but we want to work with integers in the range 0 to 255, so we'll store it as an ASCII byte using ord().

The stream of - tokens will decrement the value in #0 48 times. The ASCII code for the number 2 is 50, so decrementing 48 times will result in a value of 2 in #0. 48 isn't a magic number, that's just the ASCII code for 0.

Moving to #1, we can read in a single character of input again. Then we start a loop.

The loop itself will move back to #0, increment the value and then move to #1 again, decrementing #1 and this will continue until #1 === 0.

#0 should now contain the sum of the 2 numbers provided which we can print using echo.

Hopefully you're still with me. If you are, let's start writing the Interpreter class.

class Interpreter
{
    protected array $tape = [];

    protected int $tp = 0;

    protected ?string $input = null;

    protected int $ip = 0;

    protected string $output = '';

    public function interpret(Program $program, ?string $input = null)
    {
        $this->tape = array_fill(0, 30_000, 0);;
        $this->tp = 0;
        $this->input = $input;
        $this->ip = 0;
        $this->output = '';

        foreach ($program->getNodes() as $node) {
            $this->node($node);
        }
    }
}

The Interpreter has a tape of memory stored in the $tape property, as well as a "tape pointer" which stores the current tape index. The $ip property is the "input pointer". That is the current position in the input so that we can provide a single string of input and read the correct character when necessary.

All of the execution logic is written inside of Interpreter::node().

class Interpreter
{
    // ...

    protected function node(Node $node): void
    {
        if ($node instanceof MoveRightNode) {
            $this->tp++;
        } elseif ($node instanceof MoveLeftNode) {
            $this->tp--;
        } elseif ($node instanceof IncrementNode) {
            if ($this->tape[$this->tp] === 255) {
                $this->tape[$this->tp] = 0;
            } else {
                $this->tape[$this->tp]++;
            }
        } elseif ($node instanceof DecrementNode) {
            if ($this->tape[$this->tp] === 0) {
                $this->tape[$this->tp] = 255;
            } else {
                $this->tape[$this->tp]--;
            }
        } elseif ($node instanceof ReadByteNode) {
            if ($this->input === null) {
                throw NoInputProvidedException::make();
            }

            $this->tape[$this->tp] = ord($this->input[$this->ip]);
            $this->ip++;
        } elseif ($node instanceof WhileNode) {
            while (true) {
                foreach ($node->getNodes() as $child) {
                    $this->node($child);
                }

                if ($this->tape[$this->tp] === 0) {
                    break;
                }
            }
        } elseif ($node instanceof EchoNode) {
            $this->output .= chr($this->tape[$this->tp]);
        }
    }
}

It's important to mention a few things here. Since Peso is using the same arithmetic logic as Brainf*ck, incrementing and decrementing the value in a cell is a "wrapping operation". That means that when we reach 0 and try to decrement we wrap that around to 255 and when incrementing 255, we wrap that around to 0.

Looping is also fairly straightforward. We start an infinite loop and iterate over the child nodes in the loop. Once we have iterated over the child nodes, we will check to see if the current cell is equal to 0. If it is, we break out, otherwise we start over from the top of the loop.

Writing a test for this is also fairly simple.

it('can add two numbers', function () {
    $tokens = (new Lexer)->tokenise('$ ------------------------------------------------ => $ \ <= + => - / <= echo');
    $program = (new Parser)->parse($tokens);
    
    $interpreter = new Interpreter;
    $interpreter->interpret($program, '12');

    expect($interpreter->getOutput())
        ->toBe('3');
});

Compiling

Writing an interpreter is cool, but you might want to write a super duper complex Peso program, try to run it and find out that it's just too slow. We want Peso to be blazingly fast when necessary. To solve this (non-existent) problem, let's compile our Peso code to PHP!

To achieve this, we'll convert the Program into a valid snippet of PHP code and store it inside of a temporary file. The code doesn't need to be pretty, it just needs to work.

First step, a new Compiler class.

class Compiler
{
    public function compile(Program $program): Closure
    {
        $php = sprintf(<<<'PHP'
        <?php

        return function (?string $input = null): string {
            $tape = array_fill(0, 30_000, 0);
            $tp = 0;
            $ip = 0;
            $output = '';

            %s
        };
        PHP, $this->generate($program));

        $temp = tempnam(sys_get_temp_dir(), 'peso-');

        file_put_contents($temp, $php);

        return require $temp;
    }
}

The Compiler::compile() method accepts a Program and will generate a snippet of valid PHP code from the nodes. It will then write that PHP code to a temporary file and require it to get the Closure being returned.

That Closure can then be invoked with a string of input to evaluate the Peso code.

class Compiler
{
    // ...

    public function generate(Program $program): string
    {
        $code = '';

        foreach ($program->getNodes() as $node) {
            $code .= $this->node($node);
        }

        return $code;
    }

    protected function node(Node $node): string
    {
        if ($node instanceof MoveRightNode) {
            return '$tp++;';
        }
        
        if ($node instanceof MoveLeftNode) {
            return '$tp--;';
        }

        if ($node instanceof IncrementNode) {
            return <<<'PHP'
            if ($tape[$tp] === 255) {
                $tape[$tp] = 0;
            } else {
                $tape[$tp]++;
            }
            PHP;
        }
        
        if ($node instanceof DecrementNode) {
            return <<<'PHP'
            if ($tape[$tp] === 0) {
                $tape[$tp] = 255;
            } else {
                $tape[$tp]--;
            }
            PHP;
        } 
        
        if ($node instanceof ReadByteNode) {
            return <<<'PHP'
            if ($input === null) {
                throw \Peso\Exceptions\NoInputProvidedException::make();
            }

            $tape[$tp] = ord($input[$ip]);
            $ip++;
            PHP;
        }

        if ($node instanceof WhileNode) {
            $code = 'while (true):';

            foreach ($node->getNodes() as $child) {
                $code .= $this->node($child);
            }

            return $code . <<<'PHP'
                if ($tape[$tp] === 0) {
                    break;
                }
            endwhile;
            PHP;
        }

        if ($node instanceof EchoNode) {
            return <<<'PHP'
            $output .= chr($tape[$tp]);
            PHP;
        }
    }
}

And if we write a test case for the Compiler...

it('can compile a program that adds two numbers', function () {
    $tokens = (new Lexer)->tokenise('$ ------------------------------------------------ => $ \ <= + => - / <= echo');
    $program = (new Parser)->parse($tokens);

    $compiler = new Compiler;
    $callback = $compiler->compile($program);

    expect($callback('12'))
        ->toBe('3');
});

Everything passes and we now have a Brainf*ck inspired language that can be interpreted or compiled to PHP. Nifty!

Finishing touches

To take Peso to the next level, it makes sense to provide a command-line app that can execute a .peso file and read the program's input from STDIN.

#!/usr/bin/env php
<?php

use Peso\Compiler;
use Peso\Exceptions\UnexpectedCharacterException;
use Peso\Exceptions\UnexpectedTokenException;
use Peso\Interpreter;
use Peso\Lexer;
use Peso\Parser;

$autoloaders = [__DIR__.'/../../autoload.php', __DIR__.'/../vendor/autoload.php'];
$file = null;

foreach ($autoloaders as $autoloader) {
    if (file_exists($autoloader)) {
        $file = $autoloader;
        break;
    }
}

if ($file === null) {
    echo "error: failed to find autoloader\n";
    exit(1);
}

require_once $file;

if ($argc <= 1 || in_array('--help', $argv)) {
    echo "usage: peso [file]\n";
    exit(1);
}

$file = $argv[1];
$compile = in_array('--compile', $argv) || in_array('-c', $argv);

if (! file_exists($file)) {
    echo "error: {$file} does not exist\n";
    exit(1);
}

$code = file_get_contents($file);

if (! $code) {
    return;
}

$lexer = new Lexer;

try {
    $tokens = $lexer->tokenise($code);
} catch (UnexpectedCharacterException $e) {
    echo "lexer error: {$e->getMessage()}\n";
    exit(1);
}

$parser = new Parser;

try {
    $program = $parser->parse($tokens);
} catch (UnexpectedTokenException $e) {
    echo "parser error: {$e->getMessage()}\n";
    exit(1);
}

stream_set_blocking(STDIN, false);

$input = trim(fgets(STDIN));
$interpreter = new Interpreter;
$compiler = new Compiler;

if ($compile) {
    echo $compiler->compile($program)($input);
} else {
    $interpreter->interpret($program, $input);
    echo $interpreter->getOutput();
}

echo "\n";

Now we can execute Peso scripts using bin/peso, i.e. bin/peso examples/add.peso. Providing input to the command can be done via STDIN, i.e. echo 12 | bin/peso examples/add.peso.

The default execution method is using the Interpreter. If you want to use the Compiler instead, you just need to provide the --compile flag (-c shorthand).

The first and most important update - the project isn't dead! It's still very much alive, but time is precious resource and since this is just a hobby project it's hard for me to justify spending lots of time working on it - it doesn't pay the bills.

Now because of that, the project is going to be taking a slight change of direction. The parser is written in Rust and the parser will always be written in Rust. I've spent too much time on the parser to just throw it all away.

But. Instead of writing all of PXP's tooling (static analysis, intellisense, formatting, etc) in Rust, I'm going to be taking a hybrid approach.

PHP is my bread and butter, so right now the focus is on making the parser written in Rust usable from a PHP project.

The process there is writing a set of "bindings". I'm currently relying on FFI to do this and that process is going smoothly - I'm yet to do any benchmarks but I've got a feeling it'll still be a huge win in terms of performance.

Once the bindings are complete, they'll be open-sourced. The next stage will be using those bindings to write the transpiler. The transpiler is actually the simplest part in the project. It's more or less "change X to Y" or "extract A from B".

The transpiler will then be open-sourced too. People will be able to start using it and trying to break it (please do try). There will also likely be some syntax highlighting for editors as well, no immediate guarantees (regular PHP highlighters will mostly work).

I then want to focus on the static analyser, since that will be necessary for editor/intellisense support. I started working on this already, but it was written in Rust and whilst I like to think I'm quite good with Rust these days, my velocity is still higher in PHP.

Writing the static analyser in PHP will make it much easier to distribute, extend and contribute to which is ultimately more important. If a tool is difficult to setup and use, nobody will use it.

That said, this is the end of the report. I'll aim to do these monthly or when something big happens.

I want to spend time on this project but can't feasibly do that without support. If you would like to support my work, consider sponsoring me on GitHub.

Thankfully it's possible to automate that process in Visual Studio Code using tasks.json file.

Let's say that I'm working on a Laravel project and want to have Vite running. The command for that would be npm run dev.

Inside of a new file called .vscode/tasks.json, we could add the following JSON.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Run Vite",
            "type": "shell",
            "command": "npm run dev",
            "presentation": {
                "reveal": "always",
                "panel": "new"
            },
            "runOptions": {
                "runOn": "folderOpen"
            }
        }
    ]
}

This task will automatically run the npm run dev command when the project folder is opened. The next time it's opened, the task panel will show up alongside your regular terminal and that process will start automatically.

It is possible to specify an npm type of task, but I personally prefer using shell since it is the same command I'd use in my a terminal. It also means that you can run anything you want automatically.

Save your future self some time and setup some automated tasks!

I would normally do this using an absolutely positioned element stretching to all 4 corners of the page with a z-index lower than the <main> content of the page, but then you end up constantly working about stacking context problems.

After some digging I realised that you can pass multiple values to the background-image CSS property.

body {
    background-image: url('bg-img.jpg'), ...;
}

This makes it really simple to apply a colored overlay using a linear-gradient() between 2 identical colors, combined with the background-blend-mode property.

body {
    background-image: url('bg-img.jpg'), linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.5));
    background-blend-mode: overlay;
}

This will place the gradient on top of the background image.

If you use Tailwind, then you can use the bg-blend-overlay class to apply the blend mode.

I'm currently in the process of writing a book to accompany a video course. All of the content for that book is also written in Markdown, but I've started to notice a slowdown in build speed as the number of files and size of the files increases. The biggest bottleneck in the process is in fact the conversion of Markdown to HTML.

In this post, I'll go through the steps that I took to bind the excellent comrak Rust crate to my existing PHP build process via FFI to improve the performance of my book-building tool.

What is FFI?

FFI stands for "Foreign Function Interface". When a language provides some form of FFI, it allows you to interact with functions written in a totally different programming language.

There are plenty of practical applications for FFI, for example:

• Progressively migrating from one language to another
• Improving mission-critical code with more performant code
• Using packages written in other languages

In this case, we'll be using a package from another language to improve the performance of some PHP code.

The FFI class

PHP introduced support for FFI as part of the PHP 7.4 release with the addition of a new FFI class in the global namespace. The idea here is that we compile some Rust code into a shared library (.so, .dylib, .dll) and provide a C-style header declaration to let PHP know which structures and definitions are available as part of our code.

Generating a shared library

Let's say that we want to expose a Rust function that accepts 2 integers and returns the sum of those numbers.

fn add(a: i64, b: i64) -> i64 {
    return a + b;
}

To represent this Rust function in the style of a C function, we would need to define the signature of the function using C syntax.

long long add(long long a, long long b);

Assuming that the Rust project was created using cargo init --lib, we'll have a src/lib.rs file that will contain our Rust code. If the project is built using cargo build, the Rust compiler will product an rlib by default. This is a special library format specific to Rust and therefore no usable with FFI.

We need to tell the Rust compiler that we want to build a shared library. The way to do this is by adding a crate-type configuration key to the Cargo.toml file in the Rust project.

[package]
name = "php-comrak"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]

The cdylib format will produce the shared library in a valid C-style format for most (if not all) FFI APIs. The generated file can be found in target/debug as something similar to libcratename.dylib (or .so and .dll on other platforms).

Although we have written a Rust function, it's not currently being exposed via the shared library. To expose the function, we need to tell Rust that we which to make it public and export it as a C-compatible function using the extern keyword.

pub extern "C" fn add(a: i64, b: i64) -> i64 {
    return a + b;
}

We can still use Rust's i64 integer type since it knows how to compile that to C's long long equivalent.

Now let's hook it up to PHP using FFI::cdef().

$ffi = FFI::cdef('long long add(long long a, long long b);', __DIR__ . '/target/debug/libphp_comrak.dylib');

echo $ffi->add(100, 200);

The first argument is the declaration of the function and the second argument is the path to the object file.

Running that PHP file in a terminal produces the following output:

Fatal error: Uncaught FFI\ParserException: ';' expected, got '<EOF>' at line 1 in /.../php-comrak/main.php:3
Stack trace:
#0 /.../php-comrak/main.php(3): FFI::cdef('long long add(l...', '/...')
#1 {main}
  thrown in /.../php-comrak/main.php on line 3

What happened? The Rust file correctly defines that function and the header describes the function signature...

The culprit here is name mangling. Name mangling is a process that a compiler uses to avoid conflicts with function names during linking. To prevent mangling the name of the add function, an attribute needs to be added to the function itself.

#[no_mangle]
pub extern "C" fn add(a: i64, b: i64) -> i64 {
    return a + b;
}

Re-compiling the Rust code and re-executing the PHP code should now work.

$ cargo build
$ php ./main.php
300

Adding Comrak

First thing to do is add the crate as a dependency of the project.

$ cargo add comrak

Next we can define a new function called compile which will accept a string of Markdown and compile it into HTML.

pub extern "C" fn compile(markdown: ?) -> ? {
    // ...
}

But what type do we accept and return? This is where it starts to get more involved.

If this were a regular Rust function we'd probably use one of Rust's first-party string representations, String and &str. The issue with those types is that they're not FFI-safe. Thankfully Rust provides some extra types as part of the std::ffi module.

Instead of String, we can use the std::ffi::c_char type, accepting and returning a raw pointer (*const c_char).

use std::ffi::c_char;

#[no_mangle]
pub extern "C" fn compile(markdown: *const c_char) -> *const c_char {
    // ...
}

To see if the code is working, we can just return the markdown value directly and then update our PHP code to call the new function.

#[no_mangle]
pub extern "C" fn compile(markdown: *const c_char) -> *const c_char {
    return markdown;
}

$ffi = FFI::cdef('const char* compile(const char* markdown);', __DIR__ . '/target/debug/libphp_comrak.dylib');

$markdown = <<<'md'
## Hello, world!

Here is some **bold** and _italic_ text.
md;

echo $ffi->compile($markdown);

Compiling and executing produces the following:

$ cargo build
$ php ./main.php
## Hello, world!

Here is some **bold** and _italic_ text.%

Calling the compile() function returns const char* (a constant pointer to a character), PHP's FFI handling is smart enough to convert that into a regular PHP string for us.

Now that we know the FFI part is working, let's handle the conversion of a const* c_char into a Rust &str type.

let markdown = unsafe { CStr::from_ptr(markdown) }
    .to_str()
    .unwrap();

The use of an unsafe block is crucial here. Since we're using a raw pointer (const* c_char), Rust isn't able to do it's regular compile-time guarantees regarding memory safety. We're admitting to that by using the unsafe block to construct a std::ffi::CStr.

Comrak provides a very simple markdown_to_html() function that accepts the &str stored inside of markdown, as well as some configuration options.

let html = markdown_to_html(markdown, &ComrakOptions::default());

There's no need to worry about the options right now, we'll use the sensible defaults that Comrak provides.

Now that we have a String containing the HTML, we need to convert it back into a const* c_char. That can be done using the CString structure.

CString is to CStr as String is to &str. CString represents an owned C-compatible string, whereas CStr represents a borrowed reference to an array of characters (bytes).

return CString::new(html).unwrap().into_raw();

The CString::new() constructor can fail, so it needs to be unwrapped first. Once it is, we can grab a raw pointer to the underlying data and return it directly.

Here's the final function:

use std::ffi::{c_char, CStr, CString};
use comrak::{markdown_to_html, ComrakOptions};

#[no_mangle]
pub extern "C" fn compile(markdown: *const c_char) -> *const c_char {
    let markdown = unsafe { CStr::from_ptr(markdown) }
        .to_str()
        .unwrap();

    let html = markdown_to_html(markdown, &ComrakOptions::default());
    
    return CString::new(html).unwrap().into_raw()
}

The PHP code doesn't need to be updated again since it already has the correct signature. All we need to do is re-compile the Rust code and execute the PHP code again.

$ cargo build
$ php ./main.php
<h2>Hello, world!</h2>
<p>Here is some <strong>bold</strong> and <em>italic</em> text.</p>

And there we go! We're parsing and compiling Markdown to HTML with Rust and FFI. Let's do some rudimentary benchmarks to see how it performs compared to league/commonmark.

The benchmark is focused on the actual parsing and compilation time, it doesn't include any file I/O or other irrelevant operations. Each benchmark was executed 10 times and the results you see below are the averages of those 10 runs.

Those benchmarks demonstrate the potential performance benefits of using FFI and a lower-level language at scale.

One thing that I run into often is long-running processes, such as watcher scripts or background processes, exceeding Composer's default script timeout of 300 seconds. An example of where I see this most often is large test suites that can take more than 5 minutes to run, normally end-to-end tests.

{
    "scripts": {
        "e2e": "./bin/run-tests.sh --browser"
    }
}

To disable Composer's default timeout, you need to update the entry in the scripts section of your composer.json file to call the Composer\\Config::disableProcessTimeout method before running your own code.

{
    "scripts": {
        "e2e": [
            "Composer\\Config::disableProcessTimeout",
            "./bin/run-tests.sh --browser"
        ],
    }
}

You can read more about this in Composer's official documentation here.

The rule itself is relatively simple. We need to create a new struct and implement the Rule trait on it.

#[derive(Debug)]
pub struct ValidFunctionRule;

impl Rule for ValidFunctionRule {
    fn should_run(&self, node: &dyn Node) -> bool {
        downcast::<FunctionCallExpression>(node).is_some()
    }

    fn run(&mut self, node: &mut dyn Node, definitions: &DefinitionCollection) {
        todo!()
    }
}

The rule will only be looking at FunctionCallExpression nodes, so we can limit that down inside of should_run().

The run() method can then execute and do the existence check on the FunctionCallExpression.target.

fn run(&mut self, node: &mut dyn Node, definitions: &DefinitionCollection) {
    let function_call_expression = downcast::<FunctionCallExpression>(node).unwrap();

    match function_call_expression.target.as_ref() {
        Expression::Identifier(Identifier::SimpleIdentifier(SimpleIdentifier { value: function_name, .. })) => {
            if definitions.get_function(function_name).is_none() {
                todo!()
            }
        },
        _ => return,
    }
}

Unwrapping the result from downcast() is safe since we have already limited down the node types inside of should_run(). To get rid of the todo!() in the method, we need to update the Rule to also accept the MessageCollector that we created in the previous part.

pub trait Rule: Debug {
    fn should_run(&self, node: &dyn Node) -> bool;
    fn run(&mut self, node: &mut dyn Node, definitions: &DefinitionCollection, messages: &mut MessageCollector);
}

Now the rule can add a message to the collector.

fn run(&mut self, node: &mut dyn Node, definitions: &DefinitionCollection, messages: &mut MessageCollector) {
    let function_call_expression = downcast::<FunctionCallExpression>(node).unwrap();

    match function_call_expression.target.as_ref() {
        Expression::Identifier(Identifier::SimpleIdentifier(SimpleIdentifier { value: function_name, .. })) => {
            if definitions.get_function(function_name).is_none() {
                messages.add(format!("Function `{}` not found", function_name));
            }
        },
        _ => return,
    }
}

The rule itself can be registered with the analyser.

fn run(args: AnalyseCommand) {
    // ...

    let mut analyser = Analyser::new(collection);
    analyser.add_rule(Box::new(rules::functions::valid_function::ValidFunctionRule));

    // ...
}

A simple PHP file with the code below will produce the following messages:

<?php

foo();

cargo run -- analyse ./playground/invalid-function.php

[src/cmd/analyse.rs:29] messages = MessageCollector {
    file: "./playground/invalid-function.php",
    messages: [
        "Function `foo` not found",
    ],
}

Since we've got some real messages, we might as well spend a couple of minutes improving the format of the output in the terminal. Let's go with tables for now and pull in the prettytable-rs crate to do the heavy lifting.

cargo add prettytable-rs

impl MessageCollector {
    // ...

    pub fn iter(&self) -> Iter<String> {
        self.messages.iter()
    }

    pub fn get_file(&self) -> &str {
        self.file.as_str()
    }

    // ...
}

fn run(args: AnalyseCommand) {
    // ...

    let messages = analyser.analyse(args.file, &contents);

    let mut table = Table::new();
    table.add_row(row![messages.get_file()]);
    for message in messages.iter() {
        table.add_row(row![message]);
    }
    table.printstd();
}

And now the output looks like this:

+-----------------------------------+
| ./playground/invalid-function.php |
+-----------------------------------+
| Function `foo` not found          |
+-----------------------------------+

Much nicer than Rust's default dbg!() output.

Resolving Names

The rule that we've just written is producing an error, but it's not entirely correct. If the PHP code is updated to the following:

<?php

function foo() {
    
}

foo();

The analyser is still going to produce an error. The definition collector is saving a FunctionDefinition for foo() but it is storing it with a fully-qualified name \foo.

We need to take the same resolve_name() logic from the DefinitionCollector and add it to the Analyser somewhere. We can't simply add it to the Analyser because that will be used for multiple files, so instead we need to create some sort of Scope or Context structure that we can use for a single file.

I like the name Context, so let's go with that.

#[derive(Debug, Clone)]
pub struct Context {
    namespace: ByteString,
    imports: Vec<ByteString>,
}

impl Context {
    pub fn new() -> Self {
        Self {
            namespace: ByteString::default(),
            imports: Vec::new(),
        }
    }

    pub fn resolve_name(&self, name: &ByteString) -> ByteString {
        // If the name is already fully qualified, return as is.
        if name.bytes.starts_with(b"\\") {
            return name.clone();
        }

        let parts = name.split(|b| *b == b'\\').collect::<Vec<&[u8]>>();
        let first_part = parts.first().unwrap();

        // Check each imported name to see if it ends with the first part of the
        // given identifier. If it does, we can assume you're referencing either
        // an imported namespace or class that has been imported.
        for imported_name in self.imports.iter() {
            if imported_name.ends_with(first_part) {
                let mut qualified_name = imported_name.clone();
                qualified_name.extend(&name.bytes[first_part.len()..]);

                return qualified_name;
            }
        }

        // If we've reached this point, we have a simple name that
        // is not fully qualified and we have not imported it.
        // We can simply prepend the current namespace to it.
        let mut qualified_name = self.namespace.clone();
        qualified_name.extend(b"\\");
        qualified_name.extend(&name.bytes);

        qualified_name
    }

    pub fn set_namespace(&mut self, namespace: ByteString) {
        self.namespace = namespace;
    }

    pub fn add_import(&mut self, import: ByteString) {
        self.imports.push(import);
    }
}

Since a single-file could have multiple contexts, we'll use a context_stack on the Analyser to store them.

#[derive(Debug)]
pub struct Analyser {
    rules: Vec<Box<dyn Rule>>,
    definitions: DefinitionCollection,
    message_collector: MessageCollector,
    context_stack: Vec<Context>,
}

impl Analyser {
    pub fn new(definitions: DefinitionCollection) -> Self {
        Self {
            rules: Vec::new(),
            definitions,
            message_collector: MessageCollector::default(),
            context_stack: Vec::new(),
        }
    }

    pub fn analyse(&mut self, file: String, contents: &[u8]) -> MessageCollector {
        self.message_collector = MessageCollector::new(file);

        let parse_result = parse(contents);
        if let Err(error) = parse_result {
            self.message_collector.add(error.to_string());
            return self.message_collector.clone();
        }

        let mut ast = parse_result.unwrap();

        self.context_stack.push(Context::new());
        self.visit_node(&mut ast).unwrap();

        return self.message_collector.clone();
    }

    pub fn add_rule(&mut self, rule: Box<dyn Rule>) {
        self.rules.push(rule);
    }
}

impl Visitor<()> for Analyser {
    fn visit(&mut self, node: &mut dyn Node) -> Result<(), ()> {
        let mut context = self.context_stack.last_mut().unwrap();

        for rule in &mut self.rules {
            if rule.should_run(node) {
                rule.run(node, &self.definitions, &mut self.message_collector, &mut context);
            }
        }

        Ok(())
    }
}

Now when we run the rule on the code from earlier, it won't produce any messages because the call to foo() is being resolved to \foo which is the fully-qualified name of the function itself.

But what if we now create two separate PHP files - one with a namespaced function and the other importing that namespaced function and calling it? Well, the analyser will fail again.

<?php

namespace App;

function foo() {

}

<?php

use function App\foo;

foo();

The first problem is that the current Context isn't storing any imported names. We can add a check for use statements in the Analyser and if we come across one, we can add it to the Context.

impl Visitor<()> for Analyser {
    fn visit(&mut self, node: &mut dyn Node) -> Result<(), ()> {
        let mut context = self.context_stack.last_mut().unwrap();

        if let Some(BracedNamespace { name: Some(SimpleIdentifier { value, .. }), .. }) = downcast::<BracedNamespace>(node) {
            let mut namespace = ByteString::from(b"\\");
            namespace.extend(&value.bytes);
            context.set_namespace(namespace);
        }

        if let Some(UnbracedNamespace { name: SimpleIdentifier { value, .. }, .. }) = downcast::<UnbracedNamespace>(node) {
            let mut namespace = ByteString::from(b"\\");
            namespace.extend(&value.bytes);
            context.set_namespace(namespace);
        }

        if let Some(GroupUseStatement { prefix, uses, .. }) = downcast::<GroupUseStatement>(node) {
            for Use { name, .. } in uses {
                let mut prefixed_name = prefix.value.clone();
                prefixed_name.extend(b"\\");
                prefixed_name.extend(&name.value.bytes);

                context.add_import(prefixed_name);
            }
        }

        if let Some(UseStatement { uses, .. }) = downcast::<UseStatement>(node) {
            for Use { name, .. } in uses {
                let mut qualified_name = ByteString::from(b"\\");
                qualified_name.extend(&name.value.bytes);
                context.add_import(qualified_name);
            }
        }

        for rule in &mut self.rules {
            if rule.should_run(node) {
                rule.run(node, &self.definitions, &mut self.message_collector, &mut context);
            }
        }

        Ok(())
    }
}

There's some code duplication from the DefinitionCollector here but we can come back to tidy this up later on. This does fix the issue with importing functions from other namespaces, which is perfect!

Native Functions

If we try to analyse the following PHP code:

abs(-1);

The analyser will currently tell us that the function abs() doesn't exist. But what's the problem? That function is a native PHP one, it should definitely exist! Well, the issue is our DefinitionCollector isn't able to detect native PHP functions because they're not defined anywhere in the PHP code of our project.

Thankfully this is something that other tools have also encountered in the past, which means there are stub PHP files available with all of PHP's native functions, classes, interfaces, etc.

PHPStan has a public repository with a collection of stubs automatically taken from PHP's codebase. There are a couple of ways we can get the analyser to scan for these files:

1. Embed the files inside of the binary at compile-time.
2. Require the stubs package as part of our project and let the DefinitionCollector handle them like regular PHP files.

I'm going to opt for the second approach to keep things simple. Embedding the files is slightly more complicated and requires using a third-party crate to embed directories, since Rust only supports embedding single-files out of the box.

A quick composer command will bring those stubs into our project.

composer require phpstan/php-8-stubs --dev

Trying to analyse that same PHP code now will expose another problem. The definition collector doesn't have support for all of PHP's types just yet. Now is a good time to start adding some more types in, so let's do that.

We first want to identify what types are missing, so instead of just doing a todo!() we can add some additional information to the output.

fn map_type(&self, data_type: Option<&ParsedType>) -> Option<Type> {
    data_type.map(|t| match t {
        ParsedType::Named(_, name) => Type::Named(self.resolve_name(name)),
        ParsedType::Float(_) => Type::Float,
        ParsedType::Boolean(_) => Type::Bool,
        ParsedType::Integer(_) => Type::Int,
        ParsedType::String(_) => Type::String,
        ParsedType::Array(_) => Type::Array,
        ParsedType::Mixed(_) => Type::Mixed,
        _ => todo!("unhandled type: {:?}", t),
    })
}

And after running the analyse command and adding any missing types, we end up with this:

#[derive(Debug, Clone)]
pub enum Type {
    String,
    Int,
    Float,
    Array,
    Mixed,
    Bool,
    Object,
    Void,
    False,
    True,
    Null,
    Callable,
    Static,
    Iterable,
    Nullable(Box<Self>),
    Named(ByteString),
    Union(Vec<Self>),
}

fn map_type(&self, data_type: Option<&ParsedType>) -> Option<Type> {
    data_type.map(|t| match t {
        ParsedType::Named(_, name) => Type::Named(self.resolve_name(name)),
        ParsedType::Float(_) => Type::Float,
        ParsedType::Boolean(_) => Type::Bool,
        ParsedType::Integer(_) => Type::Int,
        ParsedType::String(_) => Type::String,
        ParsedType::Array(_) => Type::Array,
        ParsedType::Mixed(_) => Type::Mixed,
        ParsedType::Void(_) => Type::Void,
        ParsedType::Object(_) => Type::Object,
        ParsedType::Nullable(_, data_type) => Type::Nullable(Box::new(self.map_type(Some(data_type)).unwrap())),
        ParsedType::Union(data_types) => {
            let mut types = Vec::new();

            for data_type in data_types {
                types.push(self.map_type(Some(data_type)).unwrap());
            }

            Type::Union(types)
        },
        ParsedType::False(_) => Type::False,
        ParsedType::True(_) => Type::True,
        ParsedType::Null(_) => Type::Null,
        ParsedType::Callable(_) => Type::Callable,
        ParsedType::StaticReference(_) => Type::Static,
        ParsedType::Iterable(_) => Type::Iterable,
        _ => todo!("unhandled type: {:?}", t),
    })
}

There are still some types missing, such as never and intersection types, those will be added when we need them.

Analysing the abs() example once more, no messages are added and we can now successfully analyse PHP's native functions.

Next steps

Now that we have some of the base level work done for analysis, the next part will start to focus on storing variables types inside of Context. We'll start to analyse expressions and calculate the return type of an expression based on the it's type.

All of the code for this part can be found on GitHub.

The best way to do this in the form of a trait. Traits in Rust behave like a mixture of PHP's abstract classes and interfaces. You can define contractual methods that the implementing structure must define, whilst also providing default implementations for methods.

Let's think about what our Rule will need to do.

The first thing Rule needs to do is check whether or not it should be executed for a particular statement or expressions in the AST. Let's call this method should_run().

pub trait Rule: Debug {
    fn should_run(&self, node: &dyn Node) -> bool;
}

The second method will be responsible for actually checking the Node. We'll keep it simple and only pass in the Node and DefinitionCollection since we don't have any form of Scope just yet.

pub trait Rule: Debug {
    fn should_run(&self, node: &dyn Node) -> bool;
    fn run(&mut self, node: &dyn Node, definitions: &DefinitionCollection);
}

Right now, the run() method doesn't need to return anything. Soon enough, it will be able to write error messages to some sort of buffer that will later be output in the console.

With the Rule trait in place, we should create a generic Analyser structure that stores all of the registered rules. The rules will be stored inside of a Vec<Box<dyn Rule>>.

#[derive(Debug)]
pub struct Analyser {
    pub rules: Vec<Box<dyn Rule>>,
}

Let's also add some helper methods to make registering rules easier.

impl Analyser {
    pub fn new() -> Self {
        Self {
            rules: Vec::new(),
        }
    }

    pub fn add_rule(&mut self, rule: Box<dyn Rule>) {
        self.rules.push(rule);
    }
}

The API here is a little annoying since you're required to wrap the Rule in a Box yourself, but I'm okay with that.

Now that we have an Analyser, we can provide it with the DefinitionCollection that we have already obtained. This will be provided via the constructor.

impl Analyser {
    pub fn new(definitions: DefinitionCollection) -> Self {
        Self {
            rules: Vec::new(),
            definitions,
        }
    }

    // ...
}

Let's also initialise an Analyser in the command handler.

pub fn run(_: AnalyseCommand) {
    let files = discoverer::discover(&["php"], &["."]).unwrap();
    let mut collector = DefinitionCollector::new();

    for file in files {
        let contents = std::fs::read(&file).unwrap();
        let mut ast = pxp_parser::parse(&contents).unwrap();

        collector.scan(&mut ast);
    }

    let collection = collector.collect();
    let mut analyser = Analyser::new(collection);
}

We should also start to think about an API for storing errors and messages from the analyser. This structure will be passed along to each Rule that gets executed and will be used to push messages to the output. For now, we can call this the MessageCollector.

#[derive(Debug)]
pub struct MessageCollector {
    file: String,
    messages: Vec<String>,
}

impl MessageCollector {
    pub fn new(file: String) -> Self {
        Self {
            file,
            messages: Vec::new(),
        }
    }

    pub fn add(&mut self, message: impl Into<String>) {
        self.messages.push(message.into());
    }
}

Each file that gets analysed will have it's own MessageCollector. Those will then get collected into their own Vec<MessageCollector> that we can iterate over to output in the terminal.

impl Analyser {
    //...

    pub fn analyse(&mut self, file: String, contents: &[u8]) -> MessageCollector {
        let mut message_collector = MessageCollector::new(file);

        let parse_result = parse(contents);
        if let Err(error) = parse_result {
            message_collector.add(error.to_string());
            return message_collector;
        }

        let mut ast = parse_result.unwrap();

        return message_collector;
    }

    // ...
}

The Analyser is now able to accept a filename and the contents of that file, parse it and return a MessageCollector. We're starting to do a little bit of error handling now too.

If the parser fails and returns an Err(ParseError), we can convert the ParseError to a string, add it to the MessageCollector and output the error in the console.

Let's hook this up to the command to see if the parser errors are produced correctly.

pub fn run(args: AnalyseCommand) {
    let files = discoverer::discover(&["php"], &["."]).unwrap();
    let mut collector = DefinitionCollector::new();

    for file in files {
        let contents = std::fs::read(&file).unwrap();
        let mut ast = pxp_parser::parse(&contents).unwrap();

        collector.scan(&mut ast);
    }

    let collection = collector.collect();
    let mut analyser = Analyser::new(collection);

    let contents = read(&args.file).unwrap();
    let messages = analyser.analyse(args.file, &contents);

    dbg!(messages);
}

If we create a bad PHP file with a syntax error:

<?php

1 +

This should produce a parser error.

cargo run -- analyse ./playground/parse-error.php

[src/cmd/analyse.rs:27] messages = MessageCollector {
    file: "./playground/parse-error.php",
    messages: [
        "[E002] Error: unexpected end of file on line 3 column 4\n",
    ],
}

And there we go! The parser error is now being added to the collector. The formatting of that error could use a little love still, since it's using the format that the parser provides out of the box but that's a problem for a future version of me.

Next steps

In the next part, we'll start to actually write our first Rule and add in the necessary bits and pieces to make that work.

All of the code for this step can be found on GitHub.

Let's start by installing the parser. We'll be using the PXP parser since it is a superset and supports all of PHP as well as extended language features for PXP. It's also less work to use this parser now, as opposed to using the regular PHP one and changing to the PXP one in the future.

cargo add pxp-parser --git https://github.com/pxp-lang/parser --branch main

The PXP parser hasn't had official releases at this point in time, so we'll pull it from GitHub.

Discovering files

This early in development, we can make some basic assumptions to make things easier. In this instance, we'll assume that the command is being executed from the root of a project, such that ./vendor is a valid path.

With this assumption in mind, to start discovering files, we need to recursively search the current directory for PHP files. Thankfully I've already developed a crate to do just this, so it's time to get it installed.

cargo install discoverer

It's also time to make a new module in the project to store any code related to definitions and their discovery. The new file will be src/definitions/mod.rs.

To get a list of file paths, we just need to call the discoverer::discover() function. Let's do that inside of the analyse::run() function.

let files = discoverer::discover(&["php"], &["."]).unwrap();

We're looking for php files in the current directory (.). There's a lack of error handling here but that's okay for now.

Parsing files

Before we start writing the DefinitionCollector logic, we need actually parse the files we've discovered.

let files = discoverer::discover(&["php"], &["."]).unwrap();

for file in files {
    let contents = std::fs::read(&file).unwrap();
    let ast = pxp_parser::parse(&contents).unwrap();
}

The initial implementation of the analyser is going to be purely synchronous, so we don't need to worry about processing files in parallel or anything like that. We can write incredibly crude code and come back to optimise later.

The pxp_parser::parse() function essentially accepts anything that can be converted into &[u8]. In our case, we're reading the file into a Vec<u8> which can be converted into a slice. The parser will do its thing and return a Result<Vec<Statement>, ParseError>. Remember, there's no error handling just yet so we'll .unwrap() and assume everything is okay.

DefinitionCollector

Now that we've got an AST for a given file, we can start to collect definitions. This will be handled by a single structure named DefinitionCollector. The AST for each file will be passed along to a method on the structure and the nodes will be analysed.

If you remember from the overview post, there are a couple of things that the DefinitionCollector needs to keep track of - the current namespace, as well as any names imported by a use statement.

We can define the new structure like so:

use pxp_parser::lexer::byte_string::ByteString;

#[derive(Debug)]
pub struct DefinitionCollector {
    current_namespace: ByteString,
    imported_names: Vec<ByteString>,
}

Note: a small implementation detail here is that the parser doesn't store strings as String or &str. PHP source code doesn't need to be valid UTF-8. To workaround this, the parser uses a custom ByteString structure that stores characters in a Vec<u8>.

The first method the collector needs is a constructor, typically called new.

impl DefinitionCollector {
    pub fn new() -> Self {
        Self {
            current_namespace: ByteString::default(),
            imported_names: Vec::new(),
        }
    }
}

We'll initialise the current_namespace to an empty ByteString, this way we don't need to worry about unwrapping an Option and can always safely prefix a name with an empty string. The imported_names field will be empty to start with too.

While we're on the topic of constructors, we might as well create a new instance of the DefinitionCollector in the command's function and store it in a mutable variable.

use statan::definitions::collector::DefinitionCollector;

use crate::AnalyseCommand;

pub fn run(command: AnalyseCommand) {
    let files = discoverer::discover(&["php"], &["."]).unwrap();
    let mut collector = DefinitionCollector::new();

    for file in files {
        let contents = std::fs::read(&file).unwrap();
        let ast = pxp_parser::parse(&contents).unwrap();
    }
}

To actually do the collection, we'll add a scan() method to the collector as well and pass in a mutable reference to the AST. The reference needs to be mutable since that is what the parser's visitor API expects.

impl DefinitionCollector {
    pub fn new() -> Self {
        Self {
            current_namespace: ByteString::default(),
            imported_names: Vec::new(),
        }
    }

    pub fn scan(&mut self, ast: &mut Vec<Statement>) {
        
    }
}

pub fn run(command: AnalyseCommand) {
    let files = discoverer::discover(&["php"], &["."]).unwrap();
    let mut collector = DefinitionCollector::new();

    for file in files {
        let contents = std::fs::read(&file).unwrap();
        let mut ast = pxp_parser::parse(&contents).unwrap();
        
        collector.scan(&mut ast);
    }
}

Next up is traversing the given AST. The parser provides a Visitor trait that we can implement on the DefinitionCollector, the scan method will just defer everything to the visitor.

impl Visitor<()> for DefinitionCollector {
    fn visit(&mut self, node: &mut dyn Node) -> Result<(), ()> {
        Ok(())
    }
}

If you're paying attention to the code, you'll see that the visit() method receives &dyn mut Node. The parser has a special Node API that is used for various types of nodes in the AST, including statements and expressions. The benefit of using this API is that we don't need to write individual methods to handle Statement, Expression, Identifier, etc. We can use a single method and cast the node to a specific form when necessary.

We first want to check if the current node is a Namespace. We can use the parser's downcast() function to handle this, passing in a generic parameter as the target type for the cast.

impl Visitor<()> for DefinitionCollector {
    fn visit(&mut self, node: &mut dyn Node) -> Result<(), ()> {
        if let Some(BracedNamespace { name: Some(SimpleIdentifier { value, .. }), .. }) = downcast::<BracedNamespace>(node) {
            let mut namespace = ByteString::from(b"\\");
            namespace.extend(&value.bytes);
            self.current_namespace = namespace;
        } else if let Some(UnbracedNamespace { name: SimpleIdentifier { value, .. }, .. }) = downcast::<UnbracedNamespace>(node) {
            let mut namespace = ByteString::from(b"\\");
            namespace.extend(&value.bytes);
            self.current_namespace = namespace;
        }

        Ok(())
    }
}

We can take advantage of Rust's deep pattern matching capabilities to reach down into the fields on these structures and reduce some of the nested if statements that would otherwise be required. We also need to check against 2 different types of Node here since PHP has 2 ways of defining a namespace.

// Unbraced syntax
namespace Foo;

// Braced syntax
namespace Foo {
    // ...
}

With the brace syntax, it's also possible to omit the namespace's name altogether and explicitly scope the block to the global namespace. If that wasn't the case, we could match against a single pattern instead.

To make the namespaces fully-qualified, we also need to prepend a single \ to the name.

PHP also has a couple of ways to import names.

// Single use statement.
use Foo\Bar;

// Multi-use statement.
use Foo\Bar, Foo\Baz;

// Grouped use statement.
use Foo\{Bar, Baz};

You can also specifically import function and const types, but the definition collector doesn't really care about those because it's not possible to use those as parameter types, return types, etc, but the variance in syntax will mean we need to handle a couple of different statement types again.

if let Some(GroupUseStatement { prefix, uses, .. }) = downcast::<GroupUseStatement>(node) {
    // ...           
}

if let Some(UseStatement { uses, .. }) = downcast::<UseStatement>(node) {
    // ...
}

Both of these statements contain a Vec<Use>, the only extra bit of logic needed for GroupUseStatement is prefixing. It should be easy to start putting names into the list of imported_names.

if let Some(GroupUseStatement { prefix, uses, .. }) = downcast::<GroupUseStatement>(node) {
    for Use { name, .. } in uses {
        let mut prefixed_name = prefix.value.clone();
        prefixed_name.extend(b"\\");
        prefixed_name.extend(&name.value.bytes);

        self.imported_names.push(prefixed_name);
    }
}

if let Some(UseStatement { uses, .. }) = downcast::<UseStatement>(node) {
    for Use { name, .. } in uses {
        let mut qualified_name = ByteString::from(b"\\");
        qualified_name.extend(&name.value.bytes);
        self.imported_names.push(qualified_name);
    }
}

Definitions

There's a couple of ways we could structure the definitions themselves. We could create a Definition enumeration that has members for each type of definitions, or we could create separate structures for each type of definition and store them in separate fields.

I personally prefer the second option since it should improve lookup time by reducing the number of items that needs to be filtered through. Let's start with the simplest definition, a FunctionDefinition.

#[derive(Debug)]
pub struct FunctionDefinition {
    pub name: ByteString,
    pub parameters: Vec<Parameter>,
    pub return_type: Option<Type>,
}

Functions have parameters, so we'll need a structure for that too.

#[derive(Debug)]
pub struct Parameter {
    pub name: ByteString,
    pub type_: Option<Type>,
}

As well as a Type enumeration that will represent all the types that are analyser understands. The parser does have it's own Type enum too, but it won't support everything we need at this point.

#[derive(Debug)]
pub enum Type {
    String,
    Int,
    Float,
    Array,
    Mixed,
    Bool,
    Named(ByteString),
}

The Type enumeration will only support PHP's most basic types for now. Adding support for unions, intersections and more importantly generics will be easy to do later on.

We'll also need somewhere to store the definitions. Let's create a DefinitionCollection.

#[derive(Debug)]
pub struct DefinitionCollection {
    functions: Vec<FunctionDefinition>,
}

The DefinitionCollector can now hold a single DefinitionCollection and we'll start to push add some items to it.

#[derive(Debug)]
pub struct DefinitionCollector {
    current_namespace: ByteString,
    imported_names: Vec<ByteString>,
    collection: DefinitionCollection,
}

impl DefinitionCollector {
    pub fn new() -> Self {
        Self {
            current_namespace: ByteString::default(),
            imported_names: Vec::new(),
            collection: DefinitionCollection::default(),
        }
    }

    // ...
}

To make the API a little nicer, we can define an add_function() method on the collection.

impl DefinitionCollection {
    pub fn add_function(&mut self, function: FunctionDefinition) {
        self.functions.push(function);
    }
}

In the collector, we need to check if the current node is a FunctionStatement. If it is, we can start to add information to a FunctionDefinition and store it inside of the collection.

if let Some(FunctionStatement { name, parameters, return_type, .. }) = downcast::<FunctionStatement>(node) {
    let name = self.qualify_name(&name.value);
    let parameters = parameters.parameters.inner.iter().map(|p| {
        Parameter {
            name: p.name.name.clone(),
            type_: self.map_type(p.data_type.as_ref()),
        }
    }).collect::<Vec<Parameter>>();
    let return_type = if let Some(ReturnType { data_type, .. }) = return_type {
        self.map_type(Some(data_type))
    } else {
        None
    };

    self.collection.add_function(FunctionDefinition { name, parameters, return_type })
}

We first convert the function's name into a qualified name. The list of function parameters are then converted into Parameter values. If the function has a return type, we also map that into the analyser's own Type enumeration.

A set of additional utility methods have been added as well - qualify_name(), resolve_name() and map_type().

qualify_name() simply prepends the given string with the current namespace, producing a fully-qualified name.

fn qualify_name(&self, name: &ByteString) -> ByteString {
    let mut qualified_name = self.current_namespace.clone();
    qualified_name.extend(b"\\");
    qualified_name.extend(&name.bytes);

    qualified_name
}

resolve_name() is a little more complex and handles name resolution. This isn't as simple as doing a lookup on the list of imported_names, since PHP supports a few different ways of referencing names.

You can import a single named item and reference it:

use Closure;

function invoke(Closure $closure) {}

You can also reference a fully-qualified name:

function invoke(\Closure $closure) {}

You can even import a namespace and use a qualified name.

use App\Models;

function do_something(Models\User $user) {}

And finally, if an imported name doesn't match the given identifier, we assume you're referencing something in the current namespace. The resolve_name() method handles these edge-cases.

fn resolve_name(&self, name: &ByteString) -> ByteString {
    // If the name is already fully qualified, return as is.
    if name.bytes.starts_with(b"\\") {
        return name.clone();
    }

    let parts = name.split(|b| *b == b'\\').collect::<Vec<&[u8]>>();
    let first_part = parts.first().unwrap();

    // Check each imported name to see if it ends with the first part of the
    // given identifier. If it does, we can assume you're referencing either
    // an imported namespace or class that has been imported.
    for imported_name in self.imported_names.iter() {
        if imported_name.ends_with(&first_part) {
            let mut qualified_name = imported_name.clone();
            qualified_name.extend(&name.bytes[first_part.len()..]);

            return qualified_name;
        }
    }

    // If we've reached this point, we have a simple name that
    // is not fully qualified and we have not imported it.
    // We can simply prepend the current namespace to it.
    let mut qualified_name = self.current_namespace.clone();
    qualified_name.extend(b"\\");
    qualified_name.extend(&name.bytes);

    qualified_name
}

The final utility function, map_type(), takes an Option<ParsedType> and converts it into the analyser's own Type enumeration.

match data_type {
    Some(t) => Some(match t {
        ParsedType::Named(_, name) => Type::Named(self.resolve_name(name)),
        ParsedType::Float(_) => Type::Float,
        ParsedType::Boolean(_) => Type::Bool,
        ParsedType::Integer(_) => Type::Int,
        ParsedType::String(_) => Type::String,
        ParsedType::Array(_) => Type::Array,
        ParsedType::Mixed(_) => Type::Mixed,
        _ => todo!(),
    }),
    None => None,
}

Note: There's plenty of room for optimisation in these methods but they serve their purpose right now and will allow us to move on. It's a waste of time getting bogged down in optimisation tricks this early in a project.

Now that we have some functions being stored in the collection, it makes sense to add a collect() method to the collector that returns the DefinitionCollection we've been working with.

pub fn collect(&self) -> DefinitionCollection {
    self.collection.clone()
}

Instead of messing with lifetimes and references right now, we'll use .clone(). It's not a difficult task to come back and change this later on to improve performance and memory usage.

We also need to update the scan() method to actually start traversing the AST. We can loop over the AST and pass each statement along to the Visitor implementation.

pub fn scan(&mut self, ast: &mut Vec<Statement>) {
    self.current_namespace = ByteString::default();
    self.imported_names = Vec::new();

    for statement in ast.iter_mut() {
        self.visit_node(statement).unwrap();
    }
}

It's important that we reset the current_namespace and imported_names. The DefinitionCollector won't be unique to a file so we need to reset the state between scans.

If we create 2 separate PHP files, a.php and b.php, each containing a function with their respective names and run the analyser on just one of those files, we can dump out the collection and see that both functions were discovered by the collector.

use App\Foo;

function a(Foo $foo) {}

use App\Models;

function b(Models\User $user, \Closure $closure) {}

cargo run -- analyse ./playground/a.php

We get the following output from the debug dump:

[src/cmd/analyse.rs:17] collection = DefinitionCollection {
    functions: [
        FunctionDefinition {
            name: "\b",
            parameters: [
                Parameter {
                    name: "$user",
                    type_: Some(
                        Named(
                            "\App\Models\User",
                        ),
                    ),
                },
                Parameter {
                    name: "$closure",
                    type_: Some(
                        Named(
                            "\Closure",
                        ),
                    ),
                },
            ],
            return_type: None,
        },
        FunctionDefinition {
            name: "\a",
            parameters: [
                Parameter {
                    name: "$foo",
                    type_: Some(
                        Named(
                            "\App\Foo",
                        ),
                    ),
                },
            ],
            return_type: None,
        },
    ],
}

Exactly what we expected! There are two functions in the collection and all of the parameters have been picked up correctly.

The name resolution is working too. Names referencing partially imported namespaces are fully-qualified, explicit imports are qualified and references to already fully-qualified names are resolved correctly.

Next steps

The next thing to do is replicate the logic above and do the same for classes, traits, interfaces and enumerations. It's pretty repetitive so I won't include the code in this post, but if you're interested in what the result looks like, all of the code for this part is available on GitHub.

This post will cover the basics of static analysis and layout the plan for our own engine.

What is static analysis?

Static analysis is the process of analysing source code by examining its structure and syntax, without executing the program. This type of analysis can be used to find bugs, security vulnerabilities, and other issues in your code prior to execution.

How does a static analyser work?

The majority of static analysis tools will use an abstract syntax tree (AST) that represents the lexical structure of your code. Let's take the following PHP code and produce a pseudo abstract syntax tree.

function name(): string {
    return "Ryan";
}

$name = name();

A parser will take this string of code and produce something similar to the structure below:

FunctionStatement {
    name: "name",
    parameters: [],
    return_type: "string",
    body: [
        ReturnStatement {
            value: String("Ryan"),
        }
    ],
},
ExpressionStatement {
    expression: Assign {
        target: Variable("$name"),
        value: CallExpression {
            target: Identifier("name"),
            arguments: [],
        }
    }
}

By obtaining this reusable and definitive representation of the code, a program is able to reliably look at certain properties and fields during analysis.

Finding definitions

A "definition" is any form of structure in your code that can be referenced, instantiated or invoked. In PHP's case, that would be normally be a class or function. PHP also has traits, interfaces and enumerations which would be discovered too.

The analyser will find every single PHP file in your project, including any vendor files, then send each one through some form of definition collector. The job of the collector is to parse the code, analyse the AST and find one of the structure mentioned above.

Once a definition has been found, it will be further analysed to pull out any information the analyser needs. Let's take a look at an example from a fake Laravel codebase.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use App\Models\User;

class Post extends Model 
{
    /** @return BelongsTo<User> */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

The collector will parse this file and start to recursively look at each statement.

It first encounters the namespace, taking the name and storing it to use later on. Then the use statements are seen and each of those references are temporarily stored so that fully-qualified names (FQNs) can be resolved when necessary.

Once it reaches the class statement, the collector starts to do some real work. The first thing it does is grab the name of the class and turn it into a fully-qualified name. That's done by prefixing the class name with the current namespace, i.e. App\Models\User.

Since the class inherits from Model, it also needs to resolve the fully-qualified name for that too. The first check is for any imported classes that have the name Model, which works in this case.

Whilst the collector is here, it can also start to build up some information about the methods, properties and constants on the class. That's all pretty self explanatory and follows the same general pattern as above. The result of that work is a near-flat structure of all definitions across the codebase.

[
    "App\\Models\\Class" => Class {
        name: "App\\Models\\Class",
        extends: "Illuminate\\Database\\Eloquent\\Model",
        methods: [
            "user" => Method {
                name: "user",
                visibility: Public,
                parameters: [],
                return_type: "Illuminate\\Database\\Eloquent\\Relations\\BelongsTo",
            }
        ]
    }
]

Note: the collector doesn't do any analysis of the code. It won't check for valid parent classes, return types, etc. It's purely a collection phase to find out what is defined in a project's codebase.

User code

As mentioned above, the collector will analyse your entire codebase, including any third-party dependencies found in the vendor folder. This is essential to ensure the analyser has all of the information it needs.

When it comes to actually analysing your own code though, the analyser doesn't need to waste time analysing the third-party stuff, so instead it will skip over vendor and any other ignored paths and focus solely on the code that you've written.

Once again, the analyser will build up a list of files in your project and start to analyse each one independently. Most engines will provide a "rule" API that is used to separate out the logic for each check in the analyser.

The rule itself will respond to a particular type of node in the AST and only execute its logic on that node. Let's write a rule with some pseudo PHP code to check that the arguments passed to a function are the correct type so that we can explore the various APIs available to a rule.

function add(int $a, int $b): int {
    return $a + $b;
}

add("one", 2);

Let's pretend the AST produces a CallExpression for the function call to add(). Our rule will need to tell the analyser that it only cares about that particular type of expression.

class FunctionArgumentRule implements Rule
{
    public function shouldRun(Node $node): bool
    {
        return $node instanceof CallExpression;
    }

    public function run(Node $node, Scope $scope, Reporter $reporter): void
    {
        // Analysing calls to anonymous function requires a little
        // more work, so we'll skip those for now.
        if (! $node->target instanceof SimpleIdentifier) {
            return;
        }

        $definition = $scope->getFunction($node->target);

        // In the case where we can't find the definition,
        // we can return early to avoid any errors below.
        // A separate rule will handle these invalid calls.
        if ($definition === null) {
            return;
        }

        $parameters = $definition->getParameters();

        if (count($node->arguments) < count($parameters)) {
            $reporter->report(
                sprintf('Function %s expects %d arguments, only got %d.', $node->target->value, count($parameters), count($node->arguments))
            );
        }

        // As this is just an example, we'll assume that all 
        // of the arguments being passed to the function are
        // positional and ignore any named arguments.
        foreach ($definition->getParameters() as $position => $parameter) {
            $parameterType = $parameter->getType();

            if ($parameterType === null || $parameterType->isMixed()) {
                continue;
            }

            $argument = $node->arguments[$position];
            $argumentType = $scope->getTypeOfExpression($argument);

            if (! $parameterType->isCompatibleWith($argumentType)) {
                $reporter->report(
                    sprintf('Argument #%d (%s) must be of type %s, got %s.', $position, $parameter->getName(), $parameterType->stringify(), $argumentType->stringify())
                );
            }
        }
    }
}

With this pseudo-analyser API, you can begin to see how the analyser works under-the-hood.

The rule will receive some sort of "scope" or "environment" object that stores information about where the node is located. It holds informations about the variables in the scope, the types of variables and can be used to find definitions.

Searching for definitions is also important since that will be at the core of most typechecking rules. The scope will have a reference to the definitions collected earlier on in the process and be able to do arbitrary lookups when necessary.

It will first check to see if a function exists in the current namespace, e.g. in the namespace App, a call to function foo() will first check for a function with the fully-qualified name App\foo.

If that function doesn't exist, it will then check for any imported functions with the name foo, e.g. use function Package\foo. Finally, it will look for a function defined in the global namespace called foo - this is normally where a lookup will land when analysing native PHP functions.

Most analysers will have a standardised API for representing types as well. There could be dedicated objects for PHP's scalar types (string, int, etc) and then more complex objects for generic types like Collection<T> or array<K, V>. It's important that these types are able to validate their own compatibility with another type object and be able to handle inheritance, etc.

Another detail in the pseudo-implementation above is the Reporter. This object is purely used for reporting issues / errors back to the user and will generally be scoped to the current file being analysed.

Why write another static analyser?

With a lot of existing art in this area (PHPStan, Psalm, Phan, etc), you might be wondering to yourself "Why write another static analyser?"... that's an excellent question! There's been a huge boom in the JavaScript ecosystem over the last few years with lots of new tools being written in lower-level languages such as Rust, Go and Zig. The same boom is yet to happen in the PHP ecosystem and I'd like to be one of the first catalysts in that movement.

By choosing a language such as Rust for a tool, you can bring memory safety and excellent performance to the table. PHP has improved a lot in the performance department over the years, but it will never reach the speeds of a systems programming language.

Alongside the speed and memory safety, I'm also developing a superset of PHP called PXP. Part of this project involved writing a PHP parser in Rust and an extension of that parser to support the new superset. Given I already have a huge chunk of the work done, it makes sense to continue on this path and write more tools in Rust, not only as a learning experience for me but for all readers too.

The static analyser itself will play a big part in PXP's transpiler and allow us to do all sort of crazy things.

I'm not a Rust expert, but I've been using it for long enough now that I'm able to take on the challenge of writing these larger, complex systems.

The plan for this analysis engine

The rest of this series will cover the various phases in writing a static analyser. Before I get too far into the project itself, it's a good idea to come up with a plan of action and figure out the milestones and goals.

The initial goal for the analysis engine it to replicate PHPStan's lowest level of analysis (configuration on GitHub). This includes the following:

• Validating function calls (function exists, number of arguments, argument types)
• Validating class instantiation (class exists, number of constructor arguments, argument types)
• Validating inheritance (ensuring parent class exists, abstract methods implemented)
• Validating interface implementations (ensuring interface exists, contract methods implements)
• Validating enums (missing backed type, validating case values, no abstract methods, no __toString())
• Validating method calls (static and instance methods, number of arguments, argument types)
• Validating mathematical operations between invalid types, e.g. string + int.

All development will be open-source and available on GitHub. A link to the repository will be provided in the next post.

Epilogue

I'm excited to start working on this project and see where it goes. I hope that you'll learn a thing or two about static analysis and Rust, perhaps you'll even contribute to the project at some point.

Posts will likely come out once a week to allow for development time in between, as well as any feedback from readers and those interested.

The goal is to get a boilerplate Rust project created, install clap and scaffold out a couple of commands.

In typical developer fashion, we need to the most important thing first and think of a name for the project. Let's go with Statan.

cargo new statan

This will generate a statan folder with Cargo setup and a basic main.rs file.

There are quite a few options when it comes to argument parsing and command-line libraries in Rust. The most popular one is Clap, so we'll be using that. It can be installed with Cargo:

cargo add clap --features derive

We'll want the derive feature enabled so that we can use Clap's derive macros, dramatically simplifying the setup process.

The first step in setting up Clap is creating a struct to hold the command-line arguments.

use clap::Parser;

#[derive(Debug, Parser)]
struct Arguments {

}

fn main() {
    let arguments = Arguments::parse();
}

The CLI will be subcommand based. Thankfully, Clap provides a Subcommand macro that we can attach to an enumeration and it'll handle the rest.

use clap::{Parser, Subcommand};

#[derive(Debug, Parser)]
struct Arguments {
    #[clap(subcommand)]
    command: Command,
}

#[derive(Debug, Subcommand)]
enum Command {
    #[clap(about = "Analyse a file.")]
    Analyse,
}

fn main() {
    let arguments = Arguments::parse();
}

If we run the cargo run -- --help command, the analyse command should show up in the output.

Usage: statan <COMMAND>

Commands:
  analyse  Analyse a file.
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

And if we run cargo run -- analyse --help, there will be some basic output too:

Analyse a file.

Usage: statan analyse

Options:
  -h, --help  Print help

The first iteration of the analyse command will only support analysing a single file. To add the argument to the command, all we need to do is add a field to the Command::Analyse member with a macro.

#[derive(Debug, Subcommand)]
enum Command {
    #[clap(about = "Analyse a file.")]
    Analyse(AnalyseCommand)
}

#[derive(Debug, Parser)]
pub struct AnalyseCommand {
    #[clap(help = "The file to analyse.")]
    file: String,
}

Each command will have it's own module in the application exposing a single run function. I typically like to place them under src/cmd/[cmd].rs.

The main function needs to be updated to defer handling to the correct function.

use clap::{Parser, Subcommand};

mod cmd;

// ...

fn main() {
    let arguments = Arguments::parse();

    match arguments.command {
        Command::Analyse(args) => cmd::analyse::run(args),
    }
}

The src/cmd/analyse.rs file contains the function itself:

use crate::AnalyseCommand;

pub fn run(command: AnalyseCommand) {
    
}

And the help output for the subcommand reflects the new argument:

Analyse a file.

Usage: statan analyse <FILE>

Arguments:
  <FILE>  The file to analyse.

Options:
  -h, --help  Print help

Just like that, we've got a simple command-line interface to our new program. In the next part, we can start writing the business logic behind the analyser.

The code for this part is public and can be found on GitHub.

Not much has happened in my personal life this year. We're due to move house again soon, but other than that nothing major has changed.

Work

I'm still a full-time developer at Surewise. I've spent 2022 working on new systems and improving existing ones. We're continuing to adopt Livewire and Alpine.js across our stack.

We did upgrade to PHP 8.1 this year and will be looking to upgrade to PHP 8.2 early in 2023.

Freelance

My freelance adventures continued into 2022 and I've kept up with last years pace quite well. This will continue into 2023 as well as I continue to work on TALL related projects.

Open-source

It's been a bit of a quiet year on the OSS side of things. I've continued to maintain my projects and packages on GitHub and have started working on a couple of new ones.

With my day job and freelance work, it's sometimes hard to find time for OSS work. When I do get time to work on non-work related things, I tend to focus on passion projects and things that I'm interested in.

The most noteworthy project that I've worked on this year is probably a PHP parser written in Rust. I broke ground on this project in July and worked on it here and there. The progression has increased dramatically over the last month or so with some help from Saif (azjezz) who has done lots of refactoring on the project and several optimizations, as well as adding support for things that were missing. So thank you!

My goal in 2023 is to explore the realm of Rust-powered tooling for PHP even more. I've got a "small" list of projects, some of which I've already started to experiment with:

• Linter
• Code formatter
• Static analysis
• Superset

Our cousins in JavaScript-land have been taking advantage of faster tooling for a couple of years now and there's been very few attempts at doing the same for PHP. I'd like to be the pioneer of this effort and take the first steps into this unexplored realm of productive PHP tooling.

Epilogue

As always, I want to say a huge thank you to everybody who has supported my OSS work, blog posts and sponsored me on GitHub. The continued support helps maintain my existing projects and packages, as well the development of new ones.

I set some more goals last year, I managed to complete one of those:

• Reach 5,000 followers on Twitter.

I definitely wrote some more blog posts and streamed on YouTube but the consistency wasn't great.

I won't set myself any content related goals for 2023, but I would still like to speak at a conference. That would be pretty cool.

We'll see how that turns out in 2023.

Despite all of that, there are definitely still things that I'd personally like to see added to PHP. In this blog post, I'd like to cover a few of those things and provide some idealistic code snippets of what those features might look like.

1. Type aliases

A type alias is a way of giving a new name to an existing type, or set of types. They can sometimes improve readability in your code through more definitive naming and reduce duplication.

They can be found in languages such as TypeScript and Rust. Below is an example of what I imagine type aliases to look in PHP, in the context of a Filament trait where we tend to have lots of union types.

type LabelValue = string | null | Closure;

trait HasLabel
{
    protected LabelValue $label;

    public function label(LabelValue $label): string
    {
        $this->label = $label;

        return $this;
    }

    public function getLabel(): string
    {
        return $this->evaluate($this->label);
    }
}

The type alias above is what you would call "transparent". This means that at runtime, the type LabelValue is treated exactly the same as string | null | Closure.

The transparency of the type means that you could alias string to something like Name and still be able to pass is to another function that expects a string.

The opposite to a transparent type alias is an opaque one. An example of a language with opaque type aliases is Hack. The major difference between a transparent and opaque type is how the underlying value is treated by the type system.

type Counter = int;

The Counter type above is essentially a regular int. If the language treated this as an opaque type, you wouldn't be allowed to do any normal integer operations on the value since the type assigned to the value would be Counter, not int. No addition, subtraction, etc allowed.

With the introduction of union, intersection and DNF types (PHP 8.2), type aliases could be a huge step forward when it comes to code deduplication and clarity.

2. Multi-line match arms

The match expression was introduce in PHP 8.0 and is a nicer way of conditionally doing something or computing a value based on a subject or result of an expression.

(I have a whole blog post about match expressions if you want to read it)

Most people compare match expressions to switch statements. In a lot of cases they have the same result, with the added benefit of being more performant and concise.

The one drawback of match expressions is that you're limited to just a single expression in the "result" side of an arm.

$name = "Ryan";

match ($name) {
    "Ryan" => "Hey, I know you!",
};

The right-hand side of that double arrow can only be a single expression. You can't put a block of code and return a value, perhaps with further condition checks.

In an ideal world, you'd be able to do something like this:

match ($foo) {
    "bar" => {
        if ($baz) {
            // Do something here.
        }

        // Do something else and return a value.
    }
}

The original RFC for match expressions did briefly mention blocks of code on the right-hand side, but the semantics are difficult to get right.

Rust has implicit returns where you omit the semi-colon at the end of a statement, but PHP doesn't have that kind of behaviour anywhere else in the language.

You could allow using return to return a value from the block, but that's kind of confusing since return is explicitly for functions.

My own personal suggestion would be using yield. This keyword is already used to return a value from a block of code (generator functions) back to the caller / iterator, such that you're not actually returning and exiting from the function itself.

It would make perfect sense to use the same keyword in this scenario, since you are in fact yielding a value out of the block without returning from the lexical scope where the match expression is being used. The intent is clear, especially compared to implicit returns (sorry, Rust).

$message = match ($name) {
    "Ryan" => {
        if (logged_in()) {
            yield "Welcome back, Ryan";
        }

        yield "Hey Ryan, you need to log in again!";
    }
};

echo $message;

If this syntax and functionality eventually made it into the language, there's no reason you couldn't take it a step further and allow "yielding blocks" elsewhere like variables assignments.

$message = {
    if ($foo) {
        yield $bar;
    }

    yield $baz;
};

I'm interested in what people actually think about this syntax. I'd be very open to submitting an RFC and prototyping an implementation. Let me know on Twitter.

3. Generics

I know, I know. People have been banging on about generics in PHP for years. There has been an RFC, plenty of discussion and research on GitHub and even OSS attempts at bringing it to the language with tooling. I'm sure you can cope with me banging on about it for a few more minutes.

PHP's type system has come a long way since the release of PHP 7.0. We can type function parameters, class properties, return types, the lot. We don't have a need for doc comments in these cases anymore, if anything they just add noise.

/**
 * @template T
 */
final class Collection
{
    /**
     * @var array<T>
     */
    private array $values = [];

    /**
     * @param T $value
     */
    public function push(mixed $value): self
    {
        $this->values[] = $value;

        return $this;
    }

    /**
     * @return array<T>
     */
    public function all(): array
    {
        return $this->values;
    }
}

It's all visual noise. Sure, it gives you static type-safety when you use PHPStan, but it could all be more concise. Compare it to this:

final class Collection<T>
{
    protected array<T> $values = [];

    public function push(T $value): self
    {
        $this->values[] = $value;
    }

    public function all(): array<T>
    {
        return $this->values;
    }
}

That's 50% less lines of code, just in one file. Let's take a look at how you'd instantiate one of these generic classes with both syntaxes.

With the doc comment syntax, instantiation looks like a normal new expression.

$users = new Collection();

If you wanted to specify the type of the collection at this point, you'd need yet another comment above the variable.

/**
 * @var Collection<User>
 */
$users = new Collection();

Compare that to the "native" looking syntax:

$users = new Collection<User>();

Let's go one level deeper again. What if you had this collection and wanted to pass it to a method somewhere?

class CollectionFriend
{
    /**
     * @param Collection<User> $collection
     */
    public function doSomethingWithUserCollection(Collection $collection)
    {
        //
    }
}

And another doc comment. The "native" syntax?

class CollectionFriend
{
    public function doSomethingWithUserCollection(Collection<User> $collection)
    {
        //
    }
}

It's clearer and cleaner.

Moving away from the syntax side of things, let's talk about the implementation strategy.

There are a few ways that generics can be implemented in programming languages - monomorphization, reification and type erasure.

Monomorphization

This is an automated process that takes your generic usage of a class and creates an additional dedicated class, specifically typed against the generic parameters at compile / runtime.

In the case of our Collection<User>, anytime you reference that specific type of collection, PHP will replace it will an identical class called Collection_User for example. Everywhere you use T (in methods, properties, etc), it will get replaced with User. This is the approach that Rust takes with generics and for a compiled language it's not a huge deal because your program is already being compiled, so there's less overhead on real runtime performance.

Reificiation

This process is closer to how PHP's type system currently operates. If you had a function that accepted a string, PHP will evaluate the type of the argument at runtime and throw a type error if it's wrong.

Reified generics would do the exact same thing. PHP would keep track of the type of value inside of our Collection and if we tried to push something that wasn't a User, it would throw a type error.

There's still some performance and memory overhead here because PHP is going to keep track of more things at runtime and need to do deeper type checking.

Type erasure

Python recently got support for static typing through the typing module and it uses type erasure to remove all of those types at runtime and only check them at compile time / with static analyzers.

In reality, this is going to be only option that has near-zero impact on runtime performance since PHP won't ever check the generic types when you interact with them. It'll forget about them and perhaps just check that the object is of the correct type, the same way it does now.

The natural follow-up question to this approach is "Why bother putting the types there if they're not going to be checked by PHP anyway?"

Excellent question! Here's my answer...

If you're already in a scenario where you're using doc comments to create generic classes, then I can almost guarantee that you're also using a static analyzer outside of PHP (PHPStan, Psalm, Phan, etc).

Type erased generics will behave the exact same way as your existing doc comments, with the exception that it's naturally all part of the language's syntax instead.

4. Pattern matching on value types

I'm sure you've written quite a few is_array(), is_string() or $var instanceof SomeClass checks before. My biggest gripe with these checks is the inconsistency between checking non-object types such as strings and integers and object types.

if ($var is int|array) {
    //
}

This would be equivalent to the below.

if (is_int($var) || is_array($var)) {
    
}

You'd essentially have this sort of syntax:

<subject> is <type_string>

Where the type string is any valid type you can add to a parameter, property or return type.

Summary

And that's my short list of a few things I'd like to see added to PHP in the future.

Out of the 4 things above, the least likely is probably generics. The most likely additions are pattern matching on values types (RFC) and multi-line match arms.

If you weren't already aware, I'm currently working on a PHP parser written in Rust. One of my goals with this parser is to fully support the PHP language but also add extensions behind feature flags to support things such as generics, type aliases, etc.

I've started a GitHub organisation which will be the home for all of these endeavours, so follow along if you're interested.

One way of tackling this in application code is by caching things, whether it's a database query, call to an external service or some heavy computational logic. Out of the box, Blade doesn't have any caching mechanism beyond pre-compiling templates into plain PHP.

That's where my blade-cache-directive package comes into play! With this package you can cache a chunk of your Blade template and avoid unnecessary recompilation in future renders.

Begin by installing the package with Composer.

composer require ryangjchandler/blade-cache-directive

Now find the part of your Blade template that you'd like to cache and wrap it in a @cache directive.

@cache('heavy-bit-of-blade')
    @foreach($someLargeArray as $_)
        {{-- ... --}}
    @endforeach
@endcache

And now your Blade is being cached. The default TTL (time to live) set by the package is 3600 seconds, or 60 minutes. If you want to change this, you can pass a second argument to the directive.

@cache('heavy-bit-of-blade', 60)
    @foreach($someLargeArray as $_)
        {{-- ... --}}
    @endforeach
@endcache

Now it will only be cached for 60 seconds. Valid values for the TTL are the same as Laravel's own Cache methods.

One more thing to note. Since this package uses Laravel's Cache setup, clearing the cached chunk of Blade is as simple as calling Cache::forget('heavy-bit-of-blade') or clearing the application cache on deployment.

You can read more about this package on GitHub.

Adding them to your Laravel application is incredibly simple thanks to my ryangjchandler/laravel-feature-flags package.

Begin by installing the package with Composer and running the migrations:

composer require ryangjchandler/laravel-feature-flags
php artisan vendor:publish --tag="feature-flags-migrations"
php artisan migrate

This will create a new feature_flags table in your application's database.

All methods are called through the RyanChandler\LaravelFeatureFlags\Facades\Features facade. To create your first flag, call Features::add().

use RyanChandler\LaravelFeatureFlags\Facades\Features;

Features::add('show-share-buttons');

This will create a global feature flag called show-share-buttons. To check if this flag is enabled or disabled, you can use the Features::enabled() and Features::disabled() methods.

if (Features::enabled('show-share-buttons')) {
    // ...
}

It's probably quite common to conditionally render parts of your Blade templates based on a feature flag. The package also provides a Blade directive that simplifies things.

@feature('show-share-buttons')
    <a href="https://twitter.com">
        Twitter
    </a>
@endfeature

Changing the state of a flag

To change the state of a flag, use the Features::enable() and Features::disable() methods.

Features::enable('show-share-buttons');
Features::disable('show-share-buttons');

These methods use an updateOrCreate() call behind the scenes so if the flag doesn't exist, it will be created automatically.

If you simply want to toggle the state of a flag, i.e. via a button click, you can use the Features::toggle() method instead.

Model flags

All the examples so far have shown you how to handle global flags. There will definitely be cases where you want flags to be scoped to a single model, e.g. a User or Team.

To keep the API and method calls consistent, the package takes advantage of named arguments to create a modifiable method signature. This means that all of the method calls mentioned above will still work for models, you just need to provide a named for argument and model that implements the RyanChandler\LaravelFeatureFlags\Models\Contracts\HasFeatures interface.

Here's an example of a User model that is compatible.

use RyanChandler\LaravelFeatureFlags\Models\Contracts\HasFeatures;

class User extends Authenticatable implements HasFeatures
{
    // ...
}

This interface defines a few methods that need to be implemented on the class. To save you the hassle of writing them yourself, you can use the RyanChandler\LaravelFeatureFlags\Models\Concerns\WithFeatures trait to implement the methods for you.

use RyanChandler\LaravelFeatureFlags\Models\Contracts\HasFeatures;
use RyanChandler\LaravelFeatureFlags\Models\Concerns\WithFeatures;

class User extends Authenticatable implements HasFeatures
{
    use WithFeatures;
}

You can now call all of the same methods on Features and provide a named for argument.

Features::add('show-social-buttons', for: $user)
Features::enable('show-social-buttons', for: $user)
Features::disable('show-social-buttons', for: $user)
Features::toggle('show-social-buttons', for: $user)
Features::enabled('show-social-buttons', for: $user)
Features::disabled('show-social-buttons', for: $user)

Filament integration

If you're using Filament, there is an additional package that provides a simple UI for managing feature flags. You can find out more in the GitHub repository's README file.

There might be certain scenarios where you want to store the name instead of the actual color code in your applications. This could be useful if you are building a CMS and want to conditionally apply classes to an element based on the name of a color instead of the color code, avoiding the need for inline styles in your markup.

To achieve this, we'll add a new storeColorName() method to the field and adjust the field's functionality accordingly.

class ColorPalette extends Field
{
    // ...

    protected bool | Closure $shouldStoreColorName = false;

    // ...

    public function storeColorName(bool | Closure $condition = true): static
    {
        $this->shouldStoreColorName = $condition;

        return $this;
    }

    public function shouldStoreColorName(): bool
    {
        return (bool) $this->evaluate($this->shouldStoreColorName);
    }
}

And making some changes in the Blade view:

@php
    $shouldStoreColorName = $shouldStoreColorName();
@endphp

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div x-data="{ state: $wire.{{ $applyStateBindingModifiers('entangle(\'' . $getStatePath() . '\')') }} }" class="flex items-center space-x-4">
        @foreach($getOptions() as $color => $label)
            @php($value = $shouldStoreColorName ? $label : $color)

            <button
                type="button"
                x-on:click="state = @js($value)"
                class="rounded-full w-8 h-8 border border-gray-300 relative inline-flex items-center justify-center"
                x-bind:class="{
                    'ring-2 ring-gray-300 ring-offset-2': state === @js($value),
                }"
                style="background: {{ $color }}" title="{{ $label }}"
            >
                <span class="sr-only">
                    {{ $label }}
                </span>

                <span x-show="state === @js($value)" x-cloak>
                    <x-heroicon-o-check class="w-4 h-4 text-gray-400" />
                </span>
            </button>
        @endforeach
    </div>
</x-forms::field-wrapper>

When selecting an option now it will use the color's name instead of the color code.

Allowing additional color selection

In some cases you might want your users to select their own color. Modern web browsers provide a color picker input type which we can use to do this.

Let's start by adding a method like before:

class ColorPalette extends Field
{
    // ...
    
    protected bool | Closure $canChooseCustomColors = false;

    // ...

    public function allowCustomColors(bool | Closure $condition = true): static
    {
        $this->canChooseCustomColors = $condition;

        return $this;
    }

    public function canChooseCustomColors(): bool
    {
        return (bool) $this->evaluate($this->canChooseCustomColors);
    }
}

And again, make some changes in the Blade view:

@php
    $shouldStoreColorName = $shouldStoreColorName();
@endphp

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div x-data="{ state: $wire.{{ $applyStateBindingModifiers('entangle(\'' . $getStatePath() . '\')') }} }" class="flex space-x-4">
        @foreach($getOptions() as $color => $label)
            @php($value = $shouldStoreColorName ? $label : $color)

            <button
                type="button"
                x-on:click="state = @js($value)"
                class="rounded-full w-8 h-8 border border-gray-300 relative inline-flex items-center justify-center"
                x-bind:class="{
                    'ring-2 ring-gray-300 ring-offset-2': state === @js($value),
                }"
                style="background: {{ $color }}" title="{{ $label }}"
            >
                <span class="sr-only">
                    {{ $label }}
                </span>

                <span x-show="state === @js($value)" x-cloak>
                    <x-heroicon-o-check class="w-4 h-4 text-gray-400" />
                </span>
            </button>
        @endforeach

        @if($canChooseCustomColors() && ! $shouldStoreColorName)
            <div class="flex border bg-gray-50 rounded-lg">
                <input type="color" name="{{ $getStatePath() }}.custom" x-model.lazy="state" class="block h-full p-0 rounded-l-lg">
                <div class="text-xs font-medium px-2 inline-flex items-center">
                    <span>Select Color</span>
                </div>
            </div>
        @endif
    </div>
</x-forms::field-wrapper>

Alpine.js is handling the state changes on the color input and with some styling we can get it to look like a single input still. Here's the result:

Whilst we're here we should add a method that lets you change the custom color selector's label.

class ColorPalette extends Field
{
    // ...

    protected string | Closure $customColorLabel = 'Select Color';

    // ...

    public function customColorLabel(string | Closure $label): static
    {
        $this->customColorLabel = $label;

        return $this;
    }

    public function getCustomColorLabel(): string
    {
        return (string) $this->evaluate($this->customColorLabel);
    }
}

And updating the Blade view really simple:

@php
    $shouldStoreColorName = $shouldStoreColorName();
@endphp

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div x-data="{ state: $wire.{{ $applyStateBindingModifiers('entangle(\'' . $getStatePath() . '\')') }} }" class="flex space-x-4">
        @foreach($getOptions() as $color => $label)
            @php($value = $shouldStoreColorName ? $label : $color)

            <button
                type="button"
                x-on:click="state = @js($value)"
                class="rounded-full w-8 h-8 border border-gray-300 relative inline-flex items-center justify-center"
                x-bind:class="{
                    'ring-2 ring-gray-300 ring-offset-2': state === @js($value),
                }"
                style="background: {{ $color }}" title="{{ $label }}"
            >
                <span class="sr-only">
                    {{ $label }}
                </span>

                <span x-show="state === @js($value)" x-cloak>
                    <x-heroicon-o-check class="w-4 h-4 text-gray-400" />
                </span>
            </button>
        @endforeach

        @if($canChooseCustomColors() && ! $shouldStoreColorName)
            <div class="flex border bg-gray-50 rounded-lg">
                <input type="color" name="{{ $getStatePath() }}.custom" x-model.lazy="state" class="block h-full p-0 rounded-l-lg">
                <div class="text-xs font-medium px-2 inline-flex items-center">
                    <span>{{ $getCustomColorLabel() }}</span>
                </div>
            </div>
        @endif
    </div>
</x-forms::field-wrapper>

And there we have it. A pretty powerful and useful ColorPalette field that lets you select a color from a fixed list of options and also choose your own custom colors.

Hopefully you found this mini-series helpful and learned a thing or two.

If you want to use this field in your own projects without rebuilding it, it's available for free on GitHub. You can find installation and usage instructions in the repository.

All fields in a Filament form have a unique "state path". The state path is the location on the Livewire component that contains your form where the current value / state of your field can be found.

The state path for a form field can be retrieved using the getStatePath() method. This can be called from the field class itself or inside of a Blade view by invoking the $getStatePath variable.

Let's start by making the color buttons update the state of the field. We'll be using Alpine to do this instead of Livewire's own wire: directives.

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div
        x-data="{ state: $wire.entangle('{{ $getStatePath() }}') }"
        class="flex items-center space-x-4"
    >
        @foreach($getOptions() as $color => $label)
            <button
                type="button"
                x-on:click="state = @js($color)"
                class="rounded-full w-8 h-8 border border-gray-500"
                style="background: {{ $color }}" title="{{ $label }}"
            >
                <span class="sr-only">
                    {{ $label }}
                </span>
            </button>
        @endforeach
    </div>
</x-forms::field-wrapper>

On my test form component, I've added an updatedColor hook that will get called when the state is updated.

public function updatedColor()
{
    dd($this->color);
}

And this is the result...

The dd() is being reached and the property at the state path is being updated. Nifty!

Writing super optimal fields is important in Filament since any unnecessary state updates will result in back and forth Livewire requests and multiple re-renders. If I choose an option, 1 request is going to be sent to update the state. If I then realise that it's the wrong option and choose another, a second request will be sent to update the state again.

These duplicated requests aren't always necessary and Filament fields generally follow a defer-first approach. If you're not familiar with Livewire's deferred binding system, read the documentation.

Fields in Filament are responsible for their own state binding method (reactive, deferred or lazy). To get the current binding modifier, we can use the $applyStateBindingModifiers() function.

This function accepts a single string which will be the method or directive you'd like to apply the modifiers to. In our case, it's going to be the entangle() method on $wire.

Updating the code inside of the Blade view looks something like this:

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div x-data="{ state: $wire.{{ $applyStateBindingModifiers('entangle(\'' . $getStatePath() . '\')') }} }" class="flex items-center space-x-4">
        @foreach($getOptions() as $color => $label)
            <button
                type="button"
                x-on:click="state = @js($color)"
                class="rounded-full w-8 h-8 border border-gray-500"
                style="background: {{ $color }}" title="{{ $label }}"
            >
                <span class="sr-only">
                    {{ $label }}
                </span>
            </button>
        @endforeach
    </div>
</x-forms::field-wrapper>

Admittedly this code is a little hard to read at first with the string concatenation and escaping of single quotes. All it's doing is building up the same entangle('{{ $getStatePath() }}') string as before and sending it through $applyStateBindingModifiers().

On a simple ColorPalette::make() call, this will result in the .defer modifier being applied to the $wire.entangle() call meaning any state changes are deferred until the next Livewire action is invoked, normally saving the form or changing the state of a reactive field.

To make the field reactive again, you just need to call ->reactive() on the field itself, i.e.

ColorPalette::make('color')
    ->reactive(),

Visual display of selected option

Functionally speaking the field is working. Visually though, it's impossible to tell which option is selected. Let's change this by applying a ring to the selected option as well as a checkmark.

We can use Alpine again to conditionally apply classes to the button, since we already have a reference to the current state.

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div x-data="{ state: $wire.{{ $applyStateBindingModifiers('entangle(\'' . $getStatePath() . '\')') }} }" class="flex items-center space-x-4">
        @foreach($getOptions() as $color => $label)
            <button
                type="button"
                x-on:click="state = @js($color)"
                class="rounded-full w-8 h-8 border border-gray-300 appearance-none inline-flex items-center justify-center"
                x-bind:class="{
                    'ring-2 ring-gray-300 ring-offset-2': state === @js($color),
                }"
                style="background: {{ $color }}" title="{{ $label }}"
            >
                <span class="sr-only">
                    {{ $label }}
                </span>

                <span x-show="state === @js($color)" x-cloak>
                    <x-heroicon-o-check class="w-4 h-4 text-gray-400" />
                </span>
            </button>
        @endforeach
    </div>
</x-forms::field-wrapper>

Using x-bind:class and x-show we can conditionally add classes to the button and toggle a checkmark icon from Heroicons.

The final result looks like this:

In the next and final part of this series, we'll look at some extra methods we can add to ColorPalette to make it more developer friendly.

Hello, Twitter!

class ColorPalette extends Field
{
    // ...

    protected array $options = [];

    public function options(array $options): static
    {
        $this->options = $options;

        return $this;
    }
}

We can now pass an array of options to the field in our form:

ColorPalette::make('color')
    ->options([
        '#ffffff' => 'White',
        '#000000' => 'Black',
    ]),

Retrieving the options

All fields and form components in Filament are actually just Blade components under the hood. This means we can define public methods on our ColorPalette class and they will be sent through to the Blade view as invokable variables.

Let's add a getOptions() method to the field that returns the array of options given to the field.

class ColorPalette extends Field
{
    // ...

    public function getOptions(): array
    {
        return $this->options;
    }
}

Now inside of our Blade view, we can call this method and loop over the returned array.

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div class="flex items-center space-x-4">
        @foreach($getOptions() as $color => $label)
            <button type="button" class="rounded-full w-8 h-8 border border-gray-500" style="background: {{ $color }}" title="{{ $label }}">
                <span class="sr-only">
                    {{ $label }}
                </span>
            </button>
        @endforeach
    </div>
</x-forms::field-wrapper>

Using inline styles, we can change the background color of the button to the option's color. For accessibility reasons, we'll also output the $label provided but only for screenreaders.

And just like that, we're rendering the color options on the page.

Adding support for computed options

In its current state, the ColorPalette field can only accept a static array of color options. This causes problems when you want to change the color options based on the value of another field or the record you're working on.

This is where Filament's incredibly powerful Closure customisation system comes into play. By widening the type of the $options argument to also accept Closure values, we can allow developers to provide a computed list of options instead of a static list.

There are a few steps to make this work. The first being widening the types on the class itself.

class ColorPalette extends Field
{
    // ...

    protected array | Closure $options = [];

    public function options(array | Closure $options): static
    {
        $this->options = $options;

        return $this;
    }

    // ...
}

The ColorPalette::options() method now accepts an array or Closure through a union type. This allows us to do this:

Select::make('theme')
    ->reactive()
    ->options([
        'minimal' => 'Minimal',
        'abstract' => 'Abstract',
    ]),
ColorPalette::make('color')
    ->options(function (callable $get) {
        if ($get('theme') === 'abstract') {
            return [
                '#ff69b4' => 'Hot Pink',
                '#32cd32' => 'Lime Green',
            ];
        }

        return [
            '#ffffff' => 'White',
            '#000000' => 'Black',
        ];
    })

Now the ColorPalette field's options will be updated and computed based on the option selected in the Select field above it. Or will they?

There's one more thing we need to do. We need to actually invoke the Closure. Thankfully, Filament has a smooth evaluate() API which will invoke a Closure and provide some standardised arguments depending on the context you're evaluating it in.

Instead of returning $this->options inside of getOptions(), we can return send the value through $this->evaluate() and return the result of that instead.

class ColorPalette extends Field
{
    // ...
    
    public function getOptions(): array
    {
        return $this->evaluate($this->options);
    }
}

In the next part, we'll hook up our buttons and start persisting state to the form / Livewire component.

The field we'll be building is a color palette field that lets you select a color from a fixed list of options. Such a simple field will cover the basics of rendering a field and syncing the selected option with the property on the form itself.

Here's an example of the field's API:

ColorPalette::make('color')
    ->options([
        '#ffffff' => 'White',
        '#000000' => 'Black',
    ]),

The color options will be an array of colors and labels. The label will be used to show a tooltip when hovering over the chosen color and the color value itself will be used to render the option.

Generating the boilerplate

To generate an empty field, run the php artisan make:form-field command.

$ php artisan make:form-field

Name (e.g. `RangeSlider`):
> ColorPalette

Successfully created ColorPalette!

This command is provided by the filament/forms package and will generate a basic Field class and corresponding Blade view.

Open up the new app/Forms/Components/ColorPalette.php file and you should see this:

<?php

namespace App\Forms\Components;

use Filament\Forms\Components\Field;

class ColorPalette extends Field
{
    protected string $view = 'forms.components.color-palette';
}

The field is already setup to render a particular Blade view, so let's also take a look at that.

<x-forms::field-wrapper
    :id="$getId()"
    :label="$getLabel()"
    :label-sr-only="$isLabelHidden()"
    :helper-text="$getHelperText()"
    :hint="$getHint()"
    :hint-icon="$getHintIcon()"
    :required="$isRequired()"
    :state-path="$getStatePath()"
>
    <div x-data="{ state: $wire.entangle('{{ $getStatePath() }}') }">
        <!-- Interact with the `state` property in Alpine.js -->
    </div>
</x-forms::field-wrapper>

The boilerplate code inside of the Blade view might be a bit overwhelming at first, but it's actually Filament doing a lot of the heavy lifting for us. It's configuring the field wrapper (the component that renders the label, helper text, etc) and also gives us a basic Alpine component with the field's property already "entangled".

If we render this almost empty field inside of a form, you'll see something like this.

In the next part, we'll add a method to the field that accepts an array of options and start rendering some option buttons to the front-end.

We start off by creating a new Component class. I'm going to do this manually inside of app/Forms/Components.

<?php

namespace App\Forms\Components;

use Filament\Forms\Components\Component;

class DescriptionList extends Component
{
    public static function make(): static
    {
        return new static();
    }
}

The first thing we need to do is specify the view that your component uses. This is done via a $view property on the class.

class DescriptionList extends Component
{
    protected string $view = 'filament.forms.components.description-list';
}

I tend to structure my views the same way the classes are structured, with the exception of placing it inside of an extra top-level filament folder for separation from other folders in my application.

The DescriptionList components is going to loop over an array of key value pairs where the key is used as the term <dt> and the value is used as the description <dd>. Let's add a method to the component that accepts that array.

class DescriptionList extends Component
{
    protected string $view = 'filament.forms.components.description-list';

    protected array $items = [];

    public function items(array $items): static
    {
        $this->items = $items;
        
        return $this;
    }
}

Now in your form, we can use the component:

protected function getFormSchema(): array
{
    return [
        DescriptionList::make('overview')
            ->items([
                'Name' => $this->user->name,
                'Email' => $this->user->email,
            ]),
    ];
}

Inside of our view we can start to output some values, but how do we get those values?

Fields and components in Filament are actually all Blade components under the hood, which means all public properties and methods get passed to the view as variables. We can add a new getItems() method to the component class and invoke that inside of our Blade view.

class DescriptionList extends Component
{
    protected string $view = 'filament.forms.components.description-list';

    protected array $items = [];

    // ...

    public function getItems(): array
    {
        return $this->items;
    }
}

<dl>
    @foreach($getItems() as $term => $description)
        <dt>{{ $term }}</dt>
        <dd>{{ $description }}</dd>
    @endforeach
</dl>

And we have some data being rendered now, cool! Let's take this a step further and look at using Closure objects to allow more dynamic lists of data.

The first step is changing what values we accept on our items() method.

class DescriptionList extends Component
{
    protected string $view = 'filament.forms.components.description-list';

    protected array | Closure $items = [];

    public function items(array | Closure $items): static
    {
        $this->items = $items;
        
        return $this;
    }
}

If we use a union type to also accept a Closure, users will be able to use closure customisation to generate dynamic sets of data based on other fields or the current record.

protected function getFormSchema(): array
{
    return [
        DescriptionList::make()
            ->items(function (Model $record, Closure $get) {
                $items = [
                    'Name' => $record->name,
                    'Email' => $record->email,
                ];

                if (!! $get('show_dangerous_things')) {
                    $items['Password'] = magical_function_to_reverse_sha256_hash($record->password);
                }

                return $items;
            }),
    ];
}

The getItems() method also needs to be updated to handle the new Closure object. Filament provides a handy evaluate() method which will take in a value and if it happens to be a Closure, it will run it through Laravel's service container and pass through an array of handy argument such as $record, $get, etc.

If the value provided to evaluate() isn't invokable, it will just return it as is meaning our array types will still work as expected.

class DescriptionList extends Component
{
    public function getItems(): array
    {
        return $this->evaluate($this->items);
    }
}

The goal for this post will be compiling the following code:

$guess = readline("Guess a number between 1 and 3: ");
$number = rand(1, 3);

if ($guess == $number) {
    echo "You guessed the number correctly, well done!";
} else {
    echo "The correct answer is " . $number . ". Better luck next time!";
}

Before we start writing some Rust, let's analyze the code and look at the things we'll need to implement.

At the very top of the script we've got some variable assignments. This is a type of expression so we'll need to add some new code to the compile_expression() function.

On the right-hand side of those assignments we're calling some native / first-party PHP functions. These don't exist in our runtime at the moment, so we'll need to implement those in Rust land as part of our runtime.rs file.

We then reach the conditional statements. We'll need to handle the compilation of the structure itself, along with the expressions used inside of blocks.

The condition in our if statement uses the == operator which is referred to as an infix operator. The compile_expression() will need to be updated to handle this new type of expression as well. We'll also need to keep in mind that Rust doesn't have any concept of loose or strict comparisons, instead we'll need to implement thing logic ourself.

Let start by supporting the assignment expression and writing our own implementations of readline() and rand().

Assignment expressions

An assignment expression in the Rust code will be represented with a let statement. PHP variables are all mutable but Rust lets us redeclare and rebind a variable after its original definition with another let statement. Here's an example.

let foo = 1;
let foo = 2;

The second binding will replace the original without needing to make the original assignment mutable. Let's add this code to compile_expression().

fn compile_expression(expression: &Expression) -> Result<String, CompileError> {
    let result = match expression {
        // ...
        Expression::Assign(target, value) => {
            format!("let {} = {};", compile_expression(target)?, compile_expression(value)?)
        },
        _ => todo!(),
    };

    Ok(result)
}

If we try to run this code, there will actually be an unimplemented / todo panic earlier on in the code. Our parser actually stores random expressions like an assignment inside of a statement, so we need to tell compile_statement() to send our expression statements through the compile_expression() function.

fn compile_statement(statement: &Statement, source: &mut String) -> Result<(), CompileError> {
    match statement {
        // ...
        Statement::Expression { expr } => {
            source.push_str(&compile_expression(expr)?);
        },
        _ => todo!(),
    };

    Ok(())
}

The next thing to do is add a new Int type to the PhpValue enumeration and compile integer expressions. This is so we can eventually call the rand() function.

fn compile_expression(expression: &Expression) -> Result<String, CompileError> {
    let result = match expression {
        // ...
        Expression::Int(i) => format!("PhpValue::from({})", i),
        _ => todo!(),
    };

    Ok(result)
}

And updating our PhpValue enumeration to support creation from an i64.

enum PhpValue {
    String(String),
    Int(i64),
}

impl From<i64> for PhpValue {
    fn from(value: i64) -> Self {
        Self::Int(value)
    }
}

Let's write some native PHP functions in Rust. We'll start with readline().

This function accepts an optional string which will be printed before asking for user input. We'll make this argument required for now since our compiler doesn't know how to handle optional arguments just yet.

pub fn readline(prompt: PhpValue) -> PhpValue {
    print!("{}", prompt);

    std::io::stdout().flush().unwrap();

    let mut result = String::new();
    std::io::stdin().lock().read_line(&mut result).unwrap();

    PhpValue::from(result.trim_end())
}

We flush stdout() so that any previous print!() calls reach the terminal before we lock it for input. We then read in a line of text from the terminal and store it inside of the result variable.

Rust's read_line() method will also include the \n character at the end of the string so using a .trim_end() call will tidy that up.

Time for the rand() function. This is going to require a third-party crate since I don't particularly want to write my own PRNG. We'll be using the defacto rand crate.

use rand::Rng;

fn rand(from: PhpValue, to: PhpValue) -> PhpValue {
    let from: i64 = from.into();
    let to: i64 = to.into();

    let mut rng = rand::thread_rng();

    PhpValue::from(rng.gen_range(from..to))
}

For type conversions between native Rust types and PhpValue, we'll start to implement Into<T> traits. Rust will call the appropriate method based on the inferred type or provided type of the target, in this case the from and to values are both i64 so it will call the Into<i64> method.

impl Into<i64> for PhpValue {
    fn into(self) -> i64 {
        match self {
            Self::Int(i) => i,
            _ => todo!(),
        }
    }
}

Compiling if statements

This might sound a complex task but since we're compiling from one language to another, we can actually take advantage of Rust's own conditional statements. We'll just be translating one syntax to another.

Updating compile_statement() to support conditionals is quite simple:

fn compile_statement(statement: &Statement, source: &mut String) -> Result<(), CompileError> {
    match statement {
        // ...
        Statement::If { condition, then, else_ifs, r#else } => {
            source.push_str("if ");
            source.push_str(&compile_expression(condition)?);
            source.push('{');

            for statement in then {
                compile_statement(statement, source)?;
            }

            source.push('}');

            if let Some(r#else) = r#else {
                source.push_str("else {");
                for statement in r#else {
                    compile_statement(statement, source)?;
                }
                source.push('}');
            }
        },
        _ => todo!(),
    };

    Ok(())
}

It doesn't support any elseif conditions at the moment since those don't exist in our sample code. For now it compiles the initial if statement and checks to see if there is a valid else statement at the end. If there is it compiles that too.

We'll also need to support equality checks inside of compile_expression(). There's a couple of ways to do this.

1. Manually implement PartialEq on the PhpValue enumeration and perform the equality comparisons there.
2. Write our own .eq() and .identical() methods since PHP has some type juggling rules that would be easier to implement here.

I'm going to go with option 2 here since I think there will be more long-term flexibility when compared to Rust's own PartialEq trait. Right now the compiler only needs to know about loose comparisons so we'll only implement the eq() method.

impl PhpValue {
    pub fn eq(&self, other: Self) -> bool {
        match (self, &other) {
            (Self::Int(a), Self::String(b)) | (Self::String(b), Self::Int(a)) => match b.parse::<i64>() {
                Ok(b) => *a == b,
                _ => false,
            },
            _ => todo!(),
        }
    }
}

The result of readline() should be a string so the compiler only needs to support loose comparisons between Int and String right now. Rust doesn't let you do this natively so the first step is to try and parse an i64 from the given String.

If that is successful, the result of the function will be an equality check between the a and b. If it fails it means the String couldn't be converted into an i64 and it's impossible for the values to be equal.

Now for the expression compilation itself.

fn compile_expression(expression: &Expression) -> Result<String, CompileError> {
    let result = match expression {
        // ...
        Expression::Infix(lhs, op, rhs) => {
            let lhs = compile_expression(lhs)?;
            let rhs = compile_expression(rhs)?;

            match op {
                InfixOp::Equals => format!("{}.eq({})", lhs, rhs),
                _ => todo!(),
            }
        },
        Expression::Variable(var) => var.to_string(),
        _ => todo!(),
    };

    Ok(result)
}

The compiler didn't know how to handle variables either so that has been added too.

The last type of expression the compiler needs to understand is string concatenation. This is another type of infix operation so it's a case of adding another pattern to the match expression.

fn compile_expression(expression: &Expression) -> Result<String, CompileError> {
    let result = match expression {
        // ...
        Expression::Infix(lhs, op, rhs) => {
            let lhs = compile_expression(lhs)?;
            let rhs = compile_expression(rhs)?;

            match op {
                InfixOp::Equals => format!("{}.eq({})", lhs, rhs),
                InfixOp::Concat => format!("_php_concat({}, {})", lhs, rhs),
                _ => todo!(),
            }
        },
        // ...
        _ => todo!(),
    };

    Ok(result)
}

Instead of mutating existing PhpValue values the runtime will create an entirely new one from 2 separate PhpValue arguments. This function needs to be written in the runtime.rs file alongside our _php_echo() function.

fn _php_concat(left: PhpValue, right: PhpValue) -> PhpValue {
    format!("{}{}", left, right).into()
}

In the previous post we implemented the Display trait for PhpValue which allows us to natively use the enumerations inside of Rust's first-party formatting macros such as format!(), print!() and println!().

With all of that done, it's time to compile the file! And it doesn't work.

Using dependencies

If you haven't read the first blog post, the way this compiler works is by essentially concatenating the compiled PHP code with a runtime.rs file which is written inside of the phpc crate. That file is then stored inside of a temporary directory and compiled using rustc directly.

The problem with this approach is that we can't use any external dependencies inside of the runtime.rs file because they're not going to be linked against during compilation.

One potential solution to this problem is generating a static object file for the runtime and linking against that when compiling the PHP code. As the dependency list grows though the number of libraries that would need to be compiled would grow quite quickly.

I'm instead going to go down the route of ditching rustc and using cargo to build the project instead. The benefit here is that we can let cargo do all of the heavy lifting instead and run away from the rustc API.

I won't go over each step individually but will just paste the new main function code here.

fn main() {
    let args = Args::from_args();

    println!("> Compiling PHP script...");

    let compiled = compile(args.file.clone()).unwrap();

    let path = std::path::Path::new(&args.file);
    let file_stem = path.file_stem().unwrap().to_str().unwrap();
    
    let temp_dir = std::env::temp_dir();
    let temp_path = format!("{}{}", temp_dir.to_str().unwrap(), Uuid::new_v4());

    println!("> Initialising Cargo project in {}...", &temp_path);

    std::fs::create_dir(&temp_path).unwrap();

    let mut cmd = Command::new("cargo");
    cmd.args(["init", ".", "--name", &file_stem])
        .current_dir(&temp_path);

    match cmd.output() {
        Ok(o) => {
            print!("{}", String::from_utf8_lossy(&o.stdout));
        },
        Err(e) => {
            eprintln!("Failed to generate Cargo project. Error: {:?}", e);
            exit(1);
        },
    };

    let cargo_stub = include_str!("../../phpc_runtime/Cargo.toml").replace("phpc_runtime", file_stem);

    println!("> Modifying Cargo configuration...");

    match std::fs::write(format!("{}/Cargo.toml", &temp_path), cargo_stub) {
        Ok(_) => {},
        Err(e) => {
            eprintln!("Failed to modify Cargo configuration. Error: {:?}", e);
            exit(1);
        },
    };

    let runtime_stub = include_str!("../../phpc_runtime/src/lib.rs");
    
    println!("> Writing runtime module...");

    match std::fs::write(format!("{}/src/runtime.rs", &temp_path), runtime_stub) {
        Ok(_) => {},
        Err(e) => {
            eprintln!("Failed to write runtime library. Error: {:?}", e);
            exit(1);
        }
    };

    println!("> Writing compiled PHP code...");

    match std::fs::write(format!("{}/src/main.rs", &temp_path), compiled) {
        Ok(_) => {},
        Err(e) => {
            eprintln!("Failed to write compiled PHP code. Error: {:?}", e);
            exit(1);
        },
    };

    println!("> Compiling project with Cargo...");

    let mut cmd = Command::new("cargo");
    cmd.args(["build", "--release"])
        .current_dir(&temp_path);

    match cmd.output() {
        Ok(o) => {
            if o.status.success() {
                print!("{}", String::from_utf8_lossy(&o.stdout));
            } else {
                print!("{}", String::from_utf8_lossy(&o.stderr));
            }
        },
        Err(e) => {
            eprintln!("Failed to compile project with Cargo. Error: {:?}", e);
            exit(1);
        },
    };
}

The error handling of commands could be a lot tidier if there was a wrapper around the Command API, but this will do for now. The Cargo.toml file for the PHP project is taken from a new phpc_runtime crate and modified slightly.

Dependencies are now compiled into our project correctly, but there's still a problem. The compiled Rust code isn't memory safe!

The problematic code is coming from our equality expression. We're moving the value out of the current block into the .eq() function which means we can no longer reference it in the main flow of execution. A hacky fix is just to clone the value before we send it through, that way the original value isn't actually being used and a freshly allocated one is instead.

fn compile_expression(expression: &Expression) -> Result<String, CompileError> {
    let result = match expression {
        // ...
        Expression::Infix(lhs, op, rhs) => {
            let lhs = compile_expression(lhs)?;
            let rhs = compile_expression(rhs)?;

            match op {
                InfixOp::Equals => format!("{}.eq(({}).clone())", lhs, rhs),
                InfixOp::Concat => format!("_php_concat({}, {})", lhs, rhs),
                _ => todo!(),
            }
        },
        // ...
        _ => todo!(),
    };

    Ok(result)
}

A better way of doing this is probably with a smart pointer or even a garbage collector. Since we're still prototyping this code a .clone() is fine and won't hurt anybody.

The project successfully compiles but the executable hasn't been moved into the current working directory. A bit of extra logic at the end of the main() function should sort this.

fn main() {
    // ...

    let executable_path = format!("{}/target/release/{}", &temp_path, &file_stem);

    match std::fs::copy(executable_path, format!("./{}", &file_stem)) {
        Ok(_) => {
            println!("> Executable copied.");
        },
        Err(e) => {
            eprintln!("Failed to copy executable file. Error: {:?}", e);
            exit(1);
        },
    };
}

Compiling the project now will create a new guess-a-number file in the current directory. Executing that file and trying to guess a number results in this:

$ ~ ./guess-a-number
Guess a number between 1 and 3: 1
You guessed the number correctly, well done!%

Here's a list of the things that accomplished:

• Compile variable assignments.
• Write a native PHP function in Rust.
• Compile if and else statements.
• Migrate project compilation to Cargo to allow use of external crates.

All in all this was a pretty successful article. Again, if you made it to the end then thank you.

Until next time.

Some of you might already know that I've been working on a handwritten PHP parser in Rust. The project is called Trunk (source code on GitHub).

I've been working on the parser for a couple of weeks at the time of writing this blog post and it's already come a long way. It's able to parse functions, classes, interfaces and much more. It's still miles from being a compliant PHP parser comparable to Nikita's nikic/php-parser package, but the journey has been fun so far and it's amazing how many weird things you can find out about a language by parsing its grammar.

Since the parser is now able to handle some basic programs, I thought it would be worthwhile taking it for a spin to see what the API is like and to look for improvements. Dogfooding, if you want a single word.

My original plan was to work on an experimental runtime and interpreter for the language. That's quite a huge undertaking and there would be very little benefit to a new runtime at this point in time.

Instead I started to think about a compiler for PHP. Something that runs ahead of execution time (AOT). My friend Tim Morgan is the creator of Natalie, an implementation of the Ruby language that compiles to C++ and then compiles into a native binary. I've contributed to Natalie a little over the last year or so and it's truly inspiring the work that Tim is doing.

You can probably see where this is going...

The idea

Inspired by Tim's work on Natalie, I'm going to start an experiment where I take my handwritten PHP parser and try to write a compiler that turns PHP code into Rust and then compiles that Rust code into a native executable using rustc.

Let's look at a simple example:

function get_name() {
    return "Ryan";
}

echo get_name();

A PHP script like this would eventually compile into some Rust code that looks something like this:

fn get_name() -> PhpResult<PhpValue> {
    return Ok(PhpValue::from("Ryan"));
}

fn main() -> PhpResult<()>  {
    _php_echo(get_name()?);
}

That Rust code could then be stored somewhere and compiled using the Rust compiler, rustc.

No more boring introductions. Let's look at some code.

Disclaimer: The following code is incredibly naive and purely for prototyping purposes. There's plenty of rough edges that will need to be ironed out before calling this a "good idea" or "achievable project".

Parsing the code

I've already got a parser that is capable of understanding the PHP code above. The API is pretty simple, so I decided to just build a small CLI that would accept a file path and send it through the parser to obtain an abstract syntax tree (AST). I'm using the excellent structopt crate here for argument parsing.

use structopt::StructOpt;

#[derive(Debug, StructOpt)]
#[structopt(name = "phpc", about = "Compile a PHP script to Rust.")]
struct Args {
    file: String,
}

fn main() {
    let args = Args::from_args();
}

This is all written inside of a main.rs file. I prefer to separate the CLI interface code from the actual logic of the program, so the below code is written inside of lib.rs inside of the same folder.

use trunk_lexer::Lexer;
use trunk_parser::Parser;

pub fn compile(file: String) -> Result<String, CompileError> {
    let contents = match std::fs::read_to_string(file) {
        Ok(contents) => contents,
        Err(_) => return Err(CompileError::FailedToReadFile),
    };

    let mut lexer = Lexer::new(None);
    let tokens = lexer.tokenize(&contents).unwrap();

    let mut parser = Parser::new(tokens);
    let ast = parser.parse().unwrap();

    Ok(String::new())
}

#[derive(Debug)]
pub enum CompileError {
    FailedToReadFile,
}

The code takes in a file path and gets a list of tokens using the Lexer structure. The tokens are then sent through the parser to retrieve the AST.

The usage of unwrap() isn't great because the program will just panic. A good refactoring opportunity here would be transforming any errors returned from the lexer and parser into CompileError values instead.

This function can now be called from main.rs.

use structopt::StructOpt;
use phpc::compile;

#[derive(Debug, Structopt)]
#[structopt(name = "phpc", about = "Compile a PHP script to Rust.")]
struct Args {
    file: String,
}

fn main() {
    let args = Args::from_args();
    let compiled = compile(args.file);

    dbg!(compiled);
}

The main conundrum

PHP is a procedural programming language. It's really a scripting language. As such, it doesn't enforce the usage of a main() function. The same can be seen in other languages like JavaScript and Python.

Rust on the otherhand requires you to define an fn main() somewhere so that the binary knows where to start executing your code. The example PHP code shown further up in this blog post has a single function definition and then an arbitrary statement outside of any known structure.

Think of those arbitrary statements as parts inside of the pseudo main() function. The best way to force this structure is by segmenting and partitioning the AST into 2 separate smallers ASTs.

The first will contain any function definitions (for now) and the other will contain all of the rogue statements. That way all of the function definitions can be compiled first and the rest can be compiled inside of an fn main() to keep Rust happy.

use trunk_parser::{Parser, Statement};

pub fn compile(file: String) -> Result<String, CompileError> {
    // ...

    let mut parser = Parser::new(tokens);
    let ast = parser.parse().unwrap();

    let (fns, main): (Vec<_>, Vec<_>) = ast.iter().partition(|statement| match statement {
        Statement::Function { .. } => true,
        _ => false,
    });

    // ...
}

The partition() method returns a tuple containing 2 new ASTs. Rust needs some helper understanding the types - the fancy Vec<_> syntax just tells the typechecker that the generic type inside of Vec<T> is the same as the type inside of the iterator itself (call it a placeholder).

Now it's time for some string building!

Bare minimal compilation

Compiling our AST into Rust code is just a case of looping over all of the statements and concatenating a bunch of strings. Famous last words, lol.

Let's start with a compile_function() method that accepts a Statement and &mut String.

fn compile_function(function: &Statement, source: &mut String) -> Result<(), CompileError> {
    let (name, params, body) = match function {
        Statement::Function { name, params, body, .. } => (name, params, body),
        _ => unreachable!(),
    };

    source.push_str("fn ");
    source.push_str(&name.name);
    source.push('(');

    for param in params {
        source.push_str(match &param.name {
            Expression::Variable(n) => &n,
            _ => unreachable!(),
        });
        source.push_str(": PhpValue, ");
    }

    source.push_str(") -> PhpValue {");

    for statement in body {
        compile_statement(statement, source)?;
    }

    source.push('}');

    Ok(())
}

This function is going to extract some values from the Statement and return a tuple that we can unpack. There's some boilerplate code to output the fn keyword along with its name.

The function then needs a list of parameters. We don't really care about parameter types right now because all of our values are going to be represented by a single PhpValue type in the Rust code anyway.

It also needs a return type which will also be a PhpValue. It's then just a case of looping over all of the statements inside of the function and compiling those before closing off the function itself.

Pretty simple so far... let's implement a minimal compile_statement() function too.

fn compile_statement(statement: &Statement, source: &mut String) -> Result<(), CompileError> {
    match statement {
        Statement::Return { value } => {
            source.push_str("return");
            if let Some(value) = value {
                source.push(' ');
                source.push_str(&compile_expression(value)?);
            } else {
                todo!();
            }
            source.push(';');
        },
        _ => todo!(),
    };

    Ok(())
}

Our example get_name() function only contains a return statement so we'll just implement that for now. It's more string building here, with the addition of a new compile_expression() function too.

You might notice that we're actually pushing the result of compile_expression() onto the string instead of passing through a mutable reference to source. This is important since we might want to compile an expression arbitrarily without modifying the source code.

We've got another function to write so let's do that real quick.

fn compile_expression(expression: &Expression) -> Result<String, CompileError> {
    let result = match expression {
        Expression::ConstantString(value) => {
            format!(r#"PhpValue::from("{}")"#, value)
        }
        _ => todo!(),
    };

    Ok(result)
}

Still implementing the bare minimum here. The get_name() function returns a constant string which will be able to directly convert into a PhpValue type with some traits later on. The format!() macro returns a String so we can just keep it simple and avoid any temporary variables.

Time to wire it all up inside of the compile() function.

fn compile(file: String) -> Result<String, CompileError> {
    // ...

    let mut source = String::new();

    for function in fns {
        compile_function(function, &mut source)?;
    }

    Ok(source)
}

Create an empty String, loop through the function statements, compile them, return the generated source code.

Running the example code through the program now will dump the generated Rust code into the terminal. It looks like this:

cargo run --bin phpc -- ./phpc/samples/blog.php

[phpc/src/main.rs:14] compiled = Ok(
    "fn get_name() -> PhpValue {return PhpValue::from(\"Ryan\");}",
)

Our function has been generated with a rather ugly return statement inside! Visible progress - love it. Time to get the main() function.

Compiling the entrypoint

Before looping through the main statements, we need to add the boilerplate code. This can all go inside of the compile() function for now.

pub fn compile(file: String) -> Result<String, CompileError> {
    // ...

    source.push_str("fn main() {");

    for statement in main {
        compile_statement(statement, &mut source)?;
    }

    source.push('}');

    Ok(source)
}

Running this code will cause some panics since we've not implemented all of our statements. We need to add in support for echo.

fn compile_statement(statement: &Statement, source: &mut String) -> Result<(), CompileError> {
    match statement {
        // ...
        Statement::Echo { values } => {
            for value in values {
                source.push_str("_php_echo(");
                source.push_str(&compile_expression(value)?);
                source.push_str(");");
            }
        },
        _ => todo!(),
    };

    Ok(())
}

Trying to compile the example code again triggers another panic, this time it's the new call to compile_expression(). The compiler doesn't know how to generate Rust code for calling PHP functions.

fn compile_expression(expression: &Expression) -> Result<String, CompileError> {
    let result = match expression {
        // ...
        Expression::Call(target, args) => {
            let mut buffer = String::new();

            buffer.push_str(&compile_expression(target)?);
            buffer.push('(');

            for arg in args {
                buffer.push_str(&compile_expression(arg)?);
                buffer.push_str(", ");
            }

            buffer.push(')');
            buffer
        },
        Expression::Identifier(i) => i.to_string(),
        _ => todo!(),
    };

    Ok(result)
}

The code above should be pretty self-explanatory at this point. A Call expression has a target and list of arguments. The target is also an Expression so needs to be compiled, as well as the arguments.

In the example script, the target is just an identifier so the function needs to know how to compile that as well. Luckily it just needs to output the name of the identifer as a literal string. The .to_string() method call is required to generate a non-referential string.

Running the example script through the compiler one more time generates the following Rust code.

cargo run --bin phpc -- ./phpc/samples/blog.php

[phpc/src/main.rs:14] compiled = Ok(
    "fn get_name() -> PhpValue {return PhpValue::from(\"Ryan\");}fn main() {_php_echo(get_name());}",
)

A little harder to read now but the main() function exists and has the expected code inside of it. Woop woop!

The runtime

The compiler is pretty smart now. It can take an incredibly complex PHP script and generate valid Rust code. Or can it?

The answer is of course no. The Rust code is referencing a weird PhpValue type that doesn't actually exist in the generated code. There are a few potential ways to solve this but I'm going to go with the simplest and fastest way - a "runtime" file.

This runtime file will contain all of the code needed to actually run PHP code. It's going to be house the PhpValue type as well as any internal functions that handle PHP concepts, such as _php_echo().

Rust makes this really simple as well with the include_str!() macro. This macro is evaluated at compile time and takes in a file path. The contents of that file are then embedded into the program and can be assigned to a variable.

Adding that code into the compile() function looks like this:

pub fn compile(file: String) -> Result<String, CompileError> {
    // ...

    let mut source = String::new();
    source.push_str(include_str!("./runtime.rs"));

    // ...

    Ok(source)
}

The top of the generated code will now include everything inside of the runtime.rs file.

This file can now house the runtime information such as PhpValue and _php_echo().

use std::fmt::Display;

enum PhpValue {
    String(String),
}

impl From<&str> for PhpValue {
    fn from(value: &str) -> Self {
        Self::String(value.into())
    }
}

impl Display for PhpValue {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::String(string) => write!(f, "{}", string),
            _ => todo!(),
        }
    }
}

fn _php_echo(value: PhpValue) {
    print!("{value}");
}

The only type of PHP value that the example script uses is a string, so the PhpValue can just have a single variant.

I want the PhpValue type to be smart and understand conversions from native Rust types. That's where the generic From trait comes in. It tells the Rust compiler how to convert a &str into a PhpValue.

PhpValue also implements the Display trait which will allow the struct to be formatted with Rust's first party macros such as write!(), print!() and println!(). An added bonus of implementing Display is that you get a .to_string() method on the implementor for free.

The _php_echo() function takes in a value and just prints it out using print!().

Compiling with rustc

The compiler has just about everything it needs to compile the example PHP script. The last step is teaching the CLI how to take the compiled code and write it to disk and then send that file through Rust's compiler, rustc.

fn main() {
    let args = Args::from_args();
    let compiled = compile(args.file.clone()).unwrap();

    let path = std::path::Path::new(&args.file);
    let temp = std::env::temp_dir();
    let file_stem = path.file_stem().unwrap().to_str().unwrap();
    let file_path = format!("{}{}.rs", temp.to_str().unwrap(), &file_stem);

    std::fs::write(&file_path, compiled).unwrap();

    println!("Compiled code written to {}...", &file_path);
    println!("Generating binary...");

    std::process::Command::new("rustc")
        .args([file_path, "-o".to_string(), file_stem.to_string()])
        .output()
        .expect("Failed to compile with rustc");
}

The file name is converted into a Path instance. This gives us a handy file_stem() method that returns the file name without the extension. A full file path is then generated using a temporary directory, the file name and .rs file extension.

All of the compiled code is then written to that temporary file path and printed in the terminal for debugging purposes.

A new Command is then created targeting the global rustc binary. The file_path is provided as the input file and the output is set using the -o flag followed by the name of the binary. For convenience the binary is named after the original input file to the compiler.

The Command then executes and will panic if it fails to read any output. This is pretty poor since even if rustc fails to compile because of bad Rust code, the phpc program will be successful. It'll do for now though.

The moment you've all been waiting for

It's time to compile the example script...

cargo run --bin phpc -- ./phpc/samples/blog.php

Compiled code written to /var/folders/52/3xkzr5_s1zbczrn85z2kqfv40000gn/T/blog.rs...
Generating binary...

And it works as expected. In the current working directory is a new blog file which can be executed in the terminal.

./blog

Ryan%

Absolute sorcery! Four lines of incredibly simple PHP code were parsed with a handwritten parser, compiled into a Rust file with a novel compiler and compiled into a native binary using Rust's own toolchain.

Please, please, please, remember that this is just a prototype and proof of concept right now. I'm most definitely going to continue the development of this alongside the parser, but right now it's still a proof of concept!

There's plenty of hurdles to jump before it becomes remotely useful for anybody. Already my mind is thinking "How will it handle require and include?", "What about conditionally defining functions?", "How do you even represent a PHP interface with Rust code!?" and "I forgot about closures...".

I'm going to continue writing about my journey developing Trunk, no matter the outcome. Regardless of the success with the compiler, the parser work will continue and I'm sure we'll find lots of other interesting projects to experiment with too.

If you made it this far without drifting off and getting some sleep, thank you. If you're interested in viewing the commit that contains all of this code, you can view it here on GitHub. There are some bits of deleted code in there too from my original attempt at this, ignore that.

Until next time.

Let's take a look at an example using a Collection.

$collection = collect([
    'foo' => [
        'bar' => [
            'baz' => 'bob',
        ],
    ],
]);

$collection->get('foo.bar.baz')

I want this code to take the dot-notated path and return the value. The Collection object doesn't support this though. One solution would be swapping out the Collection::get() call for a data_get() call.

$baz = data_get($collection, 'foo.bar.baz');

That does actually work since the data_get() function has some special logic for Collection objects. From a readability point of view, it's not quite as nice though. The Collection object is known for its fluency and method chaining and this bit of code doesn't fit into that pattern.

Let's add a macro the Collection object that does this logic for us.

use Illuminate\Support\Collection;

Collection::macro('path', function (string $path) {
    return data_get($this, $path);
});

The Macroable::macro() method accepts 2 arguments. The first is the name of the macro and the second is a Closure or callable value.

We can now call a magic path() method on the $collection and it will return the value found at the path provided.

$baz = collect([
    // ...
])
    ->path('foo.bar.baz');

Behind the scenes the method call is being delegated to the __call() method implemented by the Macroable trait. It will check if the macro exists and invoke the callback if it does.

What is special about the callback is that we can use $this and reference the object we're calling the macro on instead of the $this context where the macro is defined.

Inside of the Closure, $this is actually the Collection object that we created. To help our IDE understand the context a little more, we can add a DocBlock at the top of the Closure.

Collection::macro('path', function (string $path) {
    /** @var \Illuminate\Support\Collection $this */
    return data_get($this, $path);
});

Intellisense

Since macros are defined at runtime, your IDE likely won't be able to provide any autocomplete or intellisense. I've found the best way to fix this problem is by creating a "stubs" file that has a carcass definition of your macros.

This file has multiple purposes:

1. It lets your IDE and static analysis tools discover the macros your define.
2. It serves as a single-source of truth for the macros that you define in your project.

I typically create a .stubs.php file in the root of my project. The path() macro might be stubbed out like below.

<?php

namespace Illuminate\Support
{
    class Collection
    {
        public function path(string $path): mixed {}
    }
}

If your tooling is able to scan that file, it should add the Collection::path() definition to its indexes and provide some autocomplete for you.

I've noticed that the bounce rate on my blog is pretty poor. I don't write a lot of content these days but I have written quite a few posts in the past. My theory is that I'm not suggesting content to people so they're never actually visiting other pages.

I want to try to improve that since the content I've written in the past can easily get lost amongst the latest posts.

Here's my grand plan:

• Add a field to store keywords on my blog posts
• Write a script to fill in keywords based on category and title
• Add a keywords field to Filament
• Start recommending blog posts based on matching keywords

Storing keywords

As I mentioned, my blog uses Orbit to store content in the form of a Markdown file and interact with those files using Eloquent models.

Adding a new keywords field to the Post model is really simple. We just need to update our model's schema.

public static function schema(Blueprint $table)
{
    $table->string('title');
    $table->string('slug');
    $table->text('excerpt')->nullable();
    $table->text('content')->nullable();
    $table->json('keywords')->nullable();
    $table->timestamp('published_at')->nullable();
    $table->string('category_slug')->nullable();
}

We'll also need a cast since we want this to return a PHP array.

protected $casts = [
    'published_at' => 'datetime',
    'keywords' => 'json',
];

Now our Post model is able to store keywords inside of the Markdown content files.

Filling in missing keywords

All of the posts on my blog are categorised. They belongTo a single Category model.

I'm going to write a command that loops over each Post, checks the Category it belongs to and fills in the keywords field with some standard values.

The command is only going to be run once, so I'm not going to bother with a dedicated Command class. Instead I'll opt for the simpler approach and write all of the logic inside of the routes/console.php file.

We need to grab all of the posts on the site.

Artisan::command('script:fill-missing-keywords', function () {
    $posts = Post::all();

    // ...
});

The only thing left to do is loop over each of the posts and update the keywords accordingly.

Artisan::command('script:fill-missing-keywords', function () {
    $posts = Post::all();

    $posts->each(function (Post $post) {
        $post->update([
            'keywords' => match ($post->category?->slug) {
                'alpinejs' => ['alpine', 'alpinejs', 'frontend', 'javascript', 'js'],
                'css' => ['css', 'style', 'styling', 'tailwind'],
                'github-actions' => ['actions', 'ci', 'cd', 'github'],
                'insights' => ['insights'],
                'javascript' => ['javascript', 'js', 'alpine', 'alpinejs'],
                'laravel' => ['php', 'laravel', 'laravelphp', 'blade', 'model', 'eloquent'],
                'livewire' => ['livewire', 'laravel', 'php', 'reactive', 'ssr', 'wire'],
                'php' => ['php', 'server', 'laravel', 'programming'],
                'programming-languages' => ['pl', 'plt', 'programming-language', 'programming'],
                'tailwind-css' => ['css', 'style', 'tailwind', 'tailwindcss'],
                'tips-tricks' => ['tips', 'tricks', 'tips-tricks', 'php', 'livewire',],
                'tooling' => ['tooling', 'tips'],
                default => [],
            }
        ]);
    });
});

Each Category has a slug column. Matching against that we can set the value of keywords to some array of strings. This could run a little faster if we eager-load the category relationship but it's a one-time script so I'm not too bothered.

Running this command will update the Markdown files. Progress!

Setting keywords from Filament

I normally write my content in Markdown files directly but sometimes I need to fix typos. It's quicker for me to do that through an admin panel so I use Filament.

To update keywords from Filament, we just need to add a new field to the PostResource. I'm going to use a TagsInput field that accepts a list of strings.

public static function form(Form $form): Form
{
    return $form
        ->schema([
            Card::make([
                // ...
                TagsInput::make('keywords')
                    ->columnSpan(2)
                    ->nullable(),
                // ...
            ])
                ->columns(2)
        ]);
}

Finding related posts

With all of that in place, we can finally write the method to find related posts. I'm going to do this in a method on the Post model directly.

Before you look at the code, it's worth mentioning that Orbit uses an SQLite database under-the-hood to proxy the flat content files between the filesystem and Eloquent. This is a trick that was first introduced by Caleb Porzio with Sushi.

public function relatedPosts(): Collection
{
    return static::query()
        ->select('posts.*')
        ->fromRaw('posts, json_each(posts.keywords)')
        ->where($this->getKeyName(), '!=', $this->getKey())
        ->whereIn(DB::raw('json_each.value'), $this->keywords)
        ->distinct()
        ->get();
}

There's a little bit of SQLite wizardry going on here. If this were a MySQL query you could run a JSON_CONTAINS() check on the keywords column and check if the array of keywords contains any matching values.

Sadly SQLite doesn't have the same level of JSON support as MySQL and Postgres. To work around this, we instead need to use the json_each() function.

The json_each() function will produce a separate row in the query result for each value found in the JSON column. If a row in the posts table contains 7 keywords, that row will be returned 7 times each with the respective keyword. The string from the JSON column will get put into a kind of virtual table for that query called json_each so we can run comparison checks on the json_each.value column.

I couldn't find a method to add the json_each call natively in Laravel so I went with a fromRaw() call that adds in the posts table and the json_each call.

We also want to exclude the current post to make sure we're not suggesting the same post the visitor is currently reading.

Some of you might be questioning the choice to use an Eloquent query here instead of a plain DB query. Using an Eloquent query will ensure that the query results are still transformed into Post model instances.

Outputting related posts

The Post::relatedPosts() method can now be used inside of our Blade template to output a couple suggestions at the very end of the blog post.

@php($relatedPosts = $post->relatedPosts())
@if($relatedPosts->isNotEmpty())
    <div id="suggestions" class="space-y-4">
        <h4>You might also enjoy...</h4>

        <div class="space-y-2">
            @foreach($relatedPosts->shuffle()->take(2) as $post)
                <x-post-card :post="$post" :excerpt="false" />
            @endforeach
        </div>
    </div>
@endif

Pretty simple Blade logic here. If we find some related posts, we loop over them and output the x-post-card Blade component. The excerpt is disabled to save some vertical space.

We also shuffle the posts and take the first 2 results so that we don't end up suggesting the same 2 posts to every visitor.

Result

With all of that in place, you should be able to see some post suggestions at the end of this page.

If you want to see all of the code changes, the pull request can be found here.

Probably worth clicking through and reading one of those suggested posts, right?

The package itself receives hundreds of thousands of hits via the CDN each month and has become quite popular.

Something that is quite common is using a template element in your HTML to provide Tippy with content. A recent release of my package (v1.2.0) now lets developers provide a raw Tippy configuration object to the x-tooltip directive.

This new integration path makes it simple to use other Alpine directives and <template> tags to generate the content for your tooltip.

Using <template> tags for content

<div x-data="{ message: 'Hello, world!' }">
    <template x-ref="template">
        <p x-text="message"></p>
    </template>

    <button type="button">
        Show message!
    </button>
</div>

I want to use the <template> tag here as my tooltip content. Tippy doesn't know about this element, so we need to use a configuration object to inform Tippy of its existence and innerHTML.

This can be done with the x-tooltip directive on <button> the like so:

<button x-tooltip="{
    content: () => $refs.template.innerHTML,
}">
    Show message!
</button>

The content property on the object is a callback function. This function is invoked by Tippy before each tooltip render and the return value should be a string or an HTML element. We'll use a string since the element itself is a <template> and doesn't actually get rendered by the browser in this scenario.

Tippy will render all HTML as plain text for security reasons. To prevent this, we also need to tell Tippy to allow HTML content using the allowHTML property.

<button x-tooltip="{
    content: () => $refs.template.innerHTML,
    allowHTML: true,
}">
    Show message!
</button>

Hovering over the button now will present an empty element... not so good. If you inspect the DOM, you'll see that Tippy actually appends an HTML element to the <body> of the document via document.body. This element is what appears when hovering or interacting with the button.

Our Alpine component is only scoped to the original <div> where x-data or x-init is defined. It doesn't operate outside of that element and therefore can't process the tooltip's HTML content.

To solve this, Tippy needs to append the dynamic tooltip element to a different element inside of the Alpine component's scope. This can be achieved using the appendTo property.

<button x-tooltip="{
    content: () => $refs.template.innerHTML,
    allowHTML: true,
    appendTo: $root,
}">
    Show message!
</button>

Using the magic $root variable, Tippy will append the tooltip's HTML element to the end of our Alpine component instead of the <body>. This means Alpine can process the HTML and bind text, event listeners etc.

Interactive HTML

The HTML rendered by Tippy won't be interactive by default. This means that links and other elements in the tooltip will essentially be unreachable by the user.

Tippy provides an interactive property that reverses this and allows interactive HTML elements to be interacted with.

<button x-tooltip="{
    content: () => $refs.template.innerHTML,
    allowHTML: true,
    appendTo: $root,
    interactive: true
}">
    Show message!
</button>

As developers we spend a lot of time in the browser. Let me show you some of my favourites, things I wouldn't be able to go without.

The code in this post won't be in the correct format for a bookmarklet since it's not super readable. I'd recommend using a bookmarklet generator like this one or this one.

Unique plus-alias emails

When you're testing applications, you'll probably need to create an account. This bookmarklets will create a unique email address using + aliases and UNIX timestamps.

(function () {
    window.navigator.clipboard.writeText(`youremail+${Date.now()}@yourdomain.com`)
})()

It's an IIFE that will copy a unique email address to your clipboard. This is great for testing registration forms and emails.

Quick color picker

I find myself converting colors from hex codes to RGB and HSL a lot. Instead of using a dedicated desktop app for this, I can just use the browser's own color picker.

<html>
    <title>Color Picker</title>
    <input type="color">
</html>

Disabling client side validation

Most of the forms I build use server-side validation as well as client-side validation. Testing the server-side validation rules can be a pain when they also have client-side counterparts (required, min, max, etc).

To get around this, I have a bookmarklet that will disable client-side validation on all forms.

(function () {
    document.querySelectorAll('form').forEach(form => form.noValidate = true)
})()

Simple, but super productive!

Design mode

Modern browsers have the something called "design mode". It turns the current page into an editable document, allowing you to modify text. Perfect for when a client or manager is asking what a piece of copy looks like in a certain position.

(function () {
    document.designMode = (document.designMode === 'on' ? 'off' : 'on')
})()

If you've got some cool bookmarklets that you'd like me to add to this article, let me know on Twitter. I'm always looking for new ways to increase / improve my productivity.

I wrote about saving for a deposit in last year's review. That deposit was eventually used after securing a mortgage and purchasing our first house. It's been super nice to have our own space with a dedicated office for my work.

Work

I'm still a full-time developer at Surewise and I've managed to enhance our tech stack even further this year. We've continued to adopt Livewire and Alpine.js.

We've also adopted Tailwind in some of our newer projects and systems, finally making the move away from heavily-overwritten Bootstrap.

I've also been hot on PHP upgrades. We started the year on PHP 7.4 and upgraded to PHP 8.0 pretty quickly and we're now aiming for an upgrade to PHP 8.1 in Q1.

Freelancing

Last year I started freelancing / contracting for other businesses who were looking for TALL stack help. I continued doing that in 2021 and have completed a plethora of projects.

There has been a huge variety of work coming in and I've enjoyed every second of it.

Open-source

Just like last year, I have spent a good chunk of time contributing to open-source projects and releasing some of my own.

I've made more than 4000 contributions to repositories of GitHub this year. Here are some of my personal favourites.

Filament

Filament is a set of Laravel packages designed for TALL stack development. It provides a table builder, form builder and highly extensible admin-panel package for your Laravel applications.

I joined the project after using it myself on this blog and some other toy projects and sending in multiple contributions. Since then, Dan has worked hard on the 2.x release and I've tried my best to contribute wherever possible.

Using these packages myself has allowed me to see some flaws and opportunities for refinement, which is never a bad thing. Dog-fooding is one of the best ways to do this.

Alpine Packages

Alpine 3.x was released in 2021 and this came thing an amazing new plugin API. I took some of my older 2.x packages and upgraded them to support 3.x.

At the time of writing this post, my Alpine Clipboard package receives more than 1 million hits per month on the CDN and my Alpine Tooltip packages receives more than 150,000 hits per month.

The Spruce library was archived and no longer receives updates since Alpine provides a first-party global state solution. Despite that, the CDN still recieves almost 100,000 hits per month.

Other work

I've been super interested in programming language theory, design and development in 2021. I've played around with multiple language ideas and have open-sourced a couple on GitHub.

A lot of this work was done using the Rust programming language which I really enjoy using. I even streamed it a few times on YouTube.

I'd like to continue this journey in 2022 and work on a solid programming language that targets a specific domain (not crypto, dw). Some of the areas that interest me are:

• Mathematical calculations and data science
• Graphical application development
• Word processing

Who knows? Perhaps I'll have a language by the end of the year that people actually use and find helpful.

Epilogue

I want to thank everybody who has supported my work over the last year through Twitter, GitHub and sponsorships. It really does mean a lot.

I set myself some goals last year and can confirm that I completed the following:

• Convincing Taylor to follow me on Twitter.
• Released at least 3 new open source packages.
• Met new friends.
• Wrote more blog posts and helped people out.

Going forward into 2022, I would like to do the following:

• Reach 5,000 followers on Twitter - currently at 3,000.
• Stream on YouTube at least once a month.
• Continue writing more blog posts.
• Speak at a conference.

We'll see that how goes next year.

At the end of the post, we'll be able to provide our virtual machine with a few mathematical instructions and it will be able to run through those instructions and produce an answer.

We'll be using JavaScript to build our virtual machine so that we don't get lost in type-system details. Most people can read and understand JavaScript too, so it's great for teaching new concepts.

What is a virtual machine?

Before we look at how to build one, let's briefly talk about what a virtual machine is.

At the highest level, a virtual machine is just a software-implementation of a computer. It loosely simulates the behaviour of a CPU by reading instructions and performing actions based on those instructions. Virtual machines are commonly used by programming languages to implement their interpretation layer. This is where the programming language actually does most of the logical work.

What is a stack machine?

There are many types of virtual-machine, so to keep things simple we'll be building one of the simplest.

A stack-based virtual machine uses the stack to, more often than not, store short-lived temporary values. You can think of the stack as an array that is constantly being pushed to, as well as popped from.

When you encounter some form of value, you will generally push that value to the stack. When you encounter an instruction, it will likely need some sort of argument to operate or (commonly known as an operand). This argument is retrieved from the stack by popping it from the end, removing it from the stack completely.

Instructions and Operands

Our virtual machine is going to act a simple calculator. We'll be able to ADD, SUBTRACT, DIVIDE, MULITPLY and PRINT values using a combination of instructions and values.

Let's take a look at a simple ADD instruction. We'll start off by creating a global constant in our program called ADD and use its string equivalent as the value.

const ADD = 'ADD';

Let's also create an array to store our instructions in.

const ADD = 'ADD';

const instructions = [
    ADD,
];

If you think of the + operation in a mathematical equation, you have 2 operands. The equation 1 + 2 is adding the numbers 1 and 2 together, making them the operands in the equation.

Our ADD instruction will behave in the exact same way. We will need to provide 2 numbers for it to function correctly. The simplest way to do this is by adding them to the instructions array before our ADD instruction.

const instructions = [
    1, 2, ADD,
];

We place them before the instruction so that the ADD instruction can pop them off of the stack and then add them together. To show this in action, let's start creating our main evaluation loop as well as our stack.

We'll use a for..of loop so that we can have direct access to the instruction, as opposed to the instruction's index in the array.

const stack = [];

for (const instruction of instructions) {
    if (! Number.isNaN(instruction)) {
        stack.push(instruction);
        continue;
    }
}

We start by handling our numeric values. To check if something is a number, we can use the isNaN() function. If it returns false, it must be a number. In that case, we can push the value onto the stack and move on to the next iteration.

To keep things super simple, let's use a switch statement to handle all of our instructions:

for (const instruction of instructions) {
    if (! isNaN(instruction)) {
        stack.push(instruction);
        continue;
    }

    switch (instruction) {
        case ADD:
            let b = stack.pop()
            let a = stack.pop()
            stack.push(a + b)
            break;
        default:
            throw new Error(`Unhandled instruction: ${instruction}`)
    }
}

When we encounter an ADD instruction, we can pop the 2 operands from the stack. The first value that is popped will be the second (right-hand) operand to the equation.

This can be quite confusing at first, but it's all down to the order that they were pushed in. The first value we pushed was 1, the left-hand side of the equation. The second value was 2, the right-hand side of the equation. When the first value is popped off of the stack, it'll be the number 2.

Once we have both a and b, we can add the 2 numbers together and push the value back on to the stack.

To help with debugging, let's create a new PRINT instruction that will print pop the last value from the stack and run it through console.log().

const ADD = 'ADD';
const PRINT = 'PRINT';

const instructions = [
    1, 2, ADD,
    PRINT,
];

for (const instruction of instructions) {
    if (! isNaN(instruction)) {
        stack.push(instruction);
        continue;
    }

    switch (instruction) {
        case ADD:
            let b = stack.pop()
            let a = stack.pop()
            stack.push(a + b)
            break;
        case PRINT:
            console.log(stack.pop())
            break;
        default:
            throw new Error(`Unhandled instruction: ${instruction}`)
    }
}

If we run this program now, we can expect the number 3 to printed to the console.

Subtraction, Multiplication and Division

With the ADD and PRINT instructions in place, let's add the logic for SUBTRACT, MULTIPLY and DIVIDE.

const ADD = 'ADD';
const SUBTRACT = 'SUBTRACT';
const MULTIPLY = 'MULTIPLY';
const DIVIDE = 'DIVIDE';
const PRINT = 'PRINT';

// ...

for (const instruction of instructions) {
    if (! isNaN(instruction)) {
        stack.push(instruction);
        continue;
    }

    switch (instruction) {
        case ADD:
            let b = stack.pop()
            let a = stack.pop()
            stack.push(a + b)
            break;
        case SUBTRACT:
            let b = stack.pop()
            let a = stack.pop()
            stack.push(a - b)
            break;
        case MULTIPLY:
            let b = stack.pop()
            let a = stack.pop()
            stack.push(a * b)
            break;
        case DIVIDE:
            let b = stack.pop()
            let a = stack.pop()
            stack.push(a / b)
            break;
        case PRINT:
            console.log(stack.pop())
            break;
        default:
            throw new Error(`Unhandled instruction: ${instruction}`)
    }
}

We now have a nice set of instructions to calculate some simple mathematical equations. Let's update our instructions array and calculate the value of 1 + 2 * 3.

const instructions = [
    1,
    2, 3, MULTIPLY,
    ADD,
    PRINT,
]

The order of these instructions might seem a little strange at first, but it's all to do with the precedence of each sub-calculation. If we were to insert some parentheses into the equation, it would really look like 1 + (2 * 3) because the multiplication needs to be calculated separately.

Putting that into words we're really calculating the result of 1 added to the result of 2 * 3. Our instruction set is doing the same. We first push the value of 1 onto the stack. The value of 2 * 3 is then calculated and pushed back on to the stack.

When the ADD instruction is reached we pop the result of 2 * 3 from the stack, as well as the value of 1 and add those together, pushing the result back on to the stack.

With any luck, running this program will print 7 in the console.

A small problem

At the moment we can only print a value at the very end of the program. This is because the PRINT instruction will pop the last value off of the stack permanently, meaning any further instructions might not have a value to pop off.

To fix this, we can update our PRINT case to instead retrieve the last value from the stack and print it.

case PRINT:
    console.log(stack[stack.length - 1])
    break;

Refactoring

There's lot of duplicated code in our instruction handling at the moment. All of our mathematical operations are popping 2 values from the stack and pushing back the result of the operation.

To tidy this up, we could create some sort of instruction handler function for each of our instructions. Let's start by creating a handler object that maps the instruction to a callback function.

const handler = {
    ADD: (a, b) => a + b,
    SUBTRACT: (a, b) => a - b,
    MULTIPLY: (a, b) => a - b,
    DIVIDE: (a, b) => a / b,
}

When we encounter one of our mathematical instructions, we can create a common case block that pops the values and invokes one of these functions.

for (const instruction of instructions) {
    if (! isNaN(instruction)) {
        stack.push(instruction);
        continue;
    }

    switch (instruction) {
        case ADD:
        case SUBTRACT:
        case MULTIPLY:
        case DIVIDE:
            let b = stack.pop()
            let a = stack.pop()
            let result = handler[instruction](a, b)

            stack.push(result)
            break;
        case PRINT:
            console.log(stack[stack.length - 1])
            break;
        default:
            throw new Error(`Unhandled instruction: ${instruction}`)
    }
}

This removes a lot of code duplication from our switch statement and gives us a single place to add new instruction handlers in the future.

Next steps

Now that you've created your own stack-based virtual machine, why not try to write a parser that converts a mathematical equation such as 1 + 2 / 3 * 4 into a set of instructions and runs them through your machine. Doing this will essentially give you a tiny calculator program that can grow further into a domain-specific language or general-purpose programming language.

There is no concept of null or nil in Rust, nor is there any concept of optional parameters in function definitions.

This is one of the things that makes Rust's type system so powerful, reliable and, at times, annoying.

The Option type itself is actually just an enum (enumeration) that is defined as:

enum Option<T> {
    Some(T),
    None
}

In Rust, enums are able to hold values inside of variants. This is something that has been thought of in PHP land too.

Rust provides some global constructors for the Option type too. You don't need to type Option::Some(value) everytime, you can just type Some(value).

If you were to add an optional parameter to a function, it would look something like this:

fn hello(name: Option<String>) {
    let name = if name.is_some() {
        name.unwrap()
    } else {
        "World!".to_string()
    }

    println!("Hello, {}", name)
}

Again, the Option enum is generic so you need to provide the type of the wrapped value.

Calling unwrap() on the Option will return the inner value, in this case a String. If the Option is None, then the program panics and fails to run.

Why is this better?

The Option type is best used in situations where you sometimes return a value from a function (typically an object).

It's not uncommon to forget about the cases where no value, or null, is returned from the function.

By introducing an Option type you have to explicitly handle the None or null case, otherwise you won't be able to access the wrapped value.

Here's an example in a Laravel application:

$name = Auth::user()->name;

If the user is logged in this code will work fine. If the user isn't logged in, Auth::user() will return null and the ->name access will error out.

In PHP 8, you could handle this with the ?-> (nullsafe) operator but you would still end up with a null value in $name.

If the Auth::user() function used Option:

public function user(): Option
{
    return $this->user ? new Some($this->user) : new None;
}

To access the User, you would need to do something like this:

$user = Auth::user()->unwrap();

If None is returned from the Auth::user() function, the unwrap() method call will fail and throw an Exception because you can't unwrap a None value.

You have to explicitly consider the None scenario when working with Option.

Creating the type

We can start by defining an interface for our Option type that the Some and None types will implement.

I'll be writing PHP 8.0 compatible code. If you haven't upgraded already, you definitely should.

interface Option
{
    public function isSome(): bool;

    public function isNone(): bool;

    public function unwrap(): mixed;
}

These three functions are the bare essentials. You'll be able to determine if a type is None, Some and retrieve the internal value.

None

With this interface defined, we can go ahead and create our None type.

class None implements Option
{
    public function isSome(): bool
    {
        return false;
    }

    public function isNone(): bool
    {
        return true;
    }

    public function unwrap(): mixed
    {
        throw new \RuntimeException('Attempt to call `unwrap()` on `None` value');
    }
}

The None type is the simplest. The unwrap() method will throw a \RuntimeException as you can't unwrap a None value.

In PHP 8.1 you could replace the mixed return type with never as it always throws a \RuntimeException.

Some

The Some type has a little more going on. We need to define a __construct method to actually hold the value and also return that value from unwrap().

class Some implements Option
{
    public function __construct(
        protected mixed $value
    ) {}

    public function isSome(): bool
    {
        return true;
    }

    public function isNone(): bool
    {
        return false;
    }

    public function unwrap(): mixed
    {
        return $this->value;
    }
}

With these implemented, we can go ahead and write our first function that uses Option.

function sayHello(Option $name) {
    $name = $name->isNone() ? 'World' : $name->unwrap();

    echo "Hello, {$name}!";
}

sayHello(new None);         // Outputs "Hello, World!"
sayHello(new Some('Ryan')); // Outputs "Hello, Ryan!"

unwrapOr()

When you start using Option, you'll find yourself using ?: (ternaries) or if..else statements to set default values.

We can help ourselves out by introducing a new unwrapOr(mixed $or) method.

Let's first add it to our Option interface.

interface Option
{
    public function unwrapOr(mixed $or): mixed;
}

And then implement in our Some and None classes.

class Some implements Option
{
    public function unwrapOr(mixed $or): mixed
    {
        return $this->unwrap();
    }
}

The Some class should always hold a value, so we will never need to return the $or.

class None implements Option
{
    public function unwrapOr(mixed $or): mixed
    {
        return $or;
    }
}

The None class can never be unwrapped so we will always return the value of $or.

With this method in place, we can remove the ternary from our sayHello() function:

function sayHello(Option $name) {
    $name = $name->unwrapOr('World');

    echo "Hello, {$name}!";
}

Generics

PHP doesn't support runtime generics. There is no first-party syntax for them either.

We're very fortunate to have static analysis engines though, so we can use DocBlocks to imitate generic types.

Let's start by adding some annotations to your Option interface.

I'll be using annotations supported by PHPStan.

/**
 * @template T
 */
interface Option {
    // ...
}

This makes the Option type generic on T. To actually make T do something, we'll need to tell the analyser where T comes from.

Let's add some annotations to the Some type.

/**
 * @template T
 *
 * @implements \Option<T>
 */
class Some implements Option
{
    // ...
}

These class-level annotations will tell the analyser that the Some class is also generic and that the type of T in Some should also be used as the generic type of Option which we're implementing.

Since our unwrap() and unwrapOr() method return a mixed type inside of Some, we can't guarantee that any further method calls or property access is valid.

To tackle this we can add more annotations to those methods, as well as the property promotion in our constructor.

/**
 * @template T
 *
 * @implements \Option<T>
 */
class Some implements Option
{
    public function __construct(
        /** @var T */
        protected mixed $value
    ) {}

    /**
     * @return T
     */
    public function unwrap(): mixed
    {
        return $this->value;
    }

    /**
     * @return T
     */
    public function unwrapOr(mixed $or): mixed
    {
        return $this->unwrap();
    }
}

Adding the @var annotation to the promoted property, the analyser will figure out that the type of $value should be used as T.

It can then detect any problems with unwrap and unwrapOr calls.

Possible Refactoring

I've implemented everything inside of an Option interface and 2 classes that implement that interface.

This means that our Some and None classes have to implement all of the methods that are part of the contract.

It's not the prettiest thing ever, so if you wanted to refactor this you could instead create an abstract class Option that the Some and None classes extend.

You can then implement the methods inside of the abstract class instead and reduce some of the duplication between the two option types.

PHP 8.1 and beyond

PHP 8.1 will be introducing first-party enum types. This brings us one tiny step closer to a Rust-like implementation:

enum Option {
    case Some;
    case None;
}

The only differences between the two languages would be that fact that PHP can't hold values inside of enum variants and that they can't be generically typed.

I hope that PHP will get tagged enums in the near future. This draft RFC has already started the conversation.

With tagged enums, we could have something like this:

enum Option {
    case Some(private $value);
    case None;
}

Add some generics ontop and we have a slightly more verbose but more powerful Option type.

enum Option<T> {
    case Some(private T $value);
    case None;
}

It provides a fluent builder pattern for declaring expectations and making assertions against your data.

Here's a very simple example:

$names = [
    'Ryan',
    'John',
    'Jane',
];

expect($names)
    ->toBeArray()
    ->toHaveCount(3)
    ->toMatchArray([
        'Ryan',
        'John',
        'Jane',
    ]);

Each of the method calls makes an assertion on the data provided to expect().

When you're working with objects, you can also use higher-order expectations to make assertions against properties and method return values.

One tricky problem that I have faced today is that you can't use the HigherOrderExpectation object as an array.

This prevents you from doing something like this:

$object = new class {
    public function getNames()
    {
        return [
            'Ryan',
            'John',
            'Jane',
        ];
    }
};

expect($object)
    ->getNames()[0]
    ->toBe('Ryan');

When you call getNames(), the HigherOrderExpectation class will proxy that method call to the original object that was passed in and return a new instance of HigherOrderExpectation with the return value of the method inside.

It does this because the method doesn't explicitly exist on the HigherOrderExpecation class or the Expectation class.

It does the same for properties too. The retrieve() method that is used to proxy the property access actually checks whether the base value is an array or not.

If the value is an array, it will take the property name and try to find a value with that key.

Unfortunately PHP doesn't let you use numeric values when accessing properties, so something like $object->0 fails.

What you can do instead is use PHP's {} interpolation syntax to create dynamically access a property. Pest will then attempt to find an array with that key and return an instance of HigherOrderExpectation with that value.

This means we can test individual array items with the Expectation API.

expect($object)
    ->getNames()->{0}
    ->toBe('Ryan');

This would return the value as index 0 so that we can perform assertions.

If you had non-numeric array keys, you can use the normal property access syntax as Pest will proxy those to the array.

$ages = [
    'Ryan' => 100,
];

expect($ages)
    ->Ryan->toBe(100);

I do have a work in progress branch that adds support for the [] syntax as it definitely feels more familiar, but in some cases the syntax is a bit strange, e.g. expect($value)[0]->toBe('Ryan')[1]->toBe('John')

PHP isn't the first language to introduce the concept of a match expression. It has existed in programming languages for quite a while, for example Rust, Scala and more recently Python.

Here's what a match expression looks like:

match ($subject) {
    [condition] => [result]
}

In its current state match is a hyper-optimised switch statement.

You can use it to conditionally evaluate an expression based on a [condition].

There are a few key differences between match and switch though:

1. match uses strict comparisons. This means that an int subject can't match a string condition.
2. match only evaluates one condition at a time, whereas switch evaluates all case conditions before calculating the result.
3. match only allows single-line expressions to be used in the place of [result], where as switch allows blocks of code to be executed for each case.

Let's take a switch statement and convert it to a match expression.

switch ($name) {
    case 'Ryan':
        echo 'Hello, Ryan!';
        break;
    case 'John':
        echo 'Hello, John! How are you?';
        break;
    default:
        echo 'Hello!';
}

Here's the equivalent code written in the form a match expression:

echo match ($name) {
    'Ryan' => 'Hello, Ryan!',
    'John' => 'Hello, John! How are you?',
    default => 'Hello!'
};

The match expression is definitely more concise.

It's also an expression, meaning it returns a value. This is great as we can use it next to the echo statement directly. We don't need to write an echo for each case like we do for a switch statement.

Multiple conditions, one result

If we had a switch statement that had multiple cases executing the same block of code, we'd do something like this:

switch ($name) {
    case 'Ryan':
    case 'John':
        echo 'Hello, Ryan or John!';
        break;
    default:
        echo 'Hello!';
}

To achieve the same effect in a match expression, we can separate the [condition] expressions with commas:

echo match ($name) {
    'Ryan', 'John' => 'Hello, Ryan or John!',
    default => 'Hello!'
};

Generalised match statements

Imagine you have the following code:

$age = (int) $request->input('age');

if ($age < 25) {
    return $this->lessThanTwentyFive();
} elseif ($age < 50) {
    return $this->lessThanFifty();
} elseif ($age < 75) {
    return $this->lessThanSeventyFive();
} else {
    return $this->olderThanSeventyFive();
}

Personally I find elseif statements hard to read. They make the code dense and hard to understand at a glance.

Since we're using boolean values inside of the expression, we can actually convert this into a match expression:

$age = (int) $request->input('age');

return match (true) {
    $age < 25 => $this->lessThanTwentyFive(),
    $age < 50 => $this->lessThanFifty(),
    $age < 75 => $this->lessThanSeventyFive(),
    default => $this->oldThanSeventyFive(),
}

Method and functions calls are expressions, so we can use those in the [result] part of the match expression.

match also returns a value so we can use it as the expression in a return statement.

In the future, we could see the (true) part disappear with the "short match" RFC.

Array pattern matching

Although PHP doesn't support complex pattern matching (RFC), you can actually do some light pattern matching when using a match expression with an array.

Here's an example of how you might do something based on the values of an array:

// Pseudo-data that you might receive from the front-end.
$options = [
    'monthly',
    'credit-card',
];

if ($options[0] === 'monthly' && $options[1] === 'direct-debit') {
    return $this->setupDirectDebit();
} else if ($options[0] === 'yearly' && $options[1] === 'credit-card') {
    return $this->takeYearlyCardPayment();
} else if ($options[0] === 'monthly' && $options[1] === 'credit-card' {
    return $this->setupCardSubscription();
}

Again, else if statements can be confusing. Maybe there's a better way to write this code using match expressions.

// Pseudo-data that you might receive from the front-end.
$options = [
    'monthly',
    'credit-card',
];

return match ($options) {
    ['monthly', 'direct-debit'] => $this->setupDirectDebit(),
    ['yearly', 'credit-card']   => $this->takeYearlyCardPayment(),
    ['monthly', 'credit-card']  => $this->setupCardSubscription(),
};

We can actually use the match expression to match an exact array pattern. This is super handy and something that is quite common in other languages like Rust where you would match some sort of tuple pattern.

PHP doesn't have tuples, but arrays are close enough.

Beyond PHP 8.0

The match expression in its current state is good enough to replace simple switch statements, lookup tables and even some if..else statements.

There are still some things that can be added to the match expression to make it even cooler though.

Code blocks

match only support single-line expressions at the moment. You can't have multiple lines of code as the result of a match arm.

This was part of the original RFC, but the syntax was hard to get right so it was removed.

I'd love to see this added, perhaps with this syntax:

match ($subject) {
    [condition] => {
        // Write multiple lines of code here.
        
        // Semi-colon is omitted from the last expression and is used as the return value of the block.
        "Hello, world!"
    }
}

It's understandable why this syntax was difficult to get right. Using return to return a value from the block is a bit odd as that would typically return a value from the function.

Omitting the semi-colon on the last line, creating an implicit return, is also strange as that behaviour doesn't exist anywhere else in the language.

Introducing a new keyword could work, but it would be yet another keyword added to the language. PHP already has a tonne of reserved keywords.

Complex pattern matching

Pattern matching has already been discussed in this draft RFC.

It's a fairly advanced feature and has lots of use-cases which makes getting the RFC right very difficult.

Here's a simple example where we can check if an object matches a pattern based on the property values:

class Vector
{
    public function __construct(
        public int|float $x,
        public int|float $y
    ) {}
}

$vector = new Vector(0, 1);

$vector is Vector { x: 0, y: 1 }; // `true` 

The plan in the RFC is to introduce a new is keyword which would act as an "infix operator" (something that goes between 2 expressions).

The part on the left would be the subject and the right would be the pattern.

In this case, the pattern is checking if $vector is of the type Vector and if the property $x === 0 and $y === 1.

If we were to do this without the pattern matching, it'd look like this:

$vector instanceof Vector && $vector->x === 0 && $vector->y === 1;

It's very word-y. It's very verbose. Pattern matching is good.

Perhaps we only want to check if the $vector object has an $x value of 1. We can ignore the rest of the fields in the object using the .. token.

$vector is Vector { x: 1, .. }; 

Although this isn't part of the RFC, it's something that I absolutely love in Rust.

If we took this pattern matching and paired it with a match expression, we'd end up with something like:

$vector = new Vector(0, 1);

match ($vector) {
    Vector { x: 0, y: 1 } => $vector->moveTo(0, 2),
};

The pattern moves into the [condition] spot and works exactly the same.

Some languages, like Rust, take this a step further an allow you to "bind" particular parts of a pattern to a variable in the match's scope.

Here's what that might look like:

echo 'Y co-ordinate: ' . match ($this->getVector()) {
    Vector { x: 0, $y @ y: 1 } => $y,
};

Bit of a silly example but it shows the concept. We can bind a specific part of a pattern to a variable using an @ token. We can then use the variable $y in the expression.

Sign off

There is definitely lots of room for new features when it comes to match expressions. Despite that, I still love them.

I've been replacing switch statements, if..else statements and boring array-powered lookup tables with them since upgrading to PHP 8.0.

If you haven't upgraded to PHP 8.0 yet, just do it. You're missing out on a lot of great stuff and PHP 8.1 is around the corner. Minimise your upgrade path!

Here are some commands that you've probably run before:

php artisan migrate --seed

php artisan migrate:fresh --seed

php artisan db:seed

Recently I learned that seeders can be more than just Factory runners.

Looking at the underlying Seeder class, you'll notice a couple of different properties:

namespace Illuminate\Database;

abstract class Seeder
{
    /**
     * The container instance.
     *
     * @var \Illuminate\Container\Container
     */
    protected $container;

    /**
     * The console command instance.
     *
     * @var \Illuminate\Console\Command
     */
    protected $command;

    // More stuff here...
}

$container

The $container property can be found in lots of classes provided by Laravel. It's the main way to automatically resolve dependencies, register bindings, etc.

If you want to read more about Laravel's container, visit the official documentation.

When you run a Seeder class via one of the many artisan commands, the $container property will actually be used to call the run() method defined on the class.

This means you can type-hint container-bound dependencies in your run method's signature to help with extra tasks.

class ExternalDataSeeder extends Seeder
{
    public function run(ExternalServiceClient $service)
    {
        $rates = $service->getRates();

        foreach ($rates as $rate) {
            // Do something with the rates here...
        }
    }
}

The ExternalServiceClient could be any class or object that has been bound to the container inside of a ServiceProvider or provided by a third-party package.

Dependency injection is a perfect way of removing the construction and resolution logic from the body of the run method.

$command

I think $command is my favourite of the two. As the DocBlock suggests, it holds an instance of Illuminate\Console\Command.

When you're running your seeders via artisan, this is likely going to be an instance of whichever command you're currently running.

The hidden power here is that we now have full access to the terminal, so we can show custom messages and provide extra information.

Let's take our $container example and provide some helpful output about what we're actually doing:

class ExternalDataSeeder extends Seeder
{
    public function run(ExternalServiceClient $service)
    {
        $rates = $service->getRates();

        foreach ($rates as $rate) {
            $rate = Rate::create([
                'name' => $rate['name'],
                'multiplier' => $rate['multiplier'],
            ]);

            $this->command->info("Created a new rate with name {$rate->name} and multiplier {$rate->multiplier}.");
        }
    }
}

$this->command->info() will print some text in a happy green colour to the console, providing the user with information about what the seeder is actually doing.

We can take this one step further and use $this->command->ask() to retreive some input from the user. Let's write a MakeUserSeeder class that creates a new User.

use App\Models\User;
use Illuminate\Support\Facades\Hash;

class MakeUserSeeder extends Seeder
{
    public function run()
    {
        $name = $this->command->ask('Name');
        $email = $this->command->ask('Email');
        $password = $this->command->secret('Password');

        User::create([
            'name' => $name,
            'email' => $email,
            'password' => Hash::make($password),
        ]);

        $this->command->info('User created successfully.');
    }
}

Running this seeder will ask the user to provide a name, email and password. It will then create that User in the database so that you can quickly login without needing to run a separate command or fill in a registration form.

Let's do one more thing. Let's replace our custom MakeUserSeeder with my package ryangjchandler/laravel-make-user.

We can begin by installing the package:

composer require ryangjchandler/laravel-make-user

This package provides a convenient make:user command that will ask similar questions to MakeUserSeeder. You can also extend the command to ask for extra data, more specific to your application.

Inside of our MakeUserSeeder, we can replace the custom logic with a single $this->command->call() statement:

class MakeUserSeeder extends Seeder
{
    public function run()
    {
        $this->command->call('make:user');
    }
}

This will invoke the make:user command inside of the current process, allowing the make:user command to write to the same "output" as the seeder. That means any $this->info() or $this->ask() calls made by the make:user command will appear in the terminal, just like they did in the original MakeUserSeeder.

All in all, I think this is pretty cool. With these 2 things, we can give our seeder classes superpowers and greatly reduce the number of commands or setup steps needed to get a local copy of the application running.

1. Model::truncate()

This is perfect for when you don't need to modify which records are being deleted and just want to delete all of them.

Post::truncate();

2. Model::query()->delete()

If you wanted to add some constraints onto the deletion, you'd likely want to use this method. The ::query() method just returns a new Builder instance, so you can chain you extra methods with, some, intellisense.

Post::query()
    ->delete();

Post::query()
    ->where('created_at', '<', now()->subYear())
    ->delete();

Spruce.store('counter', {
    count: 0,
})

Spruce.watch('counter.count', () => {
    // Do something here...
})

Anytime the counter.count property was updated, the callback would be called.

With the introduction of Alpine.store in Alpine 3.x there is no longer a dedicated watch method for stores, but we can still get the same effect with Alpine.effect (no pun intended):

Alpine.store('counter', {
    count: 0,
})

Alpine.effect(() => {
    const count = Alpine.store('counter').count;

    // Now do something with `count`...
})

This works because Alpine will keep track of any dependencies / reactive properties we use inside of the callback and invoke it when any of them change.

Keep in mind that Alpine will run this callback function atleast once, so make sure you check for your initial state and prevent anything from happening.

If you're not sure what a Proxy is or how it works, definitely go back and read that post.

In this post, I'll be creating an effect function that will allow us to react to changes on the Proxy and update the DOM.

What is an "effect"?

An effect is a side-effect of a data change. Generally speaking, it's a function that should be run when a particular piece of data changes.

Here's a good example:

<p id="greeting">Hello, reader!</p>

At the moment, this text is completely static. If we use an effect function, we can actually make this dynamic.

const greeting = document.querySelector("#greeting");

const data = reactive({
    greeting: "Hello, reader!",
});

effect(() => {
    greeting.innerText = data.greeting;
});

We haven't written the effect function yet, so let's start implementing it now.

function effect(callback) {
    callback();
}

This version of effect is the bare minimum. When we register an effect, we want to invoke / call it immediately to update the DOM.

Running effects when state changes

If you were to do something like data.greeting = 'Hello, John!', nothing will happen. Our DOM node won't be updated, which isn't very helpful.

What we can do is store all the effect callbacks in an array and call each one when our Proxy is updated.

const effects = [];

function effect(callback) {
    effects.push(callback);

    callback();
}

Inside of the Proxy.set handler, we can loop through the effects array and call each callback.

function reactive(object) {
    // ...

    return new Proxy(object, {
        // ...
        set(target, property, value) {
            target[property] = reactive(value);

            effects.forEach((effect) => {
                effect();
            });

            return true;
        },
    });
}

If we were to now run data.greeting = 'Hello, John!', the DOM node's innerText property will be updated with the value Hello, John!.

More efficient updates

The current system works quite well for small bits of reactivity, such as text changes or attribute changes.

If we were to have 50 different effects though, things would get a little bit out of hand and performance would take quite a big hit. That's because each change we make to data will invoke every callbacks inside of effects and if you're doing anything intensive such as AJAX requests, big loops or heavy DOM updates, your page will slow to a snail's pace.

To work around this issue, we can introduce dependency tracking. This is really just a fancy phrase for figuring out what data an effect callback is using.

The major benefit of dependency tracking is the fact that we will be able to only invoke / call the functions that were using the data being changed.

The first thing we need to do is update our effect callback slightly:

const effects = new Map();
let currentEffect = null;

function effect(callback) {
    currentEffect = callback;

    callback();

    currentEffect = null;
}

When we register a new effect, we will assign the callback to a currentEffect variable and remove the old effects array. This will allow us to reference the callback inside of our Proxy.get function later on.

We'll also want to store the effects for a particular Proxy somewhere. The best way to do this is with a Map object.

The Map object provides you with a key/value storage, similar to a normal object. The main difference is that you're not limited to string-based keys, you can actually store objects in the key.

This means we can store the target from our Proxy in the key and then an object literal ({}) in the value.

Here's an example:

const map = new Map();

const data = {
    user: "Ryan",
};

map.set(data, {
    user: [() => {}],
});

map.get(data)["user"]; // This returns an array containing an anonymous function.

Let's also make some changes to the Proxy.get method:

let effects = new Map;

function reactive(object) {
    //...

    return new Proxy(object, {
        get(target, property) {
            if (currentEffect === null) {
                return target[property];
            }

            if (! effects.has(target)) {
                effects.set(target, {});
            }

            const targetEffects = effects.get(target);

            if (! targetEffects[property]) {
                targetEffects[property] = [];
            }

            targetEffects[property].push(currentEffect)

            return target[property];
        },
        // ...
    });

Here's a breakdown of what's happening now:

1. Check if currentEffect is not null. If it's null, we want to just return the property without doing any tracking. It will only hold a value when effect() is doing something.
2. Check whether our Map has any entries for the target object. If it doesn't, we need to insert an empty object into the Map using Map.set().
3. We can then pull that object back out using Map.get(target).
4. We need to check whether the current property being accessed on the target has an entry inside of the object returned into targetEffects. If it doesn't, we can simply write to the object using [] notation.
5. Finally we can return the target[property] so that it still behaves like a normal object.

All of this combined allows us to track which properties are being used inside of currentEffect. Cool, right?

Running effects on change

Now that we know which effect callbacks rely on certain pieces of data, i.e. property, we can run only the required callbacks inside of Proxy.set.

let effects = new Map;

function reactive(object) {
    // ...

    return new Proxy(object, {
        // ...
        set(target, property, value) {
            target[property] = reactive(value);

            if (effects.has(target)) {
                const targetEffects = effects.get(target)

                targetEffects[property].forEach(effect => {
                    effect()
                })
            }

            return true;
        },
    });
}

Here's a breakdown of the logic:

1. We need to check whether the current target has any effects register. If it doesn't, we don't want to do anything as it will error out.
2. Then we want to pull all of the targetEffects for that target.
3. Once we have those effects, we can get the array for the property being updated and loop over it, invoking / calling each item in the array.

Wrapping up

And that's it! We now have a reactive object and an effect function that is invoked each time a relevant property in our data is updated.

In the next instalment, I'll show you how to create a reactive data object from an HTML attribute, similar to Alpine's x-data.

Until then, thank you for reading and I'll catch you next time!

We'll begin by understanding the Proxy object in JavaScript and create our own budget version of Alpine.reactive().

What is Proxy?

The Proxy object was introduced as part of the ES2015 specification. It allows you to intercept the basic operations on an object, for example retrieving a property, setting a property or deleting a property.

You're able to define your own callbacks / handlers for these operations. This is similar to how PHP's __get and __set magic methods work.

You receive the target object, the name of the property being accessed and when setting, the value that's being assigned.

Here's an example:

const proxy = new Proxy(
    {
        count: 0,
    },
    {
        get(target, property) {
            return target[property];
        },
        set(target, property, value) {
            target[property] = value;

            return true;
        },
    }
);

The code above shows a very basic Proxy handler. The behaviour implemented inside of the get and set methods isn't anything special, it's just returning the property from target and setting it to value. It's really just a regular object.

If we wanted to get fancy, we could put a console.log inside of the get() handler.

const proxy = new Proxy(
    {
        count: 0,
    },
    {
        get(target, property) {
            console.log(`Trying to access ${property}.`);

            return target[property];
        },
    }
);

proxy.count;

When the proxy.count expression is evaluated, the console.log will be called and appear in your console.

One thing that confuses people a lot about Proxy is that it doesn't change how you interact with the underlying value.

If you wrap an Array in a Proxy, you can still do myWrappedArray.push or myWrappedArray.filter.

Creating a function

Now that we know what a Proxy is, let's create a new function:

function reactive(object) {
    return new Proxy(object, {
        get(target, property) {
            return target[property];
        },
        set(target, property, value) {
            target[property] = value;

            return true;
        },
    });
}

One thing that we haven't covered in this function is nested Proxy instances. Imagine the following scenario:

const user = reactive({
    name: 'Ryan',
    address: {
        postcode: 'TT1 1TT'
    }
})

// How do we intercept this!?
user.address.postcode = 'TT2 2TT';

When we update user.address.postcode, the set handler in our Proxy won't be called as the address object inside of user isn't reactive.

Don't worry, this is easy to fix. We can recursively call reactive for each of the properties on our original object when they're typeof is object.

function reactive(object) {
    if (object === null || typeof object !== 'object') {
        return object;
    }

    for (const property in object) {
        object[property] = reactive(object[property])
    }

    return new Proxy(object, {
        get(target, property) {
            return target[property];
        },
        set(target, property, value) {
            target[property] = reactive(value);

            return true;
        },
    });
}

Voila! When the object passed into reactive has any nested objects, they will also be passed through reactive recursively.

When we set the value of a property, we'll also pass the value through reactive to ensure that any objects are wrapped in a Proxy too.

Wrapping up

And with that, we've created a semi-functional version of Alpine.reactive(). The only thing that our reactive function doesn't do yet is update or trigger any function calls.

We'll look at creating a basic version of Alpine.effect() in the next instalment.

Until then, thank you for reading and I'll catch you next time!

• An official website!
• First-party global stores.
• A new and improved reactivity engine.
• Improved CSP (Content-Security Policy) support.
• And much, much more...

I've only had my hands on it for a few hours, just like everybody else, but I've already had a big dive through the source code and here are a couple of things I've found.

1. Automatic init function calls

The new documentation states that components powered by Alpine.data declarations that contain an init function will automatically have the init function called. This is great and saves you some time since you don't need to hook up the x-init directive.

After reading through the source code, it turns out you can actually add an init function to any data object and Alpine will still call that function automatically.

<div x-data="{
    init() {
        console.log('Here we go!')
    }
}"></div>

When this component is initialized, the init function will be called automatically and the console.log will appear in your DevTools.

2. Clean up after yourself with destroy

Anybody familiar with PHP will likely know about the __destruct magic method. This method is called when an object is garbage collected, allowing you to clean up or free other resources manually.

Alpine 3.x also introduces a similar pattern for components through the use of destroy method. This method will be called when the component is removed from the DOM,

A good example might be a carousel or image gallery library that modifies the DOM outside of your component, or isn't handled directly by Alpine.

<div x-data="{
    init() {
        carouselLibrary.create();
    },
    destroy() {
        carouselLibrary.delete();
    }
}"></div>

Alpine will call the destroy method, allowing you to clean up after yourself.

This feature hasn't been documented yet. Please use with caution.

3. Interact with global stores from external JavaScript

This is something that Spruce supported to, so if you used that with Alpine 2.x you'll be familiar with this one.

Creating a store with Alpine.store allows you to access global state in your components using a $store property. That same Alpine.store method can be used to retrieve a store in your external scripts.

Alpine.store('counter', {
    count: 0
})

// In a different file or area.
Alpine.store('counter').count += 1

Calling Alpine.store with a single argument will return the Proxy instance for that particular store. Awesome, right?

4. Independent x-init directives

This one is mentioned in the documentation, but you can declare x-init on its own, inside or outside of an Alpine component.

This was a question that got asked so much previously -- people were getting frustrated with adding x-init and nothing happening.

<div x-data>
    <p x-init="console.log('I am ready!')"></p>
</div>

<img src="..." x-init="doSomeMagicHere()">

This is great for elements that don't need any state and just need to call another method or third-party library on initialisation.

5. Unfurl / unwrap Proxy with Alpine.raw

When debugging an issue in a component, 9 times out of 10 we turn to console.log(). This is fine in most cases. Other times, people get confused by the appearance of a Proxy in their console window.

This is somewhat annoying since expanding the object will give you [[Target]] and [[Handler]] which can be confusing.

To save you some confusion, you can use Alpine.raw inside of your console.log() calls. This method will unfurl / unwrap the Proxy instance created by Alpine and return the underlying value, i.e. the plain object, array, etc.

<div x-data="{ user: { name: 'Ryan' } }" x-init="console.log(user)">
    <!-- This produces a `Proxy` in the console -->
</div>

<div x-data="{ user: { name: 'Ryan' } }" x-init="console.log(Alpine.raw(user))">
    <!-- This produces the "real" `user` object in the console -->
</div>

And that's it from me, at least for now. I'll be working hard over the next couple of weeks trying to find other tips and tricks. In the meantime you can find me on Twitter and GitHub.

That is one of the main reasons why I built Orbit - a flat-file "database" driver for Laravel's Eloquent ORM.

The main idea is that all of your content and data is stored inside of a "content" file but can still be used through a normal Eloquent Model, just like it would with a MySQL or Postgres database.

The User model

To start using Orbit, you'll need to install the Composer package in your Laravel application.

composer require ryangjchandler/orbit

Orbit operates and bootstraps a model via the Orbit\Concerns\Orbital trait. This can be added to your Model class like this:

use Orbit\Concerns\Orbital;

class User extends Model
{
    use Orbital;
}

This is all you need to do for the model to be "usable", but for it to function like a normal User, there are a couple of extra steps.

The schema method

Just like a model that's hooked up to a MySQL database, you should define a schema. This is what Orbit will use to determine what content is available in your flat-files and what should be accessible from the model.

It's essentially an "up" migration, written as part of your model's definition:

class User extends Model
{
    use Orbital;
  
    public static function schema(Blueprint $table)
    {

    }
}

Laravel provides a users table migration as standard, so we can take that existing migration and copy it into the schema method:

class User extends Model
{
    use Orbital;
  
    public static function schema(Blueprint $table)
    {
        $table->id();
        $table->string('name');
        $table->string('email')->unique();
        $table->timestamp('email_verified_at')->nullable();
        $table->string('password');
        $table->rememberToken();
    }
}

Orbit will automatically add the created_at and updated_at columns to this schema if your Model class needs timestamps.

And that's all there is to it. Really!

If you were to open up a tinker session and type User::create([...]), you would see a new content/users directory in your application, as well as a new 1.md file.

Customising the primary key

One thing that I like to do with these flat-file models is use a more descriptive "key" as the primary key. In the case of the User model, that's most likely going to be the email since it's always going to be unique.

To do this in Orbit, all you need to do is change the $primaryKey or overwrite the getKeyName method.

class User extends Model
{
    use Orbital;
  
    protected $primaryKey = 'email';
  
    public static function schema(Blueprint $table)
    {
        $table->string('name');
        $table->string('email')->unique();
        $table->timestamp('email_verified_at')->nullable();
        $table->string('password');
        $table->rememberToken();
    }
}

Now, when you create a new User, the file name will be the same as the email making it really easy to see which users already exist.

Changing the primary key of a model will affect the foreign and local columns for your relationships. For example, if you use email column as your User model's primary key, Laravel will guess that the foreign column name is user_email on the related model when using belongsTo relation. You can change this by specifying the column names when you define the relationship.

Sign off

If you're interested in Orbit and want to find out more, check out the GitHub repository.

Thanks for reading this post!

To do this, use the $this->commands method in your ServiceProvider::boot method.

class MyPackageServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $this->commands([
            Commands\MyAwesomeCommand::class,
        ])
    }
}

By doing this, you can now run your command using php artisan my-awesome-command.

Scheduling the command

Now that artisan is aware of your command, you can hook it up to Laravel's Schedule and run it as often as you need.

Begin by calling $this->app->afterResolving in your ServiceProvider::boot method, passing through two arguments.

The first argument should be the abstract that is being resolved. In this case, that will be Illuminate\Console\Scheduling\Schedule. The second argument should be a Closure that accepts the object in its parameter list.

use Illuminate\Console\Scheduling\Schedule;

class MyPackageServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $this->commands([
            Commands\MyAwesomeCommand::class,
        ])
		  
        $this->app->afterResolving(Schedule::class, function (Schedule $schedule) {
            $schedule->command(Commands\MyAwesomeCommand::class)->everyMinute();
        });
    }
}

Now when you run php artisan schedule:run, the Closure will be executed and MyAwesomeCommand will be added to the scheduler, running once every minute.

php artisan make:command MakeUserCommand

This will create a new file in app/Console/Commands called MakeUserCommand.php with all of the normal command boilerplate. I've removed some of the cruft below for demonstration purposes.

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class MakeUserCommand extends Command
{
    protected $signature = 'command:name';

    protected $description = 'Command description';

    public function handle()
    {
        return 0;
    }
}

Retrieving user input

Instead of asking for input up front when the user runs the command, I'll instead be using the Command::ask() method to get input during the command's run time.

Here's how you might get the name of the new user.

public function handle()
{
    $name = $this->ask('Name:');

    return 0;
}

When the command runs, the user will be shown the text provided as the method's first argument.

If you wanted to validate this input, all you need to do is pass the data through to a new Validator and handle any errors. Let's begin by creating a new Validator with the correct data and rules.

use Illuminate\Support\Facades\Validator;

public function handle()
{
    $name = $this->ask('Name:');
    
    $validator = Validator::make([
        'name' => $name,
    ], [
        'name' => ['required', 'string']    
    ]);

    return 0;
}

Now that the validator has been created, calling the $validator->fails() method will run the data against the rules provided and return a bool.

public function handle()
{
    $name = $this->ask('Name:');
    
    $validator = Validator::make([
        'name' => $name,
    ], [
        'name' => ['required', 'string']    
    ]);
    
    if ($validator->fails()) {
        // Do something here...
    }

    return 0;
}

Now that we know if the validation has failed or not, we can look into the errors and output them to the user.

public function handle()
{
    $name = $this->ask('Name:');
    
    $validator = Validator::make([
        'name' => $name,
    ], [
        'name' => ['required', 'string']    
    ]);
    
    if ($validator->fails()) {
        foreach ($validator->errors()->all() as $error) {
            $this->error($error);
        }
        
        return 1;
    }

    return 0;
}

And that's all there is to it! If somebody tries to enter an invalid name, the validation will fail and the errors will be output in the user's console.

If you went ahead and did this for the email too, you can be confident that the data being provided is valid.

Improving the ask method

The only problem with the basic approach I've shown is that the process exits if there is an error. If you've only got one piece of data being validated, this might be okay.

Imagine you've battled with the validation for the name and finally reach the email stage. If you fail the validation here, you need to go back to the beginning, put in your name again and then try the email again too.

One way we can tackle this is with recursion... dun dun dun!

A new method

Let's start by pulling all of the validation logic into a new helper method on the class.

public function askWithValidation(
    string $message, array $rules = [], string $name = 'value'
) {

}

This new method will handle all of the validation, as well as the error displaying. Start by asking the question and instantiating a validator, just like before

public function askWithValidation(
    string $message, array $rules = [], string $name = 'value'
) {
    $answer = $this->ask($message);
    
    $validator = Validator::make([
        $name => $answer,
    ], [
        $name => $rules,
    ]);
}

This method is going to be re-usable, so instead of hardcoding the key in each array, we'll let the developer pass in a custom $name (defaulted to value).

Instead of calling $validator->fails(), we can actually use the inverse operation, $validator->passes() and return early if that returns true.

public function askWithValidation(
    string $message, array $rules = [], string $name = 'value'
) {
    $answer = $this->ask($message);
    
    $validator = Validator::make([
        $name => $answer,
    ], [
        $name => $rules,
    ]);
    
    if ($validator->passes()) {
        return $answer;
    }
}

Early returns are just cleaner, right?

If the condition fails, we can go through and check for any errors and display them to the user.

public function askWithValidation(
    string $message, array $rules = [], string $name = 'value'
) {
    $answer = $this->ask($message);
    
    $validator = Validator::make([
        $name => $answer,
    ], [
        $name => $rules,
    ]);
    
    if ($validator->passes()) {
        return $answer;
    }
    
    foreach ($validator->errors()->all() as $error) {
        $this->error($error);
    }
}

Now for the recursion. If the validation fails and errors are shown to the user, instead of returning and exiting the process, we can instead return $this->askWithValidation so that the user is asked the same question again.

public function askWithValidation(
    string $message, array $rules = [], string $name = 'value'
) {
    $answer = $this->ask($message);
    
    $validator = Validator::make([
        $name => $answer,
    ], [
        $name => $rules,
    ]);
    
    if ($validator->passes()) {
        return $answer;
    }
    
    foreach ($validator->errors()->all() as $error) {
        $this->error($error);
    }
    
    return $this->askWithValidation($message, $rules, $name);
}

And there you have it! Validated user input inside of your console commands.

I've create a little Gist with a trait that you can pull into any of your console commands here.

Sign off

Used something similar in your application or package? Let me know on Twitter.

Thanks for reading!

This article assumes you've already got a Laravel Jetstream application setup and that you are using the Livewire stack. If you haven't, read the official documentation on how to get started.

The <x-jet-banner> component

Jetstream comes jam-packed with lots of goodies. One of those goodies is an <x-jet-banner> component. If you're using the default layouts.app layout that comes with Jetstream, you might have already seen this. It can be found at the very start of the <body> tag:

<body class="font-sans antialiased">
    <x-jet-banner />

If you're using a different layout file, go ahead and include this Blade component somewhere in your markup.

A brief look at the component itself shows that it's powered by Alpine and support 2 different styles out of the box. A success style, as well as an error/danger style.

This is perfect for 99% of applications since you either want to say something is good or bad.

You might also notice that there is an @props declaration at the top of the component file:

@props(['style' => session('flash.bannerStyle', 'success'), 'message' => session('flash.banner')])

This is where the component gets all of the information for what type of banner should be shown as well as the message.

Flashing a message

Since we know the component is looking for the message and style in the session, all we need to do is flash these pieces of information to the session.

In a Livewire component, you might use the session() helper or go through the request() helper instead.

public function banner(string $message, string $style = 'success')
{
    request()->session()->flash('flash.banner', $message);
    request()->session()->flash('flash.bannerStyle', $style);
}

Add this method to your component and use it yourself!

public function save()
{
    // Some save logic goes here, I guess.
  
    $this->banner('Successfully saved!');
}

A reusable trait

If you want to re-use this throughout multiple components, you might wish to extract the method into a trait that can be used on your components.

Here's the one I use.

namespace App\Support\Concerns;

trait InteractsWithBanner
{
    public function banner(string $message, string $style = 'success')
    {
        request()->session()->flash('flash.banner', $message);
        request()->session()->flash('flash.bannerStyle', $style);
    }
}

For these sort of traits, I don't put them inside of the App/Http/Livewire folder because they're not reliant on Livewire specific methods. I could add this to anything in my application and it would still do the same thing.

Now you can use this trait in your Livewire component instead:

use App\Support\Concerns\InteractsWithBanner;

class SaveForm extends Component
{
    use InteractsWithBanner;
}

This article assumes you've already got a Laravel Jetstream application setup. If you haven't, read the official documentation on how to get started.

Publishing Jetstream's views

Although Jetstream publishes quite a few things into your application, it doesn't publish views by default. The main reason for this is it's much easier to rollout bug fixes or new features if the views are registered inside of the package.

You can publish them yourself however by running the following command:

php artisan vendor:publish --tag=jetstream-views

This will publish all of Jetstream's views into resources/views/vendor/jetstream.

Changing the logo

The steps needed here depend on which stack you have chosen.

Livewire

To use a custom logo, you'll need to customise three files:

1. resources/views/vendor/jetstream/components/application-logo.blade.php
2. resources/views/vendor/jetstream/components/application-mark.blade.php
3. resources/views/vendor/jetstream/components/authentication-card-logo.blade.php

Each of these files will contain an SVG. Replace this markup with your own logo (another SVG or even an <img> tag).

If you use an SVG, be sure to add the {{ $attributes }} on to the <svg> tag so that any attributes passed through to the component are still rendered.

Inertia

You'll need to customise three files for Inertia too:

1. resources/js/Jetstream/ApplicationLogo.vue
2. resources/js/Jetstream/ApplicationMark.vue
3. resources/js/Jetstream/AuthenticationCardLogo.vue

Much like the Livewire stack, just replace the SVG markup with your own SVG or an <img> tag.

For those of you who don't know, or haven't heard about it, Puny is my very own unit testing library.

Unlike PHPUnit et al, it's designed with minimalism as its main goal. There are only a handful (literally) of standard functions provided by Puny and it really makes you think differently about how you test your applications or packages.

The best way to showcase Puny is by writing a simple unit test for a StringFormatter class.

class StringFormatter
{
    public static function upper(string $input)
    {
        return strtoupper($input);
    }
}

All this method does is wrap the strtoupper() function, but it's a good way of showcasing the testing utilities.

Normally my test files can be found in a tests directory at the root of my project. By default, Puny will try to look for this folder.

Since we're unit testing, it's also common practice to test each component or concept inside of its own file, so I'll create a new file called tests/StringFormatter.php.

Puny provides a Puny\test function that can be used to register a new test.

use function Puny\test;

test('it can convert a string to uppercase', function () {

});

The Puny\test function accepts two arguments, the first is the name of the test itself (a description of what you will be testing) and the second is a callable / Closure that actually performs the test's logic.

In this case, we'll be calling StringFormatter::upper() and checking that the return value is suitable.

use function Puny\{test, ok};

test('it can convert a string to uppercase', function () {
    ok(StringFormatter::upper('hello') === 'HELLO', 'it converts correctly');
});

Here I'm using the Puny\ok function to make sure that something is, you guessed it, "ok". All it really does is check that the first argument is true or false.

If it's true it doesn't do anything at all. If it's false, it will print out an error in the console.

The second argument is a sub-description of the specific assertion being made. This will be used in the error output so that you can quickly find the right failing assertion.

A better equality helper

Instead of writing out a bool condition for the Puny\ok helper, you could instead use the Puny\eq helper function. This is just a shorthand for comparing two operands.

use function Puny\{test, eq};

test('it can convert a string to uppercase', function () {
    eq(StringFormatter::upper('hello'), 'HELLO', 'it converts correctly');
});

It's almost identical. You just don't need to worry about writing the === (or == if you're a menace) yourself.

It's worth noting that the Puny\eq helper will always make strict comparisons. If this isn't fit for your use case, just use Puny\ok.

How it all works

It all starts with the Puny CLI. This is a file installed with the Composer package that you can use to actually run your tests. It's only responsible for invoking the Puny::run() and setting the correct tests folder method.

As I mentioned previously, Puny will default to using a tests folder in your current working directory (according to getcwd()). This is a great default and makes running the command easier since you don't need to pass in any options or arguments.

You can specify a custom folder by passing in an argument to the command - puny ./tests-folder.

Bootstrapping

Puny does include some niceties for running some logic before your entire test suite. If it encounters a bootstrap.php file in the root of your tests folder, it will include that file.

This means you can setup singleton classes, bind things to a container or anything else that you might need to use throughout your test suite.

Discovering tests

Once Puny knows where the tests are located, it walks through that directory recursively and will include any PHP files it finds. The interesting thing here is that the tests themselves (registered using Puny\test) aren't actually being run quite yet.

Calling the Puny\test function will actually call an internal Puny::register method. This method places the test inside of a single array on the main Puny\Puny instance. This is possible because of how PHP evaluates an entire file when it is imported using include or require.

This happens for each test file and eventually, once all folders have been walked and all files have been included, Puny is left with an array of test names and callbacks.

By building up this array, it implicitly forces test names to be unique. If two different files both have a test with the same name, only the last test file to be included will actually be run because it overwrites the earlier test.

Running tests

Now that there is a collection of tests to run, Puny will loop over this array and invoke each callable / Closure.

Each callback is invoked inside of a try / catch block. This means that any exceptions thrown by the test will be caught by Puny and can therefore be handled in a special way.

This is exactly how the Puny\ok, Puny\eq and Puny\skip function work. I'll use Puny\ok as an example:

function ok(bool $check, string $id) {
    if (! $check) {
        throw new NotOkException($id);
    }

    return true;
}

This is the code for the Puny\ok helper. All it does is check if the $check is false (falsy) and throws an exception if it is. Puny can then register a catch block for this exception, NotOkException and handle it accordingly.

try {
    $callback();
} catch (NotOkException $e) {
    Console::error("Failed: {$e->getMessage()}");
  
    $this->failed++;
}

The exception is being handled so it will never be reported to the user in the console. Instead Puny uses its own output to notify the user of a failure and also increase a counter for the number of failed tests.

The benefit to this approach is that the rest of the test suite can still be run whilst notifying the user of any failures.

The Puny\eq function uses the Puny\ok function internally, so there's no special conditions needed for that.

For the Puny\skip function to work, all we need to add is another catch block for a different exception:

try {
    $callback();
} catch (NotOkException $e) {
    Console::error("Failed: {$e->getMessage()}");
  
    $this->failed++;
} catch (SkippedException $e) {
    Console::warning("Skipped: {$name}");
  
    $this->skipped++;
  
  	continue;
}

The Puny\skip function can then throw a new SkippedException when it's called.

function skip() {
    throw new SkippedException;
}

Calling the Puny\skip function will also report back to the user in the console and continue the foreach loop, moving on to the next test.

Conclusion

And that's all there is to it. Kind of, anyway. I've gone over the basic inner workings of Puny in this article but I'll be writing a follow-up in a couple of weeks that goes over how the Puny\spy helper function works.

If you are interested in giving Puny a try, head over to the GitHub repository for more information.

If you've already used Puny, I'd love to know so message me on Twitter.

Here is how I do it.

Zipping up your code

When you upload your Lambda function, you'll want to provide a ZIP file that contains all of the necessary code. I mostly write Node functions these days, so my ZIP files generally contain a node_modules folder, an index.js file and a package.json file too so I can quickly check what dependencies I'm using from the Lambda UI.

On UNIX machines, you can use the zip command to generate a ZIP file. As an example, you might run something like this:

zip -r function.zip .

This command will create a new function.zip file, compressing the contents of the current directory (or .).

If you need to exclude some files, you can use the -x option. This is handy if you have a generic input.json or output.json file, as described in my other article.

zip -r function.zip . -x output.json input.json

Deploying to AWS

Now that we've got a ZIP file with our Lambda function's dependencies and handler, we can finally deploy to AWS. AWS have, surprisingly, made this very simple using the AWS CLI.

aws lambda update-function-code --function-name NameOfFunctionHere

We haven't told the AWS CLI what to deploy though. In our case it will be a ZIP file, so let's use the --zip-file option and specify the correct file.

aws lambda update-function-code --function-name NameOfFunctionHere --zip-file fileb://function.zip

The fileb:// protocol is used because we're uploading binary data.

Condensing this down

You might have already guessed it, but I don't actually type out this entire command each time. I like putting these commands inside of NPM "scripts" so that I can quickly run them with npm run or yarn.

{
    "scripts": {
        "zip": "zip -r function.zip . -x output.json input.json",
        "deploy": "npm run zip && aws lambda update-function-code --function-name NameOfFunctionHere --zip-file fileb://function.zip"
    }
}

Before you go any further, you want to make sure you've got the AWS CLI installed. If you haven't already got it installed, you can follow the official instructions here.

Generating a payload

Unfortunately, the AWS CLI can't accept the raw contents of a file as the payload when invoking a Lambda function. Instead, you need to generate a base 64 encoded version of the file.

On Unix systems, this can be done using the base64 command. I typically store my generic payload inside of a payload-raw.json file and then output the base 64 encoded version to payload.json.

base64 payload-raw.json

This command will encode the raw JSON into base 64. To output the result of this command, we can just redirect stdout into a file.

base64 payload-raw.json > payload.json

Invoke the Lambda

You can invoke your Lambda function using the aws lambda command. This command requires a few options so that it knows which function to execute.

aws lambda \
--function-name NameOfFunctionHere

If we want to send through our base 64 encoded payload, we can use the --payload option and specify the file that needs to be used.

aws lambda \
--function-name NameOfFunctionHere
--payload file://payload.json

You need to prefix the file with file:// protocol as the AWS CLI also supports sending payloads using http:// and https://.

If you want to save the output of the execution to a file, you can specify the output file at the end of the command.

aws lambda \
--function-name NameOfFunctionHere
--payload file://payload.json
output.json

Finding it hard to remember what breakpoint you're currently viewing your screen at? Struggle no more!

Install the tailwindcss-debug-screens plugin and you'll be provided with a small visual helper in the bottom-left of your site.

Run this command in your project directory:

npm install tailwindcss-debug-screens --save-dev

Then register the plugin in your Tailwind configuration file:

module.exports = {
    //...
    plugins: [
        require('tailwindcss-debug-screens'),
    ]
}

And finally add the new debug-screens class to your <body> tag:

<body class="debug-screens">

You should ensure that this class is only added to the <body> in development. Wrap the class inside of a conditional or exclude the plugin at part of your build process.

2. Create a visual breakpoint separator

This is definitely one that you can start implementing in your project. Have you ever seen any class lists like this?

<h1 class="text-xl text-gray-500 focus:text-gray-800 hover:text-gray-800 mb-1 sm:text-2xl sm:mb-2 md:text-3xl md:mb-4 xl:text-5xl">

These can get rather large, rather quickly. As they get larger and more breakpoint-specific classes come into play, it can get harder to see each breakpoints styles.

One trick that I like to use is inserting a style-less / marker class between each breakpoints section.

<h1 class="text-xl text-gray-500 focus:text-gray-800 hover:text-gray-800 mb-1 | sm:text-2xl sm:mb-2 | md:text-3xl md:mb-4 | xl:text-5xl">

In this case, I'm using a single | as the marker for a new breakpoint. It gives each section some breathing room but also provides a visual indicator for where a new screen definition starts.

You could use any valid CSS class here instead, but a | is very common for separating things in many contexts.

3. Give your text editor / IDE some Tailwind love

There are plenty of great extensions out there for improving your Tailwind development experience. Here are some of my favourites and ones I would highly recommend to any Tailwind developer.

Tailwind CSS Intellisense for VS Code

This is an official extension for Visual Studio Code and comes with some really, really neat features.

• Autocompletion for class names and CSS functions.
• Linting of your classes and CSS files.
• Syntax highlighting of custom Tailwind directives.
• Hover previews that show entire CSS definitions for CSS classes.

I think it's great when a project develops a first-party extension for their own tool. It adds a certain degree of reliability and trust.

Headwind

Headwind is a Tailwind class sorter extension for Visual Studio Code. The documentation states that "It enforces consistent ordering of classes by parsing your code and reprinting class tags to follow a given order".

I've been using this one for quite a while now and once you get used to the order, it can make finding a class in a long list much easier.

If you're a PhpStorm user, you can get a Headwind port plugin here.

This article has been written based on functionality in Alpine.js v2.x - when a new major version is released or any of these tips are no longer applicable, I'll be sure to update it.

1. Keep your components small

When Alpine encounters a new component or some of your state changes, it walks the DOM tree of that component. This means that if you have a larger component, you might notice an impact on performance because there is more DOM to walk.

This is why it's always a good idea to keep your markup small and avoid putting x-data attributes on the <body>, especially when you've got a big page.

You'll probably notice a performance impact on huge components, but it's always good to keep in mind because each small performance impact adds up to a larger one.

2. Extract helpers into mixins

Since Alpine.js uses a regular JavaScript object, we can take advantage of the "spread" operator. This means we can compose an object using the return value of multiple functions or separate object literals.

Here's an example:

<form x-data="{ ...validationHelpers(), name: '' }" @submit.prevent="validate({ name: 'required' })">
    <input x-model="name" name="name" id="name">
</form>

Here is what the validationHelpers function might look like:

function validationHelpers() {
    return {
        validate(rules) {
            Object.entries(rules).forEach(([field, rules]) => { ... });
        }
    }
}

The ... operator will take the entries from the object returned by validationHelpers and add them to our data object. This lets us use them directly in our component whilst keeping the logic separated from the component's own.

The validation example is definitely a good use-case for this sort of thing. You might also use it for transition helpers, class name generators and a plethora of other things.

3. Alpine.js DevTools

If you didn't already know, there is a third-party Chrome and Firefox extension that provides some handy DevTools for Alpine. You can see all of the components on the page, inspect the data for each one and even modify it in real-time.

Soon you'll also be able to watch for any Alpine related errors, track events being dispatched by components and more.

If you don't already have it installed, follow the instructions in the repository!

Have you ever written a block of code like this?

$users = User::all();

dd($users);

It's not awful, but it is annoying that you need to assign the result of User::all() (an instance of Collection) to a variable just to dump and die. Turns out, you don't actually need to. Instead, you can use the dd or dump method on the Collection class instead and turn this into a one-liner.

User::all()->dd();

2. Auth::id()

I wrote a tweet about this one a little while ago and it seemed like a lot of people didn't know about it.

🔥 I still see so many people retrieving the current user's ID as shown at the top of the image. Take a shortcut and use the Auth::id() method instead! https://t.co/P7eB1PJrt2

— Ryan Chandler (@ryangjchandler) Jul 23, 2020

I think my favourite thing about using this method is that you don't need to worry about accessing the id property on a null object, you can just use Auth::id() and it will return null when the user is logged out.

3. Default Relationship Models

Laravel provides a handy withDefault() method on the belongsTo relationship that will return a model object even when the relationship doesn't actually exist.

class Post extends Model
{
    public function user()
    {
        return $this->belongsTo(User::class)->withDefault();
    }
}

Now, if we try to access the $post->user relationship, we'll still get a User object even when it does exist in the database. This is known as the "null object" pattern and helps eliminate some of those if ($post->user) conditional statements.

There's a few different things you can do with withDefault(), you can read more about it here in the documentation.

4. Custom Blade Directives

I don't use custom Blade directives all too often, but when I do it definitely makes my views look nicer. One example of a Blade directive that I use across multiple projects is @nl2br

<h3>Notes</h3>

@foreach($notes as $note)
    <p>@nl2br($note->content)</p>
@endforeach

Creating your own Blade directive really isn't difficult. Here's what the @nl2br one looks like:

Blade::directive('nl2br', function ($expression) {
    return "<?php echo nl2br(e({$expression})) ?>";
});

Under the hood, Blade transforms a Blade directive into a PHP string (or expression). In this case, we're writing the PHP code necessary to print out the result of nl2br.

The callback function accepts an $expression argument. This is what was passed to the directive as arguments. In the example above, that would be $note->content as a string.

That confuses people quite a bit, because they expect $expression to be the return value of $note->content, when in fact is it a literal string with the contents $note->content:

$expression = '$note->content';

5. Better Intellisense

This isn't something related to your code directly, but it can definitely make it faster to write.

PhpStorm

If you're one of the PhpStorm crowd, you've probably already got the Laravel extension installed. If you're looking for something a little more powerful, and premium, you should definitely check out LaravelIdea.

This extension provides auto-complete for basically everything cool and awesome in Laravel. View names, config names, Blade component tags and more.

Visual Studio Code

I've been using Laravel Extra Intellisense for a little while now and it has definitely given me a speed boost when it comes to getting the right view, configuration value or route name.

It's free, pretty powerful and feels just like any other intellisense plugin.

The syntax

Highlight.php uses JSON files for syntax definitions, where as Highlight.js uses JavaScript files. This is just down to the fact that one is written in PHP where JavaScript evaluation is basically impossible and the other is a JavaScript library, so JavaScript can be used for configuration.

Here is the JSON file for the Blade syntax definition:

{
    "case_insensitive": true,
    "subLanguage": "xml",
    "contains": [
        {
            "className": "comment",
            "begin": "\\{\\{--",
            "end": "--\\}\\}"
        },
        {
            "className": "template-variable",
            "begin": "\\{\\{",
            "starts": {
                "end": "\\}\\}",
                "returnEnd": true,
                "subLanguage": "php"
            }
        },
        {
            "className": "template-variable",
            "begin": "\\}\\}"
        },
        {
            "className": "template-variable",
            "begin": "\\{!!",
            "starts": {
                "end": "!!\\}",
                "returnEnd": true,
                "subLanguage": "php"
            }
        },
        {
            "className": "template-variable",
            "begin": "!!\\}"
        },
        {
            "className": "template-tag",
            "begin": "@php",
            "starts": {
                "end": "@endphp",
                "returnEnd": true,
                "subLanguage": "php"
            },
            "relevance": 10
        },
        {
            "begin": "@[\\w]+",
            "end": "[\\W]",
            "excludeEnd": true,
            "className": "template-tag"
        }
    ]
}

At a very basic level, this JSON files uses RegEx patterns to describe starting and ending delimiters. Those patterns are used to match your code blocks against a particular type of token and then add a class to the wrapping HTML element.

As an example, the very first items inside of the contains key is an object that stores information about comments. The className describes which hljs- class will be added to that text node. In this case a hljs-comment class will be added when {{-- is encountered.

When that first pattern is matched, it will continue to match the text until the end pattern matches. As a result, our Blade comments are rendered as:

{{-- This is a comment. --}}

Any objects that have a starts key indicate that matching the begin pattern should start a new sublanguage block. This is what lets you highlight text inside of {{ }} as PHP, instead of a plain-text string.

The same applies to the @php and @endphp blocks. Everything that is found within those 2 directives will be highlighted as PHP.

{{ \Example::method() }}

@php
$example = 2 + 2;

echo $example;
@endphp

The @php and @endphp rules also have a relevance key. The higher that value of this key, the more likely it is to be used to automatically match the current syntax.

If you don't specify which language you are currently rendering and your code contains an @php directive, Highlight.php will use this relevance and assume you're trying to render Blade.

Storing our syntax

This is all down to personal preference, but I like to keep my blade.json file in a resources/syntax folder in my Laravel applications. You can of course place this anywhere you like, just be sure to change any references to it later on.

Registering the syntax

Once you have created the blade.json file, we need to tell Highlight.php to use this new syntax definition. This is really simple and only requires a single line of code:

\Highlight\Highlighter::registerLanguage('blade', resource_path('syntax/blade.json'), true);

The first argument is the identifier for the language. In this case, I'll use blade.

The second argument is where your blade.json file is stored. I've stored mine in resources/syntax/blade.json so I'm using the resource_path() helper to get the correct path.

The third argument is optional, but it will forcefully overwrite any existing blade definitions. At the time of writing, Highlight.php doesn't have its own (obviously, that's why you're here) so I'm going to say true so that nothing unexpectedly breaks in the future.

Ensure that you execute this code before attempting to highlight anything. In a Laravel application, you could put it inside of a ServiceProvider.

Using the custom syntax

Once that's all done, you will be able to use blade code in your blocks. Here's an example:

<h1>
    @auth
        Hello, {{ $user->name }}!
    @else
        Hello!
    @endauth
</h1>

<livewire:user-profile user="{{ $user->name }}" />

Planned improvements

As I mentioned before, code inside of {{ }} will try to be highlighted using the PHP syntax definitions. This is great, but when you try to right code inside of directives that expect expressions, it isn't highlighted correctly:

@if(2 + 2 === 5)
    {{ 5 }}
@endif

This is a limitation of Highlight.js and, in turn, Highlight.php. Since the tokeniser relies on a beginning and ending pattern, it's quite hard to match all content between a pair of matching parentheses.

There might be a way to solve this, but my RegEx skills are nowhere near good enough. If you've got any ideas, I'd love to know on Twitter.

Another thing that I'd like to add in PHP highlighting inside of <x: or <livewire: attribute bindings. Since the syntax definition extends from XML, the attributes themselves can be highlighted but the content of those attributes is just rendered as a string.

This one is a bit easier to solve than the directive expressions, so I'll play around with the RegEx and update this article accordingly.

If you want a separate reference, I've put the slimmed down instructions into a GitHub Gist here.

Got any ideas or improvements? Comment on the Gist above and I'll reply as best as I can.

If you're not using Laravel Valet, you can skip the last section of this tutorial and use the localhost / 127.0.0.1 domain instead.

Installing MailHog

To install MailHog, run the follow commands in your terminal:

brew install mailhog

This command will install MailHog on your system, but won't enable the service.

To enable the service, run the command below:

brew services start mailhog

This will instruct Homebrew to setup a background service so that MailHog is always running on your machine. You won't need to manually start anything, as long as Homebrew is running.

Now, you can visit 127.0.0.1:8025 in a browser and you should be greeted with the MailHog application:

Configuring your Laravel application

To get MailHog working with your Laravel application, update the following keys in your .env file:

MAIL_DRIVER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

The reason the ports are different to the MailHog UI is that the SMTP server is running on port 1025, where as the HTTP server is running on 8025.

If you send an email from your Laravel application now, you will see it pop up in the MailHog interface. You can use the code snippet below inside of Laravel Tinker to test:

Mail::raw('MailHog', fn ($message) => $message->to('john@example.com')->from('laravel@example.com'));

Setting up a .test domain

Laravel Valet makes this process super easy. All you need to do is run the following command in your terminal:

valet proxy mailhog.test http://127.0.0.1:8025

This command will create an Nginx configuration file for the domain mailhog.test, proxying all requests to that domain through to the MailHog HTTP server.

It will also setup an SSL certificate, just like valet secure does for your normal Laravel sites.

This is my first time writing one of these "year in review" blog posts but I'd like to make this an annual tradition. It gives me an opportunity to reflect on the positives from this year and also look into next year, 2021.

Prologue

Before I get started, I want to acknowledge the fact that there are lots of people who have had it rough this year. Nobody could have predicted this year to turn out the way it did.

Some might have guessed that certain things would happen but definitely not to this extent.

I also want to acknowledge that I am very lucky and fortunate to be in a good position mentally, financially and health wise.

Personal

I don't want to go too deep into my personal life. You're probably not interested in it.

Not much has changed for me in the last year outside of the development world. I think the biggest milestone was saving for a deposit on a house.

This was one positive thing to come from COVID. Being stuck at home had a side effect of spending less money on food, travel and holidays since my partner and I couldn't do any of that. This leftover money ended up in savings and in the last couple of months has added up and allowed us to start looking at properties with the hopes of buying and moving out in the New Year.

Work

New job

I started a new job in January at an insurance company, Surewise. I joined a small team of Laravel developers who all have a shared goal of making online insurance smarter and simpler for as many people as possible.

The job is great and I've been able to innovate our technology stack over this last year. We've implemented many new tools and packages, here's a list of just a few:

• Livewire
• Alpine.js
• CI/CD

Freelancing

I'm very happy to say that this year was the year that I started (seriously) freelancing. This was the second positive thing to come from COVID, since I was at home I had some more time on my hands and I wanted to help others with their projects.

All of the freelance work was done in the evenings after work or at the weekends, but that really didn't bother me. I was helping others (people and companies) with their projects and really trying to help out companies who were invested in the TALL stack.

Open-source

I've been interested in open-source work for a few years now but this last year, it has been a real focus of mine.

My introduction to big open-source (Alpine.js)

It all started at the beginning of the year with the new Alpine (originally named Project X) project by Caleb Porzio. I was using the project myself and was very active on the repository. I'd comment on issues, try to help people out. I was also opening PRs to the project, trying to fix things, introduce new features and improve the developer experience along the way.

This was my first real taste of what it was like to contribute to an open-source project and Caleb made the whole experience beautiful.

As a developer who had come from the world of Vue, I felt like Alpine was missing something. There were also a few other people who felt the same way. That "thing" was a way of sharing state between components, a.k.a global state management.

After a few iterations and releases of an early (and ugly) prototype, Spruce was born. Spruce was my solution to that "missing something". It was designed to be minimalistic, just like Alpine. It felt natural to use through the $store variable that it provided.

I personally believe that Spruce has filled that void and the numbers do add up. On average, the CDN has had over 75,000 hits per month so either somebody is using it on a really big site, or a lot of people are using it on smaller sites.

Either way, it solved the problem for me. That's all that matters, right?

As well as Spruce, I've gone on to create and contribute to other Alpine.js related projects such as the DevTools, Magic Helpers and the Awesome list.

The TALL stack

Alongside Alpine, Caleb released a new tool called Livewire. Together they're extremely powerful and add Tailwind to the mix, you're going to be having a party.

As people started to pick up these new tools an acronym emerged, TALL:

• Tailwind
• Alpine.js
• Livewire
• Laravel

The Laravel framework has had this concept of "presets" for a little while but there wasn't a real one for the TALL stack.

So I teamed up with Liam Hammett and Dan Harrin to build one. We wanted to build the best third-party preset preset Laravel.

We went above and beyond really. It came out of the box with tests, customisable components, pretty Tailwind components and more.

At the time of writing this article, our preset has had over 33,000 downloads. That is an insane amount of downloads and we're all really happy with how it turned out, as well as how helpful it has been.

GitHub Sponsors

GitHub introduced a new Sponsors program this year. I was accepted into it and wrote a small profile.

I was initially inspired by Caleb's success with sponsorware, but I never really pushed that concept. Instead, I opted for the "if you use my packages and benefit from them in some way, you can give me $1 or more per month to show that you support my work".

At the time of writing this article, I have 25 sponsors and I couldn't be more grateful. You know who you are.

The support that these guys give me, financially, allows me to spend more time on my open-source work. It really does mean a lot.

Overview

Here are some real numbers for you:

• Total number of contributions: > 2,000
• Total number of discussions answered: > 25
• Total number of pull request by me: > 150
• Total number of issues by me: > 200

Considering I do all of that on the side of my full-time and freelance work, those numbers aren't too shabby.

Writing and Speaking

I got really serious about blogging this year. I've written 30 blog posts (not including this one) on topics that interest me but also help other people out.

One of my posts even reached Hacker News and the abuse wasn't too bad!

I won't go into numbers, but here are 4 of my most popular posts from the last year:

• Running GitHub Actions for Certain Commit Messages
• Unconventional Laravel: Custom Pipeline Classes
• Writing Reusable Alpine Components
• Unconventional Laravel: Responsable classes

I also did my first meetup talks this year. My favourite one of them all was the Laravel Worldwide Meetup where I demonstrated how to setup a simple CI/CD pipeline for your Laravel application with GitHub Actions.

You can watch that talk on YouTube.

New friends

Through all of my new ventures this year, I've been able to meet some really great people. I want to thank you all for reaching out to me for help with something, helping me with something and most of all, being awesome.

I want to thank Liam, Dan, Caleb, Sam, Samuel, Lars, Hugo, Kevin, Simone, Duncan. This feels like I'm accepting a Grammy so I've definitely missed some people off that list but if we talk, you know who you are.

You've all had a huge impact on my developer life this year and it wouldn't have been the same without you.

(I'll stop with the soppy stuff now).

Epilogue

This year has been full of thrills. For some, it has been full of lows but I really want to believe that 2021 will be a better year for all of us, all across the globe.

As I look forward into 2021, I want to set a few goals for myself:

1. Write more blog posts and help people out.
2. Speak at a conference.
3. Release at least 3 new open-source packages.
4. Finish and release GitHub Actions for PHP Developers.
5. Livestream on a regular basis.
6. Meet new friends.
7. Somehow convince Taylor to follow me.

There we go. We'll see how well that went next year.

[Text for the link](https://example.com)

Sometimes you don't need text for the link. Instead you want the URL itself to be clickable, so you end up doing something like this:

[https://example.com](https://example.com)

Some editors and Markdown parsers, such as GitHub's one, are smart and will automatically makes URLs clickable in your text. This is known as "autolinking".

The same thing can be achieved with the CommonMark parser that we have been using in this series.

Setting up the environment

Before we can get autolinking, we need to first change how our parser is being setup. Previously, I showed you how to parse Markdown like this:

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter;

$html = $converter->convertToHtml('# Hello World');

The league/commonmark package also provides a nice extensible API available through, what they call, custom environments.

To create a custom environment, you need to create a new instance of the League\CommonMark\Environment class. Instead of instantiating it via the new keyword, you instead need to use a "named constructor".

A named constructor is a static method on the class that is responsible for instantiating that class in a particular fashion.

The named constructor ensures that all of the default renderers and parsers are setup on the converter object so that you don't have to do it yourself.

Here's how it's done:

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

$environment = Environment::createCommonMarkEnvironment();

$converter = new CommonMarkConverter;

$html = $converter->convertToHtml('# Hello World');

Now that the environment has been created, it needs to be provided to the CommonMarkConverter object.

As you saw in the last instalment, the first argument to the constructor is an array of options. The environment needs to be passed through as the second argument, like so:

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;

$environment = Environment::createCommonMarkEnvironment();

$converter = new CommonMarkConverter([], $environment);

$html = $converter->convertToHtml('# Hello World');

Adding the autolink extension

With the environment setup, the extension can be added using the Environment::addExtension() method.

Each extension is declared as a separate class. In this case, the autolinking extension is declared under the League\CommonMark\Extension\Autolink\AutolinkExtension class.

The Environment::addExtension() method will expect a new instance of the extension:

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;
use League\CommonMark\Extension\Autolink\AutolinkExtension;

$environment = Environment::createCommonMarkEnvironment();

$environment->addExtension(new AutolinkExtension);

$converter = new CommonMarkConverter([], $environment);

$html = $converter->convertToHtml('This is an awesome website, check out https://ryangjchandler.co.uk now!');

With all of this setup, you can use URLs as links in your Markdown. Running the following Markdown through the converter:

This is an awesome website, check out https://ryangjchandler.co.uk now!

Will result in the following HTML:

This is an awesome website, check out <a href="https://ryangjchandler.co.uk">https://ryangjchandler.co.uk</a> now!

Striking through text

Although I can't think of many places where I ever need to strikethrough text, it can be useful sometimes. A good use case could be in a GitHub issue where you want to strikethrough something you have said previously and update it.

Out of the box, that isn't supported. The syntax for striking through also changes between specifications, but in this case, it's going to be something like this:

The next piece of text should be ~~striked~~ out.

To add support for this, you need to add another extension to the environment.

The extension needed is the League\CommonMark\Extension\Strikethrough\StrikethroughExtension extension.

use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;
use League\CommonMark\Extension\Strikethrough\StrikethroughExtension;

$environment = Environment::createCommonMarkEnvironment();

$environment->addExtension(new StrikethroughExtension);

$converter = new CommonMarkConverter([], $environment);

$html = $converter->convertToHtml('The next piece of text should be ~~striked~~ out.');

Sign off

Thanks for reading this article. In the next instalment, I'll be showing you how you can use tables in your Markdown.

Thanks for reading! 👋

Personally, I find it to be the most consistent way of writing. Yes, there are lots of different flavours but they all have the same base.

Here's an example of some Markdown:

# Let's get started with a heading.

This is some **bold** text.

These are _italics_.

Here is a small bit of `code`

Markdown was inspired by text-to-HTML filters. They're tools designed to take some non-HTML text and transform them into good ol' hypertext.

I won't go over the basics of Markdown in this series. The best place to read about that is on the author's website (John Gruber).

This series will be using tools to transform Markdown that follows the CommonMark specification into HTML.

Getting started

First thing that you need to do to start using Markdown in a PHP application is, you guessed it, install a Composer package.

Since I'm going to be using the CommonMark specification, we need to use a tool that supports that spec.

Luckily the wonderful people over at The PHP League have developed a package for that, league/commonmark

Run the following command to get it installed:

composer require league/commonmark

Parsing your first Markdown

Now that the package is installed, you can start using it straight away.

First, create a new instance of the League\CommonMark\CommonMarkConverter class.

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter;

Next, call the convertToHtml() method on the object and pass through a string of Markdown.

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter;

$html = $converter->convertToHtml('# Hello World');

The $html variable will now hold the HTML equivalent of the Markdown provided, in this case it will be <h1>Hello World</h1>.

Sanitising the Markdown

Since Markdown is converted to HTML, it makes sense that HTML can be written within the Markdown.

When you're transforming user input, this can be risky and might open up the opportunity for an XSS attack.

The PHP League have thought about this though and added an option to the converter that will help out.

To begin using these configuration options, you need to provide an array when constructing the League\CommonMark\CommonMarkConverter object.

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter([
    'html_input' => 'escape'
]);

$html = $converter->convertToHtml('# Hello World');

If you now change the Markdown being parsed and include some HTML, the result will be escaped.

use League\CommonMark\CommonMarkConverter;

$converter = new CommonMarkConverter([
    'html_input' => 'escape'
]);

$html = $converter->convertToHtml('<h1>Hello World</h1>');

After being transformed, $html will now hold the string <h1>Hello World</h1> which is the escaped version of the HTML being transformed.

If you're interested in some of the other options available, visit the package's documentation on Configuration.

Sign off

Thanks for reading this article. In the next instalment, I'll be showing you some helpful extensions you can use to make your Markdown writing experience less painful.

Thanks for reading! 👋

I'm going to be using x-ref directives to identify each part so that you can keep track of everything easily.

<div>
    <textarea x-ref="content"></textarea>
    <p x-ref="remaining"></p>
</div>

On top of that, we need to ensure Alpine can initialise a new component. Let's add an x-data attribute to the root element, in this case a <div>, as well as a data property to hold the contents of the <textarea>.

<div x-data="{ content: '' }">
    <textarea x-ref="content"></textarea>
    <p x-ref="remaining"></p>
</div>

The new content property hasn't been hooked up to the <textarea> yet. The simplest way to do this would be using x-model, which will add an event listener to the element and update the property with the elements value property.

<div x-data="{ content: '' }">
    <textarea x-ref="content" x-model="content"></textarea>
    <p x-ref="remaining"></p>
</div>

With data binding setup, all that's left to do is output the number of remaining characters. To do this, we need to know how many characters the content has and what the limit is.

I like to use data attributes for variable pieces of data, such as the character limit. I'll add a new data-limit attribute to hold this.

<div x-data="{ content: '' }" data-limit="100">
    <textarea x-ref="content" x-model="content"></textarea>
    <p x-ref="remaining"></p>
</div>

The reason I like using data attributes is because if you later decide to move the data object into a function, you can still see the arguments that change the behaviour of the component directly in the markup.

I'm also going to add a new property on our component to hold the limit.

<div x-data="{ content: '', limit: $el.dataset.limit }" data-limit="100">
    <textarea x-ref="content" x-model="content"></textarea>
    <p x-ref="remaining"></p>
</div>

If you don't want to use a data attribute for the limit, you could put the value directly in the data object instead.

The $el object being used is a magic variable provided by Alpine and is a reference to the root element (the <div>). Since this is just a regular Element object, we can use the dataset property to get the data-limit.

There are a couple of ways to go about actually outputting the remaining characters. I'll cover both of them here, since you might like one more than the other.

Method One - template literals

Using Alpine's x-text alongside template literals, you can dynamically set the innerText of an element.

Applying this method to the element looks a little something like:

<div x-data="{ content: '', limit: $el.dataset.limit }" data-limit="100">
    <textarea x-ref="content" x-model="content"></textarea>
    <p x-ref="remaining" x-text="`You have ${limit - content.length} characters remaining."></p>
</div>

Method Two - dynamic <span>

Compared to the first method, this approach will only update the innerText of a single child element instead of the entire <p> element.

This means that you can render the non-dynamic content on the server, or statically.

<div x-data="{ content: '', limit: $el.dataset.limit }" data-limit="100">
    <textarea x-ref="content" x-model="content"></textarea>
    <p x-ref="remaining">
        You have <span x-text="limit - content.length"></span> characters remaining.
    </p>
</div>

Improvements

Preventing flashing content

I personally prefer using server-rendered content to give the <span> some default text. In a Laravel application, I might do something like:

<div x-data="{ content: '', limit: $el.dataset.limit }" data-limit="{{ $limit }}">
    <textarea x-ref="content" x-model="content"></textarea>
    <p x-ref="remaining">
        You have <span x-text="limit - content.length">{{ $limit }}</span> characters remaining.
    </p>
</div>

In this case, the $limit variable is coming from the server and will be rendered as the default value inside of the <span> element. This helps with "flashing" content, since Alpine needs some time to evaluate the x-text directive and set the innerText of the element.

You could also tackle the "flashing" problem using x-cloak, as described in this article.

Using a "computed property"

Alpine doesn't support computed properties in the same sense as Vue, but since the data object is just a regular object literal, you can make use of JavaScript's "getters", as described in this article.

This can hide the calculation logic from the directive itself:

<div x-data="{
    content: '',
    limit: $el.dataset.limit,
    get remaining() {
        return this.limit - this.content.length
    }
}" data-limit="100">
    <textarea x-ref="content" x-model="content"></textarea>
    <p x-ref="remaining">
        You have <span x-text="remaining"></span> characters remaining.
    </p>
</div>

Sign off

If you would like to see an interactive version of this component, I've uploaded one to CodePen.

If you enjoyed this article or have any feedback, please feel free to let me know on Twitter.

Thanks for reading! 👋

Those responses might also vary in type: you might have an HTML response, generated from a Blade view, or a JSON response if the route being hit is an API endpoint.

Here's an example:

class PostController
{
    public function index()
    {
        return view('posts.index', [
            'post' => Post::published()->get(),
        ]);
    }
}

We're going to look at how a controller like this can grow within an application, as well as how we can expand on this concept and turn the code above into the code snippet below:

class PostController
{
    public function index()
    {
        $posts = Post::published()->get();
        
        return new PostIndexResponse($posts);
    }
}

The basic idea

Content negotiation

In some applications, it makes sense to have a single route for both your HTML responses, as well as your API responses.

This technique is known as "content negotiation". You check what sort of request is being made and send a specific type of response back, based on that request type.

Take the example above. If I wanted to return some JSON when the request wants that type of content, I would do the following:

class PostController
{
    public function index(Request $request)
    {
        $posts = Post::published()->get();
        
        if ($request->wantsJson()) {
            return $posts;
        }
        
        return view('posts.index', [
            'post' => $posts,
        ]);
    }
}

Thanks to Laravel's Request::wantsJson() method, you can easily check whether or not you need to return JSON or HTML in the response.

For small scenarios like this, custom response classes won't benefit you much. There's only 2 different conditions that determine the type of response that needs to be returned.

Let's use a hypothetical Request::wantsRss() method now.

class PostController
{
    public function index(Request $request)
    {
        $posts = Post::published()->get();
        
        if ($request->wantsRss()) {
            return RssFeed::from($posts)->create();
        }
        
        if ($request->wantsJson()) {
            return $posts;
        }
        
        return view('posts.index', [
            'post' => $posts,
        ]);
    }
}

As more and more of these different content types get added, the method will get more and more crowded. Let's try and tackle this with custom response classes.

The first step to creating a custom response class is implementing the Responsable interface and moving some of our response logic into the toResponse method.

class PostIndexResponse implements Responsable
{
    public function toResponse(Request $request)
    {
        if ($request->wantsRss()) {
            return RssFeed::from($posts)->create();
        }
        
        if ($request->wantsJson()) {
            return $posts;
        }
        
        return view('posts.index', [
            'post' => $posts,
        ]);
    }
}

First problem is that our $posts variable isn't here anymore. Thankfully, we can add a constructor the class and assign it to a property.

class PostIndexResponse implements Responsable
{
    private $posts;
    
    public function __construct($posts)
    {
        $this->posts = $posts;
    }
    
    public function toResponse(Request $request)
    {
        // ...
    }
}

If we head back to our controller, we can replace all of those if statements with a single instantiation of our new PostIndexResponse class.

class PostController
{
    public function index(Request $request)
    {
        $posts = Post::published()->get();
        
        return new PostIndexResponse($posts);
    }
}

Creating a base response class

The logic that we've just abstracted into a separate class is still a bit long and tedious to write out every time.

One way of working around this is by creating an abstract BaseResponse class that holds this logic instead.

Here's a super simple version:

abstract class BaseResponse implements Responsable
{
    public function toResponse($request)
    {
        if ($request->wantsJson()) {
            return $this->toJson();
        }
        
        return $this->toHtml();
    }
}

The logic is similar to the previous class, but now we're going to use some conventional method naming.

For requests that are expecting a JSON response, the toJson method should be used on the child class. By default, it will use the toHtml method, so you could return a view from here or an instance of HtmlString.

Let's take this new abstract class and apply it to our PostIndexResponse.

class PostIndexResponse extends BaseResponse
{
    private $posts;
    
    public function __construct($posts)
    {
        $this->posts = $posts;
    }
    
    public function toRss()
    {
        return RssFeed::from($this->posts)->create();
    }
    
    public function toJson()
    {
        return $this->posts;
    }
    
    public function toHtml()
    {
        return view('posts.index', [
            'posts' => $this->posts,
        ]);
    }
}

Adding some magic

If I wanted to add a new wantsPng condition to my BaseResponse class, I'd need to go into the toResponse method, check for it, add in a new method. This is tedious when you're using lots of different content types, so why don't we add a bit of magic to it.

I'm going to go down the route of assuming there is always a wants{format} method on the request object. This is probably going to be the case, especially if you're using the check in other places in your app, you'd probably want to macro it in.

abstract class BaseResponse implements Responsable
{
    protected $accepts = [
        'json', 'rss', 'png', 'jpg',
    ];

    public function toResponse($request)
    {
        foreach ($this->accepts as $accept) {
            $requestMethod = 'wants'.Str::studly($accept);
            $responseMethod = 'to'.Str::studly($accept);
          
            if ($request->{$requestMethod}()) {
                return $this->{$responseMethod}();
            }
        }
      
        return $this->toHtml();
    }
}

Now, instead of needing to write the condition yourself, you can simply add a new item to the $accepts property, define a to{format} method using StudlyCase and it should "just work".

Pros

Thin controllers

One of the Laravel community's many "best practices" is to always have thin controllers. This just means that your controllers are always lightweight and small, resulting in a lot of logic being moved outside into models and actions, or in this case, custom response classes.

This best practice also helps with naming things, since each method or class will be appropriately named for what it does. Custom response classes have the same effect.

Code clarity

If this is a pattern that you adopt and use across your codebase, you'll probably find that finding things becomes a lot easier. The same idea can be found in single action controllers and form requests.

If you know the name of the current route / context, or can describe what you're viewing, as long as your custom response classes are named appropriately, you can do a quick search and find exactly what you're looking for.

Cons

Hidden logic

Despite me saying that code clarity is a pro for this pattern, you could also be making an early abstraction, meaning your logic and request flow is hidden away under a named object.

For small projects, that can be problematic, especially if you're not working on them 24/7 and know the structure like the back of your hand.

It can also be problematic for new developers on a project, since it's not conventional. But hey, that's what these posts are all about.

Maintenance of accepted types

Like I've shown, you can use a bit of magic to make the maintenance of this pattern a bit easier, but if you find yourself adding 100 different content types because you have 100 different contexts, you're probably using the wrong pattern.

With each type you add, you need to remember how it works, what should happen with the response and where that magic is even coming from.

Unexpected errors

If somebody makes a request to your route asking for an unexpected content type, your code probably won't have any support for it. That means the user is going to get a nasty 500 error and you're going to be sitting there debugging the problem. Even worse, depending on your default response type, you could even leak data because it will always return JSON, or HTML.

Be sure to protect your routes correctly, or tighten up the base response class to return an empty response by default instead.

Sign off

If you enjoyed this article or have any questions, I'd love to know on Twitter. I'd also love to know if you have used this pattern in your own applications.

Thanks for reading!

The problem with these classes is that they're global and generally registered and bootstrapped for every request. This means that if you want to do something based on the current request, your service provider needs to have some knowledge of the current request context.

Take the following example:

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        if (! request()->is('admin/*')) {
            User::addGlobalScope('forTenant', new ForTenantScope);
        }
    }
}

In this example a global scope is being applied to the User model, but only for routes / URLs that don't match the pattern admin/*.

On a small scale this is probably fine, but as your application grows and you find yourself adding more code inside of this if statement, things can get out of hand quickly and become a maintenance nightmare.

The middleware approach

Since this code is only going to be run for a specific group / set of routes, it can be moved to a piece of middleware and added to the stack for that group of routes.

class BootstrapWebRoutes
{
    public function handle(Request $request, Closure $next)
    {
        User::addGlobalScope('forTenant', new ForTenantScope);
    }
}

This code is doing the same thing as before, but we can now add this middleware to the non admin/* routes and remove the request logic and knowledge from our service provider.

Route::as('web.')
    ->middleware(BootstrapWebRoutes::class)
    ->group(function () {
        Route::get('users', [UserController::class, 'index'])->name('users.index');
    });

Our global boot process now doesn't need to know about the current request context and we can guarantee that this scope is only going to be applied when visiting a route inside of this group (unless the middleware is applied elsewhere, obviously).

Pros

Thinner service providers

The benefit with this approach is that our service providers will actually be slimmer and hopefully only contain things related to actual services.

Of course, global scopes aren't the best example, but as you use more third-party libraries that have configuration values dependent on the current request context (menu builders, breadcrumbs, authorisation), you'll be thankful that it's all contained in middleware classes that are easier to find and compose.

Potentially faster bootups

On a small scale, framework bootstrapping times won't necessarily be faster since the logic that has been moved isn't heavy.

If you were doing multiple bits of string manipulation, or lots of preg_* calls, then moving this out of the global application process might bring a performance improvement since it's only going to be done when it needs to be done.

Modularity

When building applications that use a modular structure, where each component of your application is grouped up into a smaller, Laravel-esque structure, this approach could definitely be of use.

You won't need to step out of the module's context into a global service provider to run logic, or even worse, conditionally register a service provider. You can move all of that logic into a middleware class inside of the current module and register it for a group of routes as shown above.

Cons

Abstract thinking

This concept isn't something that a lot of people will think to do when building there applications, because in a lot of cases libraries will directly tell you to add code inside of a ServiceProvider class. This is even the case with Laravel's own first-party packages.

Due to this, future you might find it difficult to find logic or configuration without sifting through project-wide search results.

Late running

Route middleware is executed after global middleware and any service registration (inside ServiceProvider::register()) so using this approach might not work for all scenarios.

Make sure that if you register any services from inside of this bootstrap middleware that it runs in the correct order, especially if another piece of middleware relies on one of those services.

Also be careful when working with third-party libraries as they could be hooked into those early stages of the framework startup, meaning none of your code inside of the middleware has been evaluated at the right time.

Sign off

As always, be careful when adopting patterns like this (especially prematurely). On small projects with one or two developers, this pattern might not be a beneficial one to use since you're going to know where things are 99% of the time and it will probably cause more damage than good.

I've seen this patterns used in a couple of different scenarios, mostly when working with carbon/carbon and different default formats are used depending on the context, or the base element for breadcrumbs is different based on the request URL.

If you enjoyed this article, I'd love to know on Twitter. If you've ever used this pattern, let me know too!

Thanks for reading!

1. I don't lose things if anything goes wrong and my backup hasn't picked it up.
2. If I can't describe the change I have just made.
3. If I'm demonstrating something to somebody on a pull-request.

The problem is, my actions are setup to run on push, so every single wip commit gets run through the CI process, whether it be running tests, linting or formatting.

After doing some research, I found a way of preventing these from running on every single commit.

jobs:
  format:
    runs-on: ubuntu-latest
    if: "! contains(github.event.head_commit.message, 'wip')"

Now, whenever I push a wip commit or any commit that contains the word wip, it will be marked as skipped inside of GitHub actions.

You could also flip the logic and perhaps do something like:

jobs:
  format:
    runs-on: ubuntu-latest
    if: "contains(github.event.head_commit.message, '[build]')"

Any commit that contains [build] will now trigger these jobs, everything else will be skipped.

You can thank me later! 😉

These handler classes are simple classes that are resolved from the container and only need a single handle() or __invoke() method.

An example pipeline

Imagine you have a blog and when you publish a post, you want to run through a series of tasks. Each task has its own "action", or "handler", class that will receive the post and do something to it.

Here's what your code might look like without using pipelines (with some pseudo methods):

<?php
  
$post = Post::current();

$pipes = [
    MakeSurePostHasBeenPublished::class,
    SendTweetAboutNewPost::class,
    SendEmailAboutNewPost::class,
];

foreach ($pipes as $pipe) {
    $post = app($pipe)->handle($post);
}

There isn't anything immediately wrong with this code since it's on a small scale. Personally though, I don't like having that temporary variable that is only being used as the iterable for the foreach loop and I don't like that the $post variable is being re-assigned after each action. It makes for some confusing and messy code, especially as the number of "pipes" grows.

Let's replace this with a Pipeline implementation and see how much cleaner it is:

use Illuminate\Pipeline\Pipeline;

$post = app(Pipeline::class)
    ->send(Post::current())
    ->through([
        MakeSurePostHasBeenPublished::class,
        SendTweetAboutNewPost::class,
        SendEmailAboutNewPost::class,
    ])
    ->thenReturn();

You can instantly follow the logic of the code, since it uses a fluent method chain with sensible method names. The idea is still the same as before. The current post is being sent through each pipe and then being returned to a $post variable.

The Pipeline itself is being resolved out of the container through the app() helper function since it needs an implementation of Illuminate\Contracts\Container\Container to resolve each pipe class.

Taking it one step further

We've already made an improvement to the code leaving the foreach loop behind and moving to an object-oriented approach, but we can take this even further by wrapping this same logic up inside of a custom pipeline class.

Let's start off by creating a new class called PublishPostPipeline:

use Illuminate\Pipeline\Pipeline;

class PublishPostPipeline extends Pipeline
{
    //
}

When the Pipeline::through() method is called, the array argument passed will be assigned to the $pipes property on the object. This means that method call can be circumvented and the pipes can be assigned directly to the protected $pipes property on the class.

This change also means there is only a single place to add, or remove, a pipe from the pipeline:

use Illuminate\Pipeline\Pipeline;

class PublishPostPipeline extends Pipeline
{
    protected $pipes = [
        MakeSurePostHasBeenPublished::class,
        SendTweetAboutNewPost::class,
        SendEmailAboutNewPost::class,
    ];
}

If we refactor our previous code to use this new PublishPostPipeline class, it would look something like:

$post = app(PublishPostPipeline::class)
    ->send(Post::current())
    ->thenReturn();

The method chain doesn't read very nicely now though, because it sounds like we're just sending the post and returning straight away.

This next part is optional, but I like to add a named constructor and runner method that will accept the Post as an argument and do all of this logic for me.

use Illuminate\Pipeline\Pipeline;

class PublishPostPipeline extends Pipeline
{
    protected $pipes = [
        MakeSurePostHasBeenPublished::class,
        SendTweetAboutNewPost::class,
        SendEmailAboutNewPost::class,
    ];

    public static function run(Post $post): Post
    {
        return app(static::class)->send($post)->thenReturn();
    }
}

Instead of having all of the logic for sending and returning in our caller method, we can just call PublishPostPipeline::run() and use the return value of that method.

The benefit here is that we can type the $post argument and also add a return type of Post, allowing the intellisense plugin of your editor to pick up on the variable type and provide better autocomplete / suggestions.

Sign off

I haven't seen this pattern used too much in the wild but I have used it a lot for making my code more DRY, especially when I use the same pipelines in controllers, queues and commands.

If you want to read up on the Pipeline class a little more, Jeff Ochoa has written a blog post that goes over the basics.

The team over at Zaengle have also created a package that has a deeper approach to writing DRY pipelines, along with a few niceties.

I'd love to know what you thought about this blog post on Twitter.

Thanks for reading!

The data function

When you initialise an Alpine component, you probably put the object expression directly inside of the x-data attribute.

This approach works well for small components that only have a couple of pieces of state and is one of Alpine's strongest selling points. It can get out of hand for larger components, especially those that have large methods for sending AJAX requests, handling form logic, etc.

The simplest way to abstract these large methods is by using functions as your data source. This is similar to how the data() method in Vue works, where you return an object from that function.

This is a component before being abstracted.

<div x-data="{
    name: '',
    email: '',
    password: '',
    errors: {
        name: [],
        email: [],
        password: [],
    },
    validate() {
        if (! this.name) {
            this.errors.name.push('You must enter your name.')
        }

        if (this.email && ! this.email.includes('@')) {
            this.errors.email.push('You must enter a valid email address')
        }

        if (this.password && this.password.length < 8) {
            this.errors.password.push('Your password must be at least 8 characters long.')
        }
    }
}">
    <input type="text" x-model="name" @input="validate">

    <template x-for="error in errors.name">
        <p x-text="error"></p>
    </template>

    <input type="text" x-model="email" @input="validate">

    <template x-for="error in errors.email">
        <p x-text="error"></p>
    </template>

    <input type="password" x-model="password" @input="validate">

    <template x-for="error in errors.password">
        <p x-text="error"></p>
    </template>
</div>

Pretty nasty, right? Moving this to a function is pretty simple. You need to create a function inside of a <script> tag somewhere on the page and make the entire x-data object the return value of that function.

<script>
window.profileForm = function () {
    return {
        name: '',
        email: '',
        password: '',
        errors: {
            name: [],
            email: [],
            password: [],
        },
        validate() {
            if (! this.name) {
                this.errors.name.push('You must enter your name.')
            }
    
            if (this.email && ! this.email.includes('@')) {
                this.errors.email.push('You must enter a valid email address')
            }
    
            if (this.password && this.password.length < 8) {
                this.errors.password.push('Your password must be at least 8 characters long.')
            }
        }
    }
}
</script>

Then replace the value of x-data with the name of the function, in this case profileForm.

<div x-data="profileForm()">
    <input type="text" x-model="name" @input="validate">

    <template x-for="error in errors.name">
        <p x-text="error"></p>
    </template>

    <input type="text" x-model="email" @input="validate">

    <template x-for="error in errors.email">
        <p x-text="error"></p>
    </template>

    <input type="password" x-model="password" @input="validate">

    <template x-for="error in errors.password">
        <p x-text="error"></p>
    </template>
</div>

When you look at this again in the future, it will be much easier to read since you won't have the bloat of the x-data directive hiding all of the markup.

Note: this is a simple trick for larger components but you should be careful to not abstract too early. If you are finding it difficult to manage your Alpine component from the x-data attribute, this one is definitely for you.

Since I'm a Laravel developer, I generally use a @stack on my layout file and push to it from inside of this partial.

@push('scripts')
<script>
window.profileForm = function () {
    return {
        name: '',
        email: '',
        password: '',
        errors: {
            name: [],
            email: [],
            password: [],
        },
        validate() {
            if (! this.name) {
                this.errors.name.push('You must enter your name.')
            }
    
            if (this.email && ! this.email.includes('@')) {
                this.errors.email.push('You must enter a valid email address')
            }
    
            if (this.password && this.password.length < 8) {
                this.errors.password.push('Your password must be at least 8 characters long.')
            }
        }
    }
}
</script>
@endpush

If you're using the latest version of Laravel, you can also wrap this @push in an @once and it will only ever be pushed to the stack once in the same render.

x-spread

This directive, x-spread, was introduced in v2.4 of Alpine. It allows you to bind a collection of directives to a component, similar to x-bind="{}" in Vue.

This one kinds of follows on from the previous tip, where you can extract some re-usable logic into a function and then use x-spread to apply multiple directives at once.

Here's an example of a simple dropdown component built with Alpine. It involves binding some aria- attributes and a few click handlers. It also has no styles (but I'm sure you could make it look pretty).

<div x-data="{ open: false }" @keydown.window.escape="open = false" @click.away="open = false">
    <div>
        <span>
            <button @click="open = !open" type="button" id="options-menu" aria-haspopup="true" x-bind:aria-expanded="open">
                Options
            </button>
        </span>
    </div>

    <div x-show="open">
        <div>
            <div>
                <a href="#" role="menuitem">Account settings</a>
                <a href="#" role="menuitem">Support</a>
                <a href="#" role="menuitem">License</a>
                <form method="POST" action="#">
                    <button type="submit" role="menuitem">
                        Sign out
                    </button>
                </form>
            </div>
        </div>
    </div>
</div>

The first step here is to move to an x-data function, like we did earlier. This is only going to hold a single piece of state, but it will be much easier to setup the x-spread directives later on.

<div x-data="dropdown()" @keydown.window.escape="open = false" @click.away="open = false">
    <!-- Rest of markup here -->
</div>

window.dropdown = function () {
    return {
        open: false
    }
}

To start using the x-spread directive, we need to define an object on our component that will be used to bind the rest of the directives.

Let's first start with the keydown and click handlers on the parent element. I'm going to refer to this particular element as the "wrapper", so let's call the object wrapper.

window.dropdown = function () {
    return {
        open: false,
        wrapper: {
            ['@keydown.window.escape']() {
                this.open = false
            },
            ['@click.away']() {
                this.open = false
            }
        }
    }
}

The wrapper object now contains 2 methods, each one matches the name of the directive it will replace and the function logic matches that of the expression.

Note: Since this is now running inside of a function, Alpine will bind your data object to the this context of the function so be sure to use this.[prop] when reading and writing props.

The only thing left to do with our wrapper element is to remove the directives and add the new x-spread directive:

<div x-data="dropdown()" x-spread="wrapper">
    <!-- Rest of markup here -->
</div>

Under the hood, Alpine will go through the wrapper object and take each method name, setup the directive as usual and use the function as the expression / callback for the directive.

The same technique can be applied for the rest of the components too - the trigger and menu itself.

window.dropdown = function () {
    return {
        open: false,
        wrapper: {
            ['@keydown.window.escape']() {
                this.open = false
            },
            ['@click.away']() {
                this.open = false
            }
        },
        trigger: {
            ['@click']() {
                this.open = ! this.open
            },
            ['x-bind:aria-expanded']() {
                return this.open
            }
        },
        menu: {
            ['x-show']() {
                return this.open
            }
        }
    }
}

And the markup...

<div x-data="dropdown()" x-spread="wrapper">
    <div>
        <span>
            <button type="button" id="options-menu" aria-haspopup="true" x-spread="trigger">
                <!-- Button markup here -->
            </button>
        </span>
    </div>

    <div x-spread="menu">
        <!-- Rest of markup here -->
    </div>
</div>

Mixins

In the context of a Vue component, mixins are just a way of having small bits of re-usable code that could be used throughout your application, in multiple types of component.

Since Alpine evaluates vanilla JavaScript and all of the data is powered by an object, this pattern is even easier to achieve through the use of the spread operator.

Let's take our dropdown function from the previous section and use that as an example.

Imagine I had a component that needed the logic for a dropdown, but also some extra logic on top for changing the icon shown inside of a <button> element. The icon changing logic is only specific to this single component so it doesn't make much sense to abstract that out into the dropdown() function.

How about this, instead:

<div x-data="{ icon: 'up', ...dropdown() }">
    <!-- Rest of markup here -->
</div>

It's truly that simple. Since the window.dropdown function returns an object when invoked, we can "spread" the contents of that object into our data and still have access to the trigger, wrapper and menu objects for use with x-spread.

This pattern is really powerful for renderless components that are likely going to be used in multiple projects too. You could move the window.dropdown method into a re-usable JavaScript file or package and use it anywhere and everywhere (Alpine exists), then sprinkle your styling on top (hopefully with Tailwind).

Note: You should be careful of any property name clashes, for example, multiple open props. To workaround this, you might accept an argument to the dropdown() function that has a unique "key" or "prefix" and add that to each of the props returned.

Sign off

This article was quite a long one, but these are some of the more common patterns for abstracting component logic and making your components more re-usable.

I didn't touch on server-side abstraction too much because not everybody has the power of Blade components at their disposal, but I'm sure you can find your own ways of doing that too.

If you enjoyed this article and found it useful, I'd love to know on Twitter since I would like to cover these concepts in more detail with better examples in the future.

Computed properties are accessed using the $this context of the Blade view. Livewire has a custom Blade compiler that essentially binds an instance of the component to $this so that magic methods can be used to intercept calls to non-existent "computed" properties.

This does open up some cool ideas though - one of them being helper methods on the component class.

The idea

Wouldn't it be amazing if you could change:

<div>
    <select wire:model="selected">
        @foreach(range(1, 100) as $number)
            <option value="{{ $number }}">
                {{ $number }}
            </option>
        @endforeach
    </select>
    
    @if($selected > 0 && $selected % 2 === 0 && $selected < 50)
        <strong>
            Congrats! Your number is even and in the correct range!
        </strong>
    @endif
</div>

Into this:

<div>
    <select wire:model="selected">
        @foreach($this->range() as $number)
            <option value="{{ $number }}">
                {{ $number }}
            </option>
        @endforeach
    </select>
    
    @if($this->selectionIsValid())
        <strong>
            Congrats! Your number is even and in the correct range!
        </strong>
    @endif
</div>

All of the logic for the iterable value and whether or not a valid selection has been can be moved out of the view and into the component class.

The how

It's not difficult. Move all of the logic into methods on the component class and Bob's your uncle, you've refactored to helper methods on your component class.

class Selection extends Component
{
    public function range()
    {
        return range(1, 100);
    }
    
    public function selectedIsValid()
    {
        return $this->selected > 0 && $this->selected < 50 && $this->selected % 2 === 0;
    }
}

The why

Personally, I like this approach since it my views are clearer and easier to follow. I'm not having to search through a clouded chunk of conditional mayhem to find out where something is being output. Instead, I can use appropriately named methods to describe the condition being checked and move on with my life.

Another benefit is that I can now use any protected or private dependencies from my class without needing to explicitely pass them through to the view, or use a computed property.

Sign off

If you found this little trick useful, let me know on Twitter and share some examples of where you have benefited from it.

Note: This feature isn't documented as part of Livewire's public API, so there could be some unexpected behaviour if used incorrectly. The same API is used for computed properties so without a major version update and breaking changes, this is unlikely going to change any time soon.

There a couple of ways to reduce code duplication, especially when it comes to utility functions for string manipulation or HTTP requests. With the release of Alpine v2.5 we can register custom magic variables that will allow us to reduce that duplication without copying and pasting functions, or adding a load of functions to the global namespace.

The entry point

All of Alpine's public API runs through a global window.Alpine object. Registering magic variables is no different.

A single call to Alpine.addMagicProperty will get you well on your way.

Alpine.addMagicProperty('property', function ($el) {

});

The first argument is the name of the magic property. If you're familiar with Alpine, you have probably already used $refs, $dispatch or $el.

The name you provide doesn't need to have any prefix, Alpine will automatically add a $ prefix so that it is more inline with the Alpine ones.

The second argument is the callback for the magic variable. This function will receive the root element for the component, not the component instance itself.

You can use this callback to return a scalar value such as a string, boolean or integer, or even return another function so that the magic variable can be invoked.

A good example

Nowadays I try to avoid using third-party libraries (where possible) and ship JavaScript that utilises native browser APIs. Let's take this approach and create a little helper for the Fetch API.

I want a magic variable called $post that will send a POST request to the URL provided as the first argument and pass along any data that I provide as the second argument.

Alpine.addMagicProperty('post', function () {
    return function (url, data = {}) {
        return fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            redirect: 'follow',
            body: JSON.stringify(data)
        });
    }
});

By returning a function from our callback, we can now invoke the $post property:

<button type="button" x-on:click="$post('/posts', { id: 1, title: 'Awesome New Post' })">
  Create Post
</button>

Pretty sweet, eh?

Sign off

This was just a short article to show you the API for creating custom magic variables / properties in your Alpine components.

Note: This API is not documented and you should be careful using it.

If you want to see some more examples of magic properties, Kevin Batdorf has created a collection of packages / helpers for you to use. Here is the GitHub link. (Huge shoutout to Kevin for being so active and helpful on the Alpine.js Discord too!)

If you create any cool helper functions, please share them on Twitter, I'm sure we'd all love to see them!

As people move away from jQuery though, it is hard to find a solid answer on how you can achieve a similar effect to slideToggle. I'm going to be using Tailwind v1.2+ alongside Alpine, using some modern CSS transformation rules.

The basics

CSS provides such really useful transformation properties that allow you to modify the appearance of an element. In this case, we want to use the scaleY transformation function. This will allow us to change the height of an element and Tailwind provides scale-y-0 and scale-y-100 classes for this.

We also want to add some transitions for this scale change, so we'll use Tailwind's transition- classes too.

On the Alpine side of things, we can use some data- attributes and event handlers to trigger the slide.

The click

The first thing needed is some sort of trigger. I'm going to use a <button> for this.

<button @click.prevent="">Toggle</button>

We also need a scale target. You could hard-code this, but I want to make this re-usable and will instead use a data-target attribute. We can use this to declare the query selector of our target element.

<button @click.prevent="" data-target="#toggleTarget">Toggle</button>

It would help if that target actually existed on the page. I'll make it a sibling of the <button>, but you could put it anywhere on the page really.

<button @click.prevent="" data-target="#toggleTarget">Toggle</button>

<div id="toggleTarget"></div>

The base styles

Our target also needs some classes for this to function correctly. These classes will apply some sensible defaults to the element so that we need to do less work with Alpine.

<button @click.prevent="" data-target="#toggleTarget">Toggle</button>

<div id="toggleTarget"
     class="transition-transform ease-out overflow-hidden origin-top transform"
></div>

transition-transform will make sure that our target element will transform when any transform: ... properties change. The ease-out class defines our timing function, in this case: transition-timing-function: ease-out.

We want to hide any overflow inside of our target so that any text doesn't hang outside of it whilst scaling.

origin-top will ensure our transformation uses the top of the element as its origin / base point. If you change this to origin-bottom, the scale will go from the top to the bottom of the element. Change this depending on which effect you prefer.

transform tells Tailwind to add a master transform rule that will react to changes of CSS custom properties, made by the scale-y-* classes I mentioned earlier.

Making it move

Now that we have some basic classes on the target element, we can go ahead and start on toggle itself. I'm going to write all of this JavaScript inside of the @click.prevent on the <button>, but you are free to move this into a function.

We first need to get the target element:

<button data-target="#toggleTarget"
    @click.prevent="document.querySelector($event.target.dataset.target)"
>Toggle</button>

Then we need to toggle the scale-y-0 class.

<button data-target="#toggleTarget"
    @click.prevent="document.querySelector($event.target.dataset.target).classList.toggle('scale-y-0')"
>Toggle</button>

If you add some dummy text to the target element, you'll notice that it toggles state correctly but there's no smooth animation. That is because we haven't added a transition-duration property to our target element.

There are a couple of options here:

1. Add a class with a default duration. For example, duration-500 will make sure that the transformation takes 500ms to finish.

2. Add a class and support a data-duration attribute to change it on a trigger basis.

The first option is pretty self-explanatory but I'd like to show you how to do the section approach too.

data-duration support

Add a data-duration attribute to the trigger element. I'll use 700 as my default value.

<button data-target="#toggleTarget"
    data-duration="700"
    @click.prevent="document.querySelector($event.target.dataset.target)"
>Toggle</button>

Now, inside of your click handler we need to set the property on our target element, so let's do a little refactoring too:

<button data-target="#toggleTarget" 
    data-duration="700"
    @click.prevent="
        const target = document.querySelector($event.target.dataset.target)
                    
        if ($event.target.dataset.duration) {
            target.style.transitionDuration = `${$event.target.dataset.duration}ms`            
        }
                    
        target.classList.toggle('scale-y-0')
    "
>Toggle</button>

Since we need the target more than once, we can assign it to a constant. Then, using the style property of the element, set the transitionDuration property using the new data-duration attribute.

Live example

I've made a prettier example here for you to check out. You could take this a step-further and make a window.$slideToggle variable that has this as a function so that you can use it throughout your application.

use Illuminate\Support\Facades\Route;

Route::get('/projects', 'ProjectsController@index');

The official documentation tells you this is the way to register routes and most applications use this method.

Route groups

A route group is a way of collecting a number of routes and assigning the same properties, or options, to them. For example, you could prefix a group of routes with the same url:

Route::prefix('/projects')->group(function () {
    Route::get('/', 'ProjectsController@index');
    Route::get('/{project}', 'ProjectsController@show');
});

This is a super convenient way of reducing the amount of duplication you would get from individually registering routes with that /projects prefix.

But did you know that you can drop the use of the Route facade inside of the group callback and make use of a $router parameter instead?

The $router parameter

The Closure that is passed to the group() method can actually take an argument. I tend to call it $router but you can call it whatever you want. So taking the previous example of a route group, you can do this:

Route::prefix('/projects')->group(function ($router) {
    $router->get('/', 'ProjectsController@index');
    $router->get('/{project}', 'ProjectsController@show');
});

If you wanted to type-hint parameter, you should type hint the Illuminate\Routing\Router class. The line of code responsible can be found here.

Pros & Cons

To be honest, there aren't really any big pros or cons to this approach. It's more of a "Did you know you could do this?" one.

Some people might think that there is a performance benefit since you're not calling a method on the Route facade each time, but after testing this with 100 routes the difference was literally a couple of milliseconds. This would be down to the fact that, under the hood, Laravel caches the underlying instance so that it doesn't need to be resolved from the container each time.

Sign off

If you've ever seen or used this approach before, I'd love to know on Twitter.

Thanks for reading 👋

After looking at some larger applications, I found a few that used synchronous jobs as a way of splitting up application logic into reusable components.

The idea

Laravel provides some convenient ways of dispatching jobs. If you had a job called CreateSubscription you could push it to the queue using CreateSubscription::dispatch(). You could also process it synchronously using CreateSubscription::dispatchNow().

A little known fact is that you can actually return things from the job itself.

Let's create a barebones job:

use App\Models\User;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Contracts\Queue\ShouldQueue;

class CreateSubscription implements ShouldQueue
{
    use Dispatchable;
    
    private $user;
  
    private $plan;
    
    public function __construct(User $user, string $plan)
    {
        $this->user = $user;
        $this->plan = $plan;
    }
}

The job will receive an instance of App\Models\User and store it in a private property. The visibility of this property isn't important since this job will be self handling.

Here's the handle method:

public function handle()
{
    $subscription = SomeSubscriptionService::create([
        'email' => $this->user->email,
        'plan' => $this->plan,
    ]);

    $this->user->update([
        'subscription_id' => $subscription->id,
    ]);

    return $subscription;
}

The logic isn't important for this article. The important part is the return $subscription at the end of the method.

If we were to dispatch this job inside of a controller:

class SubscriptionController
{
    public function store(Request $request)
    {
        $subscription = CreateSubscription::dispatchNow(
            $request->user(),
            $request->input('plan')
        );
        
        return redirect()->route('subscription.thank-you', [
            'plan' => $subscription->plan,
        ]);
    }    
}

The return value of the job will be given back to the controller, in this case assigned to a variable so that it can be used further along.

Pros

It's a job, queue it when you want

Since this is just a regular Laravel job that implements the ShouldQueue marker interface, you could just as easily push it to the queue using CreateSubscription::dispatch().

There's no need to change the logic at all, since the return value will just get thrown away, it won't harm the queue.

With the example above where you need the subscription afterwards, it doesn't make much sense, but for something like RenewSubscription, you could use the job synchronously when the user manually renews in the browser, then use the same job from a scheduled command that handles automatic renewals or something.

Reusability

These jobs are reusable and can be used anywhere in your applications (controllers, listeners, commands, etc). This benefit is a little less important because in reality you could create any sort of class and have it do the same thing, just like the "action" pattern that is quite popular.

Cons

It's different

Jobs aren't designed for this. They can do it, but according to convention they shouldn't. If a new developer comes on to a project and sees this, they're probably going to think "What the f&$*?".

It's not officially documented

This functionality won't be found anywhere in the official Laravel docs, so it could disappear in a major version update. I doubt it will, but it could.

Sign off

If you've ever used this pattern, let me know on Twitter because I'd love to know. Let me know if you have any questions or things you think I missed.

I'd like to shout out laravel.io too (Dries), since this is where I initially discovered this functionality. You can take a look at the GitHub repo to find out a bit more.

As always, thanks for reading! 👋

Have you ever considered removing that logic from your main request / response flow and holding the model accountable instead? If not, let me show you how it can be done and some of the pros and cons.

How?

Model events

Most Laravel developers have used model events at some point in their career. If you haven't, here is how they work.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;

class Post extends Model
{
    public static function boot()
    {
        parent::boot();

        static::creating(function (Post $post) {
            if (!$post->slug) {
                $post->slug = Str::slug($post->title);
            }
        });
    }
}

When a new Post model is created using the Post::create() method, our closure will be run before it has actually been saved / persisted. Model::creating() is just one example. There are ::created(), ::saving(), ::saved() and so many more. You can read more about them in the Laravel documentation.

Generally speaking, these events are used to ensure that some property is always present or auto-generated on the model. Ensuring something exists kind of sounds like validation, doesn't it?

Validating the model

Now that we know how model events work, we can utilise them and validate our models on creation. Take a look at the following code:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;
use Illuminate\Support\Facades\Validator;

class Post extends Model
{
    public static $rules = [
        'title' => 'required|string|max:255',
        'slug' => 'required|string',
        'excerpt' => 'nullable|string|max:160',
        'published_at' => 'nullable|date',
    ];

    public static function boot()
    {
        parent::boot();

        static::creating(function (Post $post) {
            Validator::validate($post->toArray(), static::$rules);
        });
    }
}

The rules are defined on the model as a static property, since they're unlikely to change. In the event that they do change, you could always define a getRulesArray() method on the model, and use the following snippet instead.

static::creating(function (Post $post) {
    Validator::validate($post->toArray(), $post->getRulesArray());
});

public function getRulesArray(): array
{
    return [
        'title' => 'required|string|max:255',
        'slug' => 'required|string',
        'excerpt' => 'nullable|string|max:160',
        'published_at' => 'nullable|date',
    ];
}

The second approach would make more sense when you need to conditionally apply some logic based on a property on the model, but in most cases I'd find a static array to be fine. One example might be a unique rule that needs to ignore the current model when updating / saving.

Things to note

Hidden properties

Unfortunately Laravel's validator doesn't work with objects, meaning the Model::toArray() method is needed. The problem here is you might not actually be able to validate all of the properties if you're using the protected $hidden property on the model.

This would be the case for the default User model that Laravel provides and the password column. One way to work around this is by making those properties visible during validation:

protected $hidden = ['published_at'];

static::creating(function (Post $post) {
    $post->makeVisible(['published_at']);
  
    Validator::validate($post->toArray(), static::$rules);
});

Now when the $post->toArray() call is made, the published_at column will be present and processed.

Pros

Knowledge encapsulation

One common thing, especially in more domain-driven patterns, is ensuring that your HTTP layer knows as little as possible about your database. In Laravel, this means your model becomes a God class full of database knowledge, and your controllers simply call methods without knowing what columns are present and what data types they are.

With this auto-validation pattern, that is easy enough to achieve. Your controller no longer needs to do any validation or worry about what data is being validated. Your model handles all of that and encapsulates it in a single place.

Re-usability

Even if you didn't want to do the whole auto-validation thing, you could still place your rules on the model and use those elsewhere. This is another point on top of my last one. As long as you know the name of the method (use some sort of interface if you want), your controller won't know anything about the rules present, just that it needs to do some sort of validation.

A smaller point is that any changes to the rules will be applied everywhere. You won't need to go through all of your controllers / form requests and change them.

Forget about the boring stuff

Validation is boring. This approach will mean you only have to do is in one place, just create your models as regular elsewhere. Forget about the boring stuff and enjoy the magic.

Cons

Redirect loops

Since the Validator::validate() method throws a ValidationException when validation fails, Laravel will try to catch that exception and redirect back to the previous location.

If for whatever reason your previous location was the same as the route where validation is failing, you will probably get stuck an a redirect loop.

Be sure to only use this auto-validation pattern on separate routes, i.e. GET /posts and POST /posts would be fine.

Side effects

As mentioned a second ago, Laravel will pick up on the ValidationException and try to redirect the user back with some errors. This means that something that happens in the database layer could have some effect on the HTTP layer of your application.

This doesn't bother me much, but there will be some people who find this disgusting and some sort of anti-pattern. Remember though, this is an unconventional thing to do.

"Bottom of the drawer" logic

The final con that I'd like to mention is that this pattern will push all of your validation to the "bottom of the drawer". By that I mean the validation itself is hidden when looking at your controllers and other parts of your application, so when something goes wrong or you need to add a new validation rule, it might cause some headaches or digging to find out where it is all taking place.

Sign off

Thanks for reading! I'm super excited to write some more articles about strange patterns you can use in your Laravel applications.

If you're interested in using this automatic validation pattern in your applications, I've created a small package that will can make it a bit easier to get started with. Check it out on my GitHub or click this link.

Luckily, Laravel's Illuminate\Support\Facades\Route class provides a nice currentRouteName() method that we can use to make a comparison.

Let's create a little function that you can re-use throughout your application.

use Illuminate\Support\Facades\Route;

function active_route(string $name): bool
{
    return Route::currentRouteName() === $name;
}

This function is great, but it doesn't do anything with classes. Let's add a second parameter so that a class string such as 'bg-gray-900' could be passed through.

use Illuminate\Support\Facades\Route;

function active_route(string $name, string $classes): bool
{
    if ($active = Route::currentRouteName() === $name) {
        echo $classes;
    }
  
    return $active;
}

Perfect! Now we can pass in the name of a route and a class string and it will echo the class if the current route matches the one provided.

If we wanted to, we could also wrap this into a custom Blade directive. In any ServiceProvider::boot(), add the following snippet:

Blade::directive('active', function ($expression) {
    return "<?php \active_route({$expression}); ?>"
});

Inside of a Blade template, we could now do:

@active('projects.index', 'bg-gray-900 hover:bg-gray-500')

And it would work just the same as calling active_route() directly. Nice!

Going beyond

One way this could be improved is conditionally checking whether or not a second parameter is passed through via the directive. This means you could treat @active as an if statement and do something based on the true and false conditions.

Let's make the second parameter to active_route() optional and add some checks to see how many parameters the directive receives:

use Illuminate\Support\Facades\Route;

function active_route(string $name, string $classes = null): bool
{
    if ($active = Route::currentRouteName() === $name && $classes) {
        echo $classes;
    }
  
    return $active;
}

use Illuminate\Support\Facades\Blade;

Blade::directive('active', function ($expression) {
    $parts = explode(',', str_replace(['(', ')'], '', $expression));
  
    if (count($parts) === 1) {
        return "<?php if (active_route({$expression})) : ?>";
    }
  
    return "<?php \active_route({$expression}); ?>"
});

It seems a bit confusing at first, but I'll break it down:

1. When our custom directive handler is called, it will receive $expression as a string. For example, @active('projects.index') will mean expression is ('projects.index'). The parentheses are included, so we need to remove those from the string before running explode().

2. explode(',', ...) will split the string after each ,. If two arguments are provided, then were should be a comma separating them. You could run into problems here if you use commas in your route names, but I've never seen anybody do that, most people use full-stops. In the case that no commas are present, $parts will just be an array with a single item.

3. If there is only 1 "part" (the length of $parts is 1), then we can assume that we're in if else mode, so we return an if statement instead of the string. Luckily, our active_route() function already returns a boolean, no matter the number of arguments received.

Now, we can do something like:

@active('projects.index') bg-gray-900 hover:bg-gray-500 @else bg-gray-400 @endif

@endactive vs. @endif

We've only got a single if statement, so using @endif is perfectly fine. If you wanted to make it a bit prettier, you could just add the following bit of code;

Blade::directive('endactive', function () {
    return '<?php endif; ?>';
});

Constrained access

It's not always the best idea to put this data everywhere on your site. You might only need it when working with a particular element or view, this is where data- attributes come in handy.

Given the following HTML, I need to show the current user's name when the button is clicked, otherwise, just show a generic "Hello" message. By default, it will show the generic message.

<button type="button" id="show">Show Email Address</button>
<p id="message">Hello</p>

Let's add a data-name attribute to the <p> element.

<button type="button" id="show">Show Email Address</button>
<p id="message" data-name="{{ $user->name }}">Hello</p>

Now if we want to access it inside of our JavaScript, we can:

document.getElementById('show').addEventListener('click', el => {
    const el = document.getElementById('message')
    
    el.innerText = `Hello, ${el.dataset.name}`
})

Any data-* attributes can be accessed using the "camel case" equivalent. For example, data-first-name can be accessed using el.dataset.firstName.

In the case you have a model, you'll need to {{ $user->toJson() }} in the Blade template and then JSON.parse(el.dataset.user) in JavaScript to access it correctly.

Global object

The next one is useful if you've got loads of different scripts that rely on the data.

In a layout file, we can add a <script> somewhere in <head> of the document.

<head>
    <script>
        window.sharedData = {}
    </script>
</head>

It's just an empty object, but there is 2 different approaches we can take here. Either declare the property using JavaScript and ensure we json_encode() each value, or instead json_encode() an associative array and let PHP handle it all (nearly).

Each item

<head>
    <script>
        window.sharedData = {
            user: {{ json_encode(auth()->user()) }},
            ids: {{ json_encode([1, 2, 3]) }}
        }
    </script>
</head>

Associative array

<head>
    <script>
        window.sharedData = json_encode([
            'user' => auth()->user(),
            'ids' => [1, 2, 3],
        ])
    </script>
</head>

It's worth noting that any objects that get serialized will have all of their public properties exposed in the resulting object.

If you want to customise the serialized form, you can implement the JsonSerializable interface and add a jsonSerialize() method. This method should return an array with the things you'd like to expose.

Going beyond

The methods above don't take all scenarios into account. For example, any class that implements the Arrayable or Jsonable contracts won't be serialized using the toArray() or toJson() methods.

You should also be careful of any HTML or double quotes when serialising user-created values. I'd suggest passing through the JSON_HEX_QUOT | JSON_HEX_APOS flags to json_encode(). These flags will convert all " and ' to their Unicode equivalent.

There are plenty of packages out there that can share server-side values with your client-side scripts (coderello/js-shared-data comes to my mind), but for the simpler cases, the 2 methods above should be enough.

Here's how:

<div>
    <button wire:click="$refresh">Reload Component</button>
</div>

And that is it! The "magic" $refresh action can be used, anywhere an action can, in your component. Livewire will pick up the action name and simply re-render the component.

Quite often, you'll see something like:

$minutesInAWeek = 7 * 24 * 60

On a small scale, it's quite clear what is going on, but if you wrap this bit of logic in a function or another calculation, you can quickly lose sight of what 60 represents.

Luckily, Carbon provides a set of constants that can clear it up, making it easy to see what each number represents.

Lets take our example above and use these constants to make what's happening clearer:

use Carbon\Carbon;

$minutesInAWeek = Carbon::DAYS_PER_WEEK * Carbon::HOURS_PER_DAY * Carbon::MINUTES_PER_HOUR;

Yes, it's verbose. But this kind of verbosity is good, in my opinion.

If we wanted to take this further and figure out how many seconds are in a year, we could do:

use Carbon\Carbon;

$minutesInAWeek = Carbon::DAYS_PER_WEEK * Carbon::HOURS_PER_DAY * Carbon::MINUTES_PER_HOUR;

$secondsInAYear = $minutesInAWeek * Carbon::SECONDS_PER_MINUTE * Carbon::WEEKS_PER_YEAR;

There's some more constants too, you can check out the full list in the documentation.

Date pickers are horrendnous with browser compatibility, given IE11 and Safari don't support them, so we instead choose to use a simple <select> element with the dates as <option> inside.

Here's how you can generate an array of dates for a given period:

use Carbon\{
    CarbonPeriod,
    Carbon
};

CarbonPeriod::create(
    Carbon::now(),
    Carbon::now()->addDays(30)
);

Calling this method will return an instance of Carbon\CarbonPeriod which has implements the Iterator interface and can therefore be used inside of a foreach statement.

When looping over the CarbonPeriod instance, the iteration variable will be an instance of Carbon\Carbon, so you can call all of the regular format and toDateTimeString() methods.

Generally, each repository is responsible for one entity within your application. For example, a UserRepository should only be responsible for retrieving User records.

Abstract implementation

I've seen various people use traits to implement repositories directly inside of their models. Personally I think this gives the model too much responsibility, especially since models in Laravel are essentially "God classes" already.

Instead, I'll create an abstract class that all of the repository classes will extend:

<?php
  
namespace App\Repositories;

abstract class Repository
{
    //
}

All of the repository classes will live inside of the app/Repositories folder and are namespaced accordingly. If you're following a domain-driven design, you could put this class inside of a "shared" domain.

Each repository needs to have some model-based context, so we'll add a static property to our base class.

<?php
  
namespace App\Repositories;

abstract class Repository
{
    protected static string $model;
}

I've chosen to make this protected since I don't need to access it externally, but I still need to have access to it / overwrite it in the child class. You could make it public if you wanted to do some conditional logic based on the value.

This $model property should contain the fully-qualified namespace of a model class, for example User::class.

The reason this implementation of the repository pattern is so simple is that all method calls from inside of the class will be delegated to an instance of $model.

The missing piece of the puzzle is the all-mighty magic __call() method.

<?php
  
namespace App\Repositories;

use Illuminate\Support\Facades\App;

abstract class Repository
{
    protected static string $model;

    public function __call(string $name, array $arguments)
    {
        return App::make(static::$model)->{$name}(...$arguments);
    }
}

Now whenever we call a method that doesn't exist on your repository class, it will instead be delegated / deferred to an instance of the underlying $model.

An example

A quick example would be creating a UserRepository that has some useful methods for finding a User by email, name and id.

<?php
  
namespace App\Repositories;

use App\User;

class UserRepository extends Repository
{
    protected static string $model = User::class;
  
    public function findByName(string $name): ?User
    {
        return $this->where('name', $name)->first();
    }
  
    public function findByEmail(string $email): ?User
    {
        return $this->where('email', $email)->first();
    }
  
    public function findById(int $id): ?User
    {
        return $this->find($id);
    }
}

Then, inside of a controller you could pull the repository in using dependency injection:

<?php
  
namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController
{
    protected $users;
  
    public function __construct(UserRepository $users)
    {
        $this->users = $users;    
    }
}

Sign off

I'd love to know if anyone else has used this pattern in their applications and how they implemented it. Comment below or tweet me if you have.

See ya! 👋

Directive evaluation

When defining your directives on a component, the order does matter.

<div x-data="{ text: 'Hello' }">
    <p x-text="text" x-bind:style="color: red;"></p>
</div>

In the example above, our text will be set before the style attribute is updated. This could cause problems since you will see a flash of black, or whatever the default color is, before the x-bind:style directive is evaluated.

To counter this problem, you could swap the two directives around:

<div x-data="{ text: 'Hello' }">
    <p x-bind:style="color: red;" x-text="text"></p>
</div>

Now the x-bind:style is reached first, then our x-text directive is evaluated.

Another option would be adding x-cloak to the element, at the end.

<div x-data="{ text: 'Hello' }">
    <p x-text="text" x-bind:style="color: red;" x-cloak></p>
</div>

Now the <p> will be hidden (as long as you have the correct CSS) until Alpine has completely initialised the element.

If you're interested in the piece of code that handles all of the evaluation, you can find it here in the GitHub repository.

What's happening is the DOM is ready before Alpine takes controls of the element, so it shows up and then disappears. It can be quite jarring if you have lots of components on your site.

To counter the problem, Alpine will look for an x-cloak attribute and remove it once it has loaded. This lets you defined some CSS that will set the element to display: none when the page loads.

Add this bit of CSS to your site:

[x-cloak] {
    display: none !important;
}

And Bob's your uncle, the flicker problem has been fixed!

I'd like to take you through some of them, as well as the pros and cons of each.

Data functions

This one shouldn't be new to regular Alpine users. This approach replaces the inline x-data object literal with a function that returns an object instead.

<div x-data="data()">
    <p x-text="text"></p>
</div>

<script>
    function data() {
        return {
            text: "Hello, World!"
        }
    }
</script>

Pros:

• For component with larger datasets, it's far easier to manage than an object string.
• You can add methods to the returned object that it also easier to manage.
• Makes using Alpine with third-party libraries simpler.

Cons:

• Function must be defined on the window object, so a large number of unique components starts to add lots of bloat to the global namespace.
• These objects aren't structured in any particular way, your data is sat directly next to your methods.
• When placed in an inline <script> tag, you lose the ability to minify your JavaScript and reduce data transfer sizes.

Summary

This approach works great for small sites and developers who don't mind explicitely putting everything under window . It's also useful if you're integrating with third party libraries that interact with your Alpine components.

Async components

If you have used Vue before, you'll probably be familiar with the concept of asynchronous components, a design pattern that only loads the component / JavaScript when a particular component is needed.

This is especially useful when using code-splitting / browser-supported ES modules. I'll show you an example using browser-supported ES modules:

// index.js (loaded in browser using <script type="module">
;(async function() {
    if (document.querySelector('[x-data="example()"]')) {
        await import('./components/example.js').then(module => window['example'] = module.default)
    }
})()

// ./components/example.js
export default function() {
    return {
        message: 'Hello!',
        clear() {
            this.message = ''
        }
    }
}

The code above is taking advantage of dynamic imports. This is supported in all major modern browsers, not IE11. If you need to support IE11, I'd suggest creating a separate bundle that has support for it.

In this instance, we are checking to see if any example components are found on the page. If one is found, we want to load the code for that component. This is stored inside components/example.js . Again, this example is using ES modules hence the exports.

When the component is found on the page, we want to dynamically import the file responsible for the component and assign the default export to a window.example variable so that Alpine can call it.

Pros:

• Uses modern JavaScript features with no transpilation, can run directly in the browser.
• Only the code that is needed gets loaded, so no unnecessary data transfer.
• Component logic can be separated into individual files, on a component by component basis.

Cons:

• Uses modern JavaScript features with no transpilation so won't run directly in IE11.
• Won't be useful when dynamically inserting content into page, since it does not re-evaluate on page mutation, but this could easily be fixed with a MutationObserver .
• Still a big blur of data properties and logical methods.
• Still using puts functions on window object.

To counter the last "con", I've found a way that makes it clearer what is what in my head.

// utils.js
export const buildComponent = (data, methods, __init) {
    return () => {
        return {
            ...data,
            ...methods,
            __init
        }
    }
}

Inside of your component file, you can then import this function and use it to separate your data, methods and init method.

import { buildComponent } from '../utils.js'

const data = {
    message: 'Hello!',
}

const methods = {
    clear() {
        this.message = ''
    }
}

export default buildComponent(data, methods)

The only thing that I don't like about this approach is referencing this inside of my methods doesn't give my any autocomplete, nor is it clear what this is.

Laravel Blade Components

For Laravel developers, this one will most likely work the best.

Instead of using regular partials, you can turn your Alpine component into a Blade component and use it like a regular HTML element.

// components/input.blade.php
<div x-data="{ text: '' }">
    <input x-model="text" {{ $attributes }}>
</div>

// index.blade.php
<div>
    <x-input type="text" name="hello" id="hello" />
</div>

Unless your smaller components are being used in lots of different places, this probably won't be useful for most sites. For larger components, such as modals and dropdowns, you can nicely hide all of the logic in your component file and still pass the regular HTML attributes through.

If you're using JavaScript functions to setup your component and data, you could add a custom @pushonce directive so that you can use inline <script> tags. The idea behind this is that you include a <script> tag with the component, inside of the @pushonce directive that is pushed to an @stack in your layout file.

This approach is going to be most similar to a single file Vue component, since you have your markup, JavaScript and you could even @pushonce your CSS too.

Pros:

• Excellent reusability of both the markup and the JavaScript.
• Most familiar to Vue single file component pattern.
• Fluent use of HTML-like tags, with support for passing regular attributes through.

Cons:

• Requires Laravel (or a Blade package for external use).
• JavaScript being inlined with @pushonce can't be minified.
• Only really good for high usage components, no real gain for single use components.

Here's that @pushonce directive for you:

Blade::directive('pushonce', function ($expression) {
    [$pushName, $pushSub] = explode(':', trim(substr($expression, 1, -1)));

    $key = '__pushonce_'.str_replace('-', '_', $pushName).'_'.str_replace('-', '_', $pushSub);

    return "<?php if(! isset(\$__env->{$key})): \$__env->{$key} = 1; \$__env->startPush('{$pushName}'); ?>";
});
				 
Blade::directive('endpushonce, function () {
    return '<?php $__env->stopPush(); endif; ?>';
});

Outside of Laravel

If you're using other frameworks, or completely different languages, most templating engines have the concept of partials where you could apply the same pattern, just without the nice HTML-ish tags.

Sign off

I'm glad you made it this far. These were just a couple of tips on organising your Alpine components and how I've personally been doing it recently.

As the project evolves, there will definitely be new and improved ways to do this so I'll be sure to keep an eye out for new ideas and share them with you all too.

I'd also like to say another thank you for sponsoring me, it means a lot that people are genuinely interested and support what I do. As always, all feedback is welcome no matter how good or bad it is, so let me know what you thought through Twitter or Discord.

Have a good one! 👋

The setup

When an authenticated user visits a route in our application, we want to store the timestamp in the database for use later on. Let's store it in a column called last_active_at.

All you need to do is create a migration:

php artisan make:migration add_last_active_at_to_users_table --table=users

And add the following line in the up() method:

$table->timestamp('last_active_at')->nullable();

If the user has never visited a route, it will remain NULL in the database.

We also want to make sure this field is "fillable", so add last_active_at to the protected $fillable array on your User model.

As well as being able to update last_active_at using User::update(), we want to cast it to a Carbon\Carbon instance when using it so that we can make use of time comparison methods.

The middleware

Logic

The middleware will be responsible for checking the authentication status and updating the last_active_at column.

namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Closure;

class TrackLastActiveAt
{
    public function handle(Request $request, Closure $next)
    {
        if (! $request->user()) {
            return $next($request);
        }

        if (! $request->user()->last_active_at || $request->user()->last_active_at->isPast()) {
            $request->user()->update([
                'last_active_at' => now(),
            ]);
        }

        return $next($request);
    }
}

Here's what happens in order:

1. We check the current user is authenticated. If they're not, we're returning early so that the rest of the middleware has no effect.
2. If the current user last_active_at date & time is NULL or is in the past, we want to update it using the current date and time. Thankfully, Laravel has a now() helper function that returns an instance of Carbon\Carbon for the current date and time.
3. Forward the current request on to the next middleware.

Registration

We have a couple of different options for registering the middleware. If you want to track your users activity across all routes, it should be registered under the web array in App\Http\Kernel:

protected $middlewareGroups = [
    'web' => [
        // ...
        \App\Http\Middleware\TrackLastActiveAt::class,
    ]
]

If you only want to track the latest activity for particular routes, you can register the middleware as part of your route registration:

Route::get('/foo', 'FooController')->middleware([\App\Http\Middleware\TrackLastActiveAt::class]);

<div x-data="data()">
    <span x-text="hello()"></span>
</div>

<script>
function data() {
    return {
        hello: function () {
            return "Hello!"
        }
    }
}
</script>

This works quite well, but they're not really properties anymore. The <span> is still reactive, so if the return value depended on another data property, the UI would be updated when the dependency gets changed. To my eyes, property() isn't as pretty as property on its own.

Today though, I saw a tweet from Sebastian De Deyne that took a different approach to the same concept.

This approach just didn't occur to me at first. It's probably because I hadn't actually tried it. The first thing I did was hop into CodePen and try it out:

See the Pen Getters Alpine.js by Ryan Chandler (@ryangjchandler) on CodePen.

Out of the box, it just works! Click the button on the right and watch the <span> below update. I almost feel kind of stupid that I hadn't though of this originally. Since Alpine is using an object literal as its source of data, we can use all of the normal things an object provides, such as getters and setters.

The other added benefit this method provides is that you don't need to add the parentheses anymore because when Alpine tries to access the property, the JavaScript engine will recognise that there is a getter defined and call that for us.

Browser compatibility

Regular getters and setters are supported in all modern browsers and ... 🥁 all the way back to Internet Explorer 9. The only thing that isn't supported that far back is computed property names, so you can't do things like:

function data() {
    return {
        get [expression]() {
            return 'Hello!'
        }
    }
}

The expression is dynamic and acts like a fallthrough if the property doesn't exist or doesn't have a getter defined already. That's not a big deal, because nobody should be using IE9 today. Seriously, nobody.

Sign off