DEV Community: Matheus Lopes Santos

MySQL invisible columns and how to define it with Laravel and Doctrine

Matheus Lopes Santos — Mon, 13 Nov 2023 20:08:18 +0000

Many developers don't know that MySQL now has support for invisible columns.

But what exactly is an invisible column?

When it arrives?

This attribute is available on MySQL since v8.0.23. According to the documentation:

An invisible column is normally hidden to queries, but can be accessed if explicitly referenced. Prior to MySQL 8.0.23, all columns are visible.

The syntax to create an invisible column is very simple:

create table employees (
    id int not null primary key auto_increment,
    name varchar(45) not null,
    ssn char(11) not null INVISIBLE
) ENGINE = InnoDB;

Certainly, we can use DDL to switch a column between visible and invisible.

alter table employees alter column ssn set visible;

Querying Data

Now, what happens if I execute select * from employees?

Wow, where is my ssn column? Well, it's hidden 🙂! To retrieve that column, we need to explicitly specify it in our query:

This is a good approach to exclude columns that don't need to be displayed in our query, such as those containing sensitive data.

Generating an invisible column with a Laravel Migration

If you wish to utilize this feature in a Laravel application, you can define your column as follows:

public function up(): void
{
    Schema::create('employees', function (Blueprint $table) {
        $table->id();
        $table->string('name', 45);
        $table->char('ssn', 11)->invisible();
    });
}

Generating an invisible column with Doctrine

I've defined an entity called Employee with the following configuration

#[ORM\Entity]
#[ORM\Table(name: 'employees')]
class Employee
{
    #[ORM\Id]
    #[ORM\Column(type: 'integer')]
    #[ORM\GeneratedValue]
    private int | null $id;

    #[ORM\Column(type: 'string', length: 45)]
    private string $name;

    #[ORM\Column(columnDefinition: 'char(11) INVISIBLE')]
    private string $ssn;

    // The other methods of this entity
}

Now, we have an additional security layer to prevent the exposure of our sensitive data!

That's all folks! See you on the next post 🙂 👍🏻

Using Laravel push method to update your model and its relationships

Matheus Lopes Santos — Wed, 04 Oct 2023 21:00:40 +0000

Today's tip is about a method that I've seen a few people talking about. It's a model method called push.

"But what does this method do, Matheusão?"

Let's imagine the following scenario:

$user = User::with('address')->first();

$user->name = 'Matheusão';
$user->address->country = 'Brazil';

$user->save();
$user->address()->save();

Awesome! We've retrieved the user with his address and updated his name and country.

However, we can use the pushmethod that will save everything for us:

$user = User::with('address')->first();

$user->name = 'Matheusão';
$user->address->country = 'Brazil';

$user->push();

This simple command will save our model data and iterate over its relations and save all the new data for us.

And another great thing: If we update a relationship inside another relationship, it will be saved too!

Let's take a look at the push method definition:

public function push()
{
    if (! $this->save()) {
        return false;
    }

    foreach ($this->relations as $models) {
        $models = $models instanceof Collection
            ? $models->all() : [$models];

        foreach (array_filter($models) as $model) {
            if (! $model->push()) {
                return false;
            }
        }
    }

    return true;
}

As we can see, every time that script iterates over a relation, it calls the push method again, allowing us to save a lot of relations recursively.

But don't forget to put this kind of operation inside a transaction to avoid data loss.

$user = User::with('address')->first();

$user->name = 'Matheusão';
$user->address->country = 'Brazil';

\DB::transaction(fn () => $user->push());

That's all, folks, keep coding! 😗 🧀

pcre2.h - file not found. How to fix that when installing PCOV on macOS?

Matheus Lopes Santos — Mon, 18 Sep 2023 22:23:24 +0000

For some reason, I managed to mess up the PHP installation on my operating system. Well, no biggie, let's uninstall and reinstall it, no problem.

I installed the main extensions I use, and when I tried to install pcov - boom, a fatal installation error occurred:

Cool, all I need to do is install pcre2, right? 🙂

But it wasn't that simple. When I ran brew install pcre2, I was informed that it was already installed.

Fixing the Issue

I checked some tutorials but couldn't find anything. I even tried creating a symbolic link for the "missing" file, but without success:



ln -s /opt/homebrew/Cellar/pcre2/10.42/include/pcre2.h /opt/homebrew/Cellar/php/8.2.10/include/php/ext/pcre/php_pcre.h

So, it was time for the brute force approach. Searching by myself, I found out how to solve that problem:



ln -s /opt/homebrew/opt/pcre2/include/pcre2.h /opt/homebrew/opt/php@8.2/include/php/ext/pcre/

After that, just run pecl install pcov, and you're good to go!

Now I'm able to calculate the code coverage of my applications again.

That's all, folks! 😗 🧀

pcre2 - file not found. Corrigindo problema de instalação do PCOV no macOS

Matheus Lopes Santos — Fri, 15 Sep 2023 21:07:50 +0000

Por algum motivo eu fiz o favor de quebrar a instalação do PHP no meu sistema operacional. Beleza, vamos desinstalar e instalar novamente, sem problemas.

Instalei as principais extensões que utilizo, e na hora de instalar o pcov - pláu, erro fatal de instalação:

Massa, só o que preciso fazer é instalar o pcre2 e beleza 🙂.

Mas não foi tão beleza assim. Ao executar brew install pcre2 acabei sendo informado que isso já estava instalado.

Verifiquei em alguns tutoriais mas não descobri nada. Tentei fazer um link simbólico do arquivo que estava "faltando" e nada. Vamos para a força bruta então.

Resolvendo o problema

Por todos os fóruns por onde passei, o pessoal estava indicando fazer um link simbólico do header necessário para a compilação. Um dos mais indicados foi esse:

ln -s /opt/homebrew/Cellar/pcre2/10.42/include/pcre2.h /opt/homebrew/Cellar/php/8.2.10/include/php/ext/pcre/php_pcre.h

Porém não funcionou, então achei eu mesmo a solução:

ln -s /opt/homebrew/opt/pcre2/include/pcre2.h /opt/homebrew/opt/php@8.2/include/php/ext/pcre/

Depois disso é só rodar um pecl install pcov e tudo certo:

Agora posso calcular novamente o test coverage das minhas aplicações.

Até a próxima amigos 😗 🧀

Validating SSH keys on Laravel

Matheus Lopes Santos — Tue, 12 Sep 2023 20:45:41 +0000

When we're called to develop an application, we should keep in mind that we might have to deal with various types of problems, some of which we may never have imagined facing. However, sometimes we need to step out of our comfort zone.

Understanding the Problem

A few days ago, I was tasked with building a feature that would receive a developer's public key and later send it to Laravel forge, allowing the user to have SSH access to the respective servers.

Awesome, Matheusão, how am I going to validate this type of data?

Initially, we think about validating the basics, such as the length of the string, whether it already exists in the database, etc:

