DEV Community: Marinus van Velzen

Stop using for loops and start showing intent

Marinus van Velzen — Tue, 28 Feb 2023 14:17:27 +0000

Over the years I keep seeing people abuse the very popular for loops. This powerful tool allows you to go over entire lists of items and do things with them. The biggest downside to these is that need to read the entire loop in order to discover what it does. Luckily most programming languages these days provide multiple functions that you can apply to your lists and/or arrays of data to get the same results, but with shown intent!

In this article I will show you the most used functions and how they work with the help of PHP.

Before we start

Before we start I will set up a small amount of classes and variables that will be used as examples further into the article.

class Movie {
    public function __construct(
        public string $title,
        public string $genre,
        public int $rating
    ) {}
}

$moviesAsJson = [
    [
        'title' => 'John Wick',
        'genre' => 'action',
        'rating' => 86,
    ],
    [
        'title' => 'Frozen',
        'genre' => 'kids&family',
        'rating' => 90,
    ],
    [
        'title' => 'Hot Fuzz',
        'genre' => 'action',
        'rating' => 91,
    ],
    [
        'title' => 'Scott Pilgrim vs. the World',
        'genre' => 'comedy',
        'rating' => 82,
    ],
];

Examples of the functions

The examples given in this section will probably be of the same length of code as the examples while using foreach loops, so you will probably think that these functions are not very special.

Keep in mind that the actual code will almost always be longer, so you will need to read the entire foreach loop to see what the intention of the writer was. To keep the code simple I chose to use short examples.

Transforming data

Let's start with one of the functions I use the most. It's the map function. This function is used to transform data in an array to something completely different. We will use the result of this transformation in the following examples.

$movies = []
foreach ($moviesAsJson as $movie) {
    $movies[] = new Movie(
        $movie['title'],
        $movie['genre'],
        $movie['rating']
    );
}

$movies = array_map(
    fn (array $movie) => new Movie(
        $movie['title'],
        $movie['genre'],
        $movie['rating']
    ),
    $moviesAsJson,
);

Filtering

Sometimes you might even need to filter data from an array. Let's say I only want a list of action movies. If you don't use array methods you will write something like this.

$actionMovies = []
foreach ($movies as $movie) {
    if ($movie->genre === 'action') {
        $actionMovies[] = $movie;
    }
}

This can be made a lot more clear if you use the filter method.

$actionMovies = array_filter(
    $movies,
    fn (Movie $movie) => $movie->genre === 'action'
);

Reducing array to a new value

The reduce method usually is one of the more confusing ones in the entire suite. It is used to reduce an entire array to a single value. To demonstrate the power of this method I will give two examples.

First I want the movies to be grouped by genre. This way I can easily display the movies in their own sections without having to use an array_filter!

$moviesByGenre = [];
foreach ($movies as $movie) {
    $moviesByGenre[$movie->genre] ??= [];
    $moviesByGenre[$movie->genre][] = $movie;
}

Now this is what it would look like using the reduce function.

$moviesByGenre = array_reduce(
    $movies,
    function (array $moviesByGenre, Movie $movie) {
        $moviesByGenre[$movie->genre] ??= [];
        $moviesByGenre[$movie->genre][] = $movie;

        return $moviesByGenre;
    },
    []
);

Another usual use of the reduce function is to calculate values. Let's say we want the average rating of the given movies.

$totalRating = 0;

foreach ($movies as $movie) {
    $totalRating += $movie->rating;
}

$averageRating = $totalRating / count($movies);

This is what it would look like using array reduce

$totalRating = array_reduce(
    $movies,
    fn (int $totalRating, Movie $movie) => $totalRating + $movie->rating,
    0
);

$averageRating = $totalRating / count($movies);

Conclusion

The array functions allow the reader to instantly read the intent of what you want to do with your array. They won't have to sift through the entire foreach loop and thus they can immediately focus on whats being altered/filtered/reduced.

How to use PSR HTTP standards to upgrade your code

Marinus van Velzen — Mon, 13 Feb 2023 21:37:04 +0000

Almost every developer has made one or more classes that make HTTP requests to external APIs and services or have used composer packages to do this. You probably used cURL or Guzzle to do this, but probably without any abstraction.

Normally this isn't an issue, but if nobody does this you will end up with a lot of extra HTTP clients in your source code.

Luckily a group of smart people got together and created a couple of standards that can be used to base your code on a collection of interfaces. With this you can create packages without hard dependencies on specific HTTP clients and it will allow you to insert your own HTTP clients into the library of choice.

The strength of allowing developers to insert their own libraries also gives them the ability to configure it as needed. They might need middleware to log failed network attempts or they want to retry every call at least 3 times before giving up! Another benefit is that it allows you to use mocked or fake clients for testing, which makes it easier to write tests for your code.

