DEV Community: Matthew Daly

30 Plants a Week Tracker - React Native app built for the GitHub Copilot Challenge

Matthew Daly — Sun, 19 Jan 2025 21:27:40 +0000

This is a submission for the GitHub Copilot Challenge : New Beginnings

What I Built

For a year or so now, I've been doing the "30 plants a week" thing, whereby I try to make sure that every week, I eat at least 30 different plants over the course of a week. This has been noticeably beneficial for my health.

In the past I've used the Android notes app to manage this, which works, but is less than optimal for this use case:

It's easy for duplicates to sneak in
Clearing the list at the start of a new week is a chore

30 Plants a Week Tracker is the solution I came up with. It's a very simple app that works entirely offline and stores the data locally.

It was also an opportunity to stretch my wings a bit. I used to build mobile apps for a living with Phonegap, but that's no longer maintained, and I haven't worked on a mobile app for nearly a decade. I also wanted to work with React Native and so I decided that this would be my first app built with that

Demo

Check it out.

Repo

matthewbdaly / 30-plants-tracker

React Native app for tracking consumption of 30 plants a week

Welcome to your Expo app 👋

This is an Expo project created with create-expo-app.

Get started

Install dependencies
```
npm install
```
Start the app
```
 npx expo start
```

In the output, you'll find options to open the app in a

development build
Android emulator
iOS simulator
Expo Go, a limited sandbox for trying out app development with Expo

You can start developing by editing the files inside the app directory. This project uses file-based routing.

Get a fresh project

When you're ready, run:

npm run reset-project

This command will move the starter code to the app-example directory and create a blank app directory where you can start developing.

Learn more

To learn more about developing your project with Expo, look at the following resources:

Expo documentation: Learn fundamentals, or go into advanced topics with our guides.
Learn Expo tutorial: Follow a step-by-step tutorial where you'll create…

View on GitHub

Copilot Experience

On this project, I mostly used Copilot to help me get up and running with a new framework. While I was familiar with React, I had to learn both React Native and Expo from scratch on this project. Copilot definitely helped make this easier.

A lot of the most useful help I had from Copilot was finding suitable off-the-shelf solutions for various problems, such as a storage system. It was also useful for getting basic styles set up to get me started with an unfamiliar styling system.

GitHub Models

No, I didn't use GitHub Models for this project.

Conclusion

Building my first toy project with React Native was an interesting way to learn the basics of the framework. There's clearly a lot more to learn, but I'm eager to carry on working with it in future, and developing this app further.

Dynamic image handling with Glide and GraphQL

Matthew Daly — Sat, 21 Aug 2021 16:20:00 +0000

I've used Glide on several PHP projects in the past. It's a great package that makes it really easy to dynamically generate images on the fly. For instance, if you need a particular image at both a thumbnail size and a full-screen size, it means you have the flexibility to request it at the correct size for any one part of the page. This can potentially save bandwidth since you never have to request a larger image than you technically need and scale it down with HTML attributes or CSS, nor do you have to take steps to generate thumbnails separately before they're needed. Frontend developers can adjust their code to request exactly the version they need at any one time, and can even apply certain effects dynamically.

However, by default it's a bit too open. A malicious user could request an image at an excessive size as part of a denial of service attack. For that reason, it's considered good practice to set a maximum image size, and sign all requests so that you can be sure they're authorized by your application. This works fine if your images are being requested somewhere you can sign them easily, such as in a Blade template. However, doing so in the context of a React or Vue application can potentially be much harder because they're working on the front end and so can't sign requests that are made dynamically in the same way, at least not without you exposing your application's key to the front end, which would be really risky. An API endpoint can return URLs for pre-signed specific versions of the image, but that's not as flexible as being able to adjust what you get back via query parameters on the fly.

I'm currently working on an application that uses GraphQL for the API, and for that I wanted to use Glide to enable responsive images and minimise the size of the payload. Having recently rewritten this blog in Gatsby, I'd had some exposure to the Sharp plugin, which allows you to query for an image at specific dimensions. It struck me that I could probably do something similar with GraphQL in the context of a Laravel application. Since the GraphQL queries that would return the image URLs and other data were being handled server side, they could in theory accept parameters for the required images, validate that the specified values were acceptable, and return a secure, signed URL for that image for consumption by the front end. Since the frontend was having to make an AJAX request to fetch the items to show anyway, it could request the URLs as part of the same AJAX request as the rest of the items on a page, then render the images along with the rest of the content. Here I'll demonstrate how to do this.

The first thing to do is implement a controller for returning images via Glide. This will differ between frameworks so you'd need to check the Glide documentation, but a typical Laravel version would look something like this:

<?php

namespace App\Http\Controllers;

use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Http\Request;
use League\Glide\Filesystem\FileNotFoundException;
use League\Glide\Responses\LaravelResponseFactory;
use League\Glide\ServerFactory;
use League\Glide\Signatures\SignatureException;
use League\Glide\Signatures\SignatureFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;

final class GlideController extends Controller
{
    /**
     * Storage
     *
     * @var Filesystem
     */
    private $filesystem;

    public function __construct(Filesystem $filesystem)
    {
        $this->filesystem = $filesystem;
    }

    public function __invoke(Request $request, string $path): StreamedResponse
    {
        try {
            SignatureFactory::create((string)env('APP_KEY'))->validateRequest("/images/" . $path, $request->all());
            $server = ServerFactory::create([
                'response' => new LaravelResponseFactory($request),
                'source' => $this->filesystem->getDriver(),
                'cache' => $this->filesystem->getDriver(),
                'cache_path_prefix' => '.cache',
                'base_url' => '',
                'max_image_size' => 1000 * 1000,
            ]);
            return $server->getImageResponse("images/" . $path, $request->all());
        } catch (SignatureException) {
            abort(403);
        } catch (FileNotFoundException) {
            abort(404);
        }
    }
}

Note that I'm using a single action controller here. I've found myself gravitating more and more towards these for certain use cases, and I'm not the only one. For me, the biggest benefit of these is probably more concise naming - if a controller does one thing and one thing only, and the class name adequately describes that, you end up naming it something generic, like call(). By making the controller a single callable, you don't have to make that decision since it's taken out of your hands (it must be __invoke()). I'm also a big fan of callable classes in general - they're essentially closures on steroids since you can still pass dependencies to the constructor.

The SignatureFactory line is what handles validating the signature. It's based on the app key, and checks that the path and all its parameters are correctly signed. If the signature isn't valid, it will throw an exception, thus protecting the endpoint from requests that weren't already approved. We also specify a cache location, and a maximum image size to help prevent mass-resize attacks.

You can then register this controller in the usual way:

    Route::get('/images/{path}', GlideController::class)->where('path', '.*')->name('glide');

If the images aren't going to be accessible to users who aren't logged in, it makes sense to apply whatever authentication middleware you're using to this route as well.

Now, depending on which GraphQL package you're using, defining the schema may be different. In this case, I'm using Lighthouse and the schema definition for an Eloquent model with an image would look something like this:

enum ImageFormat {
    jpg
    pjpg
    webp
}

type Image {
    id: ID!
    caption: String!
    dynamicImage(
        width: Int @rules(apply: ["numeric", "max:1000"])
        height: Int @rules(apply: ["numeric", "max:1000"])
        quality: Int @rules(apply: ["numeric", "max:100"])
        format: ImageFormat
    ): String @method
}

Here we're specifying what parameters the dynamicImage() field accepts, as well as applying some of Laravel's validation rules to the field to ensure it remains within acceptable ranges. We also use an enum to specify the supported image formats - these are actually limited to the options Glide provdes, but by specifying this as an enum, GraphQL tooling like GraphiQL can provide autocompletion for this parameter for a better developer experience when constructing queries. Note that we also use the @method directive to tell Lighthouse that this field maps to a method, not a property. If the method name differs from the field name, you would also need to specify that method name, eg @method(name: "myMethod").

Now, assuming your image was stored on the filesystem and the appropriate model field was called image_path, the method to retrieve the image URL on the model would look something like this:

use Illuminate\Support\Facades\URL;
use League\Glide\Urls\UrlBuilderFactory;

// Define model class...

    public function dynamicImage(int $width = null, int $height = null, int $quality = null, string $format = null): ?string
    {
        $builder = UrlBuilderFactory::create('/images/', (string)env('APP_KEY'));
        return URL::to($builder->getUrl($this->image_path, [
            'w' => $width,
            'h' => $height,
            'q' => $quality,
            'fm' => $format,
        ]));
    }

Note that the parameters on the model must be specified in the same order as they are defined in the GraphQL schema for them to be lined up correctly, and must have the same names. I've only added the most obviously useful parameters here, namely height, width, quality and format, but if you need them there's nothing stopping you from adding further parameters - just don't forget to update the GraphQL schema to include them too.

We can then write GraphQL queries to call dynamicImage() with whatever parameters we wish to pass through, and will get back an appropriate URL in response. For instance, consider this query:

query {
  items {
    data {
      id
      caption
      dynamicImage(width: 400, height:400, quality: 100, format: webp)
    }
  }
}

Here we assume a query has been defined called items which returns all instances of the Item GraphQL type. This would return, for each instance of the Item model, the ID, caption and the URL for an image of 100% quality, 400x400 pixels, in WebP format. Please also note that none of these arguments to dynamicImage() are required - if you leave one out, Glide will use the default value.

By calling dynamicImage() separately with different aliases, we can even fetch multiple versions of the image. In this example, we fetch it at two different sizes:

query {
  items {
    data {
      id
      caption
      large_image: dynamicImage(width: 400, height:400, quality: 100, format: webp)
      small_image: dynamicImage(width: 200, height:200, quality: 100, format: webp)
    }
  }
}

