DEV Community: Freek Van der Herten

A walkthrough of Laravel Backup Server

Freek Van der Herten — Mon, 04 May 2020 12:17:25 +0000

In this stream (which is the first I've ever done) I'll show you what you can do with our upcoming laravel-backup-server package and how it works under the hood.

Building a realtime dashboard powered by Laravel, Livewire and Tailwind (2020 edition)

Freek Van der Herten — Mon, 04 May 2020 12:16:29 +0000

At Spatie we have a TV screen against the wall that displays a dashboard. This dashboard displays the tasks our team should be working on, important events in the near future, which tasks each of our team members should be working on, what music they are listening to, and so on. Here's what it looks like:

This dashboard is built using our laravel-dashboard package. It will allow you to built a similar dashboard in no time.

In this blogpost I'd like to walk you through both the dashboard and the package.

History

We've had a dashboard at Spatie for quite some time now. Before our current Laravel-based one we used Dashing, a framework to quickly build dashboards. The framework was created by the folks at Shopify and uses Ruby under the hood.

When I first built our dashboard, a few years ago, we were at a crossroads with our company. There wasn't much momentum in the PHP world and we were toying with the idea of switching over to Ruby. The idea was that by playing with Dashing we would get some experience with the language. Then Composer and Laravel happened and we decided to stick with PHP (and given the current state of PHP ecosystem we don't regret that choice at all).

When support for Dashing had officially stopped in 2016, I thought it was a good time to completely rebuild the dashboard using Laravel and Vue.

Every year, my team I iterated further on the dashboard. It gained some more tiles, support for Laravel Echo was added. a cleaner layout powered by Tailwind,...

The dashboard always made as a complete Laravel app. In the back of my mind I always had the plan to make the core dashboard and individual tiles available as packages. The big hurdle to take was that the stack is kinda complicated: in order to create a tile we'd need PHP classes to fetch data, create events, and have Vue component to display stuff.

This year we moved away from WebSocket and Vue in favour of Laravel Livewire. Using Livewire has some drawbacks, but a big advantage is that packaging up tiles now is much simpler. Instead of one big Laravel app, the dashboard no consist of a core package and a collection a tile packages.

The tiles

Let's take a closer look at what the dashboard is displaying. The configured dashboard from the above screenshot has the following tiles:

A Twitter tile that shows all mentions of quotes of @spatie_be. Under the hood this is powered by our Twitter Labs package.
There's a dedicated tile for each member of our team. Each tile displays the tasks for that member for the current week. Those tasks are fetched from a few markdown files in a private repo on GitHub. There's a little bit more to this tile. More on that later.
Some statistics of our numerous public repositories on GitHub. This data is coming from the GitHub and the Packagist API
A team calendar that pulls in events from a Google Calendar.
A clock with the current date. and some weather conditions, retrieved from the Open Weather Map API.
In our home city, Antwerp, there is a shared biking system called Velo. The bike tile shows how many bikes there are available in the nearest bike points near our office.

To help everyone to stay "in the zone" we bought the entire team Bose QuietComfort headphones. The dashboard displays the current track for each team member on his team member tile. The avatar will be replaced by the artwork of the album. We leverage the API of last.fm to get this info.

The team member tile will also display a little crown when it's someone's birthday?

With the ongoing Corona pandemic our team works 100% remotely. In normal times team members also regularly work from home. When not working in the office for a day we have the habit of setting our status in Slack to "Working from home". When a team member sets that status in Slack we'll display a nice little tent emoji.

High level overview

After the browser displays the dashboard for the first time we'll never refresh the page again. Livewire is used to refresh the tiles. Doing it this way will avoid having to refresh the page and in turn, avoid flashing screens.

Most tiles consist of these functionalities:

an artisan command that fetches data and stores it somewhere. The artisan commands should be scheduled so that data is fetched periodically.
a Livewire component: this class accepts various props that can be used to configure the tile. It should at least accept a position prop. Livewire components can re-render themselves. Livewire does this by re-rendering the html on the server and update the changed parts in the DOM using morphdom.
a Blade view to render the component.

The base laravel-dashboard package provides a Tile model that tiles can use to store data. Using the Tile model isn't required, tiles can choose themselves how they store and retrieve data.

A tile is entirely written in PHP. This makes it easy to create new tiles. It's also easy to package up tiles. Nearly all our tiles are available as packages:

Time and Weather: displays the current time and weather at your location
Calendar: displays events that are on a Google Calendar
Twitter: displays mentions on Twitter
Oh Dear Uptime: displays sites that are detected as down by Oh Dear
Belgian Trains: displays real-time info on Belgian trains
Velo: displays the status of Velo, the Antwerp bike sharing system.

Creating a dashboard and positioning tiles

Our company dashboard, which you can find in this repo, is a Laravel app which makes use of laravel-dashboard package. A dashboard is simply a route that points to a view.

// in routes/web.php

Route::view('/', 'dashboard');

Here's the content of the dashboard, slightly redacted for brevity.

<x-dashboard>
    <livewire:twitter-tile position="a1:a14" />

    <livewire:team-member-tile
        position="b1:b8"
        name="adriaan"
        :avatar="gravatar('adriaan@spatie.be')"
        birthday="1995-10-22"
    />

    <livewire:team-member-tile
        name="freek"
        :avatar="gravatar('freek@spatie.be')"
        birthday="1979-09-22"
        position="b9:b16"
    />

    {{-- other tile members removed for brevity --}}

    <livewire:calendar-tile position="e7:e16" :calendar-id="config('google-calendar.calendar_id')" />

    <livewire:velo-tile position="e17:e24" />

    <livewire:statistics-tile position="a15:a24" />

    <livewire:belgian-trains-tile position="a1:a24"/>

    <livewire:oh-dear-uptime-tile position="e7:e16" />

    <livewire:time-weather-tile position="e1:e6" />
</x-dashboard>

This view is quite simple. You have to use the x-dashboard Blade component. Behind the scenes, this component will pull in all necessary css and JavaScript used by Livewire.

Inside x-dashboard you can use a livewire tile component.

A tile can be positioned by passing coordinates to the position prop.

You should image the dashboard as an excel like layout. The columns are represented by letters, the rows by number. You can pass a single position like a1. The first letter, a, represent the first column. The 1 represents the first row. You an also pass ranges. Here are a few examples.

a1: display the tile in the top left corner
b2: display a tile in the second row of the second column
a1:a3: display a tile over the three first rows of the first column
b1:c2: display the tile as a square starting at the first row of the second column to the second row of the third column

The dashboard is being rendered using css grid. Behind the scenes, these coordinates will be converted to grid classes. The grid will grow automatically. If a c is the "highest" letter used on the dashboard, it will have 3 columns, if a e is used on any tile, the dashboard will have 5 columns. The same applies with the rows.

The calendar tile

Now that you know how the dashboard works in broad lines, let's go in details how some of the tiles work.

Here is how the calendar tile looks like.

To fetch data, this tile uses our google-calendar package.

Here is the command that fetches the data:

namespace Spatie\CalendarTile;

use Carbon\Carbon;
use DateTime;
use Illuminate\Console\Command;
use Spatie\GoogleCalendar\Event;

class FetchCalendarEventsCommand extends Command
{
    protected $signature = 'dashboard:fetch-calendar-events';

    protected $description = 'Fetch events from a Google Calendar';

    public function handle()
    {
        $this->info('Fetching calendar events...');

        foreach (config('dashboard.tiles.calendar.ids') ?? [] as $calendarId) {
            $events = collect(Event::get(null, null, [], $calendarId))
                ->map(function (Event $event) {
                    $sortDate = $event->getSortDate();

                    return [
                        'name' => $event->name,
                        'date' => Carbon::createFromFormat('Y-m-d H:i:s', $sortDate)->format(DateTime::ATOM),
                    ];
                })
                ->unique('name')
                ->toArray();

            CalendarStore::make()->setEventsForCalendarId($events, config('google-calendar.calendar_id'));
        }

        $this->info('All done!');
    }
}

Most of the tiles that we create also have a Store class. This store class is responsible for storing and retrieving data. When retrieving the data, it also formats it so it's easily consumable for the component.

namespace Spatie\CalendarTile;

use Carbon\Carbon;
use Illuminate\Support\Collection;
use Spatie\Dashboard\Models\Tile;

class CalendarStore
{
    private Tile $tile;

    public static function make()
    {
        return new static();
    }

    public function __construct()
    {
        $this->tile = Tile::firstOrCreateForName('calendar');
    }

    public function setEventsForCalendarId(array $events, string $calendarId): self
    {
        $this->tile->putData('events_' . $calendarId, $events);

        return $this;
    }

    public function eventsForCalendarId(string $calendarId): Collection
    {
        return collect($this->tile->getData('events_' . $calendarId) ?? [])
            ->map(function (array $event) {
                $carbon = Carbon::createFromTimeString($event['date']);

                $event['date'] = $carbon;
                $event['withinWeek'] = $event['date']->diffInDays() < 7;
                $event['presentableDate'] = $this->getPresentableDate($carbon);

                return $event;
            });
    }

    public function getPresentableDate(Carbon $carbon): string
    {
        if ($carbon->isToday()) {
            return 'Today';
        }

        if ($carbon->isTomorrow()) {
            return 'Tomorrow';
        }

        if ($carbon->diffInDays() < 8) {
            return "In {$carbon->diffInDays()} days";
        }

        if ($carbon->diffInDays() <= 14) {
            return "Next week";
        }

        $dateFormat = config('dashboard.tiles.calendar.date_format') ?? 'd.m.Y';

        return $carbon->format($dateFormat);
    }
}

If you are not as pragmatic as I am, add are a devout follower of the Single Responsibility principle, you can move the responsibilities to separate classes.

The events in the store are retrieved by the CalendarTileComponent which is a Livewire component

namespace Spatie\CalendarTile;

use Livewire\Component;

class CalendarTileComponent extends Component
{
    /** @var string */
    public $calendarId;

    /** @var string */
    public $position;

    /** @var string|null */
    public $title;

    /** @var int */
    public $refreshInSeconds;

    public function mount(string $calendarId, string $position, ?string $title = null, int $refreshInSeconds = 60)
    {
        $this->calendarId = $calendarId;

        $this->position = $position;

        $this->title = $title;

        $this->refreshInSeconds = $refreshInSeconds;
    }

    public function render()
    {
        return view('dashboard-calendar-tile::tile', [
            'events' => CalendarStore::make()->eventsForCalendarId($this->calendarId),
            'refreshIntervalInSeconds' => config('dashboard.tiles.calendar.refresh_interval_in_seconds') ?? 60,
        ]);
    }
}

This component accepts the calendar id of which the events should be displayed. It also accepts the position where the title should be displayed, a title, and a frequency at which the component should be re-rendered.

Next, let's take a look at the Blade view.

<x-dashboard-tile :position="$position" :refresh-interval="$refreshIntervalInSeconds">
    <div class="grid {{ isset($title) ? 'grid-rows-auto-auto gap-2' : '' }} h-full">
        @isset($title)
            <h1 class="uppercase font-bold">
                {{ $title }}
            </h1>
        @endisset

        <ul class="self-center divide-y-2 divide-canvas">
            @foreach($events as $event)
                <li class="py-1">
                    <div class="my-2">
                        <div class="{{ $event['withinWeek'] ? 'font-bold' : '' }}">{{ $event['name'] }}</div>
                        <div class="text-sm text-dimmed">
                            {{ $event['presentableDate'] }}
                        </div>
                    </div>
                </li>
            @endforeach
        </ul>
    </div>
</x-dashboard-tile>

This view simply renders the passed events to HTML. You probably noticed that a x-dashboard-tile Blade component is used here. That DashboardTileComponent is part of the base laravel-dashboard package. That class will, amongst other things, convert an the excel like position notation like a1:a14 to a css grid style like: grid-area: 1 / 1 / 15 / 2;.