This article will display the use of

PSR-7, the standard for requests and responses
PSR-17, the standard for request factories
PSR-18, the standard for HTTP Clients with which to send and receive the PSR-7 requests and responses.

I will demonstrate how these standards can help you by writing a small package which can retrieve cat facts from an external API with your HTTP Client of choice!

The end result will look like this if you want to use the default client

$consumer = new Consumer();
$facts = $consumer->facts()->all();

Or like this when you want to configure and use a different client!

$curlClient = new \Http\Client\Curl\Client();
$httpClient = new HttpClient($curlClient);
$catFacts = new CatFacts($httpClient);
$facts = $catFacts->facts()->all();

Let's get started

In the example above you may have noticed that I made my own HttpClient class which acts as a wrapper for the actual client. This will allow us to have an entry point for all requests and responses. Most of the PSR related stuff will be in here. Here is the entire file, but I will try to explain the constructor and the sendRequest below it.

HttpClient

<?php

declare(strict_types=1);

namespace Rocksheep\CatFacts;

use Exception;
use Http\Discovery\Psr17FactoryDiscovery;
use Http\Discovery\Psr18ClientDiscovery;
use JsonException;
use Psr\Http\Client\ClientExceptionInterface;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;

class HttpClient
{
    private ClientInterface $client;
    private RequestFactoryInterface $requestFactory;

    protected string $baseUrl = 'https://cat-fact.herokuapp.com';

    public function __construct(
        ?ClientInterface $client = null,
        ?RequestFactoryInterface $requestFactory = null
    )
    {
        $this->client = $client ?: Psr18ClientDiscovery::find();
        $this->requestFactory = $requestFactory ?: Psr17FactoryDiscovery::findRequestFactory();
    }

    /**
     * @throws JsonException
     * @throws Exception
     */
    public function sendRequest(string $method, string $uri): array
    {
        $request = $this->requestFactory->createRequest($method, sprintf('%s/%s', $this->baseUrl, ltrim($uri, '/')));

        try {
            $response = $this->client->sendRequest($request);
        } catch (ClientExceptionInterface $e) {
            throw new Exception('Oh well');
        }

        if ($response->getStatusCode() >= 400) {
            throw new Exception('Too bad');
        }

        $responseBody = (string) $response->getBody();

        return json_decode($responseBody, false, 512, JSON_THROW_ON_ERROR);
    }
}

Constructor

In the constructor you will see that we accept a nullable ClientInterface and a nullable RequestFactoryInterface. This is what allows developers to use their own implementation. If a developer does not supply a Client or an Factory we will use the Auto Discover classes to find usable classes like Guzzle, HTTPPlug or cURL.

sendRequest

This is where the interfaces are used. Nothing really special happens here. Requests are created from the RequestFactory and are sent via the Client supplied in the constructor. We do some very simple error handling and then return the contents as needed.

CatFacts, the entry point of our package

This class is the entrance point of our package and is how consumers will use our classes. This will receive the HttpClient and just pass it along to our more useful classes, which takes to the Facts class!

<?php

declare(strict_types=1);

namespace Rocksheep\CatFacts;

use Rocksheep\CatFacts\Api\Facts;

class CatFacts
{
    private HttpClient $httpClient;

    public function __construct(?HttpClient $httpClient = null)
    {
        $this->httpClient = $httpClient ?: new HttpClient();
    }

    public function getHttpClient(): HttpClient
    {
        return $this->httpClient;
    }

    public function facts(): Facts
    {
        return new Facts($this);
    }
}

Facts

This class is one of the endpoints of the API we are consuming and thus also the place where the PSR-18 client gets used! It is given an instance of our entry point, so that it can use the HttpClient from within.

For this example I only added the all call which retrieves a list of facts and transforms them into something we can work with. In this case a simple Fact data object, which just holds on to the ID and text for us.

<?php

declare(strict_types=1);

namespace Rocksheep\CatFacts\Api;

use Rocksheep\CatFacts\CatFacts;
use Rocksheep\CatFacts\Models\Fact;

class Facts
{
    private CatFacts $catFacts;

    public function __construct(CatFacts $catFacts)
    {
        $this->catFacts = $catFacts;
    }

    /**
     * @return array<Fact>
     * @throws \JsonException
     */
    public function all(): array
    {
        $response = $this->catFacts->getHttpClient()->sendRequest('get', 'facts');

        return array_map(
            fn (\stdClass $fact) => new Fact($fact->_id, $fact->text),
            $response
        );
    }
}

Conclusion