Then, when rendering a component, you could use the <picture> and <source> elements to show different versions based on media queries, as in this example of a simple React component used to render individual instances of Item:

const Card = (item) => (
  <picture>
    <source media="{max-width: 768px}" srcSet={item.small_image} />
    <source media="{min-width: 769px}" srcSet={item.large_image} />
    <img src={item.small_image} alt={item.caption} />
  </picture>
)

This enables us to serve responsive images that are appropriately sized for the current screen resolution. On mobile devices, which may not always have a connection as fast as a desktop or laptop, it also means we aren't wasting bandwidth downloading images which are larger than necessary.

Along similar lines, you could fetch both WebP and JPEG versions of an image:

query {
  items {
    data {
      id
      caption
      jpeg_image: dynamicImage(width: 400, height: 400, quality: 100, format: jpeg)
      webp_image: dynamicImage(width: 400, height: 400, quality: 100, format: webp)
    }
  }
}

Then, we can use the WebP version of the image if the web browser supports it, falling back to JPEG if it doesn't, by using the <picture> and <source> elements again in our React component:

const Card = (item) => (
  <picture>
    <source type="image/webp" srcSet={item.webp_image} />
    <img src={item.jpeg_image} alt={item.caption} />
  </picture>
)

By doing this we aren't forced to work with the lowest common denominator in terms of image formats. We can instead offer WebP to users whose browsers support it, without locking out users on older browsers.

This technique should be easy enough to apply to other PHP frameworks since Glide is fairly framework agnostic and there are GraphQL implementations for most frameworks. It should also be applicable in other languages - for example, while I'm not aware of a direct equivalent of Glide in Node.js, you could conceivably use Sharp as the basis of your own custom endpoint to serve up dynamic images based on query parameters, and then serve signed URLs for it via GraphQL.

Responsive images are something that's often overlooked when trying to build a modern web app. An approach like this makes it an awful lot easier to serve appropriately-sized images on demand, without locking front-end devs into specific known dimensions that might not fit their use case.

Lightweight Laravel - deconstructing a full stack framework

Matthew Daly — Wed, 30 Dec 2020 17:00:00 +0000

Back when I used to work with Django, I read the book Lightweight Django, and it completely changed the way I thought about building web applications. For years I’d heard the same lines parroted about how Django was too large and bloated, and something like Flask was a better bet for many applications, and this book completely blew this misconception away. By demonstrating how it was possible to break the framework apart, use just what you need, and leave out what you don’t, it showed how I could benefit from my familiarity with Django, while making it more suitable for smaller applications.

Laravel, like Django, is a full stack framework, and is often subject to similar misconceptions about bloat. But just because the framework ships with all this stuff, doesn’t mean you’re obliged to use it all. If you know you aren’t going to need all of a framework’s functionality, there’s nothing stopping you getting rid of what you don’t need, or even replacing it with something else. In this article, I’ll show you how to apply the same methodology to a Laravel application to remove what you don’t need. As part of this, we’ll be building a simple placeholder image service. This was used in Lightweight Django as it’s a good example of an application that is completely stateless, and doesn’t need sessions or a database, so it’s often seen as a bad fit for a full stack framework. Since the same applies here, it’s a good example for us too.

Getting started

Run the following command in the shell to create a new Laravel application:

$ composer create-project --prefer-dist laravel/laravel lightweight-laravel

What this actually does is as follows:

Resolve the latest release of the package laravel/laravel that will work on your system
Copy it from the repository to the specified location
Carry out any post-install scripts specified, such as creating the .env file and generating a key

However, that’s just a standardised boilerplate for Laravel applications. Most of the functionality of the framework is in the package laravel/framework, which is included as a dependency in your composer.json. This makes sense, because by keeping as much of the actual framework out of the starter boilerplate and in a separate repository, it minimises the work required to update the application to a new version. It also means you can strip that boilerplate down to remove references to things you don’t need, and even create your own custom boilerplates to save you work in future.

Stripping down the boilerplate

Let’s start stripping out the things we don’t need. Since our application is stateless, we have no need whatsoever of a database, so we can delete the app/Models and database folders. We’ll want to support Redis for the cache, so we can’t delete the file config/database.php, but we can remove any references to the database other than Redis from that file. We can delete some other files from the config/ folder, namely auth.php, broadcasting.php, filesystems.php, mail.php, queue.php, services.php and session.php.

We also don’t need a lot of the middleware that ships with Laravel. If you go into the file app/Http/Kernel.php you’ll see that it assigns some middleware as global, some to the web and api groups, and some as optional route middleware. In this file:

We don’t need to make any POST requests to this application, so we can lose the ValidatePostSize middleware from the global middleware entirely
The web group relates to cookies, sessions, CSRF, authentication and handling routing with substitute bindings. Since we don’t need any of that we can empty this group entirely
The auth, auth.basic, can, guest, password.confirm, and verified route middleware is also surplus to requirements and can go

As this change is a bit fiddly, here’s a patch, which may be easier to read:

From 6bc87e9602e839d5635963b6d740279b2dbcf16b Mon Sep 17 00:00:00 2001
From: Matthew Daly <Matthew Daly 450801+matthewbdaly@users.noreply.github.com>
Date: Wed, 30 Dec 2020 11:54:56 +0000
Subject: [PATCH] Removed unwanted middleware

---
 app/Http/Kernel.php | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/app/Http/Kernel.php b/app/Http/Kernel.php
index 30020a5..10e150d 100644
--- a/app/Http/Kernel.php
+++ b/app/Http/Kernel.php
@@ -18,7 +18,6 @@ class Kernel extends HttpKernel
         \App\Http\Middleware\TrustProxies::class,
         \Fruitcake\Cors\HandleCors::class,
         \App\Http\Middleware\PreventRequestsDuringMaintenance::class,
- \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
         \App\Http\Middleware\TrimStrings::class,
         \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
     ];