Let's take a look at the Blade view of Dashboard tile component.

<div
    style="grid-area: {{ $gridArea }};{{ $show ? '' : 'display:none' }}"
    class="overflow-hidden rounded relative bg-tile"
    {{ $refreshIntervalInSeconds ? "wire:poll.{$refreshIntervalInSeconds}s" : ''  }}
>
    <div
        class="absolute inset-0 overflow-hidden p-4"
        @if($fade)
            style="-webkit-mask-image: linear-gradient(black, black calc(100% - 1rem), transparent)"
        @endif
    >
        {{ $slot }}
    </div>
</div>

Here you can see that $refreshIntervalInSeconds is use to add Livewire's wire:poll directive. Adding this directive will result in the automatic re-rendering of the component.

In case you're not familiar with Blade components, that $slot variable contains all html that's between the x-dashboard-tile tags.

The Twitter tile

The Twitter tile is quite fun. Here is how it looks like:

It displays tweets in (near) real-time that contain a certain string. Under the hood this tile is powered by our Twitter Labs package. It uses the filtered stream Twitter API and ReactPHP to listen for tweets.

To starting listening for incoming tweets you must execute this command:

php artisan dashboard:listen-twitter-mentions

This command will never end. In production should probably want to use something like Supervisord to keep this this task running and to automatically start it when your system restarts.

The command in the config of the tile in the dashboard config file, you can specify to which tweets it should listen for. In our dashboard we are listening for @spatie_be, spatie.be and github.com/spatie.

Whenever a tweet containing any of those strings comes in, we store the tweet in the Tile model. The TwitterComponent will read the tweets stored in that tile model. The component is re-rendered every five seconds, so we have a (near) real time feed.

You can even use this tile multiple times to create a tweet wall in no time. Here's a video in which I demonstrate how you can do that.

The Oh Dear uptime tile

Oh Dear is an app I've built to monitor the uptime of sites. Most competitors only monitor the homepage. Oh Dear crawls your sites and can also alert you when your site contains a broken link or mixed content.

Oh Dear has a beautiful API to work with. It also provides a package to easily consume web hooks sent by Oh Dear.

All sites built and managed by our team are monitored by Oh Dear. The Oh Dear Uptime Tile displays all sites that are down. Here's how it looks like when sites are down.

This tile is only displayed when sites are down. The tile component class accepts a callable which is used to determine if it should be rendered. In our dashboard, that callable is registered in the boot method of AppServiceProvider.

OhDearUptimeTileComponent::showTile(fn (array $downSites) => count($downSites));

This is how that callable gets used in the OhDearUptimeTileComponent.

public function render()
{
    $downSites = OhDearUptimeStore::make()->downSites();

    $showTile = isset(static::$showTile)
        ? (static::$showTile)($downSites)
        : true;

    $refreshIntervalInSeconds = config('dashboard.tiles.oh_dear_uptime.refresh_interval_in_seconds') ?? 5;

    return view('dashboard-oh-dear-uptime-tile::tile', compact('downSites', 'showTile', 'refreshIntervalInSeconds'));
}

public static function showTile(callable $callable): void
{
    static::$showTile = $callable;
}

The contents of showTile will eventually be passed on the the $show prop of the x-dashboard-tile. In the Blade view of x-dashboard-tile it gets used to determine if the tile should be displayed or not with {{ $show ? '' : 'display:none' }}

Exploring themes

The dashboard has a dark mode. This is is how that looks like.

In the dashboard config file there are a couple of options available that determine if the dashboard should use light or dark mode.

return [
    /*
     * The dashboard supports these themes:
     *
     * - light: always use light mode
     * - dark: always use dark mode
     * - device: follow the OS preference for determining light or dark mode
     * - auto: use light mode when the sun is up, dark mode when the sun is down
     */
    'theme' => 'auto',

    /*
     * When the dashboard uses the `auto` theme, these coordinates will be used
     * to determine whether the sun is up or down
     */
    'auto_theme_location' => [
        'lat' => 51.260197, // coordinates of Antwerp, Belgium
        'lng' => 4.402771,
    ],
];

Our own dashboard used auto mode. This means that light mode is used when the sun is up, dark mode when the sun is down. To determine the position of the sun the spatie/sun package is used.

My colleague Sebastian added a nice option: you can force the dashboard in a specific mode by adding a URL parameter: ?theme=dark. This is handy if you want to display a dashboard on a second screen and always want it to be dark, no matter how the dashboard is configured.

Creating your own tile

If you have knowledge of Laravel, creating a new component is a straightforward process.

Creating a minimal tile

At the minimum a tile consist of a Livewire component class and a view. If you have never worked with Livewire before, we recommend to first read the documentation of Livewire, especially the part on making components. Are you a visual learner? Then you'll be happy to know there's also a free video course to get you started.

This is the most minimal Tile component you can create.

namespace App\Tiles;

use Livewire\Component;

class DummyComponent extends Component
{
    /** @var string */
    public $position;

    public function mount(string $position)
    {
        $this->position = $position;
    }

    public function render()
    {
        return view('tiles.dummy');
    }
}

You should always accept a position via the mount function. This position will used to position tiles on the dashboard.

Here's how that tiles.dummy view could look like

<x-dashboard-tile :position="$position">
    <h1>Dummy</h1>
</x-dashboard-tile>

In your view you should always use x-dashboard-tile and pass it the position your component accepted.

Fetching and storing data

The most common way to feed a component data is via a scheduled command. Inside that scheduled command you can perform any API request you want. You can also store fetched data and retrieve in your component however you want. To help you with this, the dashboard provides a Tile model that can be used to store and retrieve data.

Let's take a look at a simple example.

namespace App\Commands;

use Illuminate\Console\Command;
use Spatie\Dashboard\Models\Tile;

class FetchDataForDummyComponentCommand extends Command
{
    protected $signature = 'dashboard:fetch-data-for-dummy-component';

    protected $description = 'Fetch data for dummy component';

    public function handle()
    {
            $data = Http::get(<some-fancy-api-endpoint>)->json();

            // this will store your data in the database
            Tile::firstOrCreateForName('dummy')->putData('my_data', $data);
    }
}

This command could be scheduled to run at any frequency you want.

In your component class, you can fetch the stored data using the getData function on the Tile model:

// inside your component

public function render()
{
    return view('tiles.dummy', [
       'data' => Spatie\Dashboard\Models\Tile::firstOrCreateForName('dummy')->getData('my_data')
    ]);
}

In your view, you can do with the data whatever you want.

Refreshing the component

To refresh a tile, you should pass an amount of seconds to the refresh-interval prop of x-dashboard-tile. In this example the component will be refreshed every 60 seconds.

<x-dashboard-tile :position="$position" refresh-interval="60">
    <h1>Dummy</h1>

    {{-- display the $data --}}
</x-dashboard-tile>

