Duncan McClean

Year In Review 2025

Sat, 13 Dec 2025 16:51:00 +0000

I haven’t written one of these in a while. I’m not much of a reflection person, but enough happened this year that it felt worth capturing.

Work

Statamic

Work has been busy. We originally planned to ship Statamic 6 around April/May, but we decided to take on a full redesign, and things naturally snowballed.

As part of that work, we migrated to Interia.js (🎉) and built our own UI component library. That alone was a sizeable undertaking. Note to self: never build your own combobox.

Considering there are only five of us, I think we’ve done a solid job. I’m still really happy at Statamic, and I can’t see myself going anywhere anytime soon.

You'll likely hear a lot more from us in the new year!

Cargo

Cargo is an e‑commerce add‑on for Statamic that I’ve been building in my spare time. I started it last year as a replacement for an existing add‑on of mine. It isn’t fully released yet (it depends on Statamic 6), but I announced the alpha back in August.

Beyond the product itself, I spent a lot of time on documentation. I don’t love any of docs generators, and I couldn’t land on something I was happy with, so I brought in a designer friend, Mike Martin, to help with the docs and branding. I’m really pleased with how it turned out.

Early traction was slow, but things have started to pick up. There’s activity in GitHub Discussions, DMs, and email. Someone even answered another user’s question without me getting involved 🤯

At some point next year, I'd love to be in a position where I can pay someone to help with bug fixes and support. I love my job at Statamic and want to free up some time for other side projects.

Meetups & Conferences

I made it to a few meetups and conferences this year:

GlasgowPHP
Laracon EU
Laracon US
Statamic Meetup in Alkmaar

Whether it’s because I work from home or just enjoy travelling, I really like in‑person events—even as an introvert 🙈.

After attending GlasgowPHP this year, I joined the team helping to organise it. I’ve also built the websites for the Glasgow meetup and the Edinburgh one (coming soon).

I also had the chance to speak at the Statamic Meetup in Alkmaar 🇳🇱. It was my first talk. There are definitely things I’d do differently next time, but overall it went well. I spoke about building e‑commerce sites with Cargo.

I’m hoping to attend more in‑person events next year. Fingers crossed for Flat Camp 2026 🤞

Personal

On the personal side, I passed my driving test in January and bought a car not long after. It’s been really nice being able to do things without having to organise lifts or rely on public transport.

I also took my first solo, non‑work trip and visited Köln. I’ve already got two more trips planned for next year. One of the perks of living at home with minimal commitments.

More recently, I’ve been trying to limit my time on social media. I bought a Brick a few months back, which has been incredibly effective at stopping me from doom‑scrolling Twitter and Instagram first thing in the morning. These days I only check Twitter on my laptop, and Instagram every few days when I intentionally “unbrick” my phone.

Looking ahead

2025 was a busy year, in a good way.

Next year, I hope to release Cargo and get it to a mature state so I can spend less time on it and more on other side projects. I also want to be more deliberate with my time - less external noise and more focus on creating.

If you enjoy year‑in‑review posts, here are a few from internet friends that are worth a read:

Uses (September 2025)

Sat, 06 Sep 2025 00:00:00 +0000

This post lists all the tools, services, and equipment I use day-in, day-out. I'll update this post whenever I make any major changes to my setup.

If you want to see other people's setups, check out github.com/wesbos/awesome-uses, stefanzweifel.dev/uses or sebastiandedeyne.com/uses.

Hardware

