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

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.

Update in February 2025: As with any software project, things take longer than you originally expect.
I'm hoping to have an alpha/beta out at some point in the coming weeks, then I'm aiming to properly release the new version alongside Statamic 6.

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.

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:

1. Install Laravel Herd if you haven't already.

2. 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).

3. 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

4. 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".

5. 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).

6. 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.

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.

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);
    }
}

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.

It looks like Mastodon seems to be the Twitter replacement for lots of Laravel/PHP folks. After seeing Freek's post about Laravel & PHP developers to follow on Mastodon, I thought I'd make an additional list for Statamic developers to follow on Mastodon.

If you want to be featured on this list, reply to my Tweet or post on Mastodon and I'll get you added. I know I've probably missed some people.

• Joshua Blum: joshuablum@mastodon.social
• Rob de Kort: robdekort@mastodon.social
• Erin Dalzell: emd@mastodon.social
• Dave Smyth: davesmyth@mastodon.social
• Me: duncanmcclean@mastodon.social
• Jack Sleight: jacksleight@mastodon.social
• Ryan Mitchell: ryanmitchell@mastodon.social
• David Lindahl: Austriker@mstdn.io
• Marty Friedel: martyfriedel@mastodon.au
• Rias Van der Veken: rias@phpc.social
• ncla: ncla@mastodon.social
• Johannes Schuba: joschuba@mastodon.social
• Simon Schweissinger: simonolog@mstdn.social
• Konafets: Konafets@norden.social
• klickreflex: klickreflex@freiburg.social

There's a bunch of different Mastodon "servers" - you can signup for any of them really & you can follow people from different servers. I'm on mastodon.social (a popular one) but there's also other options like mastodon.cloud, mstdn.social and phpc.social.

Justin Jackson has written a post if you're interested in getting started with Mastodon.

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. 🚀

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.

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...

1. 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}"));
    }
}

2. 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);
}

3. 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);

4. 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()
    );
});

5. 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

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! 🙂

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

• 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.

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.

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 👀

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')));
}