If your component only needs to be refreshed partials, you can add wire:poll to your view (instead of using the refresh-interval prop.

<x-dashboard-tile :position="$position" >
    <h1>Dummy</h1>

     <div wire:poll.60s>
        Only this part will be refreshed
    </div>
</x-dashboard-tile>

Styling your component

The dashboard is styled using Tailwind. In your component you can use any of the classes Tailwind provides.

In addition to Tailwind, the dashboard defines these extra colors for you to use: default, invers, dimmed, accent, canvas, tile, warn, error.

By default, these colors are automatically shared by the textColor, borderColor, and backgroundColor utilities, so you can use utility classes like text-canvas, border-error, and bg-dimmed.

These colors have a separate value for light and dark mode, so your component will also look beautiful in dark mode.

Adding extra JavaScript / CSS

If your tile needs to load extra JavaScript or CSS, you can do so using Spatie\Dashboard\Facades\Dashboard facade.

Dashboard::script($urlToScript);
Dashboard::inlineScript($extraJavaScript);

Dashboard::stylesheet($urlToStyleSheet);
Dashboard::inlineStylesheet($extraCss);

Packaging up your component

If you have created a tile that could be beneficial to others, consider sharing your awesome tile with the community by packaging it up.

This repo contains a skeleton that can help you kick start your tile package.

When you have published you package, let me know by sending a mail to info@spatie.be, and we'll mention your tile in our docs.

Displaying the dashboard on a TV

Behind our tv there is a Raspberry Pi 2 that displays the dashboard. It is powered by a USB port in the tv and it has a small Wifi dongle to connect to the internet, so cables aren't necessary at all.

The Pi used the default Raspian OS. When it is powered on it'll automatically launch Chromium 56 and display the contents of https://dashboard.spatie.be.

Previous iterations

We created our dashboard a couple of years ago. Every year we iterate on it. Here are some screenshots from the very first version up until the most current one.

Comparing Vue/WebSockets to Livewire

Some people consider WebSockets to always be superior to polling. To me that is silly. I think, like a lot of things in programming, it depends on the context.

In the previous iterations of our dashboard we used WebSockets. This brought two nice benefits to the table:

the dashboard got updated as soon as new data comes in
in theory, keeping the dashboard open on multiple screens (even thousands) wouldn't result in any meaningful extra load. New event data was broadcasted out to all connected clients.

There were also some drawbacks:

the tech stack is more complicated: you need to have a WebSocket server running at all times
when opening the dashboard old data was potentially displayed. The dashboard would only be up to date after a few minutes, when all tiles got new data via newly broadcasted events. We could fix that by also storing and loading data from the db, but that would make the Vue components more complicated.
because of the Vue components, there should be a build process to compile the tiles. This makes it, not impossible, but more difficult to package tiles up.

Switching to Livewire brings a new set of benefits and drawbacks. Let's start with the benefits:

the tech stack is extremely simple. Because we use server rendered partials (powered by Livewire), you don't need to write any JavaScript yourself to achieve near real time updates.
it's now very easy to package up and share tiles. Only knowledge of PHP is needed
because the data is stored in the database and also loaded on the initial load of the dashboard, the displayed data is immediately up to date.

I see these drawbacks:

because every browser triggers re-renders, the load on the server increases with every open instance of the dashboard
the dashboard isn't 100% realtime anymore as even the Twitter tile only polls for new data every 5 seconds
Livewire isn't an industry standard like WebSockets

Choosing between Vue/WebSockets and Livewire is a trade off. For our use case, I prefer the benefits/drawbacks that Livewire brings. The simplicity is appealing to me. Our dashboard is never going to opened more than in a couple of places. Even if every member of our team has the dashboard open, our server doesn't break a sweat.

One cool thing to note is that should you want to use Livewire in combination with WebSockets, you still have that option (scroll down to the Laravel Echo section).

If you would prefer a dashboard that is powered by Vue/WebSockets, you can fork the vue-websockets branch of the dashboard.spatie.be repo.

Closing off

The dashboard is a labour of love. I'm pretty happy that in our latest iteration we could make it much simpler, thanks to Livewire. One of the things that always bothered me was the tiles couldn't be easily packaged up. That problem has now been solved. I'm pretty curious what kind of tiles people will come up with.

If you create a custom tile package, do let me know. I'll add it to our docs. Should you create a dashboard of your own using our package, feel free to send me a screenshot.

In a next iteration of the dashboard, I'm thinking of adding an admin section where people can add tiles and customise the dashboard. That might be a good addition for next year!

Want to get started using the dashboard, head over to the documentation.

If you like the dashboard, please consider sponsoring us on GitHub.

If you're still here reading this, you probably are pretty excited about the dashboard. Here's the recording of a stream where I first showed off the Livewire powered dashboard.

Mixing event sourcing in a traditional Laravel app

Freek Van der Herten — Mon, 04 May 2020 12:15:02 +0000

Together with my colleague Brent, I'm working on designing the architecture of a massive Laravel application. In that application, we'll have traditional parts and event sourced parts. In this blog post, I'd like to give a practical example of how we think to achieve this.
This post is the second one in a two-part series. I highly encourage to read the first part before continuing to read this post. You also should have a good understanding of event sourcing, the role of aggregates, and projectors. Get up to speed by going through this introduction.

Setting the stage

First, let's do a quick recap of Brent's post. We need event sourcing in our application. In certain parts, we need to make decisions based on the past and, as time progresses, we need to be able to generate reports without knowing upfront what should be in those reports.

These problems can be solved by using event sourcing. We just store all events that happen in the app, so we can have aggregate roots that can make decisions based on the past when they are reconstituted from the events. We can generate new reports by creating projectors and replaying all recorded events to them.

A wise man, by the name of Frank de Jonge, once said: "Event sourcing makes the hard parts easy, and the easy parts hard". And it's true. Setting up event sourcing takes some time, and it's not as straightforward. Some overhead gets in the way when you want to do simple things.

In our application, we also have parts that are rather cruddy and don't need the power of event sourcing. Wouldn't it be nice to be able to have the best of both worlds in a single app? Brent and I researched this subject and pair programmed on some experiments. We'd like to share one of these experiments with you.

A practical example

We're going to implement some of the parts mentioned in Brent's post: products and orders. Product is a boring cruddy part. We don't need history nor reports here. For the orders part, we'll use event sourcing.

You can find the source code of the example in this repo on GitHub. Keep in mind that this is a very simple example. In a real-world app the logic involved would probably be more complicated. In this experiment, we're just concentrating on how such to part should/would communicate with each other.

The non-event-sourced part

If you take a look in the Context directory, you'll see the two parts: Order and Product. Let's take a look at `Product first:

As you can see, this part is very simple: we just have models and events. The idea here is that we can just build it as we're used to, with not too much overhead. The only thing that we need to do is to fire off specific events when something changes, so the other parts of the app can hook into that.

In the Product model you'll see this code:

protected $dispatchesEvents = [ 'created' => ProductCreatedEvent::class, 'updated' => ProductUpdatedEvent::class, 'deleting' => DeletingProductEvent::class, 'deleted' => ProductDeletedEvent::class, ];

In $dispatchesEvents, you can define which events should be fired when certain things happen to the model. This is standard Laravel functionality. Sure, we could rely on the events that eloquent natively fires, but we want to make this very explicit by using event classes of our own.

Let's take a look at one of these events.

`
namespace App\Context\Product\Events;

use App\Context\Product\Models\Product;

class ProductCreatedEvent
{
public Product $product;

public function __construct(Product $product)
{
    $this->product = $product;
}

}
`

As you can see, there's nothing special going on here. We're just using the model as an event property.

The event sourced part

Let's now turn our eye to the Order part of the app, which is event sourced. This is how that structure looks like:

You see projectors and an aggregate root here, so it's clear that this part uses event sourcing. We're using our homegrown event sourcing package to handle the logic around storing events, projectors, aggregate roots, ...

In the Product part of the app, we fired off events. These events were just regular Laravel events, we didn't store them. The ProductEventSubscriber is listening for these events. Let's take a look at the code.

`
namespace App\Context\Order\Subscribers;

use App\Context\Product\Events\DeletingProductEvent as AdminDeletingProductEvent;
use App\Context\Product\Events\ProductCreatedEvent as AdminProductCreatedEvent;
use App\Context\Order\Events\ProductCreatedEvent;
use App\Context\Order\Events\ProductDeletedEvent;
use App\Support\Events\EventSubscriber as BaseEventSubscriber;
use App\Support\Events\SubscribesToEvents;

class ProductEventSubscriber implements BaseEventSubscriber
{
use SubscribesToEvents;

protected array $handlesEvents = [
    AdminProductCreatedEvent::class => 'onProductCreated',
    AdminDeletingProductEvent::class => 'onDeletingProduct',
];

public function onProductCreated(AdminProductCreatedEvent $event): void
{
    $event = $event->product;

    event(new ProductCreatedEvent(
        $event->getUuid(),
        $event->stock,
    ));
}

public function onDeletingProduct(AdminDeletingProductEvent $event): void
{
    $event = $event->product;

    event(new ProductDeletedEvent(
        $event->getUuid(),
    ));
}

}
`

What happens here is quite interesting. We are going to listen for the events that are coming from the non event sourced part. When an event from the Product context, that is interesting to the Order context, comes in, we are going to fire off another event. That other event is part of the Product context.

So when App\Context\Product\Events\ProductCreatedEvent comes in (and it is aliased to AdminProductCreatedEvent because probably an action by an admin on the UI will have caused that action), we are going to fire off App\Context\Order\Events\ProductCreatedEvent (from the Order context).

We are going to take all the properties that are interesting to Order context and put them in the App\Context\Order\Events\ProductCreatedEvent.

`
public function onProductCreated(AdminProductCreatedEvent $event): void
{
$event = $event->product;

event(new ProductCreatedEvent(
    $event->getUuid(),
    $event->stock,
));

}
`

Let's take a look at that event itself.

`
namespace App\Context\Order\Events;

use App\Support\ValueObjects\ProductUuid;
use Spatie\EventSourcing\ShouldBeStored;

class ProductCreatedEvent extends ShouldBeStored
{
public ProductUuid $productUuid;

public int $stock;

public function __construct(ProductUuid $productUuid, int $stock)
{
    $this->productUuid = $productUuid;

    $this->stock = $stock;
}

}

You can see that this event extends ShouldBeStored. That base class is part of our event sourcing package. This will cause the event to be stored.

We immediately use that stored event to build up a projection that holds the stock. Let's take a look at ProductStockProjector.

`
namespace App\Context\Order\Projectors;

use App\Context\Order\Events\OrderCancelledEvent;
use App\Context\Order\Events\ProductCreatedEvent;
use App\Context\Order\Events\ProductDeletedEvent;
use App\Context\Order\Events\OrderCreatedEvent;
use App\Context\Order\Models\Order;
use App\Context\Order\Models\ProductStock;
use App\Support\ValueObjects\ProductStockUuid;
use Spatie\EventSourcing\Projectors\Projector;
use Spatie\EventSourcing\Projectors\ProjectsEvents;

class ProductStockProjector implements Projector
{
use ProjectsEvents;

protected array $handlesEvents = [
    ProductCreatedEvent::class => 'onProductCreated',
    ProductDeletedEvent::class => 'onProductDeleted',
    OrderCreatedEvent::class => 'onOrderCreated',
    OrderCancelledEvent::class => 'onOrderCancelled',
];

public function onProductCreated(ProductCreatedEvent $event): void
{
    ProductStock::create([
        'uuid' => ProductStockUuid::create(),
        'product_uuid' => $event->productUuid,
        'stock' => $event->stock,
    ]);
}

public function onProductDeleted(ProductDeletedEvent $event): void
{
    ProductStock::forProduct($event->productUuid)->delete();
}

public function onOrderCreated(OrderCreatedEvent $event): void
{
    $productStock = ProductStock::forProduct($event->productUuid);

    $productStock->update([
        'stock' => $productStock->stock - $event->quantity,
    ]);
}

public function onOrderCancelled(OrderCancelledEvent $event): void
{
    $order = Order::findByUuid($event->aggregateRootUuid());

    $productStock = ProductStock::forProduct($order->product->uuid);

    $productStock->update([
        'stock' => $productStock->stock + $order->quantity,
    ]);
}

}
`

When ProductCreatedEvent is fired, we will call ProductStock::create. ProductStock is a regular Eloquent model.

`
namespace App\Context\Order\Models;

use App\Context\Product\Models\Product;
use Illuminate\Database\Eloquent\Model;

class ProductStock extends Model
{
/**
* @param \App\Context\Product\Models\Product|\App\Support\ValueObjects\ProductUuid $productUuid
*
* @return \App\Context\Order\Models\ProductStock
*/
public static function forProduct($productUuid): ProductStock
{
if ($productUuid instanceof Product) {
$productUuid = $productUuid->getUuid();
}

    return static::query()
        ->where('product_uuid', $productUuid)
        ->first();
}

}
`

In the ProductStockProjector the ProductStock model will be updated when orders come in, when they get canceled, or when an order is deleted.

Currently, we have an agreement with every member working on the project that it is not allowed to write to model from other contexts. The Order context may write and read from this model, but the Product context may only read it. Because this is such an important rule, we will probably technically enforce it soon.

Finally, let's take a look at the OrderAggregateRoot where the ProductStock model is being used to make a decision.

`
namespace App\Context\Order;

use App\Context\Product\Models\Product;
use App\Context\Order\Events\CouldNotCreateOrderBecauseInsufficientStock;
use App\Context\Order\Events\OrderCreatedEvent;
use App\Context\Order\Events\OrderCancelledEvent;
use App\Context\Order\Exceptions\CannotCreateOrderBecauseInsufficientStock;
use App\Context\Order\Models\ProductStock;
use Spatie\EventSourcing\AggregateRoot;

class OrderAggregateRoot extends AggregateRoot
{
public function createOrder(Product $product, int $quantity): self
{
$eventAvailability = ProductStock::forProduct($product);

    if ($eventAvailability->availability < $quantity) {
        $this->recordThat(new CouldNotCreateOrderBecauseInsufficientStock(
            $product->getUuid(),
            $quantity
        ));

        throw CannotCreateOrderBecauseInsufficientStock::make();
    }

    $unitPrice = $product->unit_price;

    $totalPrice = $unitPrice * $quantity;

    $this->recordThat(new OrderCreatedEvent(
        $product->getUuid(),
        $quantity,
        $unitPrice,
        $totalPrice,
    ));

    return $this;
}

public function cancelOrder(): self
{
    $this->recordThat(new OrderCancelledEvent());

    return $this;
}

}
`

In a complete app, the createOrder function would probably be triggered by an action that is performed in the UI. A product can be ordered for a certain amount. Using the ProductStock, the aggregate root will decide if there is enough stock for the order to be created.

Summary

A non event sourced part of the app fires of regular events. The event sourced parts listen for these events and record data interesting for them in events of their own. These events, own to the context, will be stored. These stored events are being used to feed projectors. These projectors create models that can be read by the non-event-sourced parts. The non-events-sourced parts may only read these models. Aggregate roots can use the events and projection to make decisions.

This approach brings a lot of benefits:

a non-event-sourced part can be built like we're used to. We just have to take care that events are being fired
an event sourced part can record its own events to act on
we could create new projectors and replay all recorded events to build up new state

I know this all is a lot to take in. This way of doing things is by no means set in stone for us. We're in a discovery phase, but we have a good feeling about what we've already discovered. Brent and/or I will probably write some follow-up posts soon.

Replacing web sockets with Livewire

Freek Van der Herten — Mon, 04 May 2020 12:13:56 +0000

Up until a few days ago, the real-time UI of Oh Dear (an uptime monitoring SaaS I run) was powered with web sockets. We recently replaced this with Livewire components.

In this blog post, I'd like to explain why and how we did that.

I'm going to assume that you already know what Livewire is. If not, head over to the Livewire docs. There's even a short video course on there. In short, Livewire enables you to create dynamic UIs using server-rendered partials.

Why ditch web sockets

There are hundreds of uptime checking services, but most of them look pretty crappy. When my buddy Mattias and I created Oh Dear, we set out the goal to create a beautiful service that is easy to use. We believe that our service doesn't necessarily has to be unique. By providing a good design, UX, and docs, you can get ahead of a large part of the competition.

One of the things we decided on very early on was that our UI needed to be real-time. We don't want users to refresh to see the latest results of their checks. When a new user adds their first site to our service, we wanted the whole process to be snappy and display results fast.

This is what that looks like in Oh Dear. After signing up, users can fill out this form. When pressing enter, it gets added to the list, and results are immediately displayed as they come in.

This behavior used to be powered by web sockets. Whenever Oh Dear started and completed a check, it would broadcast events to the front end. The broadcasting itself would be done using Laravel's native broadcasting features and the Laravel WebSockets package that Marcel and I created. On the front end, we used Laravel Echo to receive the events and a couple of Vue components.

It all worked fine, but it sure added some complexity to our stack. Also, most of the time, once users have set up their sites, they won't visit our website often again. But we'd still keep broadcasting events. We could avoid this by tracking presence in some way, but this would complicate things even further.

By moving to Livewire, we can ditch all of the things mentioned above entirely. There's no need for a web sockets server, Echo, and Vue to create the experience in the movie above. In fact, in that movie, Livewire is already being used.

Let's take a look at these Livewire components.

Displaying the list of sites

This is what the list of sites looks like.

Here is the Blade view that is used to render that screen.

<x-app-layout title="Dashboard" :breadcrumbs="Breadcrumbs::render('sites')">
    <div class="wrap">
        <section class="card pb-8 cloak-fade" v-cloak>
            @include('app.sites.list.partials.notificationsNotConfigured')

            <livewire:site-list />

            <div class="flex items-center mt-8" id="site-adder">
                <livewire:site-adder />
            </div>
        </section>
    </div>
</x-app-layout>

So we have two Livewire components going on: site-list and site-adder. In the LivewireServiceProvider you can see

namespace App\Providers;

use App\Http\App\Livewire\Sites\SiteListComponent;
use App\Http\App\Livewire\SiteSettings\SiteAdderComponent;
use Illuminate\Support\ServiceProvider;
use Livewire\Livewire;

class LivewireServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Livewire::component('site-list', SiteListComponent::class);
        Livewire::component('site-adder', SiteAdderComponent::class);

        // other components
    }
}