The example I gave is a very simple one that hopefully gets the point across. When you use the PSR standards in this way you will automatically adhere to the Liskov Substitution principle, which states that object of a super class should be replaceable with objects of its subclasses and not break the application.

It will allow consumers of the package to use their own http clients which they may have configured with specific middleware or error handling.

If you want to check out this code in its entirely you can head to this repo. It's in a useable state, but the API does not contain a lot of facts.

The way declare(strict_types=1) works in PHP

Marinus van Velzen — Sun, 19 Sep 2021 11:07:33 +0000

Readers of my previous article noticed that I used the strict_type declaration and asked me what it does. In this article I will explain what it does and why I started to love using it.

What does strict typing do

PHP has never really been a language with strict typing. You just had variables and you could put anything in it that you wanted, but we're slowly getting more and more type restrictions that we can use.

Type hinting in method parameters or class properties is very useful and it helps you catch type errors before you run your code. Class based type hinting has worked since PHP 5, but primitive hinting is rather new. When passing an unexpected type to a function, PHP will attempt to automatically cast the value to the expected type. If strict_types has been declared then PHP will throw an exception instead.

Using declare(strict_types=1) will tell PHP to throw type errors when you try to (accidentally) cast primitive values. Take a look at this example without the strict type declaration.

function dump(int $value): void  
{  
 var_dump($value);  
}  

dump('13.37');
dump(19.42);

Running this script will result in the following output.

int(13)
int(19)

You'll notice that our dump function expects integers even though we give it a string in one of our function calls. Your editor might call you out if you try to do this, but it's still valid PHP code.

How to enable strict types

Enabling strict typing for primitive values is as easy as adding a single statement to the top of your PHP files. Here is the example from above with the added declaration.

declare(strict_types=1)

function dump(int $value): void  
{  
 var_dump($value);  
}  

dump('13.37');
dump(19.42);

Running this script with the declaration will result in the following error.

Fatal error: Uncaught TypeError: dump(): Argument #1 ($value) must be of type int, string given, called in /Users/rienvanvelzen/Desktop/demo.php on line 10 and defined in /Users/rienvanvelzen/Desktop/demo.php:5
Stack trace:
#0 /Users/rienvanvelzen/Desktop/demo.php(10): dump('13.37')
#1 {main}
  thrown in /Users/rienvanvelzen/Desktop/demo.php on line 5

Using the strict_type declaration can help you catch bugs early on by restricting PHP to automatically cast primitive values. It may be a bit daunting when you start to use it, as you need to properly define everything from the start.

A (small) Caveat

There is one thing that you need to keep in mind when using the strict_type declaration. It only works for the file that the declaration is placed in. Meaning that when you use a class, which has the strict_type declaration, it can still result in PHP casting primitive value. So keep that in mind when you want to start using this!

Cleaner models with Laravel Eloquent Builders

Marinus van Velzen — Sun, 05 Sep 2021 14:02:44 +0000

Over the past few years I have created tons and tons of models in Laravel. These models have always blown up in size with tons of accessors and added scopes. For the unintroduced, model scopes are methods containing queries that can be chained while retrieving data from the database. For example:

// Models/Article.php
class Article extends Model
{
    public function scopePublished(Builder $builder)
    {
        return $builder->whereNotNull('published_at');
    }
}

// usage of the scope
Article::published()->get();

As you might imagine, these methods will add up after a while resulting in bloated models, but what if I tell you that you can clean this up easily?

Writing your own Eloquent Builder

It's possible to create your own Eloquent Builder and bind it to your models. This can be done by creating a class which extends the Eloquent Builder. I'll use the example above for the model that we will clean up. So let's start by creating a ArticleBuilder. It doesn't really matter where you place it, but I tend to create a directory for it in the App namespace.

<?php

declare(strict_types=1);

namespace App\EloquentBuilders;

use Illuminate\Database\Eloquent\Builder;

class ArticleBuilder extends Builder
{
    public function published(): self
    {
        return $this->whereNotNull('published_at');
    }
}

As you can see, it uses the same methods as before, because the scope uses a query builder in the background!

Registering your brand new Eloquent Builder

Now all that's left is to bind our custom query builder to the Article Model. This can be done by overriding the newEloquentBuilder method. After overriding it, you can remove any of the old scopes. Your end result will look something like this!

<?php

declare(strict_types=1);

namespace App\Models;

use App\EloquentBuilders\ArticleBuilder;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use HasFactory;

    public function newEloquentBuilder($query): Builder
    {
        return new ArticleBuilder($query);
    }
}

Using our new builder

Using your brand new query builder is just the same as with the scopes. All you need to do is chain it on your query like you usually do.

Article::published()->get();

In the end nothing changed functionality wise, but your model just became a lot cleaner.