Apple MacBook Air (15", M4, 2025)
Apple iPhone 15 Pro Max
Apple AirPods Pro
LG 38WN95CP QHD+ 38” Curved UltraWide
ZSA Voyager keyboard
MX Master 3 Mouse
Bose SoundLink Flex Portable Speaker
Flexispot E7 Standing Desk
CalDigit TS4 Thunderbolt Dock

Software

Development

I started using PHPStorm last year and I love it.

I honestly don't know how I managed to live without it. It makes it a breeze to refactor a large codebase or source dive some vendor code.

I also use the Laravel Idea plugin, which has recently become free.

When I'm not using the integrated terminal in PHPStorm, I'm probably using Ghostty:

I have a lot of Bash aliases and functions. They're not all that interesting, but you can find them in my dotfiles repository.

I'm currently trying out Tmux after watching Alex Six's talk at Laracon US.

Here's some of the other development-related tools I use:

I primarily use Safari, but I'll open up Chrome when I need to use Vue Devtools.
Tower (my Git GUI of choice)
TablePlus (my database GUI of choice)
Laravel Herd
Tinkerwell for running PHP code here and there.
Ray lets me debug code without cluttering my app's output with dumps.
Tuple for pair programming
GitHub, obviously. I have at least one GitHub tab open at all times.
Claude is currently my main AI tool. I use the Claude desktop app, and Claude Code via Opencode.
Laravel Forge for managing all my servers. The new UI is looking 🔥

Productivity

I'm pretty happy with my current "productivity stack". It works great for me so I have no reason to switch things up.

I use Things 3 extensively for keeping on top of to-dos. It's got to be one of the most well-designed macOS and iOS apps out there!
I use Obsidian for all my work-related notes, and Apple Notes for everything else.
I use Fastmail to host my emails. I'm picky about email clients, but I like theirs.
I use 1Password for all my password management needs.
I use Raycast as my launcher.

Business

I run my own one-person business, for my Statamic addons and freelance work. Here are some of the business-y tools I use:

I use FreeAgent for sending invoices and handling bookkeeping. I've been using it for over five years at this point and I don't know what I'd do without it.
Starling Bank is one of the big challenger banks here in the UK. The app is easy-to-use, and it automatically syncs my transactions into FreeAgent.
I use Wise for sending & receiving money internationally. They have really low rates compared to the rest of the market.

Cargo is now in Alpha!

Fri, 22 Aug 2025 00:00:00 +0000

It's been a long time coming, but Cargo is finally in alpha! 🎉

Cargo is basically a complete rewrite of Simple Commerce. It's been a massive amount of work, but I'm really happy with how it's turned out and I can't wait for you to try it out!

Carts & Orders

One of the biggest changes in Cargo is how it handles carts and orders.

Simple Commerce stored carts and orders in the same collection. It worked, but it always felt a bit clunky.

In Cargo, carts and orders are stored separately in their own Stache stores. This gives Cargo more control over how things work and also makes things more reliable, like the transition between flat files and a database.

Control Panel

Cargo is taking full advantage of the UI components built into Statamic 6, making everything feel polished and consistent. Here are a couple of sneaky screenshots:

Viewing an order in the Control Panel

Product Variants fieldtype

Editing a Discount

Discounting

Discounting is another area that has received massive improvements.

It's now possible to create "site-wide discounts" which get applied automatically when a customer's cart meets certain criteria. Useful for Black Friday or Christmas sales. Of course, manually applied discounts (coupons) are still supported.

Cargo also allows you to build your own discount types, so if you need something more complex than just percentage or fixed discounts, you can build it yourself.

Pre-built Checkout

This is probably my favourite part of Cargo... the pre-built checkout flow.

Building a checkout flow from scratch can be daunting and time-consuming, especially for smaller sites where time is money.

Cargo's pre-built checkout flow features a minimal design and flexible Antlers templates, making it easy to customise for your project.

If you need more control, you can still build your own checkout page.

Docs

As well as building Cargo itself, I've been working with long-time Statamic community member, Mike Martin on the documentation and branding for Cargo. It's looking pretty slick if you ask me! 🔥

→ Visit the docs

Migrating to Cargo

While I can't promise it'll be a 5–10 minute upgrade, I have tried to make it as smooth as possible with commands to handle most of the heavy lifting. You can find everything you need to know in the migration page.

Finally

I've been working on Cargo for a little over a year now. It’s been a massive undertaking, and in hindsight, I don’t think I’ll rewrite a side project of this scale again — but I’m glad it’s out there for you to try.

To get started, spin up a new site or migrate an existing Simple Commerce site and let me know what you think.

Oh, and by the way, if you want to update to Statamic 6, but don't have time to migrate to Cargo right away, you'll be happy to know that Simple Commerce also supports v6.

Configuring public access to Meilisearch on Laravel Forge

Wed, 18 Jun 2025 00:00:00 +0000

Meilisearch is a super fast search engine that's easy to self-host on your own infrastructure, avoiding the need for another Saas subscription.

If you're using Laravel Forge, setting up Meilisearch is super simple:

Provision a new Meilisearch server
Allow connections between your app server and your Meilisearch server
Update your .env to point at the private IP address of the Meilisearch server:

MEILISEARCH_HOST=http://10.0.0.6:7700
MEILISEARCH_KEY=key_from_forge
MEILISEARCH_INDEX=your_application

You can then use something like Laravel Scout to push your Eloquent models into Meilisearch and everything "just works".

The Frontend Problem

However, if you want to search Meilisearch directly from the frontend using something like instant-meilisearch, you'll run into an issue: requests to the server's public IP address won't work.

There isn't really a straightforward way to fix it... you can't setup additional sites in order to connect a domain name.

However, there is a workaround...

Workaround: Reverse Proxy

If you can't connect directly to the Meilisearch server, you can connect via one of the servers in the same network.

Create a new site on your application server. You might want to use a subdomain for this, like search.yourdomain.com.
Provision an SSL certificate, just like you normally would.
Edit the site's Nginx config in Forge and replace the default location block with this:

location / {        
    proxy_pass http://10.0.0.6:7700;
}

It'll tell Nginx that any requests to this site should be forwarded to the Meilisearch server. You should make sure Nginx is pointing to the server's private IP address.

Now, if you visit https://search.yourdomain.com in a browser, you should get a successful response back.

For additional security, you may wish to configure CORS headers to prevent other websites sending requests to your Meilisearch server.

Demo: Using Laravel Reverb outside of a browser 📡

Fri, 23 May 2025 00:00:00 +0000

I recently shared how I'm using Laravel Reverb outside of a browser to build a real-time webhook proxy.

Update on Cargo / Simple Commerce

Fri, 23 May 2025 00:00:00 +0000

Cargo (the new version Simple Commerce) is basically done. 🛍️

I recently invited a handful of folks into the GitHub repo to help me test things before I make it publicly available.

It's built on top of Statamic 6, so I'm planning to make the repo public when Statamic 6 goes into alpha/beta.

Then, I'm planning to tag a proper 1.0.0 around the same time as Statamic 6 is released.

Cargo includes a couple of big changes, including...

Carts & Orders are now separate, and no longer stored as entries.
Customers are now proper Statamic users.
A massive overhaul to discounting, allowing for automatic site-wide discounts.
Pre-built checkout page - publishable during the installation process.

Cargo will be a paid upgrade. However, if you purchase Simple Commerce now, you'll be able to upgrade for free.

Cargo will automatically migrate your configuration options, orders, discounts for you, leaving you to update your code.

I can't wait to finally have it out there. It's been a long time coming (see my announcement post last year 😅).

Update in August 2025: Cargo is now in alpha! Spin up a site and let me know what you think 🎉

Pair with me 🍐

Fri, 07 Feb 2025 00:00:00 +0000

After pairing with Ben Holmen last week, I've decided to open up my calendar and take part in the "Pair-amid Scheme".

I'm very much an introvert, so pairing with strangers is a little outside my comfort zone, but I'm hoping it's a good way to meet new people and learn from others.

We'll chat for a bit, then we can take turns on hacking on whatever we need to code that day, whether it's a side project, or a hard problem you need help solving.

→ Book a date in my calendar

The Future of Simple Commerce

Tue, 20 Aug 2024 00:00:00 +0000

It's nearly been five years since I started working on Simple Commerce. It started out as a way for me to play around with the Statamic 3 Alpha, but slowly and surely grew into the most popular way to build e-commerce sites with Statamic.

From the beginning, I wanted Simple Commerce to feel "native" to Statamic. It should take advantage of using entries to store products, it should tightly integrate with Antlers and seamlessly fit into the Statamic way of doing things.

I also wanted it to be simple to use - without getting in the way when you need to extend it to do something custom.

And from what I can tell from customer feedback, it seems like I've achieved that (🎉).

Over the last couple of months, I've realised that Simple Commerce has become pretty bloated and honestly not as polished of an overall product as I'd like.

So, after thinking about it for a while and doing some exploratory coding, I've decided it's time to rewrite Simple Commerce.

Woah! That's a bold move.

Indeed it is. Rewriting software is always difficult, but I believe that a rewrite is a good move for the future of Simple Commerce.

From the groundwork I've already done, the next version of Simple Commerce should be the most polished version of SC yet. 💅

There's a couple of big changes I'm already planning to make in the next version of Simple Commerce:

Orders will no longer be entries

One of the biggest, if not the biggest change, will be the fact that orders will no longer be entries. Orders don't really belong in collections, they're not content after all.

Orders will remain flat-files, living in content/orders, with the option to migrate orders to a database, as needed.

I'm also working away on a much-improved Control Panel experience for orders. In fact, here's a very early wireframe of what'll become the "order show" page:

Please don't judge my Figma skills, I'm not a designer. 😂

One other change I wanted to mention regarding orders is the fact that carts will no longer be orders under the hood, they'll be separate.

When the customer "checks out", the cart will be converted to an order, and an order number will be assigned.

Customers are now users

For most of Simple Commerce's existence, customer information has lived in a "Customers" collection.

Although, it's always been kinda awkward since "customer" entries often held much of the same information that users do.

So, in the next version of Simple Commerce, customers will just be normal Statamic users. This will make it easier for customers to be able to login & view their orders.

If you'd prefer not have lots of users, you can opt-out and use "guest customers" instead.

And a bunch more...

Support for one-page checkouts
A simplified tax engine - gone are the days of the two separate tax engines 🙈
Improvements to SC's Antlers tags
Fresh Starter Kit templates

Release Date & Upgrade Process

This next version is still a while out. Although, I'm hoping to have a beta out by the end of the year so you can start preparing your sites.

I'm aiming to try and make the upgrade process as painless as possible. However, with it being a full rewrite there will ultimately need to be some changes to "user-land" code.

If you have any custom PHP code which interacts with Simple Commerce, like an event listener or code that queries orders, chances are you'll need to re-work that code when you upgrade.

Support

Since it's just me working on Simple Commerce in my free time, I'm planning to take a little bit of a step back on support for the current version, to try and maximise the time I'm able to spend working on the new version.

I'll still be looking into High Priority issues, but not some smaller issues which might be fixed in the next version.

If you have any questions about the new version, or just want to express your excitement about the new version, then feel free to send me an email: hello@doublethree.digital.

Update in May 2025: I've just published an update on the new version of Simple Commerce, which is now called Cargo.

Update in August 2025: Cargo (the new version of Simple Commerce) is now in alpha! Spin up a site and let me know what you think 🎉

Setting up Xdebug's profiler with Laravel Herd & PHPStorm

Mon, 15 Jul 2024 00:00:00 +0000

Laravel Herd now has first-party support for profiling, without needing to change any Xdebug settings. See their documentation: https://herd.laravel.com/docs/1/advanced-usage/profiler

I recently made the switch to Laravel Herd, after using Valet for years. Even though Herd is still using Valet under the hood, I've found it to be considerably faster than plain Valet.

One of the things I've been wanting to do for a while is to setup Xdebug in order to perform performance profiling, without needing to subscribe to a service like Blackfire.

Setting up Xdebug with Laravel Herd is pretty simple - you just have to follow a couple of steps on their docs to get it configured. Or, if you're using Herd Pro, it'll automatically enable Xdebug when it detects breakpoints in your code.

By default, Xdebug's debug mode will be configured. However, in order to do profiling, we need to switch to its profile mode instead, this involves a few additional steps:

Install Laravel Herd if you haven't already.
Enable Xdebug manually or purchase Herd Pro.

Herd Pro includes some pretty nifty features - like one-click setup for MySQL, Redis, Meilisearch, as well as local email debugging and dump logging (useful if you don't have a Ray license).
We need to append a short snippet to Herd's php.ini configuration file in order to change the Xdebug mode. You can find Herd's php.ini files at ~/Library/Application Support/Herd/config/php/<version>/php.ini.

In addition to changing Xdebug's mode, it also sets the output directopry for the generated "cachegrind" files. I've got this set to the root of my project, but you're free to change this to where ever you like.

xdebug.mode = profile
xdebug.start_with_request = trigger
xdebug.output_dir = /Users/duncan/Code/Statamic/sandbox

In order for our changes in the php.ini file to take affect, we'll need to reset Laravel Herd. You can do this from Herd's menubar menu:

Click "Stop all", then "Start all".
Next, in order for Xdebug to know you want to profile incoming requests, you'll need to install the Xdebug browser extension for whichever browser you're using (found in the Chrome & Firefox extension stores).

It'll add a little widget to your browser, allowing you to start and stop profiling sessions (or debugging sessions, if you switch back to debug mode).
Finally, you'll need to "Start Listening for PHP Debug Connections" in PHPStorm.

After PHPStorm is listening, visiting a page in your browser will generate a cachegrind.out... file in your chosen directory. The "Analyze Xdebug Profiler Snapshot" action will let you open this file and view the profiling snapshot.

If you ever need to switch back to debug mode, simply comment out the additions in Herd's php.ini file and restart Herd for the changes to take affect.

Note: I've only tested this on macOS, however, in theory, it should work the same way on > Windows but the php.ini file will be different.

Simple Git Blame

Fri, 02 Feb 2024 00:00:00 +0000

I've recently found myself going to the GitHub website multiple times a day to gather context on the code I'm looking at in my code editor.

I looked at some VS Code extensions which allow you to view a "git blame" inside VS Code but I didn't really like any of the ones I tried.... so I thought it'd be a fun evening project to build one.

Introducing "Simple Git Blame". Install it, go to a file, select a line (or multiple) and summon the action. The "Blame" page will open in your browser.

You can view the source code here.

Select dropdown cells with Laravel Excel

Fri, 22 Sep 2023 00:00:00 +0000

An application I work on automatically generates & sends an spreadsheet export, with a few fields pre-filled. The user can then populate the rest of the data and upload it back into the application.

However, one of the fields that's part of that spreadsheet is an enum field. This means that whatever value that's used for the field in the spreadsheet needs to match exactly with the backing value of the enum.

After some digging, I found that I could add a 'select dropdown' to the relevant cells in the spreadsheet. The user could then select what they want from that dropdown and it'll match exactly... woo hoo! 🎉

To save you some digging, here's how you add 'select dropdown' fields to exports generated with Laravel Excel.

Note: For this to work, I believe you'll need to be exporting as a .xlsx file, rather than a .csv.

As a basic example, I'm going to use the names of Laravel Core Team members, and make a dropdown for the countries.

First of all, here's my collection of rows:

public function collection()
{
    $countries = ['United Kingdom', 'Belgium', 'United Kingdom', 'Portugal', 'Malaysia', 'Australia', 'Ireland'];

    return collect([
        ['Taylor Otwell', $countries],
        ['Dries Vints', $countries],
        ['James Brooks', $countries],
        ['Nuno Maduro', $countries],
        ['Mior Muhammad Zaki Mior Khairuddin', $countries],
        ['Jess Archer', $countries],
        ['Guus Leeuw', $countries],
        ['Tim MacDonald', $countries],
        ['Joe Dixon', $countries],
    ]);
}

Then, in order to be able to change the "type" of the country cells, we need to create a "custom value binder".

To do this, you'll first need to extend the DefaultValueBinder class and implement the WithCustomValueBinder interface:

use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithCustomValueBinder;
use PhpOffice\PhpSpreadsheet\Cell\Cell;
use PhpOffice\PhpSpreadsheet\Cell\DataValidation;
use PhpOffice\PhpSpreadsheet\Cell\DefaultValueBinder;

class LaravelTeamExport extends DefaultValueBinder implements FromCollection, WithCustomValueBinder

Then, you'll want to add a bindValue method to your export.

public function bindValue(Cell $cell, $value)
{
    if (is_array($value)) {
        $validation = $cell->getDataValidation();
        $validation->setType(DataValidation::TYPE_LIST);
        $validation->setAllowBlank(true);
        $validation->setShowDropDown(true);
        $validation->setFormula1('"'.collect($value)->join(',').'"');

        $value = '';
    }

    return parent::bindValue($cell, $value);
}

The above code will check if the $value of the current cell is an array. If it is, we'll set the type of data validation that should take place to TYPE_LIST, set some other settings and provide the formula (the options) that should be available in the cell dropdown.

If it's not an array, then Laravel Excel will bind everything just like it normally would.

So, as a finished product, you'll have something along the lines of this:

<?php

namespace App\Exports;

use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithCustomValueBinder;
use PhpOffice\PhpSpreadsheet\Cell\Cell;
use PhpOffice\PhpSpreadsheet\Cell\DataValidation;
use PhpOffice\PhpSpreadsheet\Cell\DefaultValueBinder;

class LaravelTeamExport extends DefaultValueBinder implements FromCollection, WithCustomValueBinder
{
    /**
     * @return \Illuminate\Support\Collection
     */
    public function collection()
    {
		$countries = ['United Kingdom', 'Belgium', 'United Kingdom', 'Portugal', 'Malaysia', 'Australia', 'Ireland'];

        return collect([
            ['Taylor Otwell', $countries],
            ['Dries Vints', $countries],
            ['James Brooks', $countries],
            ['Nuno Maduro', $countries],
            ['Mior Muhammad Zaki Mior Khairuddin', $countries],
            ['Jess Archer', $countries],
            ['Guus Leeuw', $countries],
            ['Tim MacDonald', $countries],
            ['Joe Dixon', $countries],
        ]);
    }

    public function bindValue(Cell $cell, $value)
    {
        if (is_array($value)) {
            $validation = $cell->getDataValidation();
            $validation->setType(DataValidation::TYPE_LIST);
            $validation->setAllowBlank(true);
            $validation->setShowDropDown(true);
            $validation->setFormula1('"'.collect($value)->join(',').'"');

            $value = '';
        }

        return parent::bindValue($cell, $value);
    }
}

Simple Commerce v5 released!

Fri, 28 Apr 2023 00:00:00 +0000

I've just tagged the latest release of Simple Commerce, version 5. It includes a new concept of order & payment statuses, now supports Stripe Payment Elements out of the box, improves developer experience around building custom gateways & adds support for Statamic 4.

It's come a long way since it was released back in 2020. Let's dive into some of the big new features!

Order & Payment statuses

Previously, orders had a couple of status toggles, like Is Paid & Is Shipped. Depending on how the toggles were toggled an order was either: cart/paid/shipped/refunded.

However, after various discussions with customers, it became clear that we should probably introduce two new concepts: Order Statuses & Payment Statuses.

The Order Status represent the 'state' of the order, either Cart/Placed/Dispatched/Cancelled.

The Payment Status represents the 'state' of the order's payment, either Unpaid/Paid/Refunded.

Decoupling the statuses means an order can be placed however not necessarily paid (for example: if you're waiting for a manual bank transfer to go through).

Both of the statuses have their own fields within orders to let your back-office staff see where they're at. The statuses can also be updated within the Control Panel via an action.

Existing orders will be migrated to the new format during the upgrade process.

Stripe Payment Elements support

Simple Commerce now takes advantage of Stripe's relatively new Payment Elements functionality. This means you can now let customers pay using payment methods other than their credit/debit card.

Stripe will localise the payment methods displayed depending on the customer's location. You can also use this to let customers pay with services like Klarna. You just need to enable them within your Stripe Dashboard.

The Payment Elements is the default for new Simple Commerce sites starting today!

If you wish to switch to it on an existing site, you'll want to copy the Stripe code from the Starter Kit into your site & also configure the Stripe webhook so Simple Commerce knows when payments have gone through successfully.

Improved developer experience (DX) around building custom gateways

These changes are zero-impact to most sites, unless you maintain your own custom payment gateway for Simple Commerce.

I've chosen this as a good time to rename some of the methods used when implementing custom gateways & various other changes in terms of what's returned by methods, like prepare and purchase.

For a full overview of what's changed in relation to the Payment Gateway DX changes, review the pull request.

Statamic 4 Support

Simple Commerce now supports Statamic 4, which was released in the last couple of days. In fact, Simple Commerce v5 only supports Statamic 4, it doesn't support 3.3 or 3.4.

In addition, PHP 8.2 and Laravel 10 are the only supported versions of PHP & Laravel.

Lots more....

There's lots of other things also included in Simple Commerce v5:

All of the documentation has been re-written
Replaced the Standard Post shipping method with a Free Shipping method.
The "Checkout Pipeline" has been refactored to make it easier to share code between on-site & off-site checkouts.
Internally, Simple Commerce now uses Vite to build JavaScript assets.

You may view a full list of all the changes in the changelog.

To update your site, follow the instructions in the v4.x to v5.x Upgrade Guide. You may create new sites using the Starter Kit.

Using Torchlight with Statamic's Bard field

Mon, 26 Sep 2022 00:00:00 +0000

Torchlight is a really awesome API for syntax highlighting. In the past, folks might have used libraries like Prism or highlight.js. These libraries work but they're not completely accurate.

Whereas, Torchlight uses the same syntax highlighting system under the hood as VS Code which means it can support any language that VS Code can (including Antlers!)

I've been using Torchlight on this site for a while, along with on my documentation sites. And as I'm seeing more and more folks using it, I thought I'd share how to setup Torchlight to work with Statamic's Bard field.

Install Torchlight

Before you can do anything else, you'll need to install Torchlight's Laravel package and copy over the default config file. You can do these two steps by running these two commands:

composer require torchlight/torchlight-laravel
php artisan torchlight:install

In your config folder, you should now see a torchlight.php file which contains some settings, like the VS Code theme you wish your code blocks to be rendered in.

If you haven't already, create an API token which you can do on this page (provided you're logged in). Then, take the token and add it to your .env file.

TORCHLIGHT_TOKEN=your-mad-torchlight-token

Next, add Torchlight's middleware to the Http Kernel (app/Http/Kernel.php).

/**
 * The application's route middleware groups.
 *
 * @var array
 */
protected $middlewareGroups = [
  'web' => [
	  \Torchlight\Middleware\RenderTorchlight::class, // [tl! add]
	  \App\Http\Middleware\EncryptCookies::class,
	  \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
	  \Illuminate\Session\Middleware\StartSession::class,
	  // \Illuminate\Session\Middleware\AuthenticateSession::class,
	  \Illuminate\View\Middleware\ShareErrorsFromSession::class,
	  \App\Http\Middleware\VerifyCsrfToken::class,
	  \Illuminate\Routing\Middleware\SubstituteBindings::class,
  ],

  'api' => [
	  'throttle:api',
	  \Illuminate\Routing\Middleware\SubstituteBindings::class,
  ],
];

Add a set your Bard field

Next, go in and edit your blueprint, click into your Bard field (create one if you don't already have one), then create a new set which will be used for your code blocks.

I have two fields in my 'Code block' sets. One for the code itself (using the Code fieldtype) and one for the language which we later pass to Torchlight to highlight the code properly (can use a normal Text fieldtype).

Then, you'll want to save your blueprint.

Torchlight 🔦

Add this code to wherever you're looping through your Bard field and have a code block set (replace the handles if you need to)

{{ torchlight :language="language" }}
  {{ code | noparse | entities }}
{{ /torchlight }}

Next, we need to create the Torchlight tag you see in the code example above. I've already written this for you, so all you need to do is paste it into app/Tags as Torchlight.php.

<?php

namespace App\Tags;

use Statamic\Tags\Tags;
use Torchlight\Blade\BladeManager;
use Torchlight\Block;

class Torchlight extends Tags
{
    /**
     * {{ torchlight language="php" }}{{ my_code }}{{ /torchlight }}
     */
    public function index()
    {
        $language = $this->params->get('language');
        $code = $this->context->raw('code');

        $block = Block::make()
            ->language($language)
            ->code($code)
            ->theme(config('torchlight.theme'));

        BladeManager::registerBlock($block);

        $render = function (Block $block) {
            return "<pre><code class='{$block->placeholder('classes')}' style='{$block->placeholder('styles')}'>{$block->placeholder()}</code></pre>";
        };

        return $render($block);
    }
}

Finally, you'll want to add in Torchlight's CSS to your site so the code blocks will be rendered properly - as documented on the Torchlight site.

Now, when you load up your site, your code blocks should be rendered with Torchlight. 🚀

Under the hood of the Duplicator addon

Sat, 21 May 2022 00:00:00 +0000

Duplicator is by far my most popular Statamic addon, by downloads at least. And to be honest, it's probably one of my simplest.

Duplicator registers a few actions: one for each of the 'things' you can delete - an entry, an asset, a term and soon (hopefully) a form.

Actions are what you see when you click the 'three dots' on the listing tables:

Today, I'm going to walk you through the action for duplicating entries (which is probably the one used most often). So let's dig in:

public static function title()
{
    return __('duplicator::messages.duplicate');
}

I thought I'd start off easy. That just returns the title of the action which is the text that's displayed on the 'actions dropdown in the CP.

We're making use of Laravel's __ method here which lets us 'localise' the text so it can be 'Duplicate' but in whatever language the current Control Panel user is using.

The community has contributed translations for a few languages - you can review the docs here on what languages are supported and how to add your own.

protected function fieldItems()
{
	if (Site::all()->count() > 1) {
		return [
			'site' => [
				'type' => 'select',
				'instructions' => __('duplicator::messages.fields.site.instructions'),
				'validate' => 'required|in:all,' . Site::all()->keys()->join(','),
				'options' => Site::all()
					->map(function (SitesSite $site) {
						return $site->name();
					})
					->prepend(__('duplicator::messages.fields.site.all_sites'), 'all')
					->toArray(),
				'default' => 'all',
			],
		];
	}

	return [];
}

Actions can optionally use the fieldItems method to return any fields which should be shown to the user before the action is run.

If Duplicator is running on a multi-site, it'll show a 'Site' dropdown field which gives the user the option of duplicating the selected entry to a specific site or even all sites.

We'll get onto how the multisite duplicating works in a little bit.

public function visibleTo($item)
{
	return $item instanceof AnEntry;
}

public function visibleToBulk($items)
{
	return $this->visibleTo($items->first());
}

These two methods (visibleTo and visibleToBulk) are where you decide whether an action is shown/visible for a certain item(s). An item could be an Entry, a Term, an Asset, etc.

The visibleTo method expects a single item to be passed in. We then check whether the $item is an instance of the Entry object. If it is, we'll return true to tell Statamic our 'Duplicate' action should show in the Actions List.

The second method, visibleToBulk does pretty much the same thing but multiple items are passed into it.

Because I was lazy when I wrote this, we're just calling the other method for the first item in the $items collection. In some of my other addons, I map through the $items, pass it through the visibleTo, then check the count of them being true is the same as the original count of the $items collection.

The visibleToBulk method is called when you select multiple entries in the Listing Table - which then displays the available Actions at the top of the table.

public function run($items, $values)
{
	collect($items)
		->each(function ($item) use ($values) {
			/** @var \Statamic\Entries\Entry $item */
			if ($item instanceof AnEntry) {
				$itemParent = $this->getEntryParentFromStructure($item);
				$itemTitleAndSlug = $this->generateTitleAndSlug($item);

				$entry = Entry::make()
					->collection($item->collection())
					->blueprint($item->blueprint()->handle())
					->locale(isset($values['site']) && $values['site'] !== 'all' ? $values['site'] : $item->locale())
					->published(config('duplicator.defaults.published', $item->published()))
					->slug($itemTitleAndSlug['slug'])
					->data(
						$item->data()
							->except(config("duplicator.ignored_fields.entries.{$item->collectionHandle()}"))
							->merge([
								'title' => $itemTitleAndSlug['title'],
							])
							->toArray()
					);

				if ($item->hasDate()) {
					$entry->date($item->date());
				}

				if (config('duplicator.fingerprint') === true) {
					$entry->set('is_duplicate', true);
				}

				$entry->save();

				if ($itemParent && $itemParent !== $item->id()) {
					$entry->structure()
						->in(isset($values['site']) && $values['site'] !== 'all' ? $values['site'] : $item->locale())
						->appendTo($itemParent->id(), $entry)
						->save();
				}

				if (isset($values['site']) && $values['site'] === 'all') {
					Site::all()
						->reject(function ($site) use ($entry) {
							return $site->handle() === $entry->locale();
						})
						->each(function ($site) use ($entry) {
							$entry->makeLocalization($site->handle())->save();
						});
				}
			}
		});
}

And here we are... the meat of the article. How Duplicator does the duplicating!

Because an action can be run on multiple items at once, the first thing we're doing is looping through each of the $items with a Laravel Collection.

Next, we check if the current $item is actually an Entry instance (in case, somehow the visibleTo stuff didn't work).

After that, we then call two custom methods: getEntryParentFromStructure which figures out the entry's parent from the collection's tree, then the second, generateTitleAndSlug generates a title and slug for the duplicated entry. We'll discuss how both of these methods work individually later on.

Next, we start building an Entry object. We set the collection, the blueprint, the locale/site for it to be duplicated into, the publish status, the slug we just made, along with 'entry data'.

The collection will be the same as the original entry, so we can use $item->collection() to grab it.
The blueprint will also be the same. We can get the handle of the blueprint with $item->blueprint()->handle()
Depending on what the user selected when choosing the site(s) to duplicate on, we'll either duplicate to the selected site or to the same site as the original entry.
By default, for the publish status, we'll use the same published state as the original entry. However, you can override this in the addon's config file (maybe you want any duplicates to be unpublished by default)
The slug will literally just be the slug we generated a minute ago.
In terms of the entry data, we'll mostly just copy over the entry data from the original entry but we'll remove any 'ignored fields' (a config option in Duplicator) and we'll set a different title.

After that, we check if the entry collection has dates enabled. If it does, we set the date of the duplicated entry to the date of the original entry.

Duplicator has a concept of 'fingerprints' which essentially means it leaves a is_duplicate key on the entry so you can tell if an entry was created by Duplicator.

We then save the entry! 🎉

After it's saved, we do a couple more things:

Add the duplicated entry into the collection's tree (if it has one) - it'll be added just underneath the original entry.
If the user wants an entry to be duplicated to all of their sites, we'll do that here by creating a 'localisation' of the entry for each of the other sites.

protected function getEntryParentFromStructure(AnEntry $entry)
{
	if (! $entry->structure()) {
		return null;
	}

	$parentEntry = $entry
		->structure()
		->in($entry->locale())
		->page($entry->id())
		->parent();

	if (! $parentEntry) {
		return null;
	}

	if ($entry->structure()->expectsRoot() && $entry->structure()->in($entry->locale())->root()['entry'] === $parentEntry->id()) {
		return null;
	}

	return $parentEntry;
}

Here's the first of our two custom methods. As described above, this method figures out the parent of the original entry in the collection's tree.

If the collection doesn't have a tree, we'll just return early.

Otherwise, we'll get the instance of the original entry in the tree, then we'll call the ->parent() method on it.

If the original entry has no parent in the collection tree, we also then just return early.

We then do another check to see if the original entry was the 'root page' in the collection tree (eg. a homepage). If it is, we also just return early as we can't have two root pages 😅.

If we make it this far, we simply return the parent entry.

/**
 * This method has been copied from the Duplicate Entry code in Statamic v2.
 * It's been updated to also deal with entry titles.
 */
protected function generateTitleAndSlug(AnEntry $entry, $attempt = 1)
{
	$title = $entry->get('title');
	$slug = $entry->slug();

	if ($attempt == 1) {
		$title = $title . __('duplicator::messages.duplicated_title');
	}

	if ($attempt !== 1) {
		if (! Str::contains($title, __('duplicator::messages.duplicated_title'))) {
			$title .= __('duplicator::messages.duplicated_title');
		}

		$title .= ' (' . $attempt . ')';
	}

	$slug .= '-' . $attempt;

	// If the slug we've just built already exists, we'll try again, recursively.
	if (Entry::findBySlug($slug, $entry->collection()->handle())) {
		$generate = $this->generateTitleAndSlug($entry, $attempt + 1);

		$title = $generate['title'];
		$slug = $generate['slug'];
	}

	return [
		'title' => $title,
		'slug' => $slug,
	];
}

And here's the second custom method...

This one generates the title & slug for duplicate entries. You might notice that if you duplicate the same entry multiple times, you get titles/slugs like Entry #1, Entry #2, Entry #3. This is the method that figures how many duplicates you've previously made and adjusts the title.

I copied this code from Statamic v2 (it had Duplicator's functionality built into Core).

The first thing this method does is assigns the title & slug of the original entry to variables.

Then, it'll generate a title based on the $attempt variable. So, $attempt being 5 would generate Entry #5.

It then checks if there's any existing entries in the collection with that title. If there is, it calls itself again, and ups the $attempt by 1. It does this until it finds a unique title/slug it can use, which it then returns.

There you go! I've literally given you all the code to build your own Duplicator addon. Hopefully that's been a helpful learning experience for you - diving into how Actions work & how to interact with some of Statamic's internal APIs.

My Documentation Sites: How they work

Sat, 19 Feb 2022 00:00:00 +0000

Last year, I unified the way I handled the docs sites for my addons.

They're all handled by a single Laravel app which pulls in the content from each addon's GitHub repo.

I thought it could be interesting to share how it works...

Get the content from GitHub: If we don't already have the docs content, it'll go grab it using GitHub's zip download feature.

Then, it'll extract the zip and move the docs into their own folder. The images are also moved around, into the 'public' directory.

if (! File::exists($package->clonePath())) {
    $zipContents = file_get_contents($package->archiveUrl());
    file_put_contents("{$package->clonePath()}.zip", $zipContents);

    $zip = new ZipArchive;

    if ($zip->open("{$package->clonePath()}.zip") === true) {
        $zip->extractTo($package->clonePath());
        $zip->close();
    }

    $firstDirectory = File::directories($package->clonePath())[0];
    File::copyDirectory("$firstDirectory/docs", $package->docsPath());

    if (File::exists("$firstDirectory/docs/images")) {
        File::copyDirectory("$firstDirectory/docs/images", public_path("img/{$package->slug}"));
    }
}

Next up, we go and get the file from the directory we just copied them to. If the requested file doesn't exist, we throw a 404.

try {
    $contents = File::get($package->docsPath() . '/' . $path . '.md');
} catch (FileNotFoundException $e) {
    abort(404);
}

Now we have the file contents: it's passed into Commonmark's Markdown converter and piped through some extensions, like Torchlight, a YAML front matter parser and one that handles Markdown tables.

$commonmarkEnvironment = new Environment([
    'heading_permalink' => [
        'symbol' => '',
    ],
    'table_of_contents' => [
        'min_heading_level' => 1,
        'max_heading_level' => 3,
    ],
]);
$commonmarkEnvironment->addExtension(new CommonMarkCoreExtension);
$commonmarkEnvironment->addExtension(new FrontMatterExtension);
$commonmarkEnvironment->addExtension(new TableExtension);
$commonmarkEnvironment->addExtension(new TorchlightExtension);
$commonmarkEnvironment->addExtension(new HeadingPermalinkExtension);
$commonmarkEnvironment->addExtension(new TableOfContentsExtension);

$converter = new MarkdownConverter($commonmarkEnvironment);
$result = $converter->convertToHtml($contents);

Now we have the HTML, it's passed into a Document class, along with some bits of metadata, like the page title & path.

At this point, whatever we returned is sent to the Cache so it's super duper quick for the next user to visit this docs page.

$document = Cache::rememberForever("oxygen.{$package->slug}.$path", function () use ($package, $path) {
    // ...

    return new Document(
        $package,
        array_merge($result->getFrontMatter(), [
            'path' => $path,
        ]),
        $result->getContent()
    );
});

Last but not least..

Whenever I push changes to my addon's on GitHub, a webhook is triggered which clears the cloned files & the Laravel cache for the addon that's been updated.

class GitHubWebhookController extends Controller
{
    public function __invoke(Request $request)
    {
        $payload = $request->all();

        collect(app('oxygen.packages'))
            ->filter(function (Package $package) use ($payload) {
                return $payload['repository']['full_name'] === $package->gitRepo;
            })
            ->filter(function (Package $package) use ($payload) {
                return str_contains($payload['ref'], $package->gitBranch);
            })
            ->each(function (Package $package) {
                info("Webhook: Clearing {$package->slug}");

                File::deleteDirectory($package->clonePath());
                File::delete($package->clonePath().'.zip');

                Cache::flush();
            });

        return new Response();
    }
}

And that's it! Honestly a pretty simple system and I'm pretty happy with it.

You can see it in action over on the Runway docs: https://runway.duncanmcclean.com

Testing with Stripe Elements in Laravel Dusk

Sat, 20 Feb 2021 00:00:00 +0000

Today I've been playing around with using Laravel Dusk to test a payment form on a small website.

The payment form is a key part of the owner's business so it's crucial it works all the time, whenever the customer makes a purchase.

The site uses Stripe Elements to let the customer enter their payment information securely.

Elements creates its own iframe element which makes it a little tricky to target and test. However, there's a handy method in Dusk which allows you to type inside of an iframe.

$this->browse(function ($browser) {
  $browser->type('@input', 'whatever')
    ->withinFrame('.__PrivateStripeElement iframe', function ($browser) {
      $browser
        ->type('[placeholder="Card number"]', '4242424242424242')
        ->type('[placeholder="MM / YY"]', '0923')
        ->type('[placeholder="CVC"]', '123');
    });
});

Anything you need to type inside of Stripe's iframe you can do inside the withinFrame method and target the relevant inputs via their placeholders.

Hopefully someone finds that helpful! 🙂

Hide red bars in Sketch

Sat, 13 Feb 2021 00:00:00 +0000

If you're slicing a design from a designer in Sketch, you may find some horizontal/vertical red bars. Here's a quick little how-to on how to get rid of them.

Go to the Sketch artboard with the red bars
Go to View in the top Sketch menu, in the dropdown, hover over Canvas and then Layout Settings.
You'll see something like this:
Uncheck Columns and Rows, then press Confirm and hey presto, bars are gone!

Install Imagick with Laravel Valet

Thu, 10 Dec 2020 00:00:00 +0000

I'm going to presume you already have Valet and Homebrew setup. To install Imagick, there's a couple of commands you'll need to run:

brew install imagemagick
brew install pkg-config (also if it's already done)
pecl install imagick
valet restart

In case you get a Connection Timeout when visiting one of your Valet sites, you may need to reinstall Valet with valet uninstall && valet install && valet park.

Regaining access to a Laravel Forge server after changing firewall rules

Sat, 28 Nov 2020 00:00:00 +0000

I did something a bit stupid yesterday... I was playing around with Firewall rules on my Forge server. I setup a rule so that the only place I can SSH into my server was from my home IP Address.

However, as soon as I did that, I realised that I could not longer deploy code or do anything via Forge on that server. Then I realised my mistake.... I blocked Forge's IP Address from SSH'ing to my server.

In case someone else finds them in my position, here are the two commands I ran to fix the issue. Of course, you need to SSH to run them.

sudo ufw allow from 159.203.161.246 to any port 22
sudo ufw allow from 159.203.163.240 to any port 22

Forge uses ufw under the hood to manage firewall rules so that's what I used to manually give Forge back control. The two IP addresses I listed in those commands link up to the IP addresses from their documentation.

Simple Commerce has launched!

Sat, 15 Aug 2020 00:00:00 +0000

A few weeks ago today I finally launched the first version of Simple Commerce.

If you've not been following me for very long, Simple Commerce is the e-commerce addon I've been building for Statamic.

If I remember correctly, I started prototyping what Simple Commerce could look like in late November/early December last year (when it was in private alpha) and started working on it properly in January/February time. I even rebuilt the addon about a gazillion times but more about that in a minute.

The story...

I've been in and around the Statamic community for the past few years. In that time, there's been plenty of people who have asked for ways to handle e-commerce in Statamic.

Previously in v1, Jason (who's now one of the Statamic gents) built Bison and in v2, someone built Statamify which has now been archived. If you really wanted to use Statamic for your e-commerce, you could also use Snipcart but it's a separate service.

In November/December of last year, when I was thinking about what I could build to test out addon development in Statamic 3, I tried to think about what I could build that's been widely requested, the first thing that came to mind was e-commerce.

I talked to a few people about it, mainly Erin, who tried to persuade me against it but I went ahead and did it anyway 😂

And so I began.....

Initially I tried building my own version of Statamic's collections system to handle products, orders etc. I inherited some traits and did some other stuff that I didn't really understand. I can't remember how well I got that version working (if I ever did). If you're really interested, feel free to dig through the commit history.

After a couple weeks doing that I think I moved onto using Eloquent instead. It wasn't completely convinced it was a great option but I went with it anyway. My main reasoning behind the switch was "its easier to do relationship stuff and query things. it makes it faster for development". Technically, all of that can be done with Statamic's facades but that's not something I understood how it worked 6 months ago.

The eloquent driven version actually worked quite well. Once it was fairly stable I have access to a few people in the Statamic community so they could give it a try and see the progress I was making. I also refactored & rebuilt the eloquent version many, many times. That's the part that probably took the longest in the whole project.

At the start of June, I decided to set a launch date for getting the Eloquent version out of the door after being in development for the longest time. I set the date for the end of the month. I had everything planned perfectly but then I thought about something....

If someone new is looking at Statamic and thinks "Oh nice, a content management system with no database. That's pretty rad. I wonder if I can build an e-commerce site with it. Looks at Simple Commerce, goes to the install guide. what the chickens?? why do I need a database for a flat-file CMS".

I kept thinking about that for a few days, in the end, I came to a conclusion: I need to rebuilt this with flat files!!

So there I went.... I spent the best part of a month, spending pretty much all of my free time rebuilding this e-commerce addon back into flat-files. But this time instead of rebuilding the collections system, I actually just used the Collections system.

I wanted to make Simple Commerce feel as native to Statamic as possible. Eloquent wasn't native, but collections/entries are. Using pre-built views and controllers wasn't native but just letting users use Statamic Antlers the way they're used to is.

It feels so much better and lightweight now that everything's done 'the Statamic way'.

A few week back I officially launched it but I didn't really make a big deal out of it. I only really announced it on Discord so hopefully this blog post is a better announcement!

There's already a few people trying it out and building sites with it, I really can't wait to see how it grows. If you're interested - feel free to give it a whirl! I've got some plans for it over the next few months but I'm keeping them secret for now 👀

Building a Likes addon in Statamic 3

Tue, 14 Apr 2020 00:00:00 +0000

Recently, I had to build out a help site for a client. One of the features in site was for the user to be able to like help article or forum posts. I managed to build it out reasonably quickly, I think it took me a day to get everything working.

I was thinking that this sort of addon would be a good candidate for building in a blog post. So that's exactly what I've done. It goes through each step of process, from bootstrapping the addon in Statamic's command-line to creating a small little front-end component for likes.

Bootstrapping our addon

The first thing we need to do is bootstrap all the things that we need for our addon. We'll need to create our service provider, setup all the Composer stuff, etc. I'm going to walk you through all of that.

You could always bootstrap your addon by using a boilerplate but we're going to do it from scratch in this tutorial.

To get started, Statamic actually provides a nice please command to get most of the stuff we need up and running. Just do php please make:addon damcclean/likes in your Terminal. Remember to replace damcclean/likes with the Composer package name for your addon.

Once that command has done it's stuff, you should see a new directory popup in your site's root directory. An addons directory. It'll contain two other folders, damcclean and then likes because that's my Composer package name.

In the likes folder, you'll see two things, a composer.json file for your addon and a src/ServiceProvider.php file which is our addon's service provider.

The composer.json file tells Statamic the name of your addon, it's description, the namespace for the Service Provider etc.

And the ServiceProvider.php is the class that tells Statamic what things should be booted up and registered. Whether that be routes or commands or middlewares, that's where they all get registered. We'll come back to this file later on in the tutorial.

We now have a Statamic addon running from addons/damcclean/likes. 🎉 Well Done us!!

Setting up our tests

I don't know about you but when I'm writing addons or any sort of backend code, I like to write tests to check that my code works and it returns what I want it to return.

You could always do your testing manually but I like to automate it. Laravel, the framework that sits behind Statamic, uses a testing framework called PHPUnit.

PHPUnit is the testing framework we're going to pull in, in a minute. We're also gonna pull in a thing called Orchestra Testbench. Testbench sits on top of PHPUnit and provides helper functionality for building Laravel packages. (if you've not guessed it already, a Statamic addon is a Laravel package)

Anyway, to install PHPUnit and Testbench, run this command inside your addon's directory. likes in my case.

composer require --dev orchestra/testbench phpunit/phpunit

After that command has done it's thing, you'll see some more files popup. You'll see a composer.lock file which you can ignore, and you'll see a vendor directory. In case your new to Composer, the vendor directory is where all of the Composer dependencies are installed. In our case, those dependencies are Testbench, PHPUnit and all of the other packages they require to run.

If you're planning on setting up a Git repository for this project, you're gonna want to ignore that vendor directory. It's never a good idea to keep those sort of things in Git (except in Statamic 2, but that's away from the point).

To do that, just create a .gitignore file and add the folder name.

// .gitignore
vendor

Also, you're going to want to install Statamic inside your addon's composer file too, so your test suite can take advantage of Statamic things.

Before you can just install it, you'll need to lower your minimum stability level for dependencies, which is easy enough to do in your composer.json file.

{
	...
	"minimum-stability": "dev"
}

And then you can require statamic into your addon with composer require statamic/cms.

Now, we need to setup our PHPUnit configuration file. You should create a file called phpunit.xml in your addon's root directory. I've also included the contents of the config file.

<?xml version="1.0" encoding="UTF-8"?>
<phpunit backupGlobals="false"
         backupStaticAttributes="false"
         bootstrap="vendor/autoload.php"
         colors="true"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true"
         processIsolation="false"
         stopOnFailure="false">
    <testsuites>
        <testsuite name="Test Suite">
            <directory suffix="Test.php">./tests</directory>
        </testsuite>
    </testsuites>
    <filter>
        <whitelist processUncoveredFilesFromWhitelist="true">
            <directory suffix=".php">./app</directory>
        </whitelist>
    </filter>
    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="APP_KEY" value="base64:xRIcDp1ReW8Y8rd9V9D7hOVV4TI7ThCF3FKxRg01Rm8="/>
        <env name="CACHE_DRIVER" value="array"/>
        <env name="SESSION_DRIVER" value="array"/>
        <env name="QUEUE_DRIVER" value="sync"/>
        <env name="MAIL_DRIVER" value="array"/>
    </php>
</phpunit>

Next, we need to create the directory where all of our tests are going to live. Just call it tests and put it alongside the src folder in your addon's root directory.

Now that we have tests folder, we'll need to create two files.

The first of which is our Test Case. The TestCase is a class that will be extended by each of your tests to tell it how to run Statamic, how to run your addon, etc. Just create a file called TestCase.php in your tests folder with the following contents.

<?php

namespace Damcclean\Likes\Tests;

use Statamic\Facades\Entry;
use Statamic\Facades\Collection;
use Statamic\Extend\Manifest;
use Orchestra\Testbench\TestCase as OrchestraTestCase;
use Damcclean\Likes\ServiceProvider;
use Statamic\Providers\StatamicServiceProvider;
use Statamic\Statamic;
use Statamic\Facades\User;
use Illuminate\Foundation\Testing\WithFaker;

abstract class TestCase extends OrchestraTestCase
{
    use WithFaker;

    protected function getPackageProviders($app)
    {
        return [
            StatamicServiceProvider::class,
            ServiceProvider::class,
        ];
    }

    protected function getPackageAliases($app)
    {
        return [
            'Statamic' => Statamic::class,
        ];
    }

    protected function getEnvironmentSetUp($app)
    {
        parent::getEnvironmentSetUp($app);

        $app->make(Manifest::class)->manifest = [
            'damcclean/likes' => [
                'id' => 'damcclean/likes',
                'namespace' => 'Damcclean\\Likes\\',
            ],
        ];

        Statamic::pushActionRoutes(function() {
            return require_once realpath(__DIR__.'/../routes/actions.php');
        });
    }

    protected function resolveApplicationConfiguration($app)
    {
        parent::resolveApplicationConfiguration($app);

        $configs = [
            'assets', 'cp', 'forms', 'static_caching',
            'sites', 'stache', 'system', 'users'
        ];

        foreach ($configs as $config) {
            $app['config']->set("statamic.$config", require(__DIR__."/../vendor/statamic/cms/config/{$config}.php"));
        }

        $app['config']->set('statamic.users.repository', 'file');
        $app['config']->set('statamic.stache', require(__DIR__.'/__fixtures__/config/statamic/stache.php'));
    }

    protected function makeUser()
    {
        return User::make()
            ->id((new \Statamic\Stache\Stache())->generateId())
            ->email($this->faker->email)
            ->save();
    }

    protected function makeCollection(string $handle, string $name)
    {
        Collection::make($handle)
            ->title($name)
            ->pastDateBehavior('public')
            ->futureDateBehavior('private')
            ->save();

        return Collection::findByHandle($handle);
    }

    protected function makeEntry(string $collectionHandle)
    {
        $slug = $this->faker->slug;

        Entry::make()
            ->collection($collectionHandle)
            ->blueprint('default')
            ->locale('default')
            ->published(true)
            ->slug($slug)
            ->data([
                'likes' => [],
            ])
            ->set('updated_by', User::all()->first()->id())
            ->set('updated_at', now()->timestamp)
            ->save();

        return Entry::findBySlug($slug, $collectionHandle);
    }
}

Most of that should just be a simple copy paste job, but there's one thing you'll need to adapt to make it work for your addon. In the getEnvironmentSetup function, you'll need to change Damcclean\Likes to your own package name.

Also, we'll need to let Composer know about our testing namespace, to do that, just add this to your addon's composer.json file.

"autoload-dev": {
	"psr-4": {
		"DoubleThreeDigital\\SimpleCommerce\\Tests\\": "tests"
	},
	"classmap": [
		"tests/TestCase.php"
  	]
},

Just to be sure, you might also want to run composer dump-autoload to make sure it picks the new namespace up.

Later on in this tutorial, we'll be running tests with real collections and entries, so there's some stuff we'll want to setup to fake that. First, create some folders:

tests/__fixtures__/config/statamic
tests/__fixtures__/content
tests/__fixtures__/users

You'll probably also want to add some more things to your addon's Gitignore file.

// .gitignore

vendor
tests/__fixtures__/users/*.yaml
tests/__fixtures__/content/*.yaml

As well, you'll want to create a stache.php file inside your fixtures/config/statamic folder. This file will be used in testing to override the default Stache config, basically just telling Statamic to use the directories we just created to store our content and users.

<?php

use Statamic\Stache\Stores;

return [

    /*
    |--------------------------------------------------------------------------
    | File Watcher
    |--------------------------------------------------------------------------
    |
    | File changes will be noticed and data will be updated accordingly.
    | This can be disabled to reduce overhead, but you will need to
    | either update the cache manually or use the Control Panel.
    |
    */

    'watcher' => true,

    /*
    |--------------------------------------------------------------------------
    | Stores
    |--------------------------------------------------------------------------
    |
    | Here you may configure which stores are used inside the Stache.
    |
    */

    'stores' => [

        'taxonomies' => [
            'class' => Stores\TaxonomiesStore::class,
            'directory' => base_path('content/taxonomies'),
        ],

        'terms' => [
            'class' => Stores\TermsStore::class,
            'directory' => base_path('content/taxonomies'),
        ],

        'collections' => [
            'class' => Stores\CollectionsStore::class,
            'directory' => __DIR__.'/../../content/collections',
        ],

        'entries' => [
            'class' => Stores\EntriesStore::class,
            'directory' => __DIR__.'/../../content/collections',
        ],

        'navigation' => [
            'class' => Stores\NavigationStore::class,
            'directory' => base_path('content/navigation'),
        ],

        'globals' => [
            'class' => Stores\GlobalsStore::class,
            'directory' => base_path('content/globals'),
        ],

        'asset-containers' => [
            'class' => Stores\AssetContainersStore::class,
            'directory' => base_path('content/assets'),
        ],

        'users' => [
            'class' => Stores\UsersStore::class,
            'directory' => __DIR__.'/../../users',
        ],

    ],

    /*
    |--------------------------------------------------------------------------
    | Indexes
    |--------------------------------------------------------------------------
    |
    | Here you may define any additional indexes that will be inherited
    | by each store in the Stache. You may also define indexes on a
    | per-store level by adding an "indexes" key to its config.
    |
    */

    'indexes' => [
        //
    ],

];

There we go! We've setup our test suite so it's all ready to go!

Writing some real code...

In order for users to like things on the site, we'll need to create a few things. We'll need to create a field where user IDs will be stored, we'll need to create a controller where the like/dislike submissions will go and we'll need to create some sort of front-end component that can send data to that controller.

OK, so let's take one thing at a time, starting with the field I was talking about. The easiest way to do any sort of content work is through the Control Panel. So just login to the CP, go to the blueprint where you want to use likes, and add a field.

You'll want to add a Users field because it allows us to store a list of Statamic user IDs, which we'll need to tell who has liked the entry.

Make sure to change the Max Items setting on the field so that it can store more than 1 user's ID.

Now that we've got the field in our blueprint, we need to create some controllers to do the legwork of actually liking and unliking entries.

In your addon's folder, addon/yourname/packagename, create a folder structure like this, src/Http/Controllers. In the Controllers folder you'll want to create a controller, you can call it whatever you want but I'll call mine LikeController.

My LikeController is going to have two methods, a store method which will be hit whenever a user likes an entry and a destroy method which will be hit whenever a user unlikes an entry.

<?php

namespace Damcclean\Likes\Http\Controllers;

class LikeController
{
    public function store()
    {
        //
    }

    public function destroy()
    {
        //
    }
}

Now we've got the methods, let's make them do something! I'm going to start with the store method.

So when someone makes a request to the controller, we want to know two things: the currently logged in user and the ID of the entry the user liked.

To do this, we're going to add the Request $request and the $id as method parameters.

Oh and by the way, Request is Illuminate\Http\Request

Next we're going to want to get an instance of the entry from the ID because the ID is just a randomly generated string. We can do that by calling the Entry facade, provided by Statamic, and it's find function.

public function store(Request $request, $id)
{
	$entry = Entry::find($id);
}

Next, we'll want to grab all of the likes the entry currently has and we'll want to add the logged in user's ID to that list.

In the code you can see below, we create the $likes variable, we check if there are any likes on entry at the moment, if yes, we use them, if not we just set an empty array.

We also go ahead and merge in the ID of the currently logged in user to that array.

public function store(Request $request, $id)
{
	$entry = Entry::find($id);

	$likes = $entry->value('likes') ?? [];
	$likes = array_merge($likes, [$request->user()->id()]);
}

Now all that's left for us to do is save the updated likes array back to entry file, which is as easy as pie.

public function store(Request $request, $id)
{
	$entry = Entry::find($id);

	$likes = $entry->value('likes') ?? [];
	$likes = array_merge($likes, [$request->user()->id()]);

	$entry->fromWorkingCopy()
		->set('likes', $likes)
		->save();

	return back();
}

I've returned went ahead and returned the user back to the page they came from, but that's up to you.

So we're done with the store method, now let's jump onto the destroy method which removes the users' like from the entry.

Again, we're going to use the Request $request and the $id as method parameters. We're also going to need to find the entry as well.

public function destroy(Request $request, $id)
{
	$entry = Entry::find($id);
}

Next we just want to remove the currently logged user's like from the array of likes and then save the entry. The way I'm going to handle it is by using Laravel's collect method, going through each of likes, removing the one with the user's ID and then outputting a fresh array.

public function destroy(Request $request, $id)
{
	$entry = Entry::find($id);

	$likes = collect($entry->data()->toArray()['likes'])
		->reject($request->user()->id())
        ->all();

  	$entry
		->fromWorkingCopy()
		->set('likes', $likes)
		->save();

	return back();
}

That's really all we need for the controllers. Next we need to create routes so the controller method can actually be hit from the web.

We're going to create Action routes, which means the URLs will look like this /!/likes/like and /!/likes/dislike.

We're going to need a routes file, create a routes folder in your addon's root and then create an actions.php file. This file will hold our addon's routes.

Your entire routes file only needs to be three lines long.

<?php

Route::post('/like/{id}', '\Damcclean\Likes\Http\Controllers\LikeController@store')->name('like');
Route::post('/dislike/{id}', '\Damcclean\Likes\Http\Controllers\LikeController@destroy')->name('dislike');

Sadly, Statamic doesn't register these routes automatically, so we'll need to go and register them in our addon's ServiceProvider.

Registering things in your service provider is actually incredibly easy. I'll just explain how you do it for routes, but it's pretty much the same thing for registering fieldtypes, tags, widgets, modifiers, etc, you get the gist.

protected $routes = [
	'actions' => __DIR__.'/../routes/actions.php',
];

As long as you've setup everything the same way I have, that should just work.

And the front-end

The backend code is all done, but we still need to actually build out the front-end so users can actually like/dislike entries.

In this example I'm going to build out a simple like/dislike thing in Antlers but there's no reason you couldn't use a Vue component or something along those lines to do it. There's no wrong answers.

I made my likes 'component' into a nice Antlers partial that displays a count of how many people have liked the entry and buttons to like/dislike depending on if the user has already liked the entry or not.

<div class="flex flex-row items-center my-6">
    <span class="mr-4">{{ likes | count }} likes</span>

  	{{ if logged_in }}
	  {{ user }}
		  {{ if (likes | to_json | contains:id) }}
			  <form class="inline-block mr-4" action="/!/likes/dislike/{{ page:id }}" method="post">
				  {{ csrf_field }}
				  <button class="font-semibold text-red-600">Dislike</button>
			  </form>
		  {{ else }}
			  <form class="inline-block mr-4" action="/!/likes/like/{{ page:id }}" method="post">
				  {{ csrf_field }}
				  <button class="font-semibold text-green-600">Like</button>
			  </form>
		  {{ /if }}
	  {{ /user }}
  	{{ /if }}
</div>

(yes I know the above code snippet is broken, here's a Github Gist of what it's meant to look like)

If you look at the code for the two forms. They are the endpoints that point to our controller actions that we made earlier.

Finally, let's write some tests

We setup PHPUnit and Orchestra Testbench earlier in this tutorial but we still need to write some actual tests so that we can know for sure that our controller code does exactly what we want it to.

We're going to write a few tests. One test to make sure that we can like an entry and one to make sure we can dislike one. We're going to need a file for our tests, I'm just going to call mine LikeControllerTest.php and place it in my addon's tests directory.

To get us started, I've made a quick scaffolding of the class.

<?php

namespace Damcclean\Likes\Tests;

class LikeControllerTest extends TestCase
{
    /** @test */
    public function can_store_like()
    {
        //
    }

    /** @test */
    public function can_destroy_like()
    {
        //
    }
}

I usually use /** @test */ above my test methods but if that feels weird to you just add test_ in front of the method names, like test_can_store_like.

Let's start writing our first test. Before writing the test, we need to think about what we need to setup, what we need to do to run the code and what we need to do to make sure the code did its job.

What we need to setup: a user, a collection and an entry

What we need to do to run the code: hit the action route

What we need to do to make sure the code did its job: make sure the user's ID is inside of the entry's file

Let's start with the setup! We're going to setup our user, our collection and our entry with some helper methods I built into the TestCase you copied in earlier, just to make the process nice and easy.

$user = $this->makeUser();
$collection = $this->makeCollection('articles', 'Articles');
$entry = $this->makeEntry('articles');

Next, we'll want to hit the route that goes to the controller. Laravel provides quite a lot of HTTP testing stuff out of the box, so there's nothing custom needing done here.

$this
	->actingAs($user)
	->post(route('statamic.like', ['id' => $entry->id()]))
	->assertRedirect();

Basically what we're doing there is logging in as the user we just created, making a POST request to our Like route with the ID of the entry and we're asserting that we get a redirect status code back.

Heads up: Be sure to change the assertRedirect assertion to something else if you didn't return a redirect in your controller.

The last thing we want to check is that the user's ID has been added to the likes array of the entry. To do this we're going to get an updated instance of the Entry and we're going to do a quick check against the likes array.

$updatedEntry = Entry::find($entry->id());
$this->assertStringContainsString($user->id(), json_encode($updatedEntry->value('likes')));

You should end up with this in the end:

/** @test */
public function can_store_like()
{
	$user = $this->makeUser();
	$collection = $this->makeCollection('articles', 'Articles');
	$entry = $this->makeEntry('articles');

	$this
		->actingAs($user)
		->post(route('statamic.like', ['id' => $entry->id()]))
		->assertRedirect();

	$updatedEntry = Entry::find($entry->id());
	$this->assertStringContainsString($user->id(), json_encode($updatedEntry->value('likes')));
}

Now onto our test to make sure a user can dislike an entry. Before writing the test, I'm going to think about what I need to setup, what code I need to run and how I can check the code has worked correctly.

What we need to setup: a user, a collection and an entry where the user's ID is in the likes array

What we need to do to run the code: hit the action route

What we need to do to make sure the code did its job: make sure the user's ID is not inside of the entry's file

This test is pretty much identical to the last one, except from the fact we need to include the users ID in the likes array during setup and we need to check the user's ID is not in the likes array at the end.

So after we've created the entry, we just need to do the same sort of thing we did in the controller to add the user's ID to likes array.

$entry
	->fromWorkingCopy()
	->set('likes', [$user->id()])
	->save();

And then at the end when we asserted that the likes array in the entry contains the User ID, we just want to do the opposite so we use assertStringNotContainsString.

$this->assertStringNotContainsString($user->id(), json_encode($updatedEntry->value('likes')));

So in full, the delete test should look a little like this:

/** @test */
public function can_destroy_like()
{
	$user = $this->makeUser();
	$collection = $this->makeCollection('articles', 'Articles');
	$entry = $this->makeEntry('articles');

	$entry
		->fromWorkingCopy()
		->set('likes', [$user->id()])
		->save();

	$this
		->actingAs($user)
		->post(route('statamic.dislike', ['id' => $entry->id()]))
		->assertRedirect();

	$updatedEntry = Entry::find($entry->id());
	$this->assertStringNotContainsString($user->id(), json_encode($updatedEntry->value('likes')));
}

And then if you go into your addon's root directory in your Terminal and if you run ./vendor/bin/phpunit, you should get some green text, like this:

That's it! You've built a likes addon, with a fully working test suite. You should be proud of yourself!

Hopefully this tutorial was clear enough for you to understand, if you have any questions, ping me on the Statamic discord and I'll try to help

Big thanks to Jason Varga for proof reading this for me!

Move S3 objects from one AWS account to another

Sat, 11 Apr 2020 00:00:00 +0000

I'm in the process of moving all of my AWS stuff into it's own account, separated from my online shopping account. It's a process that has to be done manually as AWS don't have an easy way of moving resources between accounts.

Anyway, to stop you trolling through Amazon's horrible documentation to get this ugly job done. Here's some simple instructions on moving files between buckets and AWS accounts.

In the AWS account you want to move stuff to, create a new bucket, sadly it'll need a unique name that's not used by your current bucket.
Get the AWS account ID of your new AWS account (the one you wish to move stuff to). You can find it in your 'My Account' page.
Update the bucket policy in the old bucket (old AWS account) to this. Replace ACCOUNT_ID with your new AWS account's ID and replace awsexamplesourcebucket with the name of the old bucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DelegateS3Access",
            "Effect": "Allow",
            "Principal": {"AWS": "ACCOUNT_ID"},
            "Action": ["s3:ListBucket","s3:GetObject"],
            "Resource": [
                "arn:aws:s3:::awsexamplesourcebucket/*",
                "arn:aws:s3:::awsexamplesourcebucket"
            ]
        }
    ]
}

Then you'll want to install the AWS CLI, if you haven't already and configure it for your new AWS account.
Then you should be able to run the following command, replacing the obvious. If you did everything right, that command should copy everything over to your new bucket.

aws s3 sync s3://old-bucket-name s3://new-bucket-name --copy-props

Setting up for Statamic addon development

Sun, 19 Jan 2020 00:00:00 +0000

The Statamic 3 beta has been out since the middle of November if I can remember correctly. V3 basically turns it into a package for Laravel rather than a pre-built Laravel app. This is the change which allows for Statamic add ons to finally become Laravel packages.

I’m gonna quickly give you a walk through of how you get started building an addon, including setting up the environment.

Just figured out that you can skip this whole manual process, all you need to do is run php please make:addon damcclean/github-gists. Obviously you can replace the package name with your own.

I’m going on the assumption that you already have v3 installed on your site. If not its only a composer command away.

Anyways, firstly you want to create the folder structure of where you want your addon to live.

So for example - if you wanted to create an addon called GithubGists and your Github username was damcclean, then your folder structure could look like this:

├─ addons
│  ├─ damcclean
│  │  └─ GithubGists
│  │     └─ src

Obviously you can create the folder structure in whatever way you want but this is the recommended way to do it, from what I can gather.

In your terminal, navigate to inside of your GithubGists folder (or whatever you called it) and run composer init. It’ll lead you through a wizard. When it asks you for a package type, type in statamic-addon. This will let Statamic know that your package will be a Statamic addon.

Then you can open your addon's composer.json file to make a few changes.

You’ll want to add in this snippet. It’ll let composer know where to load in your namespace from. In my code, I’m loading in the Damcclean\GithubGists namespace from my src folder.

"autoload": {
    "psr-4": {
        "Damcclean\\GithubGists\\": "src"
    }
},

This next bit of code does two things. It lets Statamic know the name and description of the addon, so it can display it inside the Control Panel. And then the second bit talks to Laravel to tell where the Service Provider is, we’ll get round to actually creating this in a bit.

"extra": {
	"statamic": {
		"name": "Github Gists",
		"description": "Awesome addon to display Github gists on your website."
	},
	"laravel": {
		"providers": [
			"Damcclean\\GithubGists\\ServiceProvider"
		]
	}
},

I think that’s pretty much it for composer.json. Next we can create our service provider.

I’d recommend just calling it ServiceProvider and putting it in the src directory. That’s the way most people do it.

For those of you who are new to the concept of service providers, it’s basically a class that Laravel goes to where you call everything you need to make your addon work.

So your routes would be registered in your service provider, so would your widgets, your tags etc.

In your service provider, you need to extend the AddonServiceProvider class and have two methods, boot and register.

namespace Damcclean\GithubGists;

use Statamic\Providers\AddonServiceProvider;

class ServiceProvider extends AddonServiceProvider
{
	public function boot()
	{
		parent::boot();
	}

	public function register()
	{
		parent::register();
	}
}

Now we’re almost done!! The next thing is to actually install our addon in our Statamic site.

So for that, in your main composer.json, add in the name of your package to the require section. Also, just add dev-master as the version.

"require": {
	"damcclean/github-gists": "dev-master"
},

Just so it knows where your project lives, as its not live on Composer, you’ll need to add it as a repository which is pretty easy, just add this code to the bottom of the same file. Obviously changing out the folder names etc for the ones you have setup.

"repositories": [
	{
		"type": "path",
		"url": "addons/damcclean/GithubGists"
	}
]

After that, just run composer install in your project’s root directory and you’ll be as good to go.

How to Force Remove Service Worker from Chrome

Wed, 06 Nov 2019 00:00:00 +0000

So I recently created a service worker for one of my apps so I could turn it into a Progressive Web App.

Although, for some reason I was under the impression that I should cache the main page of my app. I later realised that it was a very bad idea.

I think I'm the only user of the site that came across this issue before I patched it but I found it quite a pain to unregister the service worker and bust it's cache so I could get the latest version of the page from the server.

I had to do this process on both my MacBook and on my Android phone, so here's both of those processes:

Chrome on the MacBook

The first thing to do is to open up Developer Tools and head to the 'Application' tab. In there it has its own little sidebar. Go to the 'Service worker' part of that. There it should give you the option of 'Unregistering' your service worker. Click on that link and also go and clear the whole site's cache because why not.

Chrome on the Android phone

The first thing to do is to go to the site, tap on the site's security padlock (or warning sign ⚠️) and tap on Site settings. Then tap on Clear & reset. Then just refresh the page and you should be good to go!