Next, let's take a look at the SiteListComponent class and its underlying view. You don't have to understand it all now. After the source code, I'm going to explain some parts, but I think it's good that you already take a look at the component as a whole, so you have some context.

namespace App\Http\App\Livewire\Sites;

use Livewire\Component;
use Livewire\WithPagination;

class SiteListComponent extends Component
{
    use WithPagination;

    protected $listeners = ['siteAdded' => '$refresh'];

    public int $perPage = 30;

    public string $search = '';

    public bool $onlySitesWithIssues = false;

    public bool $showSiteAdder = false;

    public function showAll()
    {
        $this->search = '';

        $this->onlySitesWithIssues = false;
    }

    public function showOnlyWithIssues()
    {
        $this->search = '';

        $this->onlySitesWithIssues = true;
    }

    public function showSiteAdder()
    {
        $this->showSiteAdder = true;
    }

    public function hideSiteAdder()
    {
        $this->showSiteAdder = false;
    }

    public function render()
    {
        return view('app.sites.list.components.siteList', [
            'sites' => $this->sites(),
            'sitesWithIssuesCount' => $this->sitesWithIssuesCount(),
        ]);
    }

    protected function sites()
    {
        $query = currentTeam()->sites()->search($this->search);

        if ($this->onlySitesWithIssues) {
            $query = $query->hasIssues();
        }

        return $query
            ->orderByRaw('(SUBSTRING(url, LOCATE("://", url)))')
            ->paginate($this->perPage);
    }

    protected function sitesWithIssuesCount(): int
    {
        return currentTeam()->sites()->hasIssues()->count();
    }
}

And this is the content of the view that is being rendered in that render function: app.sites.list.components.siteList.

<div>
    <div wire:poll.5000ms>
        <section class="flex items-center justify-between w-full mb-8">
            <div class="text-xs">
                <div class="switcher">
                    <button wire:click="showAll"
                            class="switcher-button {{ ! $onlySitesWithIssues ? 'is-active' : '' }}">Display all sites
                    </button>
                    <button wire:click="showOnlyWithIssues"
                            class="switcher-button {{ $onlySitesWithIssues ? 'is-active' : '' }}">
                        Display {{ $sitesWithIssuesCount }} {{ \Illuminate\Support\Str::plural('site', $sitesWithIssuesCount) }} with issues
                    </button>
                </div>
            </div>

            <div class="flex items-center justify-end">
                <a href="#site-adder" wire:click="$emit('showSiteAdder')" class="button is-secondary mr-4">Add another site</a>
                <input wire:model="search"
                       class="form-input is-small w-48 focus:w-64"
                       type="text"
                       placeholder="Filter sites..."/>
            </div>
        </section>


        <table class="site-list-table w-full">
            <thead>
            <th style="width: 27%;">Site</th>
            <th style="width: 14%;">Uptime</th>
            <th style="width: 14%;">Broken links</th>
            <th style="width: 14%;">Mixed Content</th>
            <th style="width: 14%;">Certificate Health</th>
            <th style="width: 17%;">Last check</th>
            </thead>
            <tbody>
            @forelse($sites as $site)
                <tr>
                    <td class="pr-2">
                        <div class="flex">
                            <span class="w-6"><i
                                    class="fad text-gray-700 {{ $site->uses_https ? 'fa-lock' : '' }}"></i></span> <a
                                href="{{ route('site', $site) }}"
                                class="flex-1 underline truncate">{{ $site->label }}</a>
                        </div>
                    </td>
                    <td class="pr-2">
                        <x-check-result :site="$site" check-type="uptime"/>
                    </td>
                    <td class="pr-2">
                        <x-check-result :site="$site" check-type="broken_links"/>
                    </td>
                    <td class="pr-2">
                        <x-check-result :site="$site" check-type="mixed_content"/>
                    </td>
                    <td class="pr-2">
                        <x-check-result :site="$site" check-type="certificate_health"/>
                    </td>
                    <td class="text-sm text-gray-700">
                        @if($site->latest_run_date)
                            <a href="{{ route('site', $site) }}">
                                <time datetime="{{ $site->latest_run_date->format('Y-m-d H:i:s') }}"
                                      title="{{ $site->latest_run_date->format('Y-m-d H:i:s') }}">{{ $site->latest_run_date->diffInSeconds() < 60 ? 'Less than a minute ago' : $site->latest_run_date->diffForHumans() }}</time>
                            </a>
                        @else
                            No runs yet
                        @endif
                    </td>
                </tr>
            @empty
                <tr><td class="text-center" colspan="6">There are no sites that match your search...</td></tr>
            @endforelse
            </tbody>
        </table>

        @if ($sites->total() > $perPage)
            <div class="flex justify-between mt-4">
                <div class="flex-1 w-1/2 mt-4">
                    {{ $sites->links() }}
                </div>

                <div class="flex w-1/2 text-right text-muted text-sm text-gray-700 mt-4">
                    <div class="w-full block">
                        Showing {{ $sites->firstItem() }} to {{ $sites->lastItem() }} out of {{ $sites->total() }} sites
                    </div>
                </div>
            </div>
        @endif
    </div>
</div>

In the render function, you probably have noticed that the component itself is responsible for getting the sites.

public function render()
{
    return view('app.sites.list.components.siteList', [
        'sites' => $this->sites(),
        'sitesWithIssuesCount' => $this->sitesWithIssuesCount(),
    ]);
}

protected function sites()
{
    $query = currentTeam()->sites()->search($this->search);

    if ($this->onlySitesWithIssues) {
        $query = $query->hasIssues();
    }

    return $query
        ->orderByRaw('(SUBSTRING(url, LOCATE("://", url)))')
        ->paginate($this->perPage);
}

Filtering sites

Notice that $this->onlySitesWithIssues check? Let's see how that variable is being set. If you take a look at the screenshot of the site list, you'll notice a little filter on the top with "Display all sites" and "Display sites with issues".

This is the part of the view that renders that.

<div class="switcher">
    <button wire:click="showAll"
            class="switcher-button {{ ! $onlySitesWithIssues ? 'is-active' : '' }}">Display all sites
    </button>
    <button wire:click="showOnlyWithIssues"
            class="switcher-button {{ $onlySitesWithIssues ? 'is-active' : '' }}">
        Display {{ $sitesWithIssuesCount }} {{ \Illuminate\Support\Str::plural('site', $sitesWithIssuesCount) }} with issues
    </button>
</div>

Notice that wire:click="showOnlyWithIssues". When the user clicks an element with wire:click the method whose name is in the attribute value will be executed, and the component will be re-rendered. So, in this case, showOnlyWithIssues is executed.

public function showOnlyWithIssues()
{
    $this->search = '';

    return $this->onlySitesWithIssues = true;
}

So, here our onlySitesWithIssues instance variable is changed, causing our component to re-render. Because onlySitesWithIssues is now set to true, the sites() method will now filter on sites having issues.

if ($this->onlySitesWithIssues) {
    $query = $query->hasIssues();
}

When the component gets rendered, only sites with issues are displayed. Under the hood, Livewire takes care of a lot of things, most notably calling the method on the component when that wire:click element is called, and replacing the HTML of the component on the page when the HTML of the re-rendered version.

Searching sites

In the top right corner of the site list, you see a search box. When you type something there, you will only see sites who's name contain your query. Here's how that works.

In the Blade view, this is the relevant HTML.

<input 
   wire:model="search"
   class="form-input is-small w-48 focus:w-64"
   type="text"
   placeholder="Filter sites..."
/>

Here, another Livewire directive is used: wire:model. This directive will make sure that each time you type something in that element, Livewire will update the instance variable with the same name in the component and re-render the component. By default, this behavior is debounced, meaning that when you type fast, only one request will be made every 150ms.

So, because the search instance variable is changed on the component, it will re-render. In the first line of the sites() method, the value is being used.

$query = currentTeam()->sites()->search($this->search);

And with this in place, searching sites works. I think it's kinda amazing that you can have this behavior by merely adding livewire:model in your view, and using that value to scope your query. Sure, you could do this with Vue, but this is way simpler.

For completeness, here's the scopeSearch that's on the Site model.

public static function scopeSearch(Builder $query, string $searchFor): void
{
    if ($query === '') {
        return;
    }

    $query->where('url', 'like', "%{$searchFor}%");
}

Paginating sites

Laravel natively has excellent support for paginating query results. You only have to call paginate on your query, which we have done in the sites() method.

// in the sites() method

return $query
    ->orderByRaw('(SUBSTRING(url, LOCATE("://", url)))')
    ->paginate($this->perPage);

Calling $sites->links() in the view will render URLs with a page parameter. Under the hood of the paginate() method, that query parameter is used to fetch the results of that page. That's in short how pagination works in Laravel.

Adding pagination support to a Livewire component is super easy with Livewire. You just have to use the Livewire\WithPagination trait on your component. This trait does some magic so the render links don't contain a URL to your page, but to an internal Livewire route. This is the output of $sites()->links() in the view of Livewire component.

<ul>
    <li class="page-item active" aria-current="page"><span class="page-link">1</span></li>
    <li class="page-item"><a class="page-link" href="https://ohdear.app/livewire/message/site-list?page=2">2</a></li>
    <li class="page-item"><a class="page-link" href="https://ohdear.app/livewire/message/site-list?page=3">3</a></li>
    <li class="page-item"><a class="page-link" href="https://ohdear.app/livewire/message/site-list?page=4">4</a></li>

    <li class="page-item">
        <a class="page-link" href="https://ohdear.app/livewire/message/site-list?page=2" rel="next" aria-label="Next »">›</a>
    </li>
</ul>

When clicking such a link, Livewire will set the page query parameter in the URL and re-render the component. It's an elegant solution, and I like that it hooks in so nicely with Laravel's default pagination.

As a Livewire user, the only thing you needed to do extra was to apply that WithPagination trait. Beautiful.

Updating the list

As stated earlier, want to have our UI to display the current state, without users having to refresh. If one of the sites displayed in the list goes down, the list should get updated automatically.

The solution for this is straightforward: we're just going to poll for changes. Livewire comes with support for polling out of the box. At the top of the view you might have noticed this:

<div wire:poll.5000ms>