'ssh_key' => ['nullable', 'string', 'unique:users,ssh_key', 'max:5000']

Okay, but what if the user passes, I don't know, all the letters of the alphabet? Unfortunately, it will pass the validation 🙁.

In Search of the Perfect Validation

I did a lot of research on how to perform this validation. In many blogs, I saw many people recommending using native functions like openssl_verify, openssl_get_publickey, or openssl_pkey_get_details, but unfortunately, they didn't work for what I needed (Remember, an SSH key is different from an SSL key, so these functions won't work). In other forums, I saw people suggesting using the package https://phpseclib.com/. But think about it, why install a package when you're only going to use one class and one of its methods?

I see this as completely unnecessary coupling, but anyway...

Going a Bit Deeper

After some research, I found that we can use ssh-keygen to validate this string for us, but how?

For this, we can use two flags, -l to get the fingerprint and -f to specify the file path. So our command would look like this:

ssh-keygen -lf /path/to/my/file.pub

And this way, we can check if our SSH key is valid or not.

Creating Our Validation Command

Laravel introduced a component called Process starting from version 10, which is nothing more than a wrapper around Symfony's Process component. It's with this little guy that we're going to work our magic.

Of course, we could use the exec function, a native PHP function. However, if you think you don't need to use this wrapper, feel free to do so 🙂👍🏻.

Let's think about what we need to do:

We need to receive the string containing the user's key.
We need to save this string somewhere accessible.
We need to call the ssh-keygen command with the file path.
We need to delete the file after validation.

Setting Things Up

Let's create a directory inside storage/app called ssh. Don't forget to exclude this new directory from your version control:

storage/app/.gitignore

*
!public/
!.gitignore
!ssh/

storage/app/ssh/.gitignore

*
!.gitignore

Writing Our Class

Now we can create our class that will interact with ssh-keygen.

App/Terminal/ValidateSsh.php

<?php

declare(strict_types=1);

namespace App\Terminal;

use Illuminate\Support\Facades\Process;
use Illuminate\Support\Str;

class ValidateSsh
{
    private string $keyPath;

    public function __construct(
        private readonly string $content
    ) {
        $this->keyPath = storage_path('app/ssh/' . Str::uuid() . '.pub');

        file_put_contents($this->keyPath, $this->content);
    }

    public function __invoke(): bool
    {
        return Process::run(
            command: 'ssh-keygen -lf ' . $this->keyPath . ' && rm ' . $this->keyPath,
        )->successful();
    }
}

Great, our class is ready to be used.

It receives the content and saves it with a random name.
It checks the file, and if successful, it deletes it as well.

Now, let's write our tests.

tests/Unit/Terminal/ValidateSshTest.php

<?php

declare(strict_types=1);

use App\Terminal\ValidateSsh;

it('should return true if process if file is valid', function (string $key) {
    $validateSsh = new ValidateSsh($key);

    expect($validateSsh())->toBeTruthy();
})->with([
    'RSA'   => 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD3vYKSuh7rJf+NtWn04CFyT9+nmx+i+/sP+yMN9ueJ+Rd5Ku6d9kgscK2xwlRlkcA0sethslu0WUsG81RC1lVpF6iLrc/9O45ZhEY1CB/7dofr+7ZNwu/DJtbW6YE7oyT5G97BUW763TMq/YO9/xjMToetElTEJ4hUVWdP8q93b3MVHBazk2PEuS05wzP4p5XeQnhKq4LISetJFEgI8Y+HEpK29GiU/18fhaGZvdVwOToOxTwEwBbS3fTLNkBaUTWw9q3i7S60RRncBCHppcs2irrzw7yt7ZQOnut/BIjIGESoxx+N4ZrpTmX6P5d3/9Duk40Mfwh1ftsvze6o5AW4Xi0tki8b6bsMXmO7SapqVdiMZ5/4BWOkqHWhi926qz7I9NWoZuVFAUpSoe6fObzQBRooVp7ARw7gJ4C+Q4xc1gJJkZoQ/Wj/wHkVnbLw9M5+t5GjyWgDDOr5iyoGOyIwhuEFvATzIYH0z5B6anL1n6XQmeGh5OWKJN8wE5qVNTU= worker@envoyer.io',
    'EDCSA' => 'ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFvXWSVYzRnjxYsz/xKjOjAaPjzg98MMHaDulQYczTX28xlsMmFkviCeCCv7CLh19ydoH4LNKpvgTGiMXz8ib68= worker@envoyer.',
]);

it('should return false if ssh file is invalid', function () {
    $validateSsh = new ValidateSsh('a simple text file');

    expect($validateSsh())->toBeFalsy();
});

Writing Our Rule

Think it's over? Not at all. The responsibility of the ValidateSsh class is only to check if the key is valid or not.

Let's create a rule so that we can use this validation.

php artisan make:rule IsSshKeyValid

Great, now we can do the following:

<?php

declare(strict_types=1);

namespace App\Rules;

use App\Terminal\ValidateSsh;
use Closure;
use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Translation\PotentiallyTranslatedString;

class IsSshKeyValid implements ValidationRule
{
    /**
     * @param Closure(string): PotentiallyTranslatedString $fail
     */
    public function validate(
        string $attribute,
        mixed $value,
        Closure $fail
    ): void {
        $validateSsh = new ValidateSsh($value);

        if (!$validateSsh()) {
            $fail('The :attribute is not a valid SSH key.');
        }
    }
}

With this, we're ready to write our HTTP tests ❤️

Testing Our HTTP Call

Before moving on to the HTTP tests, we need to add our rule to our validation rules:

'ssh_key' => [
    'nullable',
    'string',
    'unique:users,ssh_key',
    'max:5000',
    new IsSshKeyValid(),
],

And our tests for this field can look like this:

it('should validate `ssh_key` field', function (mixed $value, string $error) {
    login();

    postJson(route('api.users.store'), ['ssh_key' => $value])
        ->assertUnprocessable()
        ->assertJsonValidationErrors(['ssh_key' => $error]);
})->with([
    fn () => [5000, __('validation.string', ['attribute' => 'ssh key'])],
    fn () => [str_repeat('a', 5001), __('validation.max.string', ['attribute' => 'ssh key', 'max' => 5000])],
    fn () => ['aa', 'The ssh key is not a valid SSH key.'],
    function () {
        $user = User::factory()
            ->create([
                'ssh_key' => 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD3vYKSuh7rJf+NtWn04CFyT9+nmx+i+/sP+yMN9ueJ+Rd5Ku6d9kgscK2xwlRlkcA0sethslu0WUsG81RC1lVpF6iLrc/9O45ZhEY1CB/7dofr+7ZNwu/DJtbW6YE7oyT5G97BUW763TMq/YO9/xjMToetElTEJ4hUVWdP8q93b3MVHBazk2PEuS05wzP4p5XeQnhKq4LISetJFEgI8Y+HEpK29GiU/18fhaGZvdVwOToOxTwEwBbS3fTLNkBaUTWw9q3i7S60RRncBCHppcs2irrzw7yt7ZQOnut/BIjIGESoxx+N4ZrpTmX6P5d3/9Duk40Mfwh1ftsvze6o5AW4Xi0tki8b6bsMXmO7SapqVdiMZ5/4BWOkqHWhi926qz7I9NWoZuVFAUpSoe6fObzQBRooVp7ARw7gJ4C+Q4xc1gJJkZoQ/Wj/wHkVnbLw9M5+t5GjyWgDDOr5iyoGOyIwhuEFvATzIYH0z5B6anL1n6XQmeGh5OWKJN8wE5qVNTU= worker@envoyer.io',
            ]);

        return [$user->ssh_key, __('validation.unique', ['attribute' => 'ssh key'])];
    },
]);