@@ -30,13 +29,6 @@ class Kernel extends HttpKernel
      */
     protected $middlewareGroups = [
         'web' => [
- \App\Http\Middleware\EncryptCookies::class,
- \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
- \Illuminate\Session\Middleware\StartSession::class,
- // \Illuminate\Session\Middleware\AuthenticateSession::class,
- \Illuminate\View\Middleware\ShareErrorsFromSession::class,
- \App\Http\Middleware\VerifyCsrfToken::class,
- \Illuminate\Routing\Middleware\SubstituteBindings::class,
         ],

         'api' => [
@@ -53,14 +45,8 @@ class Kernel extends HttpKernel
      * @var array
      */
     protected $routeMiddleware = [
- 'auth' => \App\Http\Middleware\Authenticate::class,
- 'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
         'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
- 'can' => \Illuminate\Auth\Middleware\Authorize::class,
- 'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
- 'password.confirm' => \Illuminate\Auth\Middleware\RequirePassword::class,
         'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
         'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
- 'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
     ];
 }
-- 
2.28.0

These changes also mean a lot of the service providers and facades are now redundant and can be removed from the application. If you go into config/app.php you can remove AuthServiceProvider, BroadcastServiceProvider, CookieServiceProvider, MailServiceProvider, NotificationServiceProvider, PaginationServiceProvider, PasswordResetServiceProvider, SessionServiceProvider and TranslationServiceProvider from the providers section, as well as the commented-out local BroadcastServiceProvider. You can also delete the facades for Auth, Cookie, DB, Eloquent, Gate, Lang, Mail, Notification, Password, Queue, Schema, Session, and Storage.

Again, here’s a patch of the required changes:

From 66be3b836706ef488b890cdae6e97d4fc6195dd6 Mon Sep 17 00:00:00 2001
From: Matthew Daly <Matthew Daly 450801+matthewbdaly@users.noreply.github.com>
Date: Wed, 30 Dec 2020 12:10:25 +0000
Subject: [PATCH] Removed unused service providers and facades

---
 config/app.php | 26 --------------------------
 1 file changed, 26 deletions(-)

diff --git a/config/app.php b/config/app.php
index 2a2f0eb..b7a38c8 100644
--- a/config/app.php
+++ b/config/app.php
@@ -139,26 +139,17 @@ return [
         /*
          * Laravel Framework Service Providers...
          */
- Illuminate\Auth\AuthServiceProvider::class,
- Illuminate\Broadcasting\BroadcastServiceProvider::class,
         Illuminate\Bus\BusServiceProvider::class,
         Illuminate\Cache\CacheServiceProvider::class,
         Illuminate\Foundation\Providers\ConsoleSupportServiceProvider::class,
- Illuminate\Cookie\CookieServiceProvider::class,
         Illuminate\Database\DatabaseServiceProvider::class,
         Illuminate\Encryption\EncryptionServiceProvider::class,
         Illuminate\Filesystem\FilesystemServiceProvider::class,
         Illuminate\Foundation\Providers\FoundationServiceProvider::class,
         Illuminate\Hashing\HashServiceProvider::class,
- Illuminate\Mail\MailServiceProvider::class,
- Illuminate\Notifications\NotificationServiceProvider::class,
- Illuminate\Pagination\PaginationServiceProvider::class,
         Illuminate\Pipeline\PipelineServiceProvider::class,
         Illuminate\Queue\QueueServiceProvider::class,
         Illuminate\Redis\RedisServiceProvider::class,
- Illuminate\Auth\Passwords\PasswordResetServiceProvider::class,
- Illuminate\Session\SessionServiceProvider::class,
- Illuminate\Translation\TranslationServiceProvider::class,
         Illuminate\Validation\ValidationServiceProvider::class,
         Illuminate\View\ViewServiceProvider::class,

@@ -170,9 +161,6 @@ return [
          * Application Service Providers...
          */
         App\Providers\AppServiceProvider::class,
- App\Providers\AuthServiceProvider::class,
- // App\Providers\BroadcastServiceProvider::class,
- App\Providers\EventServiceProvider::class,
         App\Providers\RouteServiceProvider::class,

     ],
@@ -193,35 +181,21 @@ return [
         'App' => Illuminate\Support\Facades\App::class,
         'Arr' => Illuminate\Support\Arr::class,
         'Artisan' => Illuminate\Support\Facades\Artisan::class,
- 'Auth' => Illuminate\Support\Facades\Auth::class,
         'Blade' => Illuminate\Support\Facades\Blade::class,
         'Broadcast' => Illuminate\Support\Facades\Broadcast::class,
         'Bus' => Illuminate\Support\Facades\Bus::class,
         'Cache' => Illuminate\Support\Facades\Cache::class,
         'Config' => Illuminate\Support\Facades\Config::class,
- 'Cookie' => Illuminate\Support\Facades\Cookie::class,
         'Crypt' => Illuminate\Support\Facades\Crypt::class,
- 'DB' => Illuminate\Support\Facades\DB::class,
- 'Eloquent' => Illuminate\Database\Eloquent\Model::class,
- 'Event' => Illuminate\Support\Facades\Event::class,
         'File' => Illuminate\Support\Facades\File::class,
- 'Gate' => Illuminate\Support\Facades\Gate::class,
         'Hash' => Illuminate\Support\Facades\Hash::class,
         'Http' => Illuminate\Support\Facades\Http::class,
- 'Lang' => Illuminate\Support\Facades\Lang::class,
         'Log' => Illuminate\Support\Facades\Log::class,
- 'Mail' => Illuminate\Support\Facades\Mail::class,
- 'Notification' => Illuminate\Support\Facades\Notification::class,
- 'Password' => Illuminate\Support\Facades\Password::class,
- 'Queue' => Illuminate\Support\Facades\Queue::class,
         'Redirect' => Illuminate\Support\Facades\Redirect::class,
         // 'Redis' => Illuminate\Support\Facades\Redis::class,
         'Request' => Illuminate\Support\Facades\Request::class,
         'Response' => Illuminate\Support\Facades\Response::class,
         'Route' => Illuminate\Support\Facades\Route::class,
- 'Schema' => Illuminate\Support\Facades\Schema::class,
- 'Session' => Illuminate\Support\Facades\Session::class,
- 'Storage' => Illuminate\Support\Facades\Storage::class,
         'Str' => Illuminate\Support\Str::class,
         'URL' => Illuminate\Support\Facades\URL::class,
         'Validator' => Illuminate\Support\Facades\Validator::class,
-- 
2.28.0

There are a few service providers that ideally we’d strip out but are tightly integrated into the framework. For instance, the database and queue service providers are both used by some Artisan commands, and it’s not very practical to disable only those commands, so removing them will stop Artisan from working. If you don’t mind running the development server manually, you can go ahead and remove these.

Building the application

Now, let’s set out how our application will work. We will have two routes:

A route that accepts width and height parameters in the route itself, and responds with a PNG response sized accordingly
A route that returns a simple HTML homepage

You’ve no doubt seen various novelty placeholder sites like placekitten.com for use in web projects, and this will be similar to that. We’ll use a simple black image with the dimensions in white text, but you should be able to use this as the basis of a more sophisticated placeholder service, such as if you wanted to use branded images for a particular client.

Since the home page will be fairly straightforward, let’s do that first. Delete the existing resources/views/welcome.blade.php file and save this to resources/views/home.blade.php:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Laravel Placeholder Images</title>
    <link href="{{ mix('css/app.css') }}" rel="stylesheet">
</head>
<body>
    <h1>Laravel Placeholder Images</h1>
    <p>This server can be used for serving placeholder
    images for any web page.</p>
    <p>To request a placeholder image of a given width and height
    simply include an image with the source pointing to
    <b>/image/&lt;width&gt;x&lt;height&gt;/</b>
    on this server such as:</p>
    <pre>
        &lt;img src="{{ $example }}" &gt;
    </pre>
    <h2>Examples</h2>
    <ul>
        <li><img src="{{{ route('placeholder', ['width' => 50, 'height' => 50]) }}}"></li>
        <li><img src="{{{ route('placeholder', ['width' => 100, 'height' => 50]) }}}"></li>
        <li><img src="{{{ route('placeholder', ['width' => 50, 'height' => 100]) }}}"></li>
    </ul>
</body>
</html>

Note we’re using the route() helper to add some example images, even though it’s not in place yet. Add this route to your routes/web.php as well:

Route::get('/', function () {
    return view('home', [
        'example' => route('placeholder', ['width' => 50, 'height' => 50]),
    ]);
});

Again, note that we’re using the route() helper to get the URL for the placeholder image. Next, we need to create the outline of the route for getting the placeholders:

Route::get('/placeholder/{width}x{height}', function (int $width, int $height) {
})->where(['width' => '[0-9]+', 'height' => '[0-9]+'])
    ->name('placeholder');

Due to the limited scope of this application, we won’t bother with full controllers, but you can add them if you wish. Note we’ve specified the name placeholder and set a regex to validate the width and height parameters.

Now let’s populate the callback to generate a PNG file.

Route::get('/placeholder/{width}x{height}', function (int $width, int $height) {
    if (!$img = imagecreatetruecolor($width, $height)) {
        abort();
    }
    $textColour = imagecolorallocate($img, 255, 255, 255);
    imagestring($img, 1, 5, 5, "$width X $height", $textColour);
    ob_start();
    imagepng($img);
    $file = ob_get_contents();
    ob_end_clean();
    return response()->make($file, 200, [
        'Content-type' => 'image/png'
    ]);
})->where(['width' => '[0-9]+', 'height' => '[0-9]+'])
    ->name('placeholder');

We’ll also add some very basic CSS to the provided CSS file:

body {
    text-align: center;
}

ul {
    list-type: none;
}

li {
    display: inline-block;
}

Don’t forget to build this with npm install && npm run production too.

If you now run php artisan serve you should be able to see that it works - the homepage renders, and the embedded images are pulled in OK. However, there are three potential issues:

The images themselves are regenerated each time. Since they never change, it’s a no-brainer to cache them indefinitely for the best performance, and if we do need to change them in the future we can just flush the cache to resolve this
Similarly, we should use ETags to allow the application to tell the browser when the image has changed
There’s no limit on how large images can be, so a malicious user could request a huge image to break the system

Let’s tackle these in order. First, let’s create some middleware to handle the caching:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;

final class CacheImages
{
    /**
     * Handle an incoming request.
     *
     * @param \Illuminate\Http\Request $request
     * @param \Closure $next
     * @return mixed
     */
    public function handle(Request $request, Closure $next)
    {
        $key = sprintf("%d.%d", $request->width, $request->height);
        return Cache::rememberForever($key, function () use ($next, $request) {
            return $next($request);
        });
    }
}

We construct a cache key from the request width and height, and use the Cache::rememberForever() method to cache the response. We then register this middleware as route middleware in app\Http\Kernel.php:

    protected $routeMiddleware = [
        'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
        'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
        'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
        'cache.images' => \App\Http\Middleware\CacheImages::class,
    ];

And apply it to the image route:

Route::get('/placeholder/{width}x{height}', function (int $width, int $height) {
    if (!$img = imagecreatetruecolor($width, $height)) {
        abort();
    }
    $textColour = imagecolorallocate($img, 255, 255, 255);
    imagestring($img, 1, 5, 5, "$width X $height", $textColour);
    ob_start();
    imagepng($img);
    $file = ob_get_contents();
    ob_end_clean();
    return response()->make($file, 200, [
        'Content-type' => 'image/png'
    ]);
})->where(['width' => '[0-9]+', 'height' => '[0-9]+'])
  ->name('placeholder')
  ->middleware('cache.images');

Next, let’s set ETags on our images. Laravel comes with the cache.headers middleware, which we can easily wrap around our placeholder route:

Route::middleware('cache.headers:public;etag')->group(function () {
    Route::get('/placeholder/{width}x{height}', function (int $width, int $height) {
        if (!$img = imagecreatetruecolor($width, $height)) {
            abort();
        }
        $textColour = imagecolorallocate($img, 255, 255, 255);
        imagestring($img, 1, 5, 5, "$width X $height", $textColour);
        ob_start();
        imagepng($img);
        $file = ob_get_contents();
        ob_end_clean();
        return response()->make($file, 200, [
            'Content-type' => 'image/png'
        ]);
    })->where(['width' => '[0-9]+', 'height' => '[0-9]+'])
      ->name('placeholder')
      ->middleware('cache.images');
});

Finally, let’s handle the dimensions issue. Again, this is something that is probably best handled in middleware since that way it can be rejected before the point it gets to the route handler. All we need to do is to check to see if the width and height parameters exceed the intended value, and throw an error in the middleware:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;

final class ValidateImageDimensions
{
    /**
     * Handle an incoming request.
     *
     * @param \Illuminate\Http\Request $request
     * @param \Closure $next
     * @return mixed
     */
    public function handle(Request $request, Closure $next)
    {
        if ($request->width > 2000 || $request->height > 2000) {
            abort(422, 'Height and width cannot exceed 2000 pixels');
        }
        return $next($request);
    }
}

    protected $routeMiddleware = [
        'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
        'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
        'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
        'cache.images' => \App\Http\Middleware\CacheImages::class,
        'validate.images' => \App\Http\Middleware\ValidateImageDimensions::class,
    ];

And apply it to the image route:

Route::middleware('cache.headers:public;etag')->group(function () {
    Route::get('/placeholder/{width}x{height}', function (int $width, int $height) {
        if (!$img = imagecreatetruecolor($width, $height)) {
            abort();
        }
        $textColour = imagecolorallocate($img, 255, 255, 255);
        imagestring($img, 1, 5, 5, "$width X $height", $textColour);
        ob_start();
        imagepng($img);
        $file = ob_get_contents();
        ob_end_clean();
        return response()->make($file, 200, [
            'Content-type' => 'image/png'
        ]);
    })->where(['width' => '[0-9]+', 'height' => '[0-9]+'])
      ->name('placeholder')
      ->middleware(['validate.images', 'cache.images']);
});

And we’re done! We now have a basic, but functional, stateless Laravel application that’s been stripped of a lot of the unnecessary functionality. There are a few further changes that could be made to expand this if necessary, such as:

Amend the project to allow requesting different image formats using an additional route parameter (hint - you’ll want to use something like Intervention for this)
Serve different images, either by using one as a starting template so they are all branded the same, or specifying one from several options in the URL, such as with PlaceCage

However, I will leave these as an exercise for the reader. The code for this project is available on Github if you get stuck at any point.

Hopefully, this article has given you some food for thought about how you can use Laravel for applications you might have previously considered too small to use it for. Don’t worry too much about removing something that you need to add later - version control means you can always retrieve it if it turns out you do need it later. I’d also add that potentially the same approach can be applied to other full stack PHP frameworks, though you’ll have to do some exploring on your own to determine this.

What I want in a PHP CMS

Matthew Daly — Mon, 28 Sep 2020 14:50:48 +0000

I maintain a custom PHP legacy CMS for a client, and have also been building a micro-CMS as a learning project, so I’ve spent quite a lot of time in the last few years thinking about how content should be managed, and how applications to manage it should work.

I’ve also at least tinkered with a few different content management systems down the years, and I’ve found it depressing how many times Wordpress has been the default choice, despite it being probably the worst CMS I’ve ever had the gross misfortune to use. The argument that “it’s easy to install and use” doesn’t really hold water given that in my experience most users setting up a new Wordpress site don’t go through the five-minute install, but use their shared hosting provider’s setup wizard, which typically also supports several other content management systems. Also, it just does not make sense to optimise a short five minute install that will never be repeated for that site over the rest of the workflow for maintaining the site, possibly for years - I’d rather have something that takes a bit more time to do the initial set up, but is easier to maintain.

So, what do I want in a PHP CMS? Here’s my thoughts on my ideal CMS solution.

Managed entirely with Composer

Creating a new site using a CMS should be as simple as running something like the following command:

$ composer create-project --prefer-dist my/cms newsite

And updating it should be as simple as running the following:

$ composer update

Installing a plugin should be a case of running this:

$ composer require my/plugin-foo

It should then be possible to activate the plugin simply by listing it in a config file.

As far as possible, all of the functionality of the CMS should be contained in a single “core” package, and plugins should be their own Composer packages that can be installed, and then switched on and off in a simple config file. The initial creation step should be a case of checking out a boilerplate that contains only the absolute minimum - a front controller, a starting configuration, front end tooling, and some views - and gets the rest of the functionality from the core package.

Allow creating custom site boilerplates

It should be possible to create and publish alternative boilerplates.

For instance, if a CMS provides a default starting boilerplate that ships with Bootstrap, VueJS and Laravel Mix, I should be able to fork it, replace Bootstrap with Tailwind and Vue with React, and then use my version for future projects without having to spend a lot of time maintaining the fork.

Similarly, if there are certain plugins I use all the time, it should be possible to include those plugins as dependencies in my composer.json so that when I create a new project from my boilerplate, they’re present right from the start and I don’t have to faff around downloading and configuring them manually.

Plugin API should work like a framework

The best practices we’ve all spent years learning shouldn’t go out the window when working with a CMS. A good CMS should feel familiar if you’ve got some experience working in MVC frameworks, and it should embrace PSR standards. Adding a route should largely be a matter of writing a controller, mapping it to a route, and adding a view file, just as it would be in a framework

There’s always going to be some things that need to be CMS-specific, because registering things like routes is more complex in a general purpose CMS than a custom web app as they can be defined in multiple arbitrary places. These can be handled by triggering events at various points in the CMS application’s lifecycle, so that plugin authors can set up listeners to do things such as register routes, add new view helpers and so on.

Focused exclusively on content, not presentation

I’m increasingly convinced that the ability to amend presentation in a CMS is a misfeature. The purpose of a CMS is to manage content, not presentation, and making it able to amend presentation potentially gives unskilled site owners enough rope to hang themselves with, while making it actively harder for us devs.

I’ve certainly seen enough sites that a client has completely messed up after being given access to change the presentation in Wordpress, and because it’s stored in the database it’s not possible to roll back the changes easily the way it would be if the styling was stored in version control. And it’s definitely quicker for an experienced front end developer to edit a CSS file than to use Wordpress’s own tools for amending styling.

Use a proper templating system

As a templating language, PHP sucks:

It’s too easy to overlook escaping variables properly
Handling partials is difficult
There’s always the temptation to put in more logic than is advisable in the view layer, especially when deadlines are tight

Using a dedicated templating language, rather than a full programming language, in the view layer, means that entire classes of issues can be completely eradicated from the layer of the application that the developers who work with the CMS have the most dealings with. Developers are forced to move more complex logic into dedicated helpers, and can’t just leave it in the template “until we have time to clear it up”, which is often never.

Twig is solid, reliable, fast, easy to extend, and similar enough to other templating languages such as Handlebars and Django’s templates that if you’ve used any of those you can adapt easily, and it should probably be your first choice. Blade is also a solid choice, and if you want something whose syntax is not dissimilar to PHP you should probably consider Plates.

Configuration with version control in mind

Wordpress does this particularly badly because it actively encourages storing sensitive data, such as database credentials, in a PHP file (which is then kept in the web root…). A good, solid way to store configuration details in PHP is to store generic details (for instance, a list of the active plugins, which will be the same for production and the local copy developers run) for that project in either a YAML or PHP file, and store install-specific details in either a .env file, or as environment variables.

Custom content types

It should be easy to create a new content type, and define specific fields for that content type. For instance, if I’m building a recipe site, I should be able to define a Recipe type that has the following attributes:

Ingredients
Cover image
Title
Method

Then all Recipe instances should have those attributes, and it shouldn’t be necessary to bastardise a different content type to make it work properly. It should also be possible to lock down the ability to create custom content types so it’s either limited to admins, or they’re defined in code, so end users can’t create arbitrary content types.

Custom taxonomies

It should be possible to define your own custom taxonomies for content. Continuing the Recipe example above, we should be able to define three sorts of taxonomy:

Dietary requirements (eg vegetarian, vegan, gluten-free etc)
Meal (eg breakfast, lunch, dinner, snacks)
Region (eg Indian, Chinese, Italian)

A taxonomy should be appropriately named, and again it shouldn’t be necessary to abuse generic categories and tags to categorise content. As with the content types, it should also be possible to lock them down.

A better solution than rich text for managing content

Rich text is not a great solution for more complex page layouts, and tends to be abused horribly to do all sorts of things. There’s a tendency to dump things like snippets for Google Maps, tables, galleries, Javascript widgets and many more into rich text. This means that it also loses the semantic value of the content - rather than being a paragraph, then a map of the local area, then a photo carousel, then another paragraph, it’s just a single blob of text. This can’t be easily migrated to another solution if, say, you decide to swap Google Maps for Open Streetmap, and change one carousel for another, without going through and manually replacing every map and carousel, which is a chore.

Wagtail isn’t a PHP CMS, but it has an interesting approach to rich text handling for complex content, inspired by Sir Trevor, based around blocks of different types. The Gutenberg editor in Wordpress 5.0 and up isn’t a million miles away from this, either. For simpler sites, it’s probably better to limit users to a Markdown editor and add helpers for adding more complex functionality directly in the template, such as a gallery helper.

A decent command-line runner

There are always going to be certain tasks that are best done from the command line. A decent CMS should have a command line tool that:

Allows appropriate admin tasks, such as going into maintenance mode and flushing caches, to be done from the command line
Can be easily extended by plugin authors to add their own commands
Assists developers when working locally, such as by generating boilerplate when necessary (so, for instance, you can run a command to generate the skeleton for a new plugin)

There’s no excuse not to do this when building a CMS. Symfony’s console component is solid, easy to work with, and a good base for whatever commands you need to write.

Headless as an option

The rise of headless CMS’s, both as a service and as software packages, hasn’t surprised me. Nowadays it’s quite common to have to publish the same content to multiple channels, which might be one or more websites, as well as mobile apps, and it makes sense to be able to centralise that content in one place rather than have to copy it in some fashion.

It’s therefore very useful to have an API that can retrieve that content for republishing. The same API can also be used with Javascript libraries like React and Vue to build sophisticated frontends that consume that data.

Which solutions do this best?

You’ll probably have got the idea at this point that Wordpress isn’t my first choice. It was created in a different era, and hasn’t kept up well compared to many of its contemporaries, and there are many technical issues with it that are at this point effectively impossible to ever fix. For instance, you could potentially store the post meta in the same table as the rest of the post data by using a JSON field in current versions of MySQL, which would make it more performant, but it seems unlikely it could ever be migrated across to use that solution.

Frustratingly, its mindshare means it’s erroneously seen as some kind of “gold standard” by inexperienced developers and non-technical clients, and there seems to be a common misconception that it’s the only solution that lets users update the content themselves (when in fact that’s the whole point of ANY CMS). Using Bedrock and a theme system like Sage that supports a proper templating system helps solve some of the problems with Wordpress, but not all.

I have tried a few solutions that come very close to what I want:

Bolt seems from what I’ve seen so far to be effectively a “better Wordpress” in that the interface and functionality is broadly familiar to anyone already used to Wordpress, but it uses Twig, is built in Symfony, and has a proper command-line runner. I haven’t tried it since version 4 was released a few days back, so I will probably give it a spin before long.
Grav looks like a great solution for brochure sites. I’ve long thought that these sites, which often run on shared hosting, don’t really need a database-backed solution, and a flat-file solution is probably a better bet in most cases. Grav is simple to set up and configure, has a decent admin interface, and uses Twig for the views, making it easy to theme.
Statamic is my current favourite and ticks almost all of the boxes mentioned above. It’s built on Laravel, and can be added to an existing Laravel site if required. It also allows you access to the full power of the underlying framework if you need it, and ships with a decent front-end boilerplate that includes Tailwind. The only downside compared to Wordpress is that it’s a paid-for solution, but the price is entirely reasonable, and if it’s for a client build you’ll not only save on all the premium plugins you don’t need, but you’ll probably save time on the site build.

Payment shouldn’t be an issue if you’re doing client work, unless the cost is huge. You’re getting paid for building something, and if buying an off-the-shelf product saves you time, it’s well worth it. Back when Laravel Nova was first released, a lot of people were complaining that it wasn’t free, but that was neither here nor there - the cost is only equivalent to a few hours of an experienced developer’s time, and it would take a lot longer to build out the same functionality, and the same is true of any half-decent CMS. In the early days of the web, one company I used to work for sold a CMS that was considered cheap by the standards of the time at £495, plus £96 a year, for the entry level version - Statamic is significantly cheaper than that.

It’s always a good idea to be aware of the various CMS options around. Wordpress isn’t a great solution and there are plenty of options that are technically better, easier to use, more secure, and work out cheaper when you consider the total cost of ownership. I’ll probably be favouring Statamic for the foreseeable future when building content-based websites, but that doesn’t mean I won’t look elsewhere from time to time.

Flow typed AJAX responses with React Hooks

Matthew Daly — Sat, 13 Jun 2020 12:50:41 +0000

I’m a big fan of type systems in general. Using Psalm to find missing type declarations and incorrect calls in PHP has helped me out tremendously. However, I’m not a big fan of Typescript. The idea of creating a whole new language, primarily just to add types to Javascript, strikes me as a fundamentally bad idea given how many languages that compile to Javascript have fallen by the wayside. Flow seems like a much better approach since it adds types to the language rather than creating a new language, and I’ve been using it on my React components for a good while now. However, there are a few edge cases that can be difficult to figure out, and one of those is any generic AJAX component that may be reused for different requests.

A while back I wrote the following custom hook, loosely inspired by axios-hooks (but using the Fetch API) to make a query to a GraphQL endpoint:

import { useCallback, useState, useEffect } from "react";

function useFetch(url, query) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(false)

  const fetchData = useCallback(() => {
    setLoading(true);
    fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
      body: JSON.stringify({query: query})
    }).then(r => r.json())
      .then((data) => {
        setData(data.data);
        setLoading(false);
        setError(false);
      });
  }, [url, query]);

  useEffect(() => {
    fetchData();
  }, [url, query, fetchData]);

  return [{
    data: data,
    loading: loading,
    error: error
  }, fetchData];
};