This will make Livewire refresh the component automatically every five seconds. To re-render the component in the browser, Livewire makes use of morphdom. This will compare the HTML of the component with the HTML of the re-rendered version. Only the changes will get updated in the DOM, making the cost for re-rendering in the browser very low.

While typing this blog post, I can already feel the screams of some readers: "Freek, what are you doing!?!? This is highly inefficient: it will perform queries and make requests the whole time...". And yes, that is true.

Using Livewire with polling is a trade-off. One the one hand, we have some more requests/queries, but this only happens when users are looking at their site lists. This won't happen often. To know the state of their sites, the vast majority of our users rely on the alerts we sent out (via Slack, Mail, Telegram, ...), and they won't be staring at the site list the whole time.

It's also very nice that Livewire only polls if the browser is displaying the page. When a browser tab is in the background, polling is paused.

By using a little bit of polling, we don't need to set up web sockets or Vue, and we don't need to broadcast events the whole time, ... It vastly simplifies our tech stack. I think in this case, the trade-off that Livewire / polling brings to the table is worth it.

In closing

I hope you enjoyed this dissection of our site list Livewire component. Other place in our UI, where realtime info is being displayed, was refactored in a similar fashion.

Working with Livewire was a pleasure. The API makes sense, the docs are well written, and it's easy to create powerful components in a short amount of time.

If you want to see the Livewire components discussed in this blogpost in action, head over to Oh Dear and start your ten-day trial (no credit card needed).

After ten days, you might want to get a subscription. What sets Oh Dear apart from the competition is that we not only monitor your homepage, but your entire site. We can alert you when a broken link, or mixed content, is found on any pages of your website. And we also monitor certificate health and provide beautiful status pages like this one.

Should you have questions about these Livewire components, or Oh Dear in general, let me know in the comments below.

Building complex forms with Laravel Livewire in Oh Dear

Freek Van der Herten — Mon, 04 May 2020 12:12:54 +0000

Together with my buddy Mattias Geniar, I run Oh Dear, an uptime checker service on steroids.

Unlike most uptime trackers, Oh Dear doesn't only check your homepage, but every single page of your site. When we detect a broken link or some mixed content, we send a notification. Oh, and we provide status pages, like this one from Laravel and Flare too.

In this blog post, I'd like to show you how we use Livewire to render some complex forms in the UI of Oh Dear.

What is Livewire?

Livewire is an impressive library written by Caleb Porzio that aims to make building dynamic interfaces simple, without needing to resort to JavaScript for most cases).

This blog post isn't an introduction to Livewire, if you need that head over to this video series on the Livewire docs. Before continuing reading my post, you should have a grasp of what Livewire can do.

Oh Dear was initially built a couple of years ago (oh how time flies), and our best option for creating the UI we wanted was, at the time, Vue. Both Mattias and I don't see ourselves as JavaScript experts. If we can solve something on the server-side, that will probably be our preferred route. That's why we're now slowly replacing our custom Vue components with Livewire.

I still love Vue, but in some instances, we don't want the complexity that it brings. In this blog post, I'll show you two examples of Vue components that were replaced by Livewire counterparts.

A Livewire component to add headers

Oh Dear sends requests to sites to check their health. Users can specify extra headers that should be used when making those requests.

This is how the form in the site settings screen looks like.

When clicking "Add custom header" fields are displayed to enter the name and value of the header.

Users can specify up to five headers. If there are five headers on screen, the "Add custom header" button will be hidden.

Of course, when you press "Remove", that line will get removed. Any changes you make will get saved when clicking "Update".

Let's take a look at the needed HTML when rendering two headers.

<form method="POST" class="form mb-8">
    <input type="hidden" name="_token" value="...">
    <div class="form-group is-row">
        <div class="flex-1">
            <div>
                <div>
                    <div class="flex mb-2">
                        <div class="flex flex-col flex-grow">
                            <div class="mr-2 flex-grow">
                                <input value="" placeholder="Header name" type="text"
                                       name="http_client_headers[0][name]">
                            </div>
                        </div>

                        <div class="flex flex-col flex-grow">
                            <div class="mr-2 flex-grow">
                                <input value="" placeholder="Header value" type="text"
                                       name="http_client_headers[0][value]">
                            </div>
                        </div>

                        <div class="button is-secondary items-center">
                            <div class="text-xs text-gray-500">
                                Remove
                            </div>
                        </div>
                    </div>
                    <div class="flex mb-2">
                        <div class="flex flex-col flex-grow">
                            <div class="mr-2 flex-grow">
                                <input value="" placeholder="Header name" type="text"
                                       name="http_client_headers[1][name]">
                            </div>
                        </div>

                        <div class="flex flex-col flex-grow">
                            <div class="mr-2 flex-grow">
                                <input value="" placeholder="Header value" type="text"
                                       name="http_client_headers[1][value]">
                            </div>
                        </div>

                        <div class="button is-secondary items-center">
                            <div class="text-xs text-gray-500">
                                Remove
                            </div>
                        </div>
                    </div>
                </div>

                <div class="button is-secondary mr-4">
                    Add custom header
                </div>
            </div>
        </div>
        <div class="help">
            When performing the uptime, mixed content and broken links checks we'll add these headers to each request we
            make to BackupPC.
        </div>
    </div>
    <div class="form-group has-button">
        <button type="submit">Update</button>
    </div>
</form>

The cool thing to note here is that you can use [] when you want to submit an array of data. This is standard HTML. Here are all the names of the form elements in the snippet above:

http_client_headers[0][value]
http_client_headers[0][name]
http_client_headers[1][value]
http_client_headers[1][name]

On the server-side, this is how that data gets validated.

namespace App\Http\App\Requests;

use App\Domain\Site\Rules\HttpHeaderNameRule;
use Illuminate\Foundation\Http\FormRequest;

class UpdateHeaderSettingsRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'http_client_headers' => 'array|max:5',
            'http_client_headers.*.name' => ['required','max:500', new HttpHeaderNameRule()],
            'http_client_headers.*.value' => 'required|max:500',
        ];
    }
}

I'll sidestep a little and, for completeness, show the code of that HttpHeaderRule:

namespace App\Domain\Site\Rules;

use Illuminate\Contracts\Validation\Rule;

class HttpHeaderNameRule implements Rule
{
    public function passes($attribute, $value)
    {
        $value = strtolower($value);

        return ! in_array($value, [
            'accept-encoding',
            'connection',
            'user-agent',
            'host',
            'referer',
            'pragma',
        ]);
    }

    public function message()
    {
        return 'This header is not allowed.';
    }
}

Now that you know which HTML is rendered and how it is validated, let's take a look at our Vue components that would handle rendering the HTML.

Here's the content of HttpHeaders.vue.

<template>
    <div>
        <div v-for="(httpHeader, index) in httpHeaders">
            <http-header
                :http-header="httpHeader"
                :index="index"
                :error="getError(index)"
                :removable="removable"
                @remove="removeHeader(httpHeader)"
            ></http-header>
        </div>

        <div v-if="httpHeaders.length < 10" @click="addHeader" class="button is-secondary mr-4">
            Add custom header
        </div>
    </div>
</template>

<script>
import httpHeader from './httpHeader';

export default {
    props: ['initHttpHeaders', 'initErrors'],

    components: {
        httpHeader,
    },

    computed: {
        removable() {
            return true;
        },
    },

    data() {
        return {
            httpHeaders: [],
            errors: {},
        };
    },

    created() {
        this.initHttpHeaders = this.inithttpHeaders;
        this.errors = this.initErrors;
    },

    methods: {
        addHeader() {
            this.httpHeaders.push(this.emptyHeader());
        },

        removeHeader(httpHeader) {
            this.httpHeaders.splice(this.httpHeaders.indexOf(httpHeader), 1);

            this.errors = {};
        },

        emptyHeader() {
            return { name: '', value: '' };
        },

        getError(index) {
            return {
                name: this.errors[`http_headers.${index}.name`],
                value: this.errors[`http_headers.${index}.value`],
            };
        },
    },
};
</script>

And here is the content of HttpHeader.vue.

<template>
    <div class="flex mb-2">
        <div class="mr-2 flex-grow">
            <input
                placeholder="Header name"
                type="text"
                v-model="httpHeader.name"
                :name="`http_headers[${index}][name]`"
            />

            <div class="form-error" v-if="hasError('name')">
                {{ getError('name') }}
            </div>
        </div>

        <div class="mr-2 flex-grow">
            <input
                placeholder="Header value"
                type="text"
                v-model="httpHeader.value"
                :name="`http_headers[${index}][value]`"
            />

            <div class="form-error" v-if="hasError('value')">
                {{ getError('value') }}
            </div>
        </div>

        <div class="button is-secondary items-center">
            <div v-if="removable" class="text-xs text-gray-500" @click="$emit('remove')">
                Remove
            </div>
        </div>
    </div>
</template>

<script>
export default {
    props: ['httpHeader', 'removable', 'index', 'error'],

    methods: {
        hasError(attribute) {
            return this.error[attribute] !== undefined;
        },

        getError(attribute) {
            return this.error[attribute][0];
        },
    },
};
</script>

I'm not going to go over all this code; it should be pretty straightforward if you know your way around Vue.

Something that has always bothered me is that in these Vue components, I can't make use of any partials or form helpers that are available server-side. Also, getting the errors from Laravel displayed into the component takes some effort. None of this is rocket science to solve, but still...

We've replaced these two Vue components with a single Livewire component. Let's take a look.

Here is the HttpHeaders component itself. I've added some comments to make it more clear.

namespace App\Http\Livewire;

use Livewire\Component;

class HttpHeaders extends Component
{
    /**
     * This array contains an array with a name and value for
     * each header we display.
     */
    public $headers = [];

    /**
     * This function will get called when ever the component
     * is rendered for the first time.
     */
    public function mount(array $headers)
    {
        /**
         * We first check if there are any old values for
         * the form elements we want to render.
         *
         * When a user has submitted a form with values that
         * didn't pass validation, we display those old values.
         */
        $this->headers = old('http_client_headers', $headers);
    }

    /**
     * This function will add an empty header value pair
     * causing an extra row to be rendered.
     */
    public function addHeader(): void
    {
        if (! $this->canAddMoreHeaders()) {
            return;
        }

        $this->headers[] = ['name' => '', 'value' => ''];
    }

    /**
     * Here we'll remove the item with the given key
     * from the headers array, so a rendered row will
     * disappear.
     */
    public function removeHeader(int $i): void
    {
        unset($this->headers[$i]);

        $this->headers = array_values($this->headers);
    }

    /**
     * This check is used both in this component class
     * and in the view.
     */
    public function canAddMoreHeaders(): bool
    {
        return count($this->headers) < 5;
    }

    public function render()
    {
        return view('livewire.http-headers');
    }
}

And here is that http-headers view.

<div>
    <div>
        @foreach($headers as $i => $header)
            <div class="flex mb-2">
                <div class="flex flex-col flex-grow">
                    <div class="mr-2 flex-grow">
                        <input
                            value="{{ $header['name'] }}"
                            placeholder="Header name"
                            type="text"
                            name="http_client_headers[{{ $i }}][name]"
                        >
                    </div>
                    @error("http_client_headers.{$i}.name")
                    <div>
                        <strong class="form-error">
                            {{ $errors->first("http_client_headers.{$i}.name") }}
                        </strong>
                    </div>
                    @enderror
                </div>

                <div class="flex flex-col flex-grow">
                    <div class="mr-2 flex-grow">
                        <input
                            value="{{ $header['value'] }}"
                            placeholder="Header value"
                            type="text"
                            name="http_client_headers[{{ $i }}][value]"
                        >
                    </div>
                    @error("http_client_headers.{$i}.value")
                    <div>
                        <strong class="form-error">
                            {{ $errors->first("http_client_headers.{$i}.value") }}
                        </strong>
                    </div>
                    @enderror
                </div>

                <div class="button is-secondary items-center">
                    <div wire:click.prevent="removeHeader({{ $i }})" class="text-xs text-gray-500">
                        Remove
                    </div>
                </div>
            </div>
        @endforeach
    </div>

    @if ($this->canAddMoreHeaders())
        <div wire:click.prevent="addHeader" class="button is-secondary mr-4">
            Add custom header
        </div>
    @endif