it('should store an user', function () {
    login();

    $data = [
        'name'    => 'Matheus Santos',
        'email'   => 'matheusao@my-company.com',
        'ssh_key' => 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD3vYKSuh7rJf+NtWn04CFyT9+nmx+i+/sP+yMN9ueJ+Rd5Ku6d9kgscK2xwlRlkcA0sethslu0WUsG81RC1lVpF6iLrc/9O45ZhEY1CB/7dofr+7ZNwu/DJtbW6YE7oyT5G97BUW763TMq/YO9/xjMToetElTEJ4hUVWdP8q93b3MVHBazk2PEuS05wzP4p5XeQnhKq4LISetJFEgI8Y+HEpK29GiU/18fhaGZvdVwOToOxTwEwBbS3fTLNkBaUTWw9q3i7S60RRncBCHppcs2irrzw7yt7ZQOnut/BIjIGESoxx+N4ZrpTmX6P5d3/9Duk40Mfwh1ftsvze6o5AW4Xi0tki8b6bsMXmO7SapqVdiMZ5/4BWOkqHWhi926qz7I9NWoZuVFAUpSoe6fObzQBRooVp7ARw7gJ4C+Q4xc1gJJkZoQ/Wj/wHkVnbLw9M5+t5GjyWgDDOr5iyoGOyIwhuEFvATzIYH0z5B6anL1n6XQmeGh5OWKJN8wE5qVNTU= worker@envoyer.io',
    ];

    postJson(route('api.users.store'), $data)
        ->assertCreated();

    assertDatabaseHas(Users::class, $data);
});

Cool, right?

Now, I can register users in my system without worrying about those funny folks who might enter "aaaaaaa" in the ssh_key field 😃.

And remember, sometimes we need to think outside the box to find solutions to some problems. The more open-minded we are, the faster we can make progress and learn new things.

Cheers, and until next time 😗 🧀

Validando chave ssh pública no Laravel

Matheus Lopes Santos — Mon, 11 Sep 2023 20:40:49 +0000

Quando somos chamados para desenvolver uma aplicação, devemos ter em mente que podemos ter que lidar com vários tipos de problemas, aqueles que talvez jamais tenhamos imaginado em enfrentar. Contudo, vez ou outra precisamos sair de nossa zona de conforto.

Entendendo o problema

Há alguns dias, fui acionado para construir uma feature que iria receber a chave pública de um dev e iria enviá-la, posteriormente, para o forge, fazendo com que o usuário tivesse acesso ssh aos devidos servidores.

Maravilha Matheusão, como vou validar essa tipo de dado?

Incialmente a gente pensa em validar o básico, como o tamanho da string, se ela já existe no banco de dados, etc:

'ssh_key' => ['nullable', 'string', 'unique:users,ssh_key', 'max:5000']

Beleza, mas e se o meu usuário passar, sei lá, todas as letras do alfabeto? Infelizmente vai passar pela validação 🙁.

À procura da validação perfeita

Pesquisei bastante à respeito de como realizar essa validação. Em vários blogs, vi muita gente indicando usar funções nativas, como o openssl_verify, openssl_get_publickey ou a openssl_pkey_get_details, mas elas infelizmente não funcionaram para o que eu precisava (Lembre-se, uma chave SSH é diferente de uma chave SSL, por isso essas funções não funcionam). Vi em outros fóruns um pessoal dizendo para utilizar o package https://phpseclib.com/. Mas para pra pensar, pra que instalar um pacote que você só vai utilizar uma classe e somente um método dela?

Eu vejo isso como um acoplamento totalmente desnecessário, mas enfim…

Indo um pouco mais fundo

Depois de alguma pesquisa, vi que podemos usar o ssk-keygen para validar essa string pra gente, mas como?

Para isso, podemos usar duas flags, a -l para pegar o fingerprint e o -f para indicar o caminho do arquivo. Então o nosso comando ficaria assim:

ssh-keygen -lf /path/to/my/file.pub

E dessa forma poderemos checar se nossa chave SSH é válida ou não.

Criando nosso comando de checagem

O Laravel trouxe, a partir da versão 10, um componente chamado Process, que nada mais é do que um wrapper ao redor do componente Process do Symfony. É com esse carinha que vamos fazer a mágica.

Logicamente que poderíamos usa a função exec, nativa do php. Porém, se você acha que não é necessário usar este wrapper, fique à vontade 🙂👍🏻.

Vamos pensar o que precisamos fazer:

Preciso receber a string contendo a chave do usuário.
Preciso salvar essa string em algum lugar acessível.
Preciso chamar o comando ssh-keygen com o caminho do arquivo.
Preciso destruir o arquivo após a validação.

Configurando as Coisas

Vamos criar um diretório dentro de storage/app chamado ssh. Não se esqueça de remover esse novo diretório do seu versionamento:

storage/app/.gitignore

*
!public/
!.gitignore
!ssh/

storage/app/ssh/.gitignore

*
!.gitignore

Escrevendo nossa classe

Agora podemos criar a nossa classe que fará a interação com o ssh-keygen

App/Terminal/ValidateSsh.php

<?php

declare(strict_types=1);

namespace App\Terminal;

use Illuminate\Support\Facades\Process;
use Illuminate\Support\Str;

class ValidateSsh
{
    private string $keyPath;

    public function __construct(
        private readonly string $content
    ) {
        $this->keyPath = storage_path('app/ssh/' . Str::uuid() . '.pub');

        file_put_contents($this->keyPath, $this->content);
    }

    public function __invoke(): bool
    {
        return Process::run(
            command: 'ssh-keygen -lf ' . $this->keyPath . ' && rm ' . $this->keyPath,
        )->successful();
    }
}

Maravilha, a nossa classe está prontinha pra ser utilizada.

Recebe o conteúdo e salva com um nome aleatório.
Checa o arquivo e em caso de sucesso, já o apaga também.

Agora, vamos escrever os nossos testes.

tests/Unit/Terminal/ValidateSshTest.php

<?php

declare(strict_types=1);