export default useFetch;

When called, the hook receives two parameters, the URL to hit, and the query to make, and returns an array that contains a function for reloading, and an object containing the following values:

loading - a boolean that specifies if the hook is loading right now
error - a boolean that specifies if an error has occurred
data - the response data from the endpoint, or null

Using this hook, it was then possible to make an AJAX request when a component was loaded to populate the data, as in this example:

import React from 'react';
import useFetch from './Hooks/useFetch';
import marked from 'marked';
import './App.css';

function App() {
  const url = `/graphql`;
  const query = `query {
    posts {
      title
      slug
      content
      tags {
        name
      }
    }
  }`;

  const [{data, loading, error}] = useFetch(url, query);

  if (loading) {
    return (<h1>Loading...</h1>);
  }

  if (error) {
    return (<h1>Error!</h1>);
  }

  const posts = data ? data.posts.map((item) => (
    <div key={item.slug}>
      <h2>{item.title}</h2>
      <div dangerouslySetInnerHTML={{__html: marked(item.content)}} />
    </div>
  )) : [];
  return (
    <div className="App">
      {posts}
    </div>
  );
}

export default App;

This hook is simple, and easy to reuse. However, it’s difficult to type the value of data correctly, since it will be different for different endpoints, and given that it may be reused for almost any endpoint, you can’t cover all the acceptable response types. We need to be able to specify the response that is acceptable in that particular context.