</div>

Again, not rocket science, but it's pretty beautiful. I didn't need to write a single line of JavaScript. I can make use of any Blade directive. I don't need to do anything special to handle errors.

This solution feels much lighter to me than resorting to Vue.

There's also a small drawback. Each time a user wants to add an extra header, "Add custom header" is going to get clicked, and the server will need to build up the additional HTML. When using Vue, there's no extra trip. In Oh Dear, however, the load that we get from the UI pales in comparison to the load we get from performing checks and crawling sites. So, I gladly accept this small drawback. The benefits that Livewire brings to the table outweigh the drawbacks.

Displaying notification preferences

Let's take a look at a more complex form. The core business of Oh Dear is to notify users when something is wrong. We support my notification channels, such as mail, SMS, Slack, Webhooks, Pushover, ... In our UI, users can specify which notifications should be sent to which channels.

Here's what it looks like.

Much like the headers component, you can add multiple values.

Something to keep in mind is that, for some channels, multiple form fields need to be rendered.

What's different compared to the headers component is that, by default, some form fields are shown. We don't display any form element by default for the http headers component, because most users don't need to set custom headers. When you're on the notification screen, you probably do want to set up or view your notification preference.

This form is a bit more complicated than the HTTP headers one. We have different form fields per channel, and we have a bunch of toggles.

Let's first take a look at the Vue components that we've ditched.

Here's NotificationDestinations.vue, which handles the entire collection of forms.

<template>
    <div class="mb-12">
        <h2 class="h2 mb-2">{{ title }}</h2>
        <p v-if="$slots.description" class="help mb-6">
            <slot name="description" />
        </p>
        <div class="alert is-success mb-4" v-if="form.successful">
            The notification settings have been updated!
        </div>
        <notification-destination
            v-for="(notificationDestination, index) in form.notification_destinations"
            :key="notificationDestination.id"
            :init-notification-destination="notificationDestination"
            :input-label="inputLabel + ' #' + (index + 1)"
            :validation-error="getValidationError(index)"
            :removable="removable"
            @remove="removeNotificationDestination(notificationDestination.id)"
        ></notification-destination>
        <div class="flex items-center justify-end mb-4">
            <button
                v-if="form.notification_destinations.length < 5"
                @click="addNotificationDestination"
                class="button is-secondary mr-4"
            >
                Add another {{ inputLabel.toLowerCase() }}
            </button>
            <button class="button" type="submit" @click.prevent="update" :disabled="form.busy">
                Update
            </button>
        </div>
    </div>
</template>

<script>
import NotificationDestination from './NotificationDestination';

export default {
    props: ['title', 'notificationDestinations', 'channel', 'inputLabel', 'updateEndpoint'],

    components: {
        NotificationDestination,
    },

    computed: {
        removable() {
            if (this.form.notification_destinations.length > 1) {
                return true;
            }

            return this.form.notification_destinations[0].destination != '';
        },
    },

    data() {
        return {
            form: new SparkForm({
                notification_destinations: [],
                channel: this.channel,
            }),
        };
    },

    mounted() {
        this.form.notification_destinations = this.notificationDestinations.map(
            (notificationDestination, index) => {
                notificationDestination.id = index;

                return notificationDestination;
            }
        );

        if (!this.form.notification_destinations.length) {
            this.form.notification_destinations.push(this.newDestination());
        }
    },

    methods: {
        async update() {
            await Spark.put(this.updateEndpoint, this.form);
        },

        addNotificationDestination() {
            this.form.notification_destinations.push(this.newDestination());
        },

        removeNotificationDestination(id) {
            const destinations = this.form.notification_destinations.filter(
                destination => destination.id !== id
            );

            if (!destinations.length) {
                destinations.push(this.newDestination());
            }

            this.$set(this.form, 'notification_destinations', destinations);
        },

        getValidationError(index) {
            return this.form.errors.get(`notification_destinations.${index}`);
        },

        newDestination() {
            return {
                id: this.form.notification_destinations.length,
                channel: this.channel,
                destination: {},
                accepts_notification_classes: [
                    'CertificateExpiresSoon',
                    'CertificateFixed',
                    'CertificateHasChanged',
                    'CertificateUnhealthy',
                    'CertificateIssued',
                    'MixedContentFixed',
                    'MixedContentFound',
                    'BrokenLinksFixed',
                    'BrokenLinksFound',
                    'UptimeCheckRecovered',
                    'UptimeCheckFailed',
                    'SiteAdded',
                ],
            };
        },
    },
};
</script>

This is the code of NotificationDestination.vue, which handles a single form.

<template>
    <div>
        <p class="alert is-danger is-small mb-2" v-show="validationError">
            {{ validationError }}
        </p>

        <div
            :is="this.channelComponentName"
            :input-label="inputLabel"
            :notification-destination="notificationDestination"
        ></div>
        <div class="notification-toggles" :class="{ 'is-removable': removable }">
            <div class="notification-toggles-left">
                <button v-if="removable" class="text-xs text-gray-500" @click="$emit('remove')">
                    Remove
                </button>
            </div>
            <div class="notification-toggles-right">
                <div v-for="toggle in toggles" :key="toggle.type" class="inline-block w-full">
                    <notification-toggle
                        :label="toggle.label"
                        :type="toggle.type"
                        :checked="acceptsNotification(toggle.type)"
                        @change="updateAcceptsNotification"
                    ></notification-toggle>
                </div>
            </div>
        </div>
    </div>
</template>

<script>
import NotificationToggle from './NotificationToggle';
import HipChat from './Channels/HipChat';
import Slack from './Channels/Slack';
import Discord from './Channels/Discord';
import Mail from './Channels/Mail';
import Pushover from './Channels/Pushover';
import Nexmo from './Channels/Nexmo';
import Webhook from './Channels/Webhook';

export default {
    props: ['initNotificationDestination', 'inputLabel', 'validationError', 'removable'],

    components: {
        NotificationToggle,
        Slack,
        Discord,
        HipChat,
        Mail,
        Pushover,
        Nexmo,
        Webhook,
    },

    computed: {
        channelComponentName() {
            return (
                this.notificationDestination.channel.charAt(0).toUpperCase() +
                this.notificationDestination.channel.slice(1)
            );
        },
    },

    data() {
        return {
            notificationDestination: {},
            toggles: _.sortBy(
                [
                    { type: 'UptimeCheckFailed', label: 'Site down' },
                    { type: 'UptimeCheckRecovered', label: 'Site recovered' },
                    { type: 'MixedContentFound', label: 'Mixed content found' },
                    { type: 'MixedContentFixed', label: 'Mixed content fixed' },
                    { type: 'BrokenLinksFound', label: 'Broken links found' },
                    { type: 'BrokenLinksFixed', label: 'Broken links fixed' },
                    { type: 'CertificateExpiresSoon', label: 'Certificate expires soon' },
                    { type: 'CertificateUnhealthy', label: 'Certificate not ok' },
                    { type: 'CertificateFixed', label: 'Certificate fixed' },
                    { type: 'CertificateIssued', label: 'Certificate issued' },
                    { type: 'CertificateHasChanged', label: 'Certificate changed' },
                    { type: 'SiteAdded', label: 'Site added to account' },
                ],
                'label'
            ),
        };
    },

    created() {
        this.notificationDestination = this.initNotificationDestination;
    },

    methods: {
        acceptsNotification(notificationType) {
            return this.notificationDestination.accepts_notification_classes.includes(
                notificationType
            );
        },

        updateAcceptsNotification(notificationClass, accepts) {
            if (accepts) {
                this.notificationDestination.accepts_notification_classes.push(notificationClass);

                return;
            }

            const newNotifificationClasses = this.notificationDestination.accepts_notification_classes.filter(
                existingNotificationClass => existingNotificationClass !== notificationClass
            );

            return (this.notificationDestination.accepts_notification_classes = newNotifificationClasses);
        },
    },
};
</script>

Here is the Slack.vue component which was responsible for rendering the Slack specific fields.

<template>
    <label class="form-group is-row">
        <span class="label">{{ inputLabel }}</span>
        <input
            placeholder="https://hooks.slack.com/services/..."
            type="text"
            v-model="notificationDestination.destination.url"
            name="webhook_url"
        />
    </label>
</template>

<script>
export default {
    props: ['notificationDestination', 'inputLabel'],
};
</script>

You don't need to go through the entire Vue code. I just want to stress that quite some code was required to make this work.

Now let's look at the Livewire component that replaces the Vue components above.

First, let's take a look at the controller that will render the view.

namespace App\Http\App\Controllers\Settings\Team\Notifications\Channels;

use App\Http\App\Controllers\Settings\Team\Notifications\Channels\Concerns\HandlesTeamNotificationDestinations;
use App\Http\App\Requests\Notifications\UpdateSlackNotificationsRequest;

class SlackTeamNotificationsController
{
    use HandlesTeamNotificationDestinations;

    public $channel = 'slack';

    public function update(UpdateSlackNotificationsRequest $request)
    {
        return $this->handleUpdateRequest($request);
    }
}

We have a controller per channel. The real meat of the functionality is in the BuildsTeamNotificationsTestView trait. When working with controllers, I generally prefer moving common functionality to traits and not to (abstract) base classes because you can apply multiple traits to a class, but you can only have one class where you can extend from.

The update method is overridden so I can use a specific form request for validation.

Here's that UpdateSlackNotificationsRequest.

namespace App\Http\App\Requests\Notifications;

use App\Domain\Notification\Rules\NotificationDestinationTypeRule;
use App\Domain\Site\Rules\UrlRule;
use Illuminate\Foundation\Http\FormRequest;

class UpdateSlackNotificationsRequest extends FormRequest
{
    public function rules()
    {
        return [
            'notification_destinations' => 'array|max:5',
            'notification_destinations.*.destination.url' => [new UrlRule()],
            'notification_destinations.*.accepts_notification_classes.*' => [new NotificationDestinationTypeRule()],
        ];
    }
}

The request makes it clear that we accept two arrays back
notification_destinations.*.destination and notification_destinations.*.accepts_notification_classes. In destination all specific configuration values of the channel are expected.accepts_notification_classes should hold all types of notification that should be sent to this notification destination.

It surprises exactly no-one that the controller for handling Nexmo notifications looks quite similar.

namespace App\Http\App\Controllers\Settings\Team\Notifications\Channels;

use App\Http\App\Controllers\Settings\Team\Notifications\Channels\Concerns\HandlesTeamNotificationDestinations;
use App\Http\App\Requests\Notifications\UpdateNexmoNotificationsRequest;

class NexmoTeamNotificationsController
{
    use HandlesTeamNotificationDestinations;

    public $channel = 'nexmo';

    public function update(UpdateNexmoNotificationsRequest $request)
    {
        return $this->handleUpdateRequest($request);
    }
}

Let's take a look at the HandlesTeamNotificationDestinations trait.

namespace App\Http\App\Controllers\Settings\Team\Notifications\Channels\Concerns;

use Illuminate\Http\Request;

trait HandlesTeamNotificationDestinations
{
    public function edit()
    {
        $channel = $this->channel;

        $notificationDestinations = currentTeam()
            ->notificationDestinationsForChannel($channel)
            ->toArray();

        return view("app.settings.team.notifications.channels.{$this->channel}", compact(
            'notificationDestinations',
            'channel'
        ));
    }