use App\Terminal\ValidateSsh;

it('should return true if process if file is valid', function (string $key) {
    $validateSsh = new ValidateSsh($key);

    expect($validateSsh())->toBeTruthy();
})->with([
    'RSA'   => 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD3vYKSuh7rJf+NtWn04CFyT9+nmx+i+/sP+yMN9ueJ+Rd5Ku6d9kgscK2xwlRlkcA0sethslu0WUsG81RC1lVpF6iLrc/9O45ZhEY1CB/7dofr+7ZNwu/DJtbW6YE7oyT5G97BUW763TMq/YO9/xjMToetElTEJ4hUVWdP8q93b3MVHBazk2PEuS05wzP4p5XeQnhKq4LISetJFEgI8Y+HEpK29GiU/18fhaGZvdVwOToOxTwEwBbS3fTLNkBaUTWw9q3i7S60RRncBCHppcs2irrzw7yt7ZQOnut/BIjIGESoxx+N4ZrpTmX6P5d3/9Duk40Mfwh1ftsvze6o5AW4Xi0tki8b6bsMXmO7SapqVdiMZ5/4BWOkqHWhi926qz7I9NWoZuVFAUpSoe6fObzQBRooVp7ARw7gJ4C+Q4xc1gJJkZoQ/Wj/wHkVnbLw9M5+t5GjyWgDDOr5iyoGOyIwhuEFvATzIYH0z5B6anL1n6XQmeGh5OWKJN8wE5qVNTU= worker@envoyer.io',
    'EDCSA' => 'ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFvXWSVYzRnjxYsz/xKjOjAaPjzg98MMHaDulQYczTX28xlsMmFkviCeCCv7CLh19ydoH4LNKpvgTGiMXz8ib68= worker@envoyer.',
]);

it('should return false if ssh file is invalid', function () {
    $validateSsh = new ValidateSsh('a simple text file');

    expect($validateSsh())->toBeFalsy();
});

Escrevendo nossa rule

Pensa que acabou? Não mesmo. A responsabilidade da classe ValidateSsh é apenas a de verificar se a chave é válida ou não.

Vamos criar uma rule para que possamos fazer uso dessa validação.

php artisan make:rule IsSshKeyValid

Maravilha, agora, podemos fazer o seguinte:

<?php

declare(strict_types=1);

namespace App\Rules;

use App\Terminal\ValidateSsh;
use Closure;
use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Translation\PotentiallyTranslatedString;

class IsSshKeyValid implements ValidationRule
{
    /**
     * @param Closure(string): PotentiallyTranslatedString $fail
     */
    public function validate(
        string $attribute,
        mixed $value,
        Closure $fail
    ): void {
        $validateSsh = new ValidateSsh($value);

        if (!$validateSsh()) {
            $fail('The :attribute is not a valid SSH key.');
        }
    }
}

Com isso, já estamos prontos para fazer os nossos testes http ❤️

Testando nosso nossa chamada Http

Antes de prosseguir para os testes http, precisamos adicionar a nossa rule em nossas regras de validação:

'ssh_key' => [
    'nullable',
    'string',
    'unique:users,ssh_key',
    'max:5000',
    new IsSshKeyValid(),
],

E nossos testes para esse campo podem ficar dessa maneira:

it('should validate `ssh_key` field', function (mixed $value, string $error) {
    login();

    postJson(route('api.users.store'), ['ssh_key' => $value])
        ->assertUnprocessable()
        ->assertJsonValidationErrors(['ssh_key' => $error]);
})->with([
    fn () => [5000, __('validation.string', ['attribute' => 'ssh key'])],
    fn () => [str_repeat('a', 5001), __('validation.max.string', ['attribute' => 'ssh key', 'max' => 5000])],
    fn () => ['aa', 'The ssh key is not a valid SSH key.'],
    function () {
        $user = User::factory()
            ->create([
                'ssh_key' => 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD3vYKSuh7rJf+NtWn04CFyT9+nmx+i+/sP+yMN9ueJ+Rd5Ku6d9kgscK2xwlRlkcA0sethslu0WUsG81RC1lVpF6iLrc/9O45ZhEY1CB/7dofr+7ZNwu/DJtbW6YE7oyT5G97BUW763TMq/YO9/xjMToetElTEJ4hUVWdP8q93b3MVHBazk2PEuS05wzP4p5XeQnhKq4LISetJFEgI8Y+HEpK29GiU/18fhaGZvdVwOToOxTwEwBbS3fTLNkBaUTWw9q3i7S60RRncBCHppcs2irrzw7yt7ZQOnut/BIjIGESoxx+N4ZrpTmX6P5d3/9Duk40Mfwh1ftsvze6o5AW4Xi0tki8b6bsMXmO7SapqVdiMZ5/4BWOkqHWhi926qz7I9NWoZuVFAUpSoe6fObzQBRooVp7ARw7gJ4C+Q4xc1gJJkZoQ/Wj/wHkVnbLw9M5+t5GjyWgDDOr5iyoGOyIwhuEFvATzIYH0z5B6anL1n6XQmeGh5OWKJN8wE5qVNTU= worker@envoyer.io',
            ]);

        return [$user->ssh_key, __('validation.unique', ['attribute' => 'ssh key'])];
    },
]);

it('should store an user', function () {
    login();

    $data = [
        'name'    => 'Matheus Santos',
        'email'   => 'matheusao@my-company.com',
        'ssh_key' => 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD3vYKSuh7rJf+NtWn04CFyT9+nmx+i+/sP+yMN9ueJ+Rd5Ku6d9kgscK2xwlRlkcA0sethslu0WUsG81RC1lVpF6iLrc/9O45ZhEY1CB/7dofr+7ZNwu/DJtbW6YE7oyT5G97BUW763TMq/YO9/xjMToetElTEJ4hUVWdP8q93b3MVHBazk2PEuS05wzP4p5XeQnhKq4LISetJFEgI8Y+HEpK29GiU/18fhaGZvdVwOToOxTwEwBbS3fTLNkBaUTWw9q3i7S60RRncBCHppcs2irrzw7yt7ZQOnut/BIjIGESoxx+N4ZrpTmX6P5d3/9Duk40Mfwh1ftsvze6o5AW4Xi0tki8b6bsMXmO7SapqVdiMZ5/4BWOkqHWhi926qz7I9NWoZuVFAUpSoe6fObzQBRooVp7ARw7gJ4C+Q4xc1gJJkZoQ/Wj/wHkVnbLw9M5+t5GjyWgDDOr5iyoGOyIwhuEFvATzIYH0z5B6anL1n6XQmeGh5OWKJN8wE5qVNTU= worker@envoyer.io',
    ];

    postJson(route('api.users.store'), $data)
        ->assertCreated();

    assertDatabaseHas(Users::class, $data);
});

Legal não?

Agora, posso cadastrar os usuários no meu sistema sem me preocupar com aqueles engraçadinhos que vão passar um aaaaaaaa no campo ssh_key 😃.