Generics to the rescue

Flow provides a solution for this in the shape of generic types. By passing in a polymorphic type using <T> in the function declaration, we can then refer to that type when specifying what data should look like:

//@flow
import { useCallback, useState, useEffect } from "react";

function useFetch<T>(url: string, query: string): [{
  data: ?T,
  loading: boolean,
  error: boolean
}, () => void] {
  const [data, setData]: [?T, ((?T => ?T) | ?T) => void] = useState(null);
  const [loading, setLoading]: [boolean, ((boolean => boolean) | boolean) => void] = useState(false);
  const [error, setError]: [boolean, ((boolean => boolean) | boolean) => void] = useState(false)

  const fetchData = useCallback(() => {
    setLoading(true);
    fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
      body: JSON.stringify({query: query})
    }).then(r => r.json())
      .then((data) => {
        setData(data.data);
        setLoading(false);
        setError(false);
      });
  }, [url, query]);

  useEffect(() => {
    fetchData();
  }, [url, query, fetchData]);

  return [{
    data: data,
    loading: loading,
    error: error
  }, fetchData];
};

export default useFetch;

Then, when calling the hook, we can define a type that represents the expected shape of the data (here called <Data>, and specify that type when calling the hook, as in this example:

//@flow
import React from 'react';
import useFetch from './Hooks/useFetch';
import marked from 'marked';
import './App.css';

type Data = {
  posts: Array<{
    title: string,
    slug: string,
    content: string,
    name: Array<string>
  }>
};

function App() {
  const url = `/graphql`;
  const query = `query {
    posts {
      title
      slug
      content
      tags {
        name
      }
    }
  }`;

  const [{data, loading, error}] = useFetch<Data>(url, query);

  if (loading) {
    return (<h1>Loading...</h1>);
  }

  if (error) {
    return (<h1>Error!</h1>);
  }

  const posts = data ? data.posts.map((item) => (
    <div key={item.slug}>
      <h2>{item.title}</h2>
      <div dangerouslySetInnerHTML={{__html: marked(item.content)}} />
    </div>
  )) : [];
  return (
    <div className="App">
      {posts}
    </div>
  );
}

export default App;

That way, we can specify a completely different shape for our response data every time we call a different endpoint, without creating a different hook for every different endpoint, and still enjoy properly typed responses from our hook.

Generics can be useful for many other purposes, such as specifying the contents of collections. For instance, if you had a Collection object, you could use a generic type to specify that any one instance must consist of instances of a given type. Flow would then flag it as an error if you assigned an item of the wrong type to that collection, thus making some unit tests redundant.

Does technical debt make burnout more likely?

Matthew Daly — Thu, 14 May 2020 09:24:13 +0000

I've been working on a large legacy project for just over two years, and it's been my primary focus at work. It's built in a now-deprecated PHP framework (Zend 1), and has an awful lot of technical debt.

I've experienced developer burnout in the past, and mostly know how to avoid it, but I've noticed it's considerably harder to avoid it with this project. The mental burden of trying to figure out what's going on at any point is much higher than with a project with less technical debt - the inconsistency between how different objects work and confusing names of variables and methods means I spend far more time figuring out what's going on, and it stresses me out. Also the so-called "flow" state of maximum productivity simply isn't possibe to achieve, so I'm far less productive than I would be on a better-written project, and the drop in productivity makes it more likely deadlines are missed, causing even more stress. Tools like Psalm are helpful in finding what items are and adding type hints, but they're not a panacea, and at the current rate it's going to be a long time before the project is in a state where I'm happy with it.

Have you noticed a relationship between working on projects with high levels of technical debt and burnout? Has a particularly bad project caused you significant stress, or have you seen a code base you'd be working on and not taken/left a job for that reason? And how can we get across to non-technical colleagues the effect a particularly bad code base can have on developer productivity and well-being?

Caching the Laravel user provider with a decorator

Matthew Daly — Wed, 11 Mar 2020 21:20:14 +0000

A couple of years ago I posted this article about constructing a caching user provider for Laravel. It worked, but with the benefit of hindsight I can now see that there were a number of issues with this solution:

Because it extended the existing Eloquent user provider, it was dependent on the internals of that remaining largely the same - any change in how that worked could potentially break it
For the same reason, if you wanted to switch to a different user provider, you’d need to add the same functionality to that provider, either by writing a new provider from scratch or extending an existing one

I’ve used the decorator pattern a few times in the past, and it’s a good fit for situations like this where you want to add functionality to something that implements an interface. It allows you to separate out one part of the functionality (in this case, caching) into its own layer, so it’s not dependent on any one implementation and can wrap any other implementation of that same interface you wish. Also, as long as the interface remains the same, there likely won’t be any need to change it when the implementation that is wrapped changes. Here I’ll demonstrate how to create a decorator to wrap the existing user providers.

If we only want to cache the retrieveById() method, like the previous implementation, the decorator class might look something like this:

<?php

namespace App\Auth;

use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Contracts\Cache\Repository;

final class UserProviderDecorator implements UserProvider
{
    /**
     * @var UserProvider
     */
    private $provider;

    /**
     * @var Repository
     */
    private $cache;

    public function __construct(UserProvider $provider, Repository $cache)
    {
        $this->provider = $provider;
        $this->cache = $cache;
    }

    /**
     * {@inheritDoc}
     */
    public function retrieveById($identifier)
    {
        return $this->cache->remember('id-' . $identifier, 60, function () use ($identifier) {
            return $this->provider->retrieveById($identifier);
        });
    }

    /**
     * {@inheritDoc}
     */
    public function retrieveByToken($identifier, $token)
    {
        return $this->provider->retrieveById($identifier, $token);
    }

    /**
     * {@inheritDoc}
     */
    public function updateRememberToken(Authenticatable $user, $token)
    {
        return $this->provider->updateRememberToken($user, $token);
    }

    /**
     * {@inheritDoc}
     */
    public function retrieveByCredentials(array $credentials)
    {
        return $this->provider->retrieveByCredentials($credentials);
    }

    /**
     * {@inheritDoc}
     */
    public function validateCredentials(Authenticatable $user, array $credentials)
    {
        return $this->provider->validateCredentials($user, $credentials);
    }
}

It implements the same interface as the user providers, but accepts two arguments in the constructor, which are injected and stored as properties:

Another instance of Illuminate\Contracts\Auth\UserProvider
An instance of the cache repository Illuminate\Contracts\Cache\Repository

Most of the methods just defer to their counterparts on the wrapped instance - in this example I have cached the response to retrieveById() only, but you can add caching to the other methods easily enough if need be. You do of course still need to flush the cache at appropriate times, which is out of scope for this example, but can be handled by model events as appropriate, as described in the prior article.

Then you add the new decorator as a custom user provider, but crucially, you need to first resolve the provider you’re going to use, then wrap it in the decorator:

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Gate;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Illuminate\Contracts\Auth\UserProvider;
use Auth;
use Illuminate\Auth\EloquentUserProvider;
use Illuminate\Contracts\Cache\Repository;
use App\Auth\UserProviderDecorator;

class AuthServiceProvider extends ServiceProvider
{
    /**
     * The policy mappings for the application.
     *
     * @var array
     */
    protected $policies = [
        'App\Model' => 'App\Policies\ModelPolicy',
    ];

    /**
     * Register any authentication / authorization services.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        Auth::provider('cached', function ($app, array $config) {
            $provider = new EloquentUserProvider($app['hash'], $config['model']);
            $cache = $app->make(Repository::class);
            return new UserProviderDecorator($provider, $cache);
        });
    }
}

Finally, set up the config to use the caching provider:

    'providers' => [
        'users' => [
            'driver' => 'cached',
            'model' => App\Eloquent\Models\User::class,
        ],
    ],

This is pretty rough and ready, and could possibly be improved upon by allowing you to specify a particular provider to wrap in the config, as well as caching more of the methods, but it demonstrates the principle effectively.

By wrapping the existing providers, you can change the behaviour of the user provider without touching the existing implementation, which is in line with the idea of composition over inheritance. Arguably it’s more complex, but it’s also more flexible - if need be you can swap out the wrapped user provider easily, and still retain the same caching functionality.

The trouble with integrated static analysis

Matthew Daly — Wed, 12 Feb 2020 22:40:15 +0000

I’ve always been a big fan in general of tools that provide feedback about the quality of my code. The development role in which I spent the most time was one in which I had no peer feedback or mentoring at all, and while I could definitely have done with more peer review than I had, automated tools helped fill the gap a little bit. When I started building my first Phonegap app, about a year after I started programming professionally, it used far more Javascript than I’d ever used before, and JSLint was very helpful in instilling good practices at that early stage in my career.

In addition, I often find that using an automated tool largely eliminates the issue of ego - if your colleague Bob tells you something is a bad practice, you can potentially dismiss it as “That’s just Bob’s preferences”, whereas an automated tool is potentially much more objective. Nowadays, my typical set of static analysis tools on a project includes:

ESLint
Flow
PHP CodeSniffer
Psalm

However, I’m always dubious of using any static analysis tool that’s tightly integrated with a particular editor or IDE. In this post, I will explain my reasoning.

In-editor feedback

Having instant feedback on the quality of your code is tremendously useful. Sure, you can run something like CodeSniffer from the command line and see what the problems are, but that’s nowhere near as useful as having it actually in your code. If you work on a legacy code base, there’s no way in hell you can wade through a long list of output in the terminal and fix them without losing the will to live. By comparison, actually seeing something flagged as an error where it actually occurs makes the mental cost of fixing it much smaller - you can see it in context, and can usually therefore resolve it more easily.

However, that doesn’t explicitly require that any one tool form an integral part of the editor. Most editors can hand off linting and static analysis to other, standalone tools, and doing so offers the following advantages:

Less dependence on a given development environment - it’s always a struggle if you wind up stuck using a development environment you dislike (I grew to utterly despise Netbeans in my first role), but if you can use generic feedback tools that can be integrated with just about any editor, your team can use the development environment that suits them most, while still all benefiting from the feedback these tools provide
These tools tend to be open source, meaning you have the security of knowing that if the creator ceases maintaining it, either someone else may pick up the baton, or you can choose to fork it yourself. If a commercial IDE provider ceases trading, it’s likely you won’t be able to use their offering at all at some point in the future.

Nowadays I use vim-ale in Neovim, and that provides real-time feedback for a number of linters and static analysis tools, including all those I mentioned above. I have comprehensive information on any issues in my code, and because any configuration is in simple text files that form part of the repository, it’s easy to update those settings for all developers working on the project to ensure consistency.

It’s possible that an integrated solution might offer a few advantages in terms of tighter integration with autocompletion and other functionality allowing for it, but whether they outweigh the tradeoffs mentioned here is dependent entirely on the implementation and how useful it is for any one team.

Continous integration to the rescue

There’s another issue I have with this sort of tightly integrated static analysis, which is probably the biggest, and that is that the feedback is available only at the level of an individual developer, not the team.

It’s great providing all this feedback to developers, but what if they just ignore it? Not all developers have had the sort of experience that leads one to really appreciate the value of coding standards and type hints, particularly if they’ve worked primarily on small or greenfield projects, or in environments where the emphasis was on churning out large quantities of work, and getting developers to tidy up the sort of issues these tools identify can sometimes be a tough sell when faced with code which, at least superficially, works.

Suppose you take on a new developer and ask them to work alone on a particular project for several months. Due to your own workload you can’t easily schedule code reviews with them, so you don’t see what they’re writing until they’re done. Then you take a look at what they’ve written and it’s full of issues that the IDE caught, but the developer either didn’t bother to fix, or didn’t know how to. What they’ve done may well work, but they’ve introduced a huge morass of technical debt that will slow down future development for the foreseeable future.

If your static analysis tools work only in the context of a given editor or IDE, then if the new dev introduce issues in the code base and doesn’t resolve them because they don’t know how, or don’t see the value, then the first you knows about it is when you clone the repo yourself and open it up. With a solution that runs in a CI environment, you can catch any reduction in code quality when it’s pushed. Sure, code reviews can do that too, but that requires manual input in a way that not every team is willing to spare, whereas a CI server, once set up, is largely self sustaining. And you could run one tool locally and another in a CI environment, but you can’t be sure they’ll necessarily catch all the same issues.

Now consider the same scenario if you’re using a separate code quality tool that’s integrated both into the editor, and your continuous integration workflow. Obviously, it will depend on your personal CI setup, but once code quality either begins to drop, or drops below a given level, the CI server will mark the build as failed, and you’ll be alerted. You can therefore then raise the issue with the new dev before it gets out of hand, and provide whatever support they need to resolve the problem there and then.

I personally maintain a legacy project in which, at one point prior to my arrival, a junior dev introduced an enormous amount of technical debt after working on it alone for six months. An integrated linter or static analysis tool probably wouldn’t have stopped that from happening, for the reasons stated above, but if a similar tool were part of the CI workflow, it could have been flagged as an issue much earlier and dealt with. Yes, leaving a junior dev unsupported and unsupervised for that length of time isn’t a great idea, but it happens, particularly in busy environments such as agencies. A good CI setup lets you see if someone is adding these kinds of issues, and act to nip it in the bud before it becomes too much of a problem, which is ultimately good for that developer’s career.

Peer pressure can also be a strong motivating factor under these circumstances. By simply displaying a metric, you encourage people’s natural competitiveness, so displaying code quality stats in your CI dashboard will encourage your team to do better in this regard, and no-one wants to be visibly seen to be letting the team down by producing substandard code.

For these reasons, where possible for feedback on code quality, I would always prefer to rely on a standalone tool that can be integrated with an editor, or used as part of a continuous integration workflow, as opposed to any IDE-specific functionality.

Don't use stdClass

Matthew Daly — Sun, 09 Feb 2020 10:10:48 +0000

The digital agency I work for specialises in marketing, so some of my work tends to relate to mailing lists. This week I was asked to look at an issue on a Laravel-based export system built by a co-worker who left a few months ago. This particular application pulled data from the Campaign Monitor API about campaigns, and it returned the data as instances of stdClass, something that I’m not terribly happy about.

Now, this was an implementation detail of the Campaign Monitor PHP SDK, which is old and creaky (to say the least…) and doesn’t exactly abide by modern best practices. However, the legacy application I maintain also does this (there’s a lot of stuff that needs sorting out on it, and sadly replacing the stdClass instances is a long way down the list), so I thought it was an interesting subject for a blog post. I consider using stdClass, even just as a dumb container for data, to be an antipattern, and I thought it would be useful to explain my thoughts on this.

Why shouldn’t I use stdClass?

Readability

One of the first things I learned about throwing exceptions is that they should be meaningful. It’s trivial to define a named exception and use that to specify the type of exception, and you can then capture exceptions to handle them differently elsewhere in the application. For instance, a validation error is entirely due to a user submitting the wrong details, and should therefore be handled in an entirely different manner to the database going down.

The same is applicable to an object. If an API client returns an instance of stdClass, that doesn’t tell me anything about what that object is. If I need to pass it elsewhere in a large application, it may become very difficult to understand what it represents without tracking it back to where it came from, which will slow me down. If instead I use a named class, the name can convey what it represents. It may seem like overkill to create a class that adds no new functionality, but the mere fact that it has a name makes your code more meaningful and easier to understand. I can also add DocBlock comments to describe it further.

Of course, just giving something a generic name like Container isn’t much of an improvement, and coming up with meaningful names for classes and methods is notoriously hard. As always, give some serious thoughts into what your objects represent and attempt to give them names that will make it easy to understand what they are if you look at the code base again six months down the line.

Type hinting

A related argument is that it makes type hinting more useful. You can type hint stdClass, but as noted above it tells someone working on the code receiving it very little about where it’s come from, or what it represents, and it doesn’t offer much value since an stdClass could mean anything, and could be created anywhere in the appication.

By contrast, named classes provides much more information about what the type hinted parameter represents. For instance, naming your class something such as App\Api\Response\Item, makes it much clearer that that object represents an individual item returned from an API, and others developers working on the same code base (including your future self, who may not necessarily remember all of the details of how you’re implementing it now), will have less trouble understanding what is going on. There’s also a much-reduced likelihood of the same class being used to represent completely different types of data.

New functionality

Finally, are you sure you don’t want to add any functionality? PHP includes a number of interfaces that can be extremely useful for working with this sort of data.

First off, the ArrayAccess interface allows you to access an object’s values using array syntax, which can be useful. Also, implementing either Iterator or IteratorAggregate will allow you to iterate over the object using a foreach loop. The Countable interface is less useful, since all it does is let you get the number of items, but it’s sometimes handy. Finally, the Serializable interface lets you serialize an object so it can be stored in a suitable medium, which can sometimes be useful.

The same also applies to some of the magic methods. The __toString() method, in particular, can be useful for returning a suitable string-based representation of an object - for instance, if it represents an item in a database, it might be appropriate to use this to return the ID of the item, or a text representation of it (eg title for a blog post, or product name for a product in an e-commerce site). The __get() and __set() magic methods may be a bit more dubious, but they can be useful if your object is intended to just be a dumb container as they allow you to make the properties on the object private, but keep them accessible without writing explicit getters and setters. I’d also suggest adding __debugInfo() to objects unless you have a good reason not to, as when you’re debugging it can be hard to see the wood for the trees, and returning only the most pertinent data can make your job a lot easier.

Of course, you don’t have to implement all this functionality from scratch for every class. It often makes sense to create an abstract class that implements this sort of basic container functionality, and then base all your container classes on that, overriding it when necessary.

Summary

Hopefully, this has made it clear how compelling it is to use named classes instead of stdClass, and how much benefit you can get from not just using named classes, but creating your own base container class for them. I’m of the opinion that PHP should probably make stdClass abstract to prevent them from being used like this, and indeed I’m seriously considering the idea of creating a Codesniffer sniff to detect instances of stdClass being instantiated and raise them as an error.

F*** PHPStorm Man and the high horse he rode in on

Matthew Daly — Sat, 25 Jan 2020 22:25:17 +0000

There’s a particularly unpleasant type of programmer that exists, and you’ve probably met him, either online or in person. I call him PHPStorm Man.

NB: Despite the name I’ve chosen, I’m not singling out users of PHPStorm in particular about this. The first time I encountered PHPStorm Man in person, he was using Sublime Text, and you will find PHPStorm Men using all different editors and IDEs. PHPStorm Man is an archetype defined not by any particular piece of software, but by a common bad attitude, and given that I work primarily with PHP these days, I’ve most often encountered this kind of behaviour from PHPStorm users (or at least, people claiming to be PHPStorm users, since at least online you can’t discount the possibility that they’re trolls). Users of other languages may well see this behaviour most prominently from those who use some other editor or IDE, but the same underlying phenomenon is at work, whether we call him PHPStorm Man, Eclipse Man, Vim Man or PyCharm Man.

Who is PHPStorm Man?

PHPStorm Man (and he will almost certainly be a man - while it could be just because our industry is male-dominated, I’ve never known a woman to behave like this, and I strongly suspect it’s nothing more than an industry-specific example of the common phenomenon of mansplaining) doesn’t know squat about your editor or IDE. He just knows his is superior, and he wants you to know it, regardless of the evidence.

His knowledge of your editor is probably either non-existent, grossly outdated, plain ill-informed or second-hand (probably from another PHPStorm Man). If he’s advocating an IDE, he’ll likely equate all text editors with Notepad - he may claim the advantages of his one over yours include such fundamentals as syntax highlighting and autocompletion.

He’ll boast about some feature his editor has that yours doesn’t, even if it does. If your editor lacks that functionality out of the box, but can add it via a plugin, apparently that doesn’t count because although you’re intelligent enough to build a working web app, somehow installing and configuring that plugin is an insurmountable burden (yet mysteriously turning off all the stuff you don’t need in his editor is quick and easy). If it does do that out of the box, he’ll probably find some bullshit reason why his editor’s implementation is better, even if it’s something as pointless and irrelevant as “it’s been around longer”. He’ll likely claim, with absolutely no evidence whatsoever, or indeed in the presence of evidence to the contrary, that you’d be more productive if you only used his editor.

In short, if you aren’t using his editor or IDE of choice, you’re a troglodyte living in a dung hut.

PHPStorm man in the wild

I had an encounter with PHPStorm Man in person a while back. Just over two years ago I started a new job, which as it turned out didn’t last long after I caught the flu that was going around in late 2017 my first week. On the second day, shortly after going over something with me, the senior dev sent me the following message on Slack:

I noticed you’re using Vim. Have you tried using Sublime Text?

I responded that I had, and chose not to use it. There followed a long string of messages along the following lines:

Him: Sublime Text has X!

Me: I have that

Him: Well Sublime Text also has Y!

Me: I have that too, via a plugin

Him: Well, Sublime Text doesn’t need a plugin for that

Me: Irrelevant since the plugin is already installed and configured, and I know how to use it

Him: Well, what about this?

Me: That sounds cool, so I just found a plugin to do that and installed it

Him: And this?

Me: I have absolutely no need for that

Him: Well, Vim is old, Sublime Text is new!

Me: Actually, this is Neovim, which is technically newer than Sublime Text

Him: Well, Sublime Text is a GUI application

Me: Exactly. That makes it slower and forces me to use the mouse, aggravating my RSI. I use the terminal because it’s more efficient

Him: Well, I don’t mind what you use…(despite the evidence of that entire conversation)

With the benefit of hindsight, what I should have responded with was this:

I’m an experienced, professional web developer of over six years, and I chose my editor based on years of personal experience, and have chosen my plugins and configuration based on what’s useful to me, and continue to do so to this day. I don’t appreciate you talking down to me like a child.

Why I personally don’t use an IDE

In my case, I have a particularly good reason not to use any GUI application to develop in. Before I was a developer, I worked for an insurance company in a customer service role, and I didn’t have access to the sort of decent quality keyboards and mice developers habitually use, as well as having output goals linked to discipline and bonus/salary raises and having to use custom internal applications on Windows XP, with dreadful keyboard support. As a result I developed a degree of RSI in both hands, which I’ve found is aggravated by using any application that requires me to use a mouse extensively - I’m generally OK if I only have to type, but reaching for the mouse all the time quickly becomes tiring, and soon after painful.

For that reason I’ve developed a workflow that’s strongly dependent on the command line - I use Neovim in the terminal, alongside Byobu so that I can run multiple tabs and switch between them quickly without touching the mouse. Moving to a more GUI-oriented workflow would require me to use the mouse more than I do now, which would probably become physically painful quite quickly. Using an editor or IDE which I found made me more prone to further flare-ups of RSI could have serious consequences for my long-term health, and could potentially be career-ending. If I worked somewhere that mandated a particular IDE that didn’t work well for me, I’d have to either negotiate an exception on health and safety grounds or quit.

I’m also of the personal opinion that much of the functionality of an IDE should not be, in principle, tied to that IDE, but should instead be the province of more general purpose tools that can used, not merely in any editor or IDE but, where appropriate, on a continuous integration server. For instance, language servers provide a tool-agnostic way for any IDE or editor to implement functionality such as completion or navigation, and linters such as ESLint can integrate into any half-decent editor or run in a CI environment. Since these tend to be open source projects, whereas IDE’s are normally commercial offerings, they’re less vulnerable to suddenly disappearing and leaving users high and dry.

There’s also a lot of functionality in an IDE that I rarely, if ever, use. There’s no point including and starting up an FTP client as part of my editor if I’m never going to use it, as it slows the application down, and nor should I have to root around trying to turn off functionality I’m never going to have to use. For a lot of other functionality, there are more powerful standalone applications that I’m used to such as Postman or MySQL Workbench, and I’ll use them as and when I need them - I gain nothing by having them integrated with my editor.

I also like to be able to use the same editor everywhere. I still occasionally dabble in Python, so a language-specific IDE wouldn’t be suitable when switching between languages. I also sometimes work on personal projects on an HP Stream netbook running Xubuntu, which is fine for small PHP projects that don’t require a database server or any web server other than the PHP dev server. I can happily run Neovim on that, but there’s no way it could run an IDE at an acceptable speed.

Last of all, screen real estate is an issue. I don’t like interfaces that are too busy - I cannot stand having anything, at all on my desktop for any length of time at all, and any interface that has too much on screen at once is distracting. I will typically have Neovim open in a terminal, with the NERDTree file finder open on the left, and two panels split in the main body, and that’s all. A big factor in my productivity is how much code I can see at once, and having too much screen real estate taken up by menus and sidebars is counterproductive - with Neovim there’s almost nothing getting in the way.

I personally have had to give this sort of explanation many, many times as to why I use first Vim and then Neovim, and indeed part of the motivation behind writing this post is that I’m sick to death of having to explain myself over and over again and will now be able to merely direct them to this article. Thanks to tools like PHPActor, vim-ale and FZF, I don’t feel like there’s anything I’m missing out on that an IDE would give me, and Psalm is very good at catching type errors without being tied to any one IDE, but that doesn’t stop people telling me I’m missing out on features I already have. Any time I come across a feature I think is cool, I go through the following process:

Find cool feature
Find plugin that implements said feature
Install plugin by adding a single line to my Neovim config and running :PlugUpdate
Add a few lines of config
Start using feature

Using an IDE would eliminate the middle three steps, but I don’t find those onerous - we’re talking about the work of five minutes, which is insignificant compared to the time taken to learn to use the feature effectively. And a feature you don’t use is one that you still have to start up if it’s present, so making it an opt-in plugin is often a better way to go.

Every other developer will have their own version of this story. Some will have stayed mostly static in their editor choices, while others will be changing all the time - indeed, I’ve sometimes used other editors for specific tasks in the past. In short, everyone has their own reasons for using their editor of choice, and it’s appallingly arrogant to assume that their reasons for using a particular one are less valid than yours.

Am I PHPStorm Man?

As I’ve said before, this behaviour is not confined to PHPStorm users, nor is it in any way universal among them. If you use PHPStorm and enjoy it, then fine, rock on. If you use a different editor or IDE, then that’s fine too - I don’t have a problem with that, and nor should your colleagues or line manager. Using any one editor or IDE does not make you PHPStorm Man. What makes you PHPStorm Man is the patronising attitude.

In the example given above, what made the senior dev PHPStorm Man was not the initial enquiry as to whether I’d tried Sublime Text, but the fact that he wouldn’t leave it be when confronted with evidence that I either had, could easily obtain, or didn’t need the functionality of his editor in mine, and that he was talking down to an experienced developer like a child.

Obviously, this isn’t a new development - editor wars have long been a feature of our industry, as has the divide between IDE and editor users. But that doesn’t mean I, and no doubt others, don’t get utterly sick of it.

How not to be PHPStorm Man

When talking to users of other editors or IDE’s about the subject of those tools, you should always bear this in mind:

If they use a different tool to you, they probably know a hell of a lot more about it than you do, and are unlikely to take kindly to you ignorantly telling them what it can and can’t do
Mastering an editor or IDE can take years, and if they’re already invested in one, it’s incredibly arrogant to just assume that they’re less productive in it than they would be in yours - even if they would (and that’s almost certainly debatable), it would take some time to adjust.
They’ve probably had this conversation many times before, and are sick of hearing it, especially if they have a few years experience under their belt
Not every feature you use is useful to them
No-one minds seeing a cool feature, so feel free to demonstrate it, but bear in mind that it’s almost certainly not limited to that platform - if it’s suffficiently cool, someone will have made it available as a plugin on most of the major editors and IDE’s. If they like it, the most likely scenario is that they’ll look to add that feature to their own editor via a plugin
Just because it makes you more productive, doesn’t mean that it would make them more productive
It’s perfectly possible to enforce consistent code styles and catch errors using standalone tools such as PHP CodeSniffer, Psalm, or ESLint, and these tools can be integrated in any editor, triggered with Git hooks, or run with continuous integration.

Now, it has to be said that sometimes there are some people who plod on with painfully outdated tools, like Notepad. But those tools tend to be limited to either commercial offerings that are no longer mainained or supported, or ones that lack any sort of plugin or extension system, making them limited in terms of how they can integrate with other services, so they’re fairly easy to spot. However, making a particular editor or IDE compulsory is going to be disruptive. If you’re in a leadership position, one way to resolve this is to simply require that everyone’s editor have certain functionality - for instance, if you specify that everyone’s editor must allow integration with PHP CodeSniffer and support for .editorconfig, then anyone using a legacy editor that can’t support those will need to move away from it, but they’ll be able to pick one that suits them, rather than be forced into one they may well dislike. Editors and IDE’s don’t produce proprietary formats the way word processors do - they work with common formats, and if prominent open-source projects can enforce a consistent coding standard with many different editors there’s absolutely no reason why your colleagues can’t do so too,

Summary

This post is a bit of an angry rant, but at the same time it shouldn’t be taken too seriously. As I said, despite the name PHPStorm Man, it’s not specifically about users of any one editor or IDE, but about the widespread, patronising attitude many developers have about editors and IDE’s other than their own in general.

Someone using a different IDE or editor is absolutely none of your business unless you’re their line manager or you work on the same code base, and even then it should only be an issue if it causes a clear effect on their productivity or the quality of their code. If that’s not the case, keep your nose out.

Unconventional backends and data sources

Matthew Daly — Mon, 16 Dec 2019 21:18:28 +0000

I've been a web dev for seven years now, and most of the sites I've worked on have used a database, API or a text format like Markdown as the primary source of content.

However, there's been a few more unusual ones down the years. I once inherited a Tumblr blog for a client that pulled the navigation data from Google Sheets, and once built a static site generator to build a site from two CSV files of equipment listings.

Do you have a story like this? What unusual data sources or backends have you used or inherited?

Input components with the useState and useEffect hooks in React

Matthew Daly — Sun, 27 Oct 2019 21:20:00 +0000

Like many developers who use React.js, I’ve been eager to explore the Hooks API in the last year or so. They allow for easier ways to share functionality between components, and can allow for a more expressive syntax that’s a better fit for Javascript than class-based components. Unfortunately, they became production ready around the time I rolled out a new React-based home page, so I didn’t want to jump on them immediately in the context of a legacy application. I’m now finding myself with a bit of breathing space, so I’ve begun refactoring these components, and converting some to use hooks, in order to more easily reuse some code that currently resides in a big higher-order component.

The useState and useEffect hooks are by far the most common hooks in most applications. However, I’ve found that the React documentation, while OK at explaining how to use these individually, is not so good at explaining how to use them together, particularly in the case of an input component, which is a common use case when looking to convert existing components. For that reason, I’m going to provide a short example of how you might use them together for that use case.

A simple function component

A basic component for an input might look like this:

//@flow
import React from 'react';

type Props = {
  name: string,
  id: string,
  value: string,
  placeholder: string
};

const Input = (props: Props) => {
  return (
    <input type="text" name={props.name} id={props.id} value={props.value} placeholder={props.placeholder} />
  );
}

export default Input;

Note I’m using Flow annotations to type the arguments passed to my components. If you prefer Typescript it should be straightforward to convert to that.

As you can see, this component accepts a name, ID, value and placeholder as props. If you add this to an existing React app, or use create-react-app to create one and add this to it, you can include it in another component as follows:

<Input name="foo" id="foo" value="foo" placeholder="foo" />

Adding state

This will render, but as the value will never change it’s not actually of any use in a form. If you’ve written class-based React components before, you’ll know that the usual way to handle this is to move the value of the input from props to state. Prior to the introduction of the Hooks API, while you could create a function component, you couldn’t use state with it, making situations like this difficult to handle. Fortunately, the useState hook now allows you to add state to a function component as follows:

//@flow
import React, { useState } from 'react';

type Props = {
  name: string,
  id: string,
  value: string,
  placeholder: string
};

const Input = (props: Props) => {
  const [value, setValue] = useState(props.value);

  return (
    <input type="text" name={props.name} id={props.id} value={value} placeholder={props.placeholder} onChange={(e) => setValue(e.target.value)} />
  );
}

export default Input;

We import the useState hook at the top, as usual. Then, within the body of the component, we call useState(), passing in the initial value of props.value, and get back two variables in response:

value is the value of the state variable, and can be thought of as equivalent to what this.state.value would be in a class-based component
setValue is a function for updating value - rather than explicitly defining a function for this, we can just get one back from useState()

Now we can set the value with value={value}. We also need to handle changes in the state, so we add onChange={(e) => setValue(e.target.value)} to call setValue() on a change event on the input.

Handling effects

The component will now allow you to edit the value. However, one problem remains. If you open the React dev tools, go to the props for this component, and set value manually, it won’t be reflected in the input’s value, because the state has diverged from the initial value passed in as a prop. We need to be able to pick up on changes in the props and pass them through as state.

In class-based components, there are lifecycle methods that fire at certain times, such as componentDidMount() and componentDidUpdate(), and we would use those to handle that situation. Hooks condense these into a single useEffect hook that is more widely useful. Here’s how we might overcome this problem in our component:

//@flow
import React, { useState, useEffect } from 'react';

type Props = {
  name: string,
  id: string,
  value: string,
  placeholder: string
};

const Input = (props: Props) => {
  const [value, setValue] = useState(props.value);

  useEffect(() => {
    setValue(props.value);
  }, [props.value]);

  return (
    <input type="text" name={props.name} id={props.id} value={value} placeholder={props.placeholder} onChange={(e) => setValue(e.target.value)}/>
  );
}

export default Input;

useEffect takes one compulsory argument, in the form of a callback. Here we’re using that callback to set our state variable back to the value of the prop passed through.

Note the second argument, which is an array of variables that should be watched for changes. If we had used the following code instead:

useEffect(() => {
  setValue(props.value);
});

Then the callback would fire after every render, reverting the value back and possibly causing an infinite loop. For that reason, we pass through the second argument, which tells React to only fire the callback if one of the specified variables has changed. Here we only want to override the state when the value props passed down to the component changes, so we pass that prop in as an argument.

Summary

This is only a simple example, but it does show how simple and expressive hooks can make your React components, and how to use the useEffect and useState hooks together, which was something I found the documentation didn’t make clear. These two hooks cover a large chunk of the functionality of React, and knowledge of them is essential to using React effectively.