    public function handleUpdateRequest(Request $request)
    {
        currentTeam()->setNotificationDestinationsForChannel(
            $this->channel,
            $request->validated(),
        );

        $channelLabel = ucfirst($this->channel);

        flash()->success("The {$channelLabel} notification preferences have been updated.");

        return back();
    }
}

Here you can see that the actual handleUpdateRequest logic is the same for all notification channels.

In edit you see that there is a specific view per channel. Let's take a look at the app.settings.team.notifications.channels.slack view.

@component('app.sites.components.page', [
    'site' => $site,
    'breadcrumbs' => ['site-notifications', $site],
])
    <div class="card">
        <x-site-notification-header channel="slack" :site="$site" />

            <p class="help mb-4">
                Oh Dear can notify you via Slack. You can learn how to set up a Slack webhook at <a href="/docs/notifications/slack">our Slack documentation</a>.
            </p>

        <livewire:slack-notification-destinations :notificationDestinations="$notificationDestinations"/>
    </div>
@endcomponent

The view above uses the old @component notation to extend from app.sites.components.page, which contains the general application layout. In a future refactor, we'll probably refactor this to Laravel 7 style Blade components.

To render the header of the card (which contains the title and the tabs), a blade component is already used. Last, you can see that we render a Livewire component slack-notification-destinations. In a future refactor, I might wrap this up in a Blade component.

Here is the class component that backs slack-notification-destinations.

namespace App\Http\Livewire;

class SlackNotificationDestinations extends NotificationDestinations
{
    public function fields(): array
    {
        return [
            ['name' => 'url', 'label' => 'Webhook URL', 'placeholder' => 'https://hooks.slack.com/services/...'],
        ];
    }
}

So this one only holds the field definitions for the channel.

When looking at the Nexmo specific one, you'll see other fields.

namespace App\Http\Livewire;

class NexmoNotificationDestinations extends NotificationDestinations
{
    public function fields(): array
    {
        return [
            ['name' => 'apiKey', 'label' => 'API Key', 'placeholder' => 'API Key'],
            ['name' => 'apiSecret', 'label' => 'API Secret', 'placeholder' => 'API Secret', 'type' => 'password'],
            ['name' => 'from', 'label' => 'From', 'placeholder' => 'Telephone number'],
            ['name' => 'to', 'label' => 'To', 'placeholder' => 'Telephone number'],
        ];
    }
}

The meat functionality of this component is the NotificationDestinations where the channel-specific components extend from. I've added some comments to make it more clear.

namespace App\Http\Livewire;

use App\Domain\Notification\Models\NotificationDestination as NotificationDestinationModel;
use Illuminate\View\View;
use Livewire\Component;

abstract class NotificationDestinations extends Component
{
    public array $notificationDestinations = [];

    public $listeners = ['removeNotificationDestination'];

    /**
     *  Here the notification destinations from the server
     * are passed to the components.
     *
     * If there are none defined, we are going to add an empty so at least
     * an empty form is being displayed at all times.
     */
    public function mount(array $notificationDestinations): void
    {
        $notificationDestinations = old('notification_destinations', $notificationDestinations);


        if (count($notificationDestinations) === 0) {
            $notificationDestinations[] = $this->defaults();
        }

        $this->notificationDestinations = $notificationDestinations;
    }

    public function add(): void
    {
        if (! $this->canAddMoreNotificationDestinations()) {
            return;
        }

        $this->notificationDestinations[] = $this->defaults();
    }

    public function removeNotificationDestination(int $index): void
    {
        unset($this->notificationDestinations[$index]);

        if (count($this->notificationDestinations) === 0) {
            $this->notificationDestinations[] = $this->defaults();
        }
    }

    public function canAddMoreNotificationDestinations(): bool
    {
        return count($this->notificationDestinations) < 5;
    }

    public function render(): View
    {
        return view('livewire.notification-destinations');
    }

    /*
     * We are going to merge the channel-specific fields with the possible notification
     * types (these are the values that back all the checkboxes)
     */
    protected function defaults(): array
    {
        $channelSpecifiedFields = collect($this->fields())->map(function (array $field) {
            return [$field['name'] => ''];
        })->toArray();

        $notificationTypes = NotificationDestinationModel::notificationTypes()->pluck('type')->toArray();

        return array_merge(
            ['accepts_notification_classes' => $notificationTypes],
            $channelSpecifiedFields,
        );
    }

    abstract public function fields(): array;
}

And here's the notification-destinations view.

<form method="POST">
    @method('PUT')
    @csrf

    <div>
        @foreach($notificationDestinations as $i => $notificationDestination)
            <livewire:notification-destination
                :key="$i"
                :fields="$this->fields()"
                :notificationDestination="$notificationDestination"
                :index="$i"
            />

        @endforeach

        <div class="flex items-center justify-end mb-4">
            @if ($this->canAddMoreNotificationDestinations())
                <button wire:click.prevent="add" class="button is-secondary mr-4">
                    Add another
                </button>
            @endif
            <button type="submit" class="button">
                Update
            </button>
        </div>
    </div>
</form>

This view is responsible for rendering the outer form, the "Add another", and "Update" button. The form fields themselves are rendered in the livewire:notification-destination component. It gets passed the definitions of the fields and the notification destination values. Let's take a look at that component.

namespace App\Http\Livewire;

use Illuminate\View\View;
use Livewire\Component;

class NotificationDestination extends Component
{
    public int $index = 0;

    public array $notificationDestination = [];

    public array $fields = [];

    public function mount(int $index, array $notificationDestination, array $fields): void
    {
        $this->index = $index;

        $this->notificationDestination = $notificationDestination;

        $this->fields = $fields;
    }

    public function render(): View
    {
        return view('livewire.notification-destination');
    }

    public function remove(): void
    {
        $this->emitUp('removeNotificationDestination', $this->index);
    }
}

You can see, it's a straightforward component. The only thing to note here is that when remove is called, it emits up an event where the NotificationDestinations component. This is done because that component is in charge of the state. NotificationDestinations will execute removeNotificationDestination, which will update its notificationDestinations array, which will re-render the entire component.

Let's take a look at the notification-destination view.

<div class="mt-8">
    @foreach($fields as $field)
        <label class="form-group is-row">

            <span class="label">{{ $field['label'] }}</span>
            <input placeholder="{{ $field['placeholder'] }}"
                   value="{{ $notificationDestination['destination'][$field['name']] ?? '' }}"
                   type="{{ $field['type'] ?? 'text' }}"
                   name="notification_destinations[{{ $index }}][destination][{{ $field['name'] }}]"
            >
        </label>

        @error("notification_destinations.{$index}.destination.{$field['name']}")
        <div class="-mt-4 mb-4">
            <strong class="form-error">
                {{ $errors->first("notification_destinations.{$index}.destination.{$field['name']}") }}
            </strong>
        </div>
        @enderror
    @endforeach

    <div class="notification-toggles is-removable">
        <div class="notification-toggles-left">
            <button wire:click.prevent="remove" class="text-xs text-gray-500">
                Remove
            </button>
        </div>

        @include('app.settings.team.notifications.partials.notifications', [
             'enabledNotificationTypes' => $notificationDestination['accepts_notification_classes'],
             'index' => $index,
            ])
    </div>
</div>

In the code above, you can see the specific fields being rendered based on their definition.

And that is all there is to it!

In closing

Working with Livewire was fun. It enabled us to write some complex form and behaviors without having to write a single line of JavaScript. It makes these forms more maintainable and also more testable.

If you want to see these forms in action, start a free Oh Dear trial and head over to the team notifications screen. When you click "Add another", or "Remove", you might want to open your inspector so you can see the chunks of server-rendered HTML being passed to the client. Beautiful!

For more on Livewire, be sure to read the Livewire docs and follow Caleb Porzio on Twitter.

How to check which version of PHP you are running

Freek Van der Herten — Mon, 16 Mar 2020 09:49:00 +0000

When working on open source code, I like using the latest version of PHP. When developers that are not on the latest version use the package, they might see syntax errors.

You might ask why Composer doesn't protect against this? When composer.json requires the latest version, how do devs, not on the latest version, can even install the package?

Well, there seemingly are a lot of people that only upgrade the PHP version on the command line. For handling web requests, they are unknowingly using an older version of PHP. Here's how to make sure you are on the latest version of PHP on both the CLI and for handling web requests.

On the CLI type this command to see your PHP version:

php -v

To check the PHP version that handles web requests, create a .php file with this content somewhere the public directory of your app.

<?php

phpinfo();

Point your browser to that file. You will now see which version of PHP you are running. Don't forget to delete the file afterward.

How to configure and use multiple SES accounts in a Laravel app

Freek Van der Herten — Mon, 16 Mar 2020 09:48:22 +0000

When working on Mailcoach, it was unclear to me how I could use multiple SES (or Mailgun or Postmark) accounts inside a Laravel app. In this short blog post, I'd like to explain that to you.

Laravel 7 introduced the ability to configure multiple mailers. Inside the mail.php config file, there's now a mailers key when an entry for each email provider.

// in config/mail.php

'mailers' => [
    'smtp' => [
        'transport' => 'smtp',
        'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
        'port' => env('MAIL_PORT', 587),
        'encryption' => env('MAIL_ENCRYPTION', 'tls'),
        'username' => env('MAIL_USERNAME'),
        'password' => env('MAIL_PASSWORD'),
    ],

    'ses' => [
        'transport' => 'ses',
    ],

    'mailgun' => [
        'transport' => 'mailgun',
    ],

    'postmark' => [
        'transport' => 'postmark',
    ],

    'sendmail' => [
        'transport' => 'sendmail',
        'path' => '/usr/sbin/sendmail -bs',
    ],

    'log' => [
        'transport' => 'log',
        'channel' => env('MAIL_LOG_CHANNEL'),
    ],

    'array' => [
        'transport' => 'array',
    ],
],

For some of these mailers, the Laravel documentation specifies that you should add some extra configuration values in config/services.php. Here's what you should add to that file if you want to use ses.

// in config/services.php

'ses' => [
    'key' => 'your-ses-key',
    'secret' => 'your-ses-secret',
    'region' => 'a-ses-region',
],

Here's how you could send a mail using one of these configured mailers.

// send a mail using ses
Mail::mailer('ses')
    ->to($request->user())
    ->send(new YourAwesomeMailable());

// send a mail using smtp
Mail::mailer('smtp')
    ->to($request->user())
    ->send(new YourAwesomeMailable());

This works fine when you want to send mail using different email providers. But how would you send mail using different accounts on the same service? Let's say, for instance, you want to use two SES mailers? How would you do that, there's only one entry in the config/services.php file.

The answer lies in the source code! Let's take a look at the code where Laravel is reading the mail config to build the SES transport.

protected function createSesTransport(array $config)
{
    if (! isset($config['secret'])) {
        $config = array_merge($this->app['config']->get('services.ses', []), [
            'version' => 'latest', 'service' => 'email',
        ]);
    }

    $config = Arr::except($config, ['transport']);

    return new SesTransport(
        new SesClient($this->addSesCredentials($config)),
        $config['options'] ?? []
    );
}

Here you can see that if there's no secret set on the config, Laravel will look in the services config file if there are configuration values present in the ses key. So, if you specify a secret in the ses mailer in the mail config file, Laravel will use those values.

So here's how you can define and use multiple SES accounts in one Laravel app:

// in config/mail.php

'mailers' => [
    'ses' => [
        'transport' => 'ses',
        'key' => 'your-ses-key',
        'secret' => 'your-ses-secret',
        'region' => 'a-ses-region',
        'version' => 'latest',
        'service' => 'mail',
    ],

    'another-ses' => [
        'transport' => 'ses',
        'key' => 'another-ses-key',
        'secret' => 'another-ses-secret',
        'region' => 'another-ses-region',
        'version' => 'latest',
        'service' => 'mail',
    ],
],

Those versions and service keys are required too. In the source code above, you can see that Laravel only automatically adds those when you've put your configuration in services.php.