E lembre-se, às vezes precisamos sair do óbvio para encontrar as soluções para alguns problemas. Quanto mais mente-aberta formos, mais rápido conseguimos progredir e aprender novas coisas.

Um abraço e até a próxima 😗 🧀

Unleashing the power of Laravel Horizon

Matheus Lopes Santos — Fri, 08 Sep 2023 16:06:27 +0000

I think background jobs are really handy, whether it's for importing a large CSV file, processing data from a webhook, or many other tasks that we can delegate to be processed without anyone watching.

In Laravel, it's no different. The framework provides us with a powerful out-of-the-box feature for queue processing. Let's recap how we can run our queue:

php artisan queue:work {connectionName} --queue={queueName} ...

Above, we have a very basic example of how to start our queue. There are several other options, and to learn about all of them, I suggest checking out the official documentation.

Enter Horizon

Horizon was released in 2017, and it's a package for running and monitoring the queue (remember, what isn't measured can't be managed). Its mission was not to replace but to complement Laravel's queues.

With Horizon, we have a much simpler way to manage everything needed to run our queue, as well as mechanisms to balance our queue execution.

A Common Issue...

One of the most common problems I've seen in applications I've maintained is the underutilization of Horizon. What do I mean by that? Let's see:

Projects that use only one worker for all queues.
Poor memory management.
An inadequate number of workers compared to the number of jobs the system processes.

"Does that mean I don't know how to configure my queue, Matheusão?"

It's not about that. Each project has its uniqueness, and all the configurations I'm going to show here will depend on whether the system uses queues extensively or not.

In this short article, I'll show you how to optimize your Horizon so it can handle many jobs and execute them smoothly.

Default Configuration

By default, Horizon comes with only one configured worker:

'defaults' => [
    'supervisor-1' => [
    'connection'          => 'redis',
        'queue'               => ['default'],
        'balance'             => 'auto',
        'autoScalingStrategy' => 'time',
        'maxProcesses'        => 3,
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
],

Great, but what does this configuration tell us?

Our worker will handle the default queue.
In this case, load balancing doesn't apply because we have only one queue.
We will have the maximum of three running process.
Jobs will be executed only once, and no other attempts are allowed.
Jobs have a timeout of 60 seconds.

That's great, but what if our demand starts to grow?

Adding Queues to the Worker

Let's imagine I have one queue for processing emails and another for other system jobs. Cool, I could do it like this:

'defaults' => [
    'supervisor-1' => [
    'connection'          => 'redis',
        'queue'               => ['emails', 'default'],
        'balance'             => 'auto',
        'autoScalingStrategy' => 'time',
        'maxProcesses'        => 3,
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
],

Nice, but what do we have now?

Two queues being processed by the worker.
A maximum of 3 processes for the queues.

With this configuration, whoever needs more gets more processes. Imagine that the email queue has 40 jobs and the default queue only has 4. Horizon will allocate 2 processes for the emails queue and 1 process for the default queue.

Configuring Multiple Workers in Horizon

Now, let's get to the peak of our scenario. Let's imagine the following:

Notifications (e.g., via Slack)
Email sending
Receiving webhook data
CSV data import

"Isn't that a bit too much?"

Let's take it step by step; it will work out.

Prioritizing Our Queue

To start things off, let's categorize our queues:

High priority
Low priority
Default
Jobs that can take a long time to finish

Great, now that I have these categories, I'll use an enum to keep track of them:

<?php

declare(strict_types=1);

namespace App\Enums;

enum QueuePriority: string
{
    case Low         = 'low';
    case High        = 'high';
    case LongTimeout = 'long-timeout';
}

Note that I didn't add the default queue to this enum because jobs that aren't categorized will go directly to it in queue. But feel free to add it if you want 😃.

This way, we can dispatch our jobs like this:

InviteUser::dispatch($user)->onQueue(
    QueuePriority::High->value
);

Elegant, isn't it?

Tuning Our Horizon

Now, we can create more workers and further separate and organize our queue:

'defaults' => [
    'supervisor-high-priority' => [
        'connection'          => 'redis',
        'queue'               => [QueuePriority::High->value],
        'balance'             => 'auto',
        'minProcesses'        => 1,
        'maxProcesses'        => 6,
        'balanceMaxShift'     => 3,
        'balanceCooldown'     => 2,
        'autoScalingStrategy' => 'size',
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
    'supervisor-low-priority' => [
        'connection'          => 'redis',
        'queue'               => [QueuePriority::Low->value, 'default'],
        'balance'             => 'auto',
        'minProcesses'        => 1,
        'maxProcesses'        => 3,
        'balanceMaxShift'     => 1,
        'balanceCooldown'     => 3,
        'autoScalingStrategy' => 'size',
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
    'supervisor-long-timeout' => [
        'connection'          => 'redis',
        'queue'               => [QueuePriority::LongTimeout->value],
        'balance'             => 'auto',
        'minProcesses'        => 1,
        'maxProcesses'        => 3,
        'balanceMaxShift'     => 1,
        'balanceCooldown'     => 3,
        'autoScalingStrategy' => 'size',
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 600,
        'nice'                => 0,
    ],
],

'environments' => [
    'production' => [
        'supervisor-high-priority' => [],
        'supervisor-low-priority'  => [],
        'supervisor-long-timeout'  => [],
    ],

    'staging' => [
        'supervisor-high-priority' => [],
        'supervisor-low-priority'  => [],
        'supervisor-long-timeout'  => [],
    ],

    'local' => [
        'supervisor-high-priority' => [],
        'supervisor-low-priority'  => [],
        'supervisor-long-timeout'  => [],
    ],
],

What do we have here, my friend? Now we've got 3 workers for different queues, with the following setups:

supervisor-high-priority

Takes care of the high priority queue.
Maximum of 6 processes.
It will start or terminate 3 processes (maxShift) every 2 seconds (coolDown).
Timeout set to 1 minute.

supervisor-low-priority

Manages the low priority and default queues.
Maximum of 3 processes.
It will start or terminate 1 process (maxShift) every 3 seconds (coolDown).
Timeout set to 1 minute.

supervisor-long-timeout

Handles the long-timeout queue.
Maximum of 3 processes.
It will start or terminate 1 process (maxShift) every 3 seconds (coolDown).
Timeout set to 10 minutes.

It's a straightforward setup, but it gets the job done 😃.

To wrap it up...

Now our queue is configured and ready to handle a good number of jobs. But remember, before increasing the number of workers, make sure your server has enough resources available for your new workers.

The way I presented it, the queue itself won't cause issues for your server. However, if you're using Redis, for example, what can potentially cause problems is seeing your application go down due to memory shortages, but that's a topic for another conversation.

Start small, increase a process here, another there, tweak a timeout as needed. Never go all-in with the maximum your server can handle. Gradually and with caution, you can find the perfect balance between background processing and the rest of your application.

Take care and until next time 😗🧀.

Liberando os poderes do Laravel Horizon

Matheus Lopes Santos — Fri, 08 Sep 2023 15:40:03 +0000

Particularmente acho que jobs em background são uma mão na roda. Que seja para importação de um grande arquivo csv, processamento de dados que chegaram de um webhook, dentre tantas outras coisas que podemos designar para serem processadas sem que ninguém esteja olhando.

No Laravel não é diferente. O framework nos provê uma poderosa feature de processamento de filas totalmente out-of-the-box. Vamos recapitular como podemos executar a nossa fila:

php artisan queue:work {connectionName} --queue={queueName} ...

Acima, temos um exemplo bem básico de como iniciar a nossa fila. Existem várias outras opções e, para conhecer todas, sugiro dar uma conferida na documentação oficial do framework.

A vinda do Horizon

O horizon foi lançado em 2017 e é um package para execução e monitoramento da fila (Lembre-se, o que não é medido, não pode ser gerenciado). Ele veio não com a missão de substituir, mas a de complementar as queues do Laravel.

Com ele, temos uma execução bem mais simples de tudo o que eu preciso para rodar a minha fila, além de definir mecanismos para balancear a execução de nossa fila.

Um problema constante…

Um dos problemas que mais vi em aplicações em que dei manutenção foi a subutilização do horizon. Como assim Matheusão? Vejamos:

Projetos que utilizavam somente um worker e com todas as filas configuradas nesse worker
Gerenciamento de memória deficiente
Número de workers incompatível com a quantidade que jobs que o sistema processa

Quer dizer que eu não sei configurar a minha fila, Matheusão?

Não é isso. Cada projeto tem a sua particularidade, e todas as configurações que farei aqui vão depender do uso massivo ou não do sistema de filas.

Neste pequeno artigo, vou mostrar pra vocês como otimizar o seu horizon para que possa receber vários jobs e executar tudo de forma suave.

A configuração padrão

Por padrão, o horizon vem com um worker configurado apenas:

'defaults' => [
    'supervisor-1' => [
    'connection'          => 'redis',
        'queue'               => ['default'],
        'balance'             => 'auto',
        'autoScalingStrategy' => 'time',
        'maxProcesses'        => 3,
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
],

Maravilha, mas o que essa configuração mostra pra gente?

Nosso worker trabalhará com a fila default
Nesse caso, o balanceamento não se aplica, pois só temos uma fila
Teremos, no máximo, 3 processos em execução
Os jobs serão executados somente uma vez, não sendo permitidas outras tentativas
Os jobs terão timeout de 60 segundos

Maravilha, amigos. Com esta configuração padrão, uma aplicação consegue rodar bastante coisa, mas, e se nossa demanda começar a crescer?

Adicionando filas ao worker

Vamos imaginar que eu tenho uma fila para para processar e-mails e outra para os demais jobs do sistema. Top, poderia fazer da seguinte forma:

'defaults' => [
    'supervisor-1' => [
    'connection'          => 'redis',
        'queue'               => ['emails', 'default'],
        'balance'             => 'auto',
        'autoScalingStrategy' => 'time',
        'maxProcesses'        => 3,
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
],

Massa, mas, o que temos agora?

Duas filas sendo executadas pelo worker
máximo de 3 processos para as filas

Com esta configuração, quem estiver precisando mais, leva mais processos com ele. Imagine você que a fila de e-mails tem 40 jobs e a fila default, só 4. O horizon vai disponibilizar 2 processos para a fila emails e 1 processo para a fila default.

Configurando vários workers no horizon

Agora chegaremos ao ápice do nosso cenário. Vamos imaginar o seguinte:

Notificações (via slack por exemplo)
Envio de emails
Recebimento de dados de webhooks
Importação de dados via CSV

Cara, não tem coisa demais ai não?

Vamos com calma que o negócio vai dar bom.

Priorizando nossa fila

Pra começar os trabalhos, vamos categorizar as nossas filas

Alta prioridade
Baixa Prioridade
Default
Jobs que podem levar muito tempo para finalizarem

Maravilha, agora que já tenho as minhas categorias, vou fazer uso de um enum que guardará essas categorias pra mim:

<?php

declare(strict_types=1);

namespace App\Enums;

enum QueuePriority: string
{
    case Low         = 'low';
    case High        = 'high';
    case LongTimeout = 'long-timeout';
}

Note que eu não adicionei a fila default nesse enum, pelo simples fato de que os jobs que não forem categorizados já vão direto pra ela. Mas se quiser colocar, fique à vontade 😃.

Dessa forma, podemos despachar os nossos jobs da seguinte forma:

InviteUser::dispatch($user)->onQueue(
    QueuePriority::High->value
);

Elegante, não?

Tunando o nosso horizon

Agora, poderemos criar mais workers e deixar nossa fila ainda mais separada e organizada:

'defaults' => [
    'supervisor-high-priority' => [
        'connection'          => 'redis',
        'queue'               => [QueuePriority::High->value],
        'balance'             => 'auto',
        'minProcesses'        => 1,
        'maxProcesses'        => 6,
        'balanceMaxShift'     => 3,
        'balanceCooldown'     => 2,
        'autoScalingStrategy' => 'size',
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
    'supervisor-low-priority' => [
        'connection'          => 'redis',
        'queue'               => [QueuePriority::Low->value, 'default'],
        'balance'             => 'auto',
        'minProcesses'        => 1,
        'maxProcesses'        => 3,
        'balanceMaxShift'     => 1,
        'balanceCooldown'     => 3,
        'autoScalingStrategy' => 'size',
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 60,
        'nice'                => 0,
    ],
    'supervisor-long-timeout' => [
        'connection'          => 'redis',
        'queue'               => [QueuePriority::LongTimeout->value],
        'balance'             => 'auto',
        'minProcesses'        => 1,
        'maxProcesses'        => 3,
        'balanceMaxShift'     => 1,
        'balanceCooldown'     => 3,
        'autoScalingStrategy' => 'size',
        'maxTime'             => 0,
        'maxJobs'             => 0,
        'memory'              => 128,
        'tries'               => 1,
        'timeout'             => 600,
        'nice'                => 0,
    ],
],

'environments' => [
    'production' => [
        'supervisor-high-priority' => [],
        'supervisor-low-priority'  => [],
        'supervisor-long-timeout'  => [],
    ],

    'staging' => [
        'supervisor-high-priority' => [],
        'supervisor-low-priority'  => [],
        'supervisor-long-timeout'  => [],
    ],

    'local' => [
        'supervisor-high-priority' => [],
        'supervisor-low-priority'  => [],
        'supervisor-long-timeout'  => [],
    ],
],

O que temos aqui, meu querido? Agora temos 3 workers para diferentes filas, com as seguintes configurações:

supervisor-high-priority
- Toma conta da fila high
- Máximo de 6 processos
- Vai subir ou matar 3 processos (maxShift) a cada 2 segundos (coolDown)
- Timeout de 1 minuto
supervisor-low-priority
- Toma conta das filas low e default
- Máximo de 3 processos
- Vai subir ou matar 1 processo (maxShift) a cada 3 segundos (coolDown)
- Timeout de 1 minuto
supervisor-long-timeout
- Toma conta da fila long-timeout
- Máximo de 3 processos
- Vai subir ou matar 1 processo (maxShift) a cada 3 segundos (coolDown)
- Timeout de 10 minutos

Uma configuração simples, mas que dá conta do recado 😃.

Pra finalizar…

Agora a nossa fila está configurada e pronta para metralhar uma boa quantidade de jobs. Mas lembre-se que, antes de aumentar os workers, certifique-se de que seu servidor tenha recursos disponíveis para seus novos workers.

Da forma que apresentei para vocês, a fila em si não trará gargalos para seu servidor; o que pode vir a trazer problemas, caso use o Redis por exemplo, é ver a sua aplicação cair por falta de memória, mas aí já é papo para outra conversa.

Sempre comece do pouco, aumente um processo aqui, outro ali, um timeout acolá. Jamais coloque tudo que você achar o máximo que o seu servidor consegue processar. Aos poucos e com prudência, você consegue achar o equilíbrio perfeito entre o que é processado em background e o restante da aplicação.

Um abraço e até a próxima 😗🧀

Mocking Browsershot library in your tests

Matheus Lopes Santos — Tue, 05 Sep 2023 20:29:38 +0000

In our journey as developers, we often find ourselves creating applications that need to export reports or pages to PDF format. For a long time, we used various libraries for this task, such as mPDF, FPDF, wkHtmlToPdf, among others. However, today, in my humble opinion, we have one of the best packages for PDF generation on the market, which is Browsershot. It's straightforward to configure and generate PDF files.

But, here's the issue some devs face: How can I write tests for a class that uses Browsershot? Let's dive a bit deeper.

Imagine we have a class called GeneratePdf that takes a file name, a URL to render, and maybe the paper size as parameters. This class will save our PDF to AWS S3.

⚠️ The examples here are written in a Laravel application and using Pest for automated tests.

<?php

declare(strict_types=1);

namespace App\Actions;

use Illuminate\Support\Facades\Storage;
use Spatie\Browsershot\Browsershot;

class GeneratePdf
{
    public function handle(
        string $fileName,
        string $url,
        string $paperSize = 'A4'
    ): string | false {
        $path    = '/exports/pdf/' . $fileName;
        $content = Browsershot::url($url)
            ->format($paperSize)
            ->noSandbox()
            ->pdf();

        if (!Storage::disk('s3')->put($path, $content)) {
            return false;
        }

        return $path;
    }
}

Fantastic! Our action will save the PDF and return the path so that we can use it in an email, save it in a database, and so on. The only responsibility of this class is to generate the PDF and return the path.

But now, how do we test this little guy?

Writing Our Tests

Okay, in this phase, let's write a simple test to see if everything works as expected.

it('should generate a pdf', function () {
    Storage::fake('s3');

    $pdf = (new GeneratePdf())->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

However, you might notice that our test takes a while to execute. But why?

Our test took a while because Browsershot made a request to google.com to fetch its content and create the PDF for you.

Alright, it's just one test, what's the harm in that? Let's think:

What if there's more than one class using Browsershot?
What if you have no internet connection? The test fails.
What if you're using a paid pipeline service? The test will take longer, and you'll pay more for it.

So, how can we write our test more efficiently?

with MOCKERY ✨✨✨

Mockery

To simulate the behavior of a class, we can use the Mockery library, which is already available in PHPUnit and Pest.

This library provides an interface where we can mimic or spy on our class's behavior to make assertions on the methods that were called.

But there's a problem (there always is), a static call...

BrowserShot::url(...)

The Problem with Static Methods

Static methods are great, especially for helper classes, such as a method that checks whether a CPF (Brazilian social security number) is valid or not. In such cases, since we won't have access to $this, we can make these methods static without any issues.

However, this comes at a cost...

Writing unit tests for static methods is straightforward. We call the method and make the necessary assertions, simple as that. But what if I need to mock a class that calls a static method and then calls its non-static methods?

According to the Mockery documentation, it doesn't support mocking public static methods. To work around this, there's a kind of hack to bypass this behavior, which involves creating an alias. (You can read more about it here).

it('should generate a pdf', function () {
    Storage::fake('s3');

    mock('alias:' . Browsershot::class)
        ->shouldReceive('url->format->noSandbox->pdf');

    $pdf = (new GeneratePdf())->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

Alright, but what does this do? When we use alias:, we're telling Composer:

"Hey, when I need Browsershot, bring this one here to me, not the original class."

The catch is that even Mockery doesn't recommend using alias: or overload:. This can lead to class name collision errors and should be run in separate PHP processes to avoid this.

So, my friend, how do I write this test?

In fact, let's change the approach on how we use Browsershot :)

Dependency Analysis and Dependency Injection

By analyzing the Browsershot::url method, we can discover what it does, and it's extremely simple.

public static function url(string $url): static
{
    return (new static())->setUrl($url);
}

Great, to avoid using alias: or overload:, we can simply inject Browsershot into our class. Now, it looks like this:

<?php

declare(strict_types=1);

namespace App\Actions;

use Illuminate\Support\Facades\Storage;
use Spatie\Browsershot\Browsershot;

class GeneratePdf
{
    public function __construct(
        private Browsershot $browsershot
    ) {
    }

    public function handle(
        string $fileName,
        string $url,
        string $paperSize = 'A4'
    ): string | false {
        $path    = '/exports/pdf/' . $fileName;
        $content = $this->browsershot->setUrl($url)
            ->format($paperSize)
            ->noSandbox()
            ->pdf();

        if (!Storage::disk('s3')->put($path, $content)) {
            return false;
        }

        return $path;
    }
}

This way, mocking becomes much lighter and efficient:

it('should generate a pdf', function () {
    Storage::fake('s3');

    $mock = mock(Browsershot::class);
    $mock->shouldReceive('setUrl->format->noSandbox->save');

    $pdf = (new GeneratePdf($mock))->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

If you're using Laravel, you can use the $this->mock method, which interacts directly with the framework's container.

Our test now looks like this:

it('should generate a pdf', function () {
    Storage::fake('s3');
    Storage::put('pdf/my-file-name.pdf', 'my-fake-file-content');

    $this->mock(Browsershot::class)
        ->shouldReceive('setUrl->format->noSandbox->save');

    $pdf = app(GeneratePdf::class)->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

By doing this, we make our class loosely coupled, allowing us to perform a wide range of tests without much hassle, and we get to use a powerful pattern, which is dependency injection.

Until next time, folks. 😗 🧀

Mockando a biblioteca BrowserShot em seus testes

Matheus Lopes Santos — Tue, 05 Sep 2023 12:08:40 +0000

Em nossa carreira como dev acabamos por fazer várias aplicações que necessitam exportar algum relatório, ou página, em PDF. Por muito tempo, nós usamos várias bibliotecas para isso, como a mPDF, FPDF, wkHtmlToPdf dentre outras. Hoje temos, na minha humilde opinião, um dos melhores packages para geração de PDF no mercado, que é o Browsershot. Muito simples de configurar e gerar arquivos PDF pra gente.

Porém, vejo alguns devs com o seguinte problema: Como posso escrever testes para uma classe que vai fazer uso do Browsershot? Vamos mergulhar um pouco mais.

Vamos imaginar que temos uma classe chamada GeneratePdf e que aceitará um nome para o arquivo, uma URL para ser renderizada e, talvez, o tamanho do papel. Essa classe irá salvar o nosso PDF na AWS S3.

⚠️ Os exemplos aqui escritos foram feitos em uma aplicação Laravel e utilizando o pest para testes automatizados

<?php

declare(strict_types=1);

namespace App\Actions;

use Illuminate\Support\Facades\Storage;
use Spatie\Browsershot\Browsershot;

class GeneratePdf
{
    public function handle(
        string $fileName,
        string $url,
        string $paperSize = 'A4'
    ): string | false {
        $path    = '/exports/pdf/' . $fileName;
        $content = Browsershot::url($url)
            ->format($paperSize)
            ->noSandbox()
            ->pdf();

        if (!Storage::disk('s3')->put($path, $content)) {
            return false;
        }

        return $path;
    }
}

Maravilha, a nossa action vai salvar o PDF e retornar o caminho para que possamos utilizar ele em um e-mail, salvar em um banco de dados, etc. A única responsabilidade dessa classe é gerar o PDF e retornar o caminho.

Mas, e agora, como faço para testar esse carinha?

Escrevendo meus testes

Beleza, nessa fase escrevemos um teste simples para ver se tudo vai funcionar como esperamos.

it('should generate a pdf', function () {
    Storage::fake('s3');

    $pdf = (new GeneratePdf())->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

Contudo, podemos notar que o nosso teste vai demorar um pouco. Mas, por quê?

Nosso teste demorou a ser executado por que o Browsershot fez uma requisição ao google.com para pegar seu conteúdo e montar o pdf pra você.

Ok, ok. É um teste apenas, que mal há nisso? Vamos pensar:

E se houver mais de uma classe que faz uso do Browsershot?
E se você estiver sem internet? - O teste falha;
E se você estiver utilizando um serviço de pipeline pago? O teste vai demorar e você vai pagar a mais por isso;

Então Matheusão, como faço para escrever meu teste de uma forma mais eficiente?

Com MOCKERY ✨✨✨

Mockery

Para que possamos simular o comportamento de uma classe, podemos usar a biblioteca Mockery, que já vem disponível no PHPUnit e no Pest.

Essa lib provê uma interface onde eu posso simular o comportamento da minha classe, ou expiá-la, para que possamos fazer o assert dos métodos que foram chamados.

Mas existe um problema (sempre ele), uma chamada estática...

BrowserShot::url(...)

O problema dos métodos estáticos.

Métodos estáticos são legais, principalmente para classes de helpers, como por exemplo, um método que checa se um CPF é válido ou não.

Nesses casos, como sei que não terei acesso ao $this, posso desenhar esse método para ser estático, sem problema algum.

Porém, isso tem um custo...

Fazer testes unitários para métodos mágicos é muito simples. Chamo o meu método e faço as asserções que preciso, simples assim. Mas e quando eu preciso mockar uma classe que está chamando um método estático e, logo após, chama os métodos não estáticos dela?

Segundo a documentação do mockery, ele não suporta o mocking de métodos públicos estáticos. Para fazer isso, existe uma espécie de hack para burlar esse comportamento, que é criando um alias. (Você pode ler mais aqui)

it('should generate a pdf', function () {
    Storage::fake('s3');

    mock('alias:' . Browsershot::class)
        ->shouldReceive('url->format->noSandbox->pdf');

    $pdf = (new GeneratePdf())->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

Show, mas, o que isso faz? Quando usamos o alias:, nós dizemos ao composer:

Olha, quando eu precisar do Browsershot, traz esse carinha aqui pra mim, não a classe original.

O detalhe é que nem a própria mockery recomenda que façamos uso do alias: ou do overload:. Isso pode causar erros de colisão de nomes de classes e devem ser executados em processos PHP separados para evitar isso.

Pô amigo, como vou escrever esse teste?

Na verdade, vamos mudar a abordagem de como usamos o Browsershot :)

Análise de dependência e Dependency Injection

Ao analisar o método Browsershot::url, podemos descobrir o que ele faz, e é extremamente simples.

public static function url(string $url): static
{
    return (new static())->setUrl($url);
}

Massa, então para evitar o uso de alias: ou overload:, podemos simplesmente injetar o browsershot em nossa classe. Agora ela fica assim:

<?php

declare(strict_types=1);

namespace App\Actions;

use Illuminate\Support\Facades\Storage;
use Spatie\Browsershot\Browsershot;

class GeneratePdf
{
    public function __construct(
        private Browsershot $browsershot
    ) {
    }

    public function handle(
        string $fileName,
        string $url,
        string $paperSize = 'A4'
    ): string | false {
        $path    = '/exports/pdf/' . $fileName;
        $content = $this->browsershot->setUrl($url)
            ->format($paperSize)
            ->noSandbox()
            ->pdf();

        if (!Storage::disk('s3')->put($path, $content)) {
            return false;
        }

        return $path;
    }
}

Dessa forma, o mock fica muito mais leve e eficiente:

it('should generate a pdf', function () {
    Storage::fake('s3');

    $mock = mock(Browsershot::class);
    $mock->shouldReceive('setUrl->format->noSandbox->save');

    $pdf = (new GeneratePdf($mock))->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

Se você estiver utilizando o Laravel, pode usar o método $this->mock que vai interagir diretamente com o container do framework.

Nosso teste fica assim:

it('should generate a pdf', function () {
    Storage::fake('s3');
    Storage::put('pdf/my-file-name.pdf', 'my-fake-file-content');

    $this->mock(Browsershot::class)
        ->shouldReceive('setUrl->format->noSandbox->save');

    $pdf = app(GeneratePdf::class)->handle(
        fileName: 'my-file-name.pdf',
        url: 'https://www.google.com'
    );

    Storage::disk('s3')
        ->assertExists($pdf);
});

Dessa forma, deixamos a nossa classe fracamente acoplada, com uma ampla gama de testes que podemos fazer sem penar muito e, de quebra, ainda podemos fazer uso de um pattern poderoso que é a injeção de dependência.

Até a próxima, pessoal. 😗 🧀