With all this in place, you can start using the mailers.

// send a mail using ses
Mail::mailer('ses')
    ->to($request->user())
    ->send(new YourAwesomeMailable());

// send a mail using another ses account
Mail::mailer('another-ses')
    ->to($request->user())
    ->send(new YourAwesomeMailable());

Laravel reads the config for the other mailers like Mailgun and Postmark in a similar fashion. So, if you need to use multiple accounts of the same service, define the config in the mail.php config file, and not in services.php.

(Thanks Taylor, for pointing me in the right direction)

Mailcoach v2 has been released with support for custom HTML editors and multiple mailers

Freek Van der Herten — Mon, 16 Mar 2020 09:37:23 +0000

A couple of months ago, my team released Mailcoach, a self-hosted solution to send out newsletters. It sends out mail via services like Amazon SES, Mailgun, Sendgrid, and Postmark. It can optionally track opens and clicks. When your email list grows, this is a much more cost-effective solution when compared to a service like Mailchimp.

Mailcoach can be used as a premium Laravel package or as a stand-alone app. When installed into a Laravel app, it can be greatly customized. The Mailcoach stand alone app can be used without knowing how to program.

Today we're releasing v2 of Mailcoach. It offers support for Laravel 7, html editors, and multiple mailers, together with a bunch of quality of life improvements. In this blog post, I'd like to walk you through these features and show some technical details.

If you already bought Mailcoach, you'll be happy to know that this is a free upgrade.

Introducing Mailcoach

If you're not familiar with Mailcoach yet, you can watch this video to see the core features in action.

Support for custom HTML editors

By default, Mailcoach uses a plain text area field to edit campaigns and tables. One of the most requested features after launching Mailcoach v1, was support for an HTML editor.

Unlayer, an easy to use HTML editor

In Mailcoach v2 we've added the ability to install editors via add on packages, so you can bring any editor you like. We've created two add-on packages ourselves. The first one brings the free version of Unlayer, a powerful WYSIWYG HTML editor to Mailcoach.

When using this editor, you don't need any knowledge of HTML to compose your campaign. It also can handle image uploads. Any uploads will be handled by our laravel-medialibrary package, but users don't need to care about that, it all happens behind the scenes.

Installing the Unlayer editor in Mailcoach is easy. You just have to require the add on package.

composer require spatie/laravel-mailcoach-unlayer

Next, you'll have to run the migration provided by the package, add the route macro, and set the editor key in the mailcoach.app config file to \Spatie\MailcoachUnlayer\UnlayerEditor::class. If you're familiar with adding packages to a Laravel app, this shouldn't take you long.

Monaco, a powerful code editor

Monaco is a powerful code editor created by Microsoft. It
provides code highlighting, auto-completion, and much more.

Installing this package is dead simple too. Just require the package...

composer require spatie/laravel-mailcoach-monaco

Install the assets...

php artisan vendor:publish --tag mailcoach-monaco-assets --force

Set the editor in the mailcoach.app config file...

'editor' => \Spatie\MailcoachMonaco\MonacoEditor::class,

And you're good to go!

Optionally, you can customize the looks of Monaco by specifying some options in the monaco key of the mailcoach.php config file.

'monaco' => [
    'theme' => 'vs-light', // vs-light or vs-dark
    'fontFamily' => 'Jetbrains Mono',
    'fontLigatures' => true,
    'fontWeight' => 400,
    'fontSize' => '16', // No units
    'lineHeight' => '24' // No units
],

When using Mailcoach as a stand-alone app, you can configure these options on the editor screen.

Using multiple mailers

Some email providers have very strict rules on sending mails. They require to keep a low bounce rate at all times. Confirmation emails have a higher chance of bouncing because they are sent to unverified email addresses.

Mailcoach v1 was built on Laravel v6. In that version of the framework, you could only define one mailer. In Laravel v7 support for multiple mailers was introduced. Mailcoach makes use of that feature to allow confirmation mails to be sent using a different mailer.

In the mailcoach.php config file, there are a couple of values that govern which mailer should be used.

return [

    /*
     * The mailer used by Mailcoach for password resets and summary emails.
     * Mailcoach will use the default Laravel mailer if this is not set.
     */
    'mailer' => null,

    /*
     * The default mailer used by Mailcoach for sending campaigns.
     */
    'campaign_mailer' => null,

    /*
     * The default mailer used by Mailcoach for confirmation and welcome mails.
     */
    'transactional_mailer' => null,

    // ...
];

On the settings screen of an email list, you can also specify which mailer should be used for that particular list.

Building Mailcoach

While building Mailcoach, I've recorded a video course on how to use Mailcoach, and how it was built. You can use these techniques to improve your projects as well. I've made a couple of videos available for free.

When creating a function, it's a good idea to keep the number of arguments as low as possible. In this video, you'll learn a technique on how to do this.

Most developers have probably have seen complex conditionals in legacy code. In this video, I show you how to refactor those.

Want to see more videos like this? Then head over to the video course page on Mailcoach.

Even if you don't require a self-hosted email solution, you could still benefit from purchasing it. Mailcoach is a labor of love, and our team polished it a lot. You can probably learn some nice things and pick up some tricks by reading the source code. The test suite of Mailcoach has been opensource, you can view it in this repo on GitHub.

In closing

Mailcoach v2 has a few smaller new features too, such as adding a delay for a welcome mail, some new customization options when sending mail, support for the latest version of laravel-medialibrary, support for Postmark ...

I'd like to thank my colleague Rias, who has done a lot getting v2 ready.

If you want to know more about Mailcoach, check out the extensive documentation. If you like what you see, consider getting your license.

Here are some more blog posts on Mailcoach

The origin story or Mailoach.
Take a look at how I added and tested a feature to delete unconfirmed users automatically.
My colleague Sebastian blogged about how JavaScript is used in the Mailcoach UI.

Mailcoach is probably the best package I've worked on. I use it myself to send my own newsletter. I hope you'll like it too!

On using arrow functions in PHP 7.4

Freek Van der Herten — Wed, 11 Mar 2020 07:45:44 +0000

In PHP 7.4 a widely requested feature landed: arrow function. In this blogpost I'd like to show you how I like to use them.

Let's start with an example from the Oh Dear codebase I tweeted out a few days ago.

In Laravel 6 and PHP 7.3 you could do this:

public static function boot()
{
    static::boot();

    static::creating(
        function (Team $team) {
            return $team->webhook_signing_secret = Str::random(32);
        }
    );
}

In Laravel 7 and PHP 7.4 you can rewrite it to this:

public static function booted()
{
   static::creating(fn (Team $team) => $team->webhook_signing_secret = Str::random(32));
}

In the code snippet above, a short closure is used. It's a bit beyond the scope of this post, but in Laravel 7, the booted lifecycle method was introduced, which will, unsuprisingly, be called we the model has booted. Using that method, you can lose the static::boot(); call from the initial code snippet.

A lot of people seemed to like it. Some didn't, and that's ok. When introducing new syntax, I don't think there's a single thing where all programmars will agree on. A comment I agree on however, is the line lenght. Luckily this can be easily fixed by moving the closure itself to it's own line.

public static function booted()
{
   static::creating(
      fn (Team $team) => $team->webhook_signing_secret = Str::random(32)
   );
}

To make the line length shorter, you could opt to remove the typehint. You could even rename the $team variable to $t, this is pretty common practice in the JavaScript. Personally I live typehints and full variable names, so personally I stick to the code snippet above.

I think it would be silly to blindly switch to short closures wherever it is technically possible. The question you should keep in mind when converting a closure to a short one is: "Does this make the code more readable?". Of course, the answer is subjective. When in doubt, I recommend just asking your team members, they're the ones that will have to read your code too.

If you use PhpStorm you can easily switch between a normal and a short closurse, so you can quickly get a feel of how it reads.

Let's end by taking a look at an example where I think short closures really shine: in collection chains (thanks for the example, Liam).

Liam Hammett

@liamhammett

@mattiasgeniar Take #2

23:34 PM - 07 Mar 2020

1 6

Writing readable PHP: decrease indentation by returning early

Freek Van der Herten — Wed, 11 Mar 2020 07:43:53 +0000

When working older code, or code submitted through PRs, I sometimes see this pattern:

public function doSomething($someParameter)
{
    /** can be any kind of test */
    if ($someParameter === 0) {
        // do the actual work
    }
}

At the beginning of the function, there's a test being performed. The actual work is in the if block.

This can be refactored by reversing the condition and using an early return.

public function doSomething($someParameter)
{
    if ($someParameter !== 0) {
        return;
    }

    // do the actual work
}

Doing this has a couple of benefits:

A level of indention is lost. This alone makes it more pleasant to read. You don't need to keep in your head that the code is wrapped in something.
Using an early return is great for humans too. When somebody reading your code is interested in the case concerning the early return, he or she doesn't need further that that early return. In the first example, there could still be some code to be executed after the if block.
When you're respecting a line length limit (you should), you now have more characters available when performing the actual work.

This technique also works when there are multiple conditions. Consider this function:

public function doSomething($someParameter, $someOtherParameter)
{
    /** can be any kind of test */
    if ($someParameter === 0) {
        if ($someOtherParameter === 0) {
            // do the actual work
        }
    }
}

By using early returns, you can rewrite it to something more readable.

public function doSomething($someParameter, $someOtherParameter)
{
    if ($someParameter !== 0) {
        return;
    }

    if ($someOtherParameter !== 0) {
        return;
    }

    // do the actual work
}

You may be tempted to rewrite combine that if statement.

if ($someParameter !== 0 || $someOtherParameter !== 0) {

In most cases, I don't do this for three reasons:

Personally, I need more brainpower to parse this.
It's easy to make mistakes (should I use || or &&) when there are more conditions
Using early returns is easier to debug. You could put a breakpoint or dump statement inside those if blocks. That way, you know which condition causes an early return.

This post summarised: whenever you see some code executed within an if block, check if you can reverse the condition to lose a level of indentation.

Behind the scenes of Flare (or How to structure big Laravel applications)

Freek Van der Herten — Wed, 04 Mar 2020 15:28:26 +0000

At Laracon AU, I gave a talk on how you can structure a big Laravel application. The codebases of both Flare and Oh Dear served as examples.

By watching this talk you'll gain some valuable insights that could be applicable to your projects as well. Enjoy!

Here are some of the resources mentioned in the video:

How to use a MySQL database on GitHub Actions

Freek Van der Herten — Wed, 04 Mar 2020 15:27:20 +0000

Recently we started using GitHub Actions to test all our packages. You can read more about our general setup in this blog post.

For most of the packages, this works great. However, some of our packages, such as Laravel Tags, use JSON functions that are not available in SQLite. Luckily it's straightforward to use a database like MySQL in GitHub Actions.

In your test workflow, you need to add MySQL to the services.

services:
    mysql:
        image: mysql:5.7
        env:
            MYSQL_ALLOW_EMPTY_PASSWORD: yes
            MYSQL_DATABASE: laravel_tags
        ports:
            - 3306
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3

In the step that executes the test, you should add an env variable DB_PORT. Laravel uses that environment variable to set up the connection to the database.

- name: Execute tests
  run: vendor/bin/phpunit
  env:
      DB_PORT: ${{ job.services.mysql.ports[3306] }}

In phpunit.xml.dist you should add this section.

<php>
    <env name="DB_CONNECTION" value="mysql"/>
    <env name="DB_USERNAME" value="root"/>
    <env name="DB_DATABASE" value="laravel_tags"/>
    <env name="DB_HOST" value="127.0.0.1" />
    <env name="DB_PORT" value="3306" />
</php>

That DB_PORT there is used for local tests. On GitHub Actions, it will be overwritten by the port set in the workflow.

And that is all there is to it. Take a look at the entire GitHub Actions workflow and phpunit config file, to get a little bit more context where you need to use the code snippets above.