Forem: Joubert RedRat

CNPJ alfanumérico com PHP

Joubert RedRat — Thu, 26 Sep 2024 14:02:46 +0000

Disclaimer: Eu não sou uma entidade divina. O que eu falo não é uma verdade absoluta. Não tenha medo de questionar até o mundo, pois ele pode estar errado, não você. #devsforliberty

Hoje o CNPJ (Cadastro Nacional da Pessoa Jurídica) é um número único que identifica uma pessoa jurídica e outros tipos de arranjo jurídico sem personalidade, ou seja, basicamente é um número identificador de uma empresa.

Fonte: Wikipédia

Hoje ele é composto por 14 dígitos ou 18 dígitos se você considerar os pontos, hífen e barra, o famoso 12.345.6789/0001-23, porém, iremos ver que isto irá mudar.

Nota Técnica conjunta COCAD, SUARA e RFB

Recentemente, surgiu uma nova nota técnica com mudanças no número do CNPJ, permitindo além dos números, letras, visando a expansão de combinações, dos atuais 99,9 milhões para quase um trilhão, isto é virtualmente infinito!

Caso queira acessar a nota técnica na integra, basta acessar o endereço http://sadd.receita.fazenda.gov.br/sadd-internet/pages/validadocumento.xhtml e usar o código AP16.0524.06247.2039 para baixar o PDF.

E aqui eu deixo minha pequena e ácida crítica a Receita Federal baseado no dia de hoje, 26/09/2024. É sério mesmo que uma plataforma importante de validação de documento não está com proteção SSL no HTTP Receita? É sério mesmo que vai fazer esse tipo de noobagem nesta altura do campeonato? Foda viu…

CNPJ alfanumérico

Certo, agora iremos ter mudanças no número do CNPJ, como a imagem abaixo.

Felizmente, a fórmula de cálculo do módulo 11, usado para validar o CNPJ não mudou, pois ele vai considerar os valores representados pelas letras, conforme a memória de cálculo, que é claro, iremos ignorar, mas fica bonito no post.

O Dev.to ainda não suporta MathJax, então se quiser ver a fórmula, vai ter que ir em https://blog.redrat.com.br/cnpj-alfanumerico-com-php#heading-cnpj-alfanumerico

Porque a memória de cálculo não muda? Porque basicamente o valor de cada letra será o seu valor correspondente na tabela ASCII subtraindo 48. Então a lógica será como abaixo.

A = 65 - 48 = 17
B = 66 - 48 = 18
C = 67 - 48 = 19
D = 68 - 48 = 20
E = 69 - 48 = 21
...
E assim sucessivamente

Vale lembrar que está sendo considerado somente as letras maiúsculas neste cálculo, pois o valor das letras minúsculas são diferentes, então é preciso tomar cuidado com isto.

Tá, como fica isto no PHP?

Bom, como eu estava atoa na calada da noite, decidi refatorar meu Value Object do CNPJ para suportar esse novo cálculo.

Caso você queria ver todas as alterações na íntegra, basta conferir o meu commit 7fd37a3.

Primeiro eu mudei as funções de regex que validavam o valor string que eu recebia para deixar em conformidade com basicamente ser uma string numérica com 11 caracteres e que não tivesse números todos repetidos, como 11111111111111 por exemplo. Agora esta regex também aceita letras maiúsculas e minúsculas.

$number = preg_replace('/[^A-Za-z0-9]/', '', $number);

if (14 != strlen($number)) {
    return false;
}

if (false !== filter_var($number, FILTER_VALIDATE_REGEXP, ['options' => ['regexp' => '/([A-Za-z0-9])\1{13}/']])) {
    return false;
}

Depois disto, eu faço a conversão do meu valor string alfanumérico para um array de 14 elementos números inteiros que serão usados na memória de cálculo para validar o CNPJ.

private const ALPHA_ASCII_SUBTRACT = 48;

/* code */

$numbers = self::convert($number);

/* code */

private static function convert(string $number): array
{
    $numbers = [];
    foreach (str_split($number) as $char) {
        $numbers[] = ctype_alpha($char) ? ord(strtoupper($char)) - self::ALPHA_ASCII_SUBTRACT : (int) $char;
    }

    return $numbers;
}

Note que embora eu esteja aceitando letras maiúsculas ou minúsculas, eu faço a conversão para letras maiúsculas, evitando o erro para o cálculo.

Como a memória de cálculo não mudou, eu basicamente troquei a string numérica pelo array de números para fazer o cálculo.

A implementação completa da classe pode ser conferida em Cnpj.php. Pode usar minha classe a vontade para brincar ou para produção, pois ele usa uma linda licença MIT.

Quando isto irá ocorrer?

Felizmente, a Receita Federal ainda tem um pouco de bom senso, então está previsto a implementação interna deles em 2025 e o início da produção do novo padrão no início de 2026. Parece muito tempo, mas é bom estar preparado antecipadamente para o seu sistema não quebrar.

Então é isto, até a próxima!

Integration tests on Symfony with Testcontainers

Joubert RedRat — Thu, 12 Sep 2024 00:46:57 +0000

Disclaimer: I'm not a divine entity. What I say is not an absolute truth. Don't be afraid to question even the world, because it might be wrong, not you.

Today isn't a secret for nobody the importance of automated tests for keeping quality and integrity of your software and normally we talk much about unit tests, but, today, we will focus more in integration tests into Symfony Framework.

I have no patience, show me the code!

Okay okay! If you have no patience for reading the article, I have a test project with the implementation of this article in link below.

https://github.com/joubertredrat/symfony-testcontainers

Symfony Framework and integration tests

Today Symfony Framework is one of most mature and stable frameworks in PHP universe and it have various good implemented solutions, as integration tests for example. But, personally I always thought that although is easy to do integration tests itself, to provide external dependencies for test It wasn't always so easy, as databases for example.

Even with a solutions like Docker, I still realized necessity to provide the external dependencies in a way for the tests, but, exists a very interesting solution that can make this step much easier, the Testcontainers.

Testcontainers

Testcontainers is an open source framework that let you provide in a easy way any external dependency that you need using Docker, as databases, message broker, cache system, or ever dependency in container.

The big advantages of Testcontainers in relation to Docker compose or other way of container orchestration is you can code the provisioning of container, and today already have support to Golang, Java, .NET, Node.js, Python, Rust, various other languages and of course, PHP too!

My first contact with Testcontainers was in a project in Golang and I liked so much the facility of provisioning MongoDB container to do the repository tests and after that, I decided to do same thing in my personal project in PHP using Symfony Framework.

Symfony + Testcontainers = ❤️

One of biggest advantages of Symfony is the support to do tests integrated with PHPUnit and with a functional kernel to do the bootstrap necessary for the tests.

Although Testcontainers have support to PHP, their implementation is recent and you can view it at https://github.com/testcontainers/testcontainers-php.

Below we have a implementation of MySQL 8.0 container, that is a external dependency of this project, and the boot of Symfony kernel, creation of database and schema.

class IntegrationTestCase extends KernelTestCase
{
    protected static ?MySQLContainer $container = null;

    public static function setUpBeforeClass(): void
    {
        parent::setUpBeforeClass();

        if (!static::$container) {
            static::$container = MySQLContainer::make('8.0', 'password');
            static::$container->withPort('19306', '3306');
            static::$container->run();

            $kernel = self::bootKernel();
            $container = $kernel->getContainer();

            $application = new Application($kernel);
            $application->setAutoExit(false);

            $application->run(
                new ArrayInput(['command' => 'doctrine:database:create', '--if-not-exists' => true])
            );

            $entityManager = $container->get('doctrine')->getManager();
            $metadata = $entityManager->getMetadataFactory()->getAllMetadata();
            $schemaTool = new SchemaTool($entityManager);
            $schemaTool->dropSchema($metadata);
            $schemaTool->createSchema($metadata);
        }
    }

    public static function tearDownAfterClass(): void
    {
        parent::tearDownAfterClass();

        if (static::$container instanceof MySQLContainer) {
            static::$container->remove();
        }
    }

With this, we have the basis class for the classes that will execute the tests itself, as example below.

class UserRepositoryTest extends IntegrationTestCase
{
    public function testSave(): void
    {
        $user = new User();
        $user->setName('John Doe');
        $user->setEmail('john@doe.local');

        $repo = $this->getRepository();
        $repo->save($user, true);

        self::assertNotNull($user->getId());
        self::assertIsInt($user->getId());
        self::assertTrue($user->getId() > 0);
    }

    public function testGetByEmail(): void
    {
        $user = new User();
        $user->setName('John Doe');
        $user->setEmail('john2@doe.local');

        $repo = $this->getRepository();
        $userNotFound = $repo->getByEmail($user->getEmail());
        self::assertNull($userNotFound);

        $repo->save($user, true);
        $userFound = $repo->getByEmail($user->getEmail());

        self::assertEquals($user->getEmail(), $userFound->getEmail());
    }

    protected function tearDown(): void
    {
        parent::tearDown();

        $connection = $this
            ->getContainer()
            ->get('doctrine')
            ->getManager()
            ->getConnection()
        ;
        $connection->executeStatement('TRUNCATE TABLE users');
    }

    protected function getRepository(): UserRepository
    {
        return $this->getContainer()->get(UserRepository::class);
    }
}

When running suite of tests, you can view that tests will execute slowly compared with unit tests of tests with just mocked behaviors, but this is normal, because during this process, Testcontainers is provisioning the container that you defined to use in tests.

Finally, with this facility, can be possible to do crazy things, like 100% of coverage. Don't believe it? You can see for yourself at https://joubertredrat.github.io/symfony-testcontainers.

UPDATE 12/11: At start, in examples above I used setUpBeforeClass() and tearDownAfterClass() for control the operating state of container for tests, but, after I discovered that these methods executes in each new test classes, and we don't want this.

Because of this, I've fixed the project for using Extensions and Subscribers from PHPUnit in 11 version, and this solved the issue, making that container starts before and stop after all suit of tests.

Depending of PHPUnit version you're using, can be necessary use a different approach.

That's it, see you next!

Testes de Integração no Symfony com Testcontainers

Joubert RedRat — Thu, 29 Aug 2024 14:46:49 +0000

Disclaimer: Eu não sou uma entidade divina. O que eu falo não é uma verdade absoluta. Não tenha medo de questionar até o mundo, pois ele pode estar errado, não você.

Hoje não é segredo para ninguém a importância dos testes automatizados para manter a qualidade e integridade do seu software e normalmente falamos muito de testes unitários, porém, hoje, iremos focar mais em testes de integração no Symfony Framework.

Estou sem paciência, mostre me o código!

Okay okay! Caso você não esteja com paciência para ler este artigo, eu tenho um projeto de teste com a implementação deste artigo no link abaixo.

https://github.com/joubertredrat/symfony-testcontainers

Symfony Framework e testes de Integração

Hoje o Symfony Framework é um dos frameworks mais maduros do universo do PHP e ele tem várias soluções bem implementadas, como para testes de integração por exemplo. Porém, pessoalmente eu sempre achei que embora existe uma facilidade de fazer os testes de integração em si, fornecer as dependências externas para os testes nem sempre foi tão fácil, como banco de dados por exemplo.

Mesmo com o surgimento do Docker, eu ainda percebia a necessidade de provisionar as dependências externas de alguma forma para os testes, porém, existe uma solução muito interessante que pode facilitar muito esta etapa, o Testcontainers.

Testcontainers

Testcontainers é um framework open source que permite você provisionar de forma mais facilitada qualquer dependência externa que você precise usando Docker, como banco de dados, broker de mensagens, sistemas de cache, ou praticamente qualquer dependência em container.

O grande diferencial do Testcontainers em relação a Docker compose ou qualquer outra forma de provisionamento de containers é que você consegue programar o provisionamento do container, sendo que hoje já tem suporte para Golang, Java, .NET, Node.js, Python, Rust, várias outras linguagens, e é claro, não poderia faltar, o PHP!

O meu primeiro contato com Testcontainers foi com um projeto em Golang e eu gostei muito da facilidade do provisionamento de um container MongoDB para fazer meus testes nos repositórios e após isto, decidi fazer o mesmo em um projeto pessoal que eu tenho em PHP usando o Symfony Framework.

Symfony + Testcontainers = ❤️

Uma das grandes vantagens do Symfony é justamente o suporte para os testes no PHPUnit por fornecer um Kernel totalmente funcional para fazer o bootstrap necessário para os testes.

Embora Testcontainers tenha suporte para PHP, a implementação é mais recente e você pode conferir ele em https://github.com/testcontainers/testcontainers-php.

Abaixo temos uma implementação de um container do MySQL 8.0, que é a dependência externa deste projeto, além do boot do Kernel do Symfony, criação do banco de dados e do schema.

class IntegrationTestCase extends KernelTestCase
{
    protected static ?MySQLContainer $container = null;

    public static function setUpBeforeClass(): void
    {
        parent::setUpBeforeClass();

        if (!static::$container) {
            static::$container = MySQLContainer::make('8.0', 'password');
            static::$container->withPort('19306', '3306');
            static::$container->run();

            $kernel = self::bootKernel();
            $container = $kernel->getContainer();

            $application = new Application($kernel);
            $application->setAutoExit(false);

            $application->run(
                new ArrayInput(['command' => 'doctrine:database:create', '--if-not-exists' => true])
            );

            $entityManager = $container->get('doctrine')->getManager();
            $metadata = $entityManager->getMetadataFactory()->getAllMetadata();
            $schemaTool = new SchemaTool($entityManager);
            $schemaTool->dropSchema($metadata);
            $schemaTool->createSchema($metadata);
        }
    }

    public static function tearDownAfterClass(): void
    {
        parent::tearDownAfterClass();

        if (static::$container instanceof MySQLContainer) {
            static::$container->remove();
        }
    }

Com isto, temos a classe base para as classes que irão de fato executar os testes, como no exemplo abaixo.

class UserRepositoryTest extends IntegrationTestCase
{
    public function testSave(): void
    {
        $user = new User();
        $user->setName('John Doe');
        $user->setEmail('john@doe.local');

        $repo = $this->getRepository();
        $repo->save($user, true);

        self::assertNotNull($user->getId());
        self::assertIsInt($user->getId());
        self::assertTrue($user->getId() > 0);
    }

    public function testGetByEmail(): void
    {
        $user = new User();
        $user->setName('John Doe');
        $user->setEmail('john2@doe.local');

        $repo = $this->getRepository();
        $userNotFound = $repo->getByEmail($user->getEmail());
        self::assertNull($userNotFound);

        $repo->save($user, true);
        $userFound = $repo->getByEmail($user->getEmail());

        self::assertEquals($user->getEmail(), $userFound->getEmail());
    }

    protected function tearDown(): void
    {
        parent::tearDown();

        $connection = $this
            ->getContainer()
            ->get('doctrine')
            ->getManager()
            ->getConnection()
        ;
        $connection->executeStatement('TRUNCATE TABLE users');
    }

    protected function getRepository(): UserRepository
    {
        return $this->getContainer()->get(UserRepository::class);
    }
}

Ao executar a suite de testes, você vai notar uma demora para finalizar os testes, porém, isto é normal, porque durante este processo, o Testcontainers está provisionando o container que você definiu para usar nos testes.

Por fim, com essa facilidade, dá para até tentar fazer coisas loucas, como 100% de coverage. Não acredita? Você mesmo pode ver em https://joubertredrat.github.io/symfony-testcontainers.

UPDATE 12/11: A princípio, nos exemplos acima eu usei o setUpBeforeClass() e tearDownAfterClass() para controlar o estado de funcionamento do container para os testes, porém, depois eu descobri que esses métodos executam a cada nova classe de testes, o que não é o que desejamos.

Por isso corrigi o projeto para passar a usar Extensions e Subscribers do PHPUnit na versão 11, e isto resolveu o problema, fazendo com que o container inicie antes e pare depois de toda a suite de testes.

Dependendo da versão do PHPUnit você usar, pode ser necessário uma abordagem diferente.

Então é isto, até a próxima!

Testes unitários para Custom Validation no Symfony

Joubert RedRat — Fri, 11 Aug 2023 11:56:33 +0000

Disclaimer: Eu não sou uma entidade divina. O que eu falo não é uma verdade absoluta. Não tenha medo de questionar até o mundo, pois ele pode estar errado, não você.

Hoje, uma das coisas mais importantes para qualquer projeto é ter testes automatizados, de preferência, unitários. Eu gosto de seguir uma lógica própria que é:

Todo código que você cria deve ter testes automatizados

Tendo isto em mente, vamos falar de testes unitários para Custom Validation que você cria em seu projeto do Symfony.

Estou sem paciência, mostre me o código!

Okay okay! Caso você não esteja com paciência para ler este artigo, eu tenho um projeto de teste com a implementação deste artigo no link abaixo.

https://github.com/joubertredrat/symfony-request-validation

Custom Validation

Um dos recursos mais antigos e funcionais do Symfony, é o componente de Validation, que é validação dos dados de entrada na sua aplicação. Embora no próprio Symfony já tem suporte a várias constraints, em casos específcios é possível criar suas próprias constraints customizadas, como no exemplo abaixo.

<?php declare(strict_types=1);

namespace App\Validator;

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;
use Symfony\Component\Validator\Exception\UnexpectedTypeException;
use Symfony\Component\Validator\Exception\UnexpectedValueException;

class CreditCardValidator extends ConstraintValidator
{
    private const REGEX = '/^(4|5){1}[0-9]{15}$/';

    public function validate(mixed $value, Constraint $constraint): void
    {
        if (!$constraint instanceof CreditCard) {
            throw new UnexpectedTypeException($constraint, CreditCard::class);
        }

        if (null === $value || '' === $value) {
            return;
        }

        if (!is_string($value)) {
            throw new UnexpectedValueException($value, 'string');
        }

        if (!preg_match(self::REGEX, $value)) {
            $this
                ->context
                ->buildViolation($constraint->message)
                ->setParameter('{{ string }}', $value)
                ->addViolation()
            ;
        }
    }
}

No Validator acima, é feita uma validação de um número de cartão de crédito que deve conter 16 números começando com o número 4 ou 5.

Teste unitário do Custom Validation

Para o nosso teste unitário, iremos utilizar o famoso PHPUnit, como no exemplo abaixo.

<?php declare(strict_types=1);

namespace App\Tests\Validator;

use App\Validator\CreditCard;
use App\Validator\CreditCardValidator;
use Symfony\Component\Validator\Constraints\Blank;
use Symfony\Component\Validator\ConstraintValidatorInterface;
use Symfony\Component\Validator\Exception\UnexpectedTypeException;
use Symfony\Component\Validator\Test\ConstraintValidatorTestCase;

class CreditCardValidatorTest extends ConstraintValidatorTestCase
{
    protected function createValidator(): ConstraintValidatorInterface
    {
        return new CreditCardValidator();
    }

    public function testValidateValueWithSuccess(): void
    {
        $this->validator->validate('5234567890123456', new CreditCard());
        $this->assertNoViolation();
    }

    public function testValidateWithInvalidConstraint(): void
    {
        $this->expectException(UnexpectedTypeException::class);
        $this->validator->validate('foo', new Blank());
    }

    public function testValidateWithInvalidValue(): void
    {
        $constraint = new CreditCard();
        $this->validator->validate('1234567890123456', $constraint);

        $this
            ->buildViolation($constraint->message)
            ->setParameter('{{ value }}', '1234567890123456')
            ->assertRaised()
        ;
    }
}

Analizando o exemplo acima, parece ser um típico teste unitário, porém, ele tem pequenas diferenças. Normalmente, as classes de teste é uma extensão da classe PHPUnit\Framework\TestCase, porém, no nosso caso, é uma extensão de Symfony\Component\Validator\Test\ConstraintValidatorTestCase, pois o componente de Validation já tem uma classe de TestCase com todas as dependências necessárias para fazer os testes unitários. Ao usar ConstraintValidatorTestCase, será necessário implementar a função createValidator retornando a classe de constraint relacionada a classe de validation e pronto. Depois disto, só criar todos os asserts necessários e executar os testes.

$ composer run tests
> vendor/phpunit/phpunit/phpunit --testdox
PHPUnit 10.3.1 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.8
Configuration: phpunit.xml.dist

...                                                                 3 / 3 (100%)

Time: 00:00.017, Memory: 10.00 MB

Credit Card Validator (App\Tests\Validator\CreditCardValidator)
 ✔ Validate value with success
 ✔ Validate with invalid constraint
 ✔ Validate with invalid value

OK (3 tests, 4 assertions)

Então é isto, até a próxima!

Validating requests on Symfony Framework

Joubert RedRat — Fri, 04 Aug 2023 16:07:01 +0000

Today Symfony is one of the most mature PHP frameworks in the world and because of this, it's used in various projects, including the APIs creation. Recently Symfony included various cool features, like mapping request data to typed objects, that appeared in version 6.3.

With this, we will take advantage of some of the best resources from the last versions of PHP, that provide support to attributes and readonly properties and create validations for Requests in Symfony.

For this, We will use the Symfony Validation component.

I have no patience, show me the code!

Okay okay! If you aren't patient to read this post, I have a test project with this implementation of this post in the link below.

https://github.com/joubertredrat/symfony-request-validation

Basic example

Following the Symfony documentation, we just need to create a class that will be used for mapping the values from the request, as example below.

<?php declare(strict_types=1);

namespace App\Dto;

use App\Validator\CreditCard;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Positive;
use Symfony\Component\Validator\Constraints\Range;
use Symfony\Component\Validator\Constraints\Type;

class CreateTransactionDto
{
    public function __construct(
        #[NotBlank(message: 'I dont like this field empty')]
        #[Type('string')]
        public readonly string $firstName,

        #[NotBlank(message: 'I dont like this field empty')]
        #[Type('string')]
        public readonly string $lastName,

        #[NotBlank()]
        #[Type('string')]
        #[CreditCard()]
        public readonly string $cardNumber,

        #[NotBlank()]
        #[Positive()]
        public readonly int $amount,

        #[NotBlank()]
        #[Type('int')]
        #[Range(
            min: 1,
            max: 12,
            notInRangeMessage: 'Expected to be between {{ min }} and {{ max }}, got {{ value }}',
        )]
        public readonly int $installments,

        #[Type('string')]
        public ?string $description = null,
    ) {
    }
}

With this, we just use the class as a dependency in the method of the controller with the annotation #[MapRequestPayload] and that's it, the values will be automatically mapped into the object, like the example below.

<?php declare(strict_types=1);

namespace App\Controller;

use App\Dto\CreateTransactionDto;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\Routing\Annotation\Route;

class TransactionController extends AbstractController
{
    #[Route('/api/v1/transactions', name: 'app_api_create_transaction_v1', methods: ['POST'])]
    public function v1Create(#[MapRequestPayload] CreateTransactionDto $createTransaction): JsonResponse
    {
        return $this->json([
            'response' => 'ok',
            'datetime' => (new DateTimeImmutable('now'))->format('Y-m-d H:i:s'),
            'firstName' => $createTransaction->firstName,
            'lastName' => $createTransaction->lastName,
            'amount' => $createTransaction->amount,
            'installments' => $createTransaction->installments,
            'description' => $createTransaction->description,
        ]);
    }
}

With this, just do the request and check the result.

curl --request POST \
  --url http://127.0.0.1:8001/api/v1/transactions \
  --header 'Content-Type: application/json' \
  --data '{
  "firstName": "Joubert",
  "lastName": "RedRat",
  "cardNumber": "4130731304267489",
  "amount": 35011757,
  "installments": 2
}'

< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "response": "ok",
  "datetime": "2023-07-04 19:36:37",
  "firstName": "Joubert",
  "lastName": "RedRat",
  "cardNumber": "4130731304267489",
  "amount": 35011757,
  "installments": 2,
  "description": null
}

In the example above, if the values aren't correctly filled as the rules defined, will throw an exception and we will receive a response with the found errors.

The problem is this exception is the default ValidationFailedException but as we are building an API, it's necessary a response in JSON format.

With this in mind, we can try a different approach, which will be explained ahead.

UPDATE August/2023: After publishing this post and sharing it on Symfony's Slack. Faizan and mdeboer told me that it's possible to have a JSON response because Symfony has a normalizer for these cases.

To be able to get a JSON response, you should add a header Accept: application/json, with this you will get a JSON response, like the example below.

As you can view, the response is in JSON, but, in the Symfony layout based on RFC 7807. In the next steps, we will do a class in which we can format a JSON response in the layout that we want.

Thanks Faizan and mdeboer for the contribution.

Abstract Request class

One of the biggest advantages of Symfony is the big and extensive support to DIP "Dependency inversion principle" by your powerful dependency injection container with autowire support.

With this, we will create our abstract class, which will have all code responsible to do the parse of request and validation, as in the example below.

<?php declare(strict_types=1);

namespace App\Request;

use Fig\Http\Message\StatusCodeInterface;
use Jawira\CaseConverter\Convert;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\RequestStack;
use Symfony\Component\Validator\Validator\ValidatorInterface;

abstract class AbstractJsonRequest
{
    public function __construct(
        protected ValidatorInterface $validator,
        protected RequestStack $requestStack,
    ) {
        $this->populate();
        $this->validate();
    }

    public function getRequest(): Request
    {
        return $this->requestStack->getCurrentRequest();
    }

    protected function populate(): void
    {
        $request = $this->getRequest();
        $reflection = new \ReflectionClass($this);

        foreach ($request->toArray() as $property => $value) {
            $attribute = self::camelCase($property);
            if (property_exists($this, $attribute)) {
                $reflectionProperty = $reflection->getProperty($attribute);
                $reflectionProperty->setValue($this, $value);
            }
        }
    }

    protected function validate(): void
    {
        $violations = $this->validator->validate($this);
        if (count($violations) < 1) {
            return;
        }

        $errors = [];

        /** @var \Symfony\Component\Validator\ConstraintViolation */
        foreach ($violations as $violation) {
            $attribute = self::snakeCase($violation->getPropertyPath());
            $errors[] = [
                'property' => $attribute,
                'value' => $violation->getInvalidValue(),
                'message' => $violation->getMessage(),
            ];
        }

        $response = new JsonResponse(['errors' => $messages], 400);
        $response->send();
        exit;
    }

    private static function camelCase(string $attribute): string
    {
        return (new Convert($attribute))->toCamel();
    }

    private static function snakeCase(string $attribute): string
    {
        return (new Convert($attribute))->toSnake();
    }
}

In the class above it's possible to see the ValidatorInterface and the RequestStack as the dependencies and in the constructor is executed the fill and validation of attributes.

Also, it's possible to see the conversion between the style snake_case and camelCase in the attributes and errors, this happens because exists a convention that the fields in the JSON must be snake_case, and PSR-2 and PSR-12 suggest the camelCase for the names of attributes in the classes, then it's necessary a conversion. For this was used the Case converter lib.

But, it's good to remember it isn't an absolute rule, if you want to use a different default from snake_case in the JSON, you can.

Request Class with validation attributes

With an abstract class responsible for all validation, now we will create validation classes, as an example below.

<?php declare(strict_types=1);

namespace App\Request;

use App\Validator\CreditCard;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Positive;
use Symfony\Component\Validator\Constraints\Range;
use Symfony\Component\Validator\Constraints\Type;

class CreateTransactionRequest extends AbstractJsonRequest
{
    #[NotBlank(message: 'I dont like this field empty')]
    #[Type('string')]
    public readonly string $firstName;

    #[NotBlank(message: 'I dont like this field empty')]
    #[Type('string')]
    public readonly string $lastName;

    #[NotBlank()]
    #[Type('string')]
    #[CreditCard()]
    public readonly string $cardNumber;

    #[NotBlank()]
    #[Positive()]
    public readonly int $amount;

    #[NotBlank()]
    #[Type('int')]
    #[Range(
        min: 1,
        max: 12,
        notInRangeMessage: 'Expected to be between {{ min }} and {{ max }}, got {{ value }}',
    )]
    public readonly int $installments;

    #[Type('string')]
    public ?string $description = null;
}

The big advantage of the class above is that all required attributes of request are with readonly status, being possible to warranty the immutability of the data.

Another interesting point is to be able to use attributes of Symfony Validation for doing the necessary validations or even create customized validations.

Using request class in Route

With the request class ready, now it's just to use as a dependency in the route that we want to do the validation, and it's good to remember that different from the previous example, here isn't necessary #[MapRequestPayload] annotation, as an example below.

<?php declare(strict_types=1);

namespace App\Controller;

use App\Request\CreateTransactionRequest;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;

class TransactionController extends AbstractController
{
    #[Route('/api/v2/transactions', name: 'app_api_create_transaction_v2', methods: ['POST'])]
    public function v2Create(CreateTransactionRequest $request): JsonResponse
    {
        return $this->json([
            'response' => 'ok',
            'datetime' => (new DateTimeImmutable('now'))->format('Y-m-d H:i:s'),
            'first_name' => $request->firstName,
            'last_name' => $request->lastName,
            'amount' => $request->amount,
            'installments' => $request->installments,
            'description' => $request->description,
            'headers' => [
                'Content-Type' => $request
                    ->getRequest()
                    ->headers
                    ->get('Content-Type')
                ,
            ],
        ]);
    }
}

In the controller above, it's possible to see that we didn't use the traditional Request from HttpFoundation, instead of this, our class CreateTransactionRequest as dependency and it's in that magic happens because all class dependencies are injected and validation is done.

Advantages of this approach

In comparison with the basic example, this approach has 2 advantages.

It's possible to customize the JSON structure and status code of the response as you want.
It's possible to have access to Request class from Symfony which was injected as a dependency, with this it's possible to access any information from a request, as headers for example. In the basic example, this isn't possible unless you also add Request class as a dependency in route, which sounds strange, because it has two distinct sources of data in the same request.

It's test time!

With our implementation ready, let's go for the tests.

The request example is with deliberate errors to be able to us see the validation response.

curl --request POST \
  --url http://127.0.0.1:8001/api/v2/transactions \
  --header 'Content-Type: application/json' \
  --data '{
  "last_name": "RedRat",
  "card_number": "1130731304267489",
  "amount": -4,
  "installments": 16
}'

< HTTP/1.1 400 Bad Request
< Content-Type: application/json

{
  "errors": [
    {
      "property": "first_name",
      "value": null,
      "message": "I dont like this field empty."
    },
    {
      "property": "card_number",
      "value": "1130731304267489",
      "message": "Expected valid credit card number."
    },
    {
      "property": "amount",
      "value": -4,
      "message": "This value should be positive."
    },
    {
      "property": "installments",
      "value": 16,
      "message": "Expected to be between 1 and 12, got 16"
    }
  ]
}

As we can see, the validation happened with success and fields not filled or with wrong data didn't pass in validation and we got a validation response.

Now, let's do a valid request and see that will have success in response because all fields will be filled as we want.

curl --request POST \
  --url http://127.0.0.1:8001/api/v2/transactions \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Joubert",
  "last_name": "RedRat",
  "card_number": "4130731304267489",
  "amount": 35011757,
  "installments": 2
}'

< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "response": "ok",
  "datetime": "2023-07-01 16:39:48",
  "first_name": "Joubert",
  "last_name": "RedRat",
  "card_number": "4130731304267489",
  "amount": 35011757,
  "installments": 2,
  "description": null
}

Limitations

The optional fields can't be readonly because if you want to access the data without initialization, PHP will throw an exception. Then, for now, I'm using normal fields with default values for this case.

I'm still looking for any option as a solution for being able to use readonly in optional fields, like using Reflection for example, and I accept suggestions.

Finally, I let my gratitude to my great friend Vinicius Dias who helped me with the revision of this post.

Validando requests no Symfony Framework

Joubert RedRat — Wed, 05 Jul 2023 21:45:47 +0000

Hoje o Symfony é um dos mais maduros e robustos frameworks no mercado e por conta disto, é usado em vários projetos, incluíndo a criação de APIs. Recentemente o Symfony incluiu várias features legais, como a funcionalidade de mapear os dados da Request para um Objeto, que surgiu na versão 6.3.

Com isto iremos aproveitar alguns dos melhores recursos das últimas versões do PHP, que é o suporte a attributes e atributos readonly e criar validações para Requests no Symfony.

Para isto, iremos usar o componente Symfony Validation.

Estou sem paciência, mostre me o código!

Okay okay! Caso você não esteja com paciência para ler este artigo, eu tenho um projeto de teste com a implementação deste artigo no link abaixo.

https://github.com/joubertredrat/symfony-request-validation

Exemplo básico

Seguindo a própria documentação, basta criarmos uma classe que iremos usar para mapear os valores da request, como no exemplo abaixo.

<?php declare(strict_types=1);

namespace App\Dto;

use App\Validator\CreditCard;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Positive;
use Symfony\Component\Validator\Constraints\Range;
use Symfony\Component\Validator\Constraints\Type;

class CreateTransactionDto
{
    public function __construct(
        #[NotBlank(message: 'I dont like this field empty')]
        #[Type('string')]
        public readonly string $firstName,

        #[NotBlank(message: 'I dont like this field empty')]
        #[Type('string')]
        public readonly string $lastName,

        #[NotBlank()]
        #[Type('string')]
        #[CreditCard()]
        public readonly string $cardNumber,

        #[NotBlank()]
        #[Positive()]
        public readonly int $amount,

        #[NotBlank()]
        #[Type('int')]
        #[Range(
            min: 1,
            max: 12,
            notInRangeMessage: 'Expected to be between {{ min }} and {{ max }}, got {{ value }}',
        )]
        public readonly int $installments,

        #[Type('string')]
        public ?string $description = null,
    ) {
    }
}

Com isto, basta usar a classe como dependência no método do controller com a annotation #[MapRequestPayload] e pronto, os valores serão automaticamente mapeados para o objeto, como no exemplo abaixo.

<?php declare(strict_types=1);

namespace App\Controller;

use App\Dto\CreateTransactionDto;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\Routing\Annotation\Route;

class TransactionController extends AbstractController
{
    #[Route('/api/v1/transactions', name: 'app_api_create_transaction_v1', methods: ['POST'])]
    public function v1Create(#[MapRequestPayload] CreateTransactionDto $createTransaction): JsonResponse
    {
        return $this->json([
            'response' => 'ok',
            'datetime' => (new DateTimeImmutable('now'))->format('Y-m-d H:i:s'),
            'firstName' => $createTransaction->firstName,
            'lastName' => $createTransaction->lastName,
            'amount' => $createTransaction->amount,
            'installments' => $createTransaction->installments,
            'description' => $createTransaction->description,
        ]);
    }
}

Com isto, basta fazermos uma requisição e vermos o resultado.

curl --request POST \
  --url http://127.0.0.1:8001/api/v1/transactions \
  --header 'Content-Type: application/json' \
  --data '{
  "firstName": "Joubert",
  "lastName": "RedRat",
  "cardNumber": "4130731304267489",
  "amount": 35011757,
  "installments": 2
}'

< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "response": "ok",
  "datetime": "2023-07-04 19:36:37",
  "firstName": "Joubert",
  "lastName": "RedRat",
  "cardNumber": "4130731304267489",
  "amount": 35011757,
  "installments": 2,
  "description": null
}

No exemplo acima, caso os valores não sejam corretamente preenchidos de acordo com as regras definidas, será disparado uma exceção e recebemos uma resposta com os erros encontrados.

O porém é que esta exceção é padrão ValidationFailedException e como estamos construindo uma API, é necessária uma resposta em formato de json.

Com isto em mente, podemos tentar uma abordagem diferente, que será explicado a seguir.

UPDATE Agosto/2023: Depois de ter publicado a versão em inglês deste post e compartilhado no slack do Symfony, Faizan e mdeboer me falaram que é possível ter a resposta em JSON pois o Symfony tem um normalizer para estes casos.

Para obter uma resposta em JSON, você deve adicionar o header Accept: application/json, com isto a resposta também será em JSON, como no exemplo abaixo.

Como é possível ver, de fato, a resposta é em JSON, porém, no padrão do Symfony baseado no RFC 7807. A seguir, iremos fazer uma classe para podermos formatar a resposta de JSON no formato que desejamos.

Obrigado Faizan e mdeboer pela contribuição.

Classe de Request abstrata

Uma das grandes vantagens do Symfony é o grande e extenso suporte a DIP "Dependency inversion principle" por meio do seu poderoso container de injeção de dependências com suporte a autowire.

Com isto, iremos criar a nossa classe abstrata, que vai conter todo o código responsável por fazer o parse da request e validação, como no exemplo abaixo.

<?php declare(strict_types=1);

namespace App\Request;

use Fig\Http\Message\StatusCodeInterface;
use Jawira\CaseConverter\Convert;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\RequestStack;
use Symfony\Component\Validator\Validator\ValidatorInterface;

abstract class AbstractJsonRequest
{
    public function __construct(
        protected ValidatorInterface $validator,
        protected RequestStack $requestStack,
    ) {
        $this->populate();
        $this->validate();
    }

    public function getRequest(): Request
    {
        return $this->requestStack->getCurrentRequest();
    }

    protected function populate(): void
    {
        $request = $this->getRequest();
        $reflection = new \ReflectionClass($this);

        foreach ($request->toArray() as $property => $value) {
            $attribute = self::camelCase($property);
            if (property_exists($this, $attribute)) {
                $reflectionProperty = $reflection->getProperty($attribute);
                $reflectionProperty->setValue($this, $value);
            }
        }
    }

    protected function validate(): void
    {
        $violations = $this->validator->validate($this);
        if (count($violations) < 1) {
            return;
        }

        $errors = [];

        /** @var \Symfony\Component\Validator\ConstraintViolation */
        foreach ($violations as $violation) {
            $attribute = self::snakeCase($violation->getPropertyPath());
            $errors[] = [
                'property' => $attribute,
                'value' => $violation->getInvalidValue(),
                'message' => $violation->getMessage(),
            ];
        }

        $response = new JsonResponse(['errors' => $messages], 400);
        $response->send();
        exit;
    }

    private static function camelCase(string $attribute): string
    {
        return (new Convert($attribute))->toCamel();
    }

    private static function snakeCase(string $attribute): string
    {
        return (new Convert($attribute))->toSnake();
    }
}

Na classe acima podemos ver que recebe o ValidatorInterface e o RequestStack como dependências e no construtor é realizado o preenchimento e validação dos atributos.

Também é possível ver a conversão entre os padrões snake_case e camelCase nos atributos e erros, isto ocorre porque existe uma convenção em que os campos de um JSON devem ser snake_case, enquanto a PSR-2 e PSR-12 sugere o uso camelCase para nomes de atributos nas classes, então é feito esta conversão. Para isto foi utilizado a biblioteca Case converter.

Porém, vale lembrar que isto não é uma regra absoluta, se você quiser usar qualquer padrão diferente do snake_case no JSON, você pode.

Classe de Request com os atributos de validação

Com a classe abstrata responsável por toda a validação, agora iremos criar as classes de validação, como no exemplo abaixo.

<?php declare(strict_types=1);

namespace App\Request;

use App\Validator\CreditCard;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Positive;
use Symfony\Component\Validator\Constraints\Range;
use Symfony\Component\Validator\Constraints\Type;

class CreateTransactionRequest extends AbstractJsonRequest
{
    #[NotBlank(message: 'I dont like this field empty')]
    #[Type('string')]
    public readonly string $firstName;

    #[NotBlank(message: 'I dont like this field empty')]
    #[Type('string')]
    public readonly string $lastName;

    #[NotBlank()]
    #[Type('string')]
    #[CreditCard()]
    public readonly string $cardNumber;

    #[NotBlank()]
    #[Positive()]
    public readonly int $amount;

    #[NotBlank()]
    #[Type('int')]
    #[Range(
        min: 1,
        max: 12,
        notInRangeMessage: 'Expected to be between {{ min }} and {{ max }}, got {{ value }}',
    )]
    public readonly int $installments;

    #[Type('string')]
    public ?string $description = null;
}

A grande vantagem da classe acima é que todos os atributos obrigatórios da request estão com o status readonly, sendo possível garantir a imutabilidade dos dados. Outro ponto interessante é poder usar os attributes do Symfony Validation para fazer as validações necessárias ou até mesmo criar validações customizadas.

Usando a classe de request na Rota

Com a classe de request pronta, agora é só usar ela como dependência na rota que você deseja fazer a validação, valendo lembrar que diferente do exemplo anterior, aqui não será necessaria a annotation #[MapRequestPayload], como no exemplo abaixo.

<?php declare(strict_types=1);

namespace App\Controller;

use App\Request\CreateTransactionRequest;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;

class TransactionController extends AbstractController
{
    #[Route('/api/v2/transactions', name: 'app_api_create_transaction_v2', methods: ['POST'])]
    public function v2Create(CreateTransactionRequest $request): JsonResponse
    {
        return $this->json([
            'response' => 'ok',
            'datetime' => (new DateTimeImmutable('now'))->format('Y-m-d H:i:s'),
            'first_name' => $request->firstName,
            'last_name' => $request->lastName,
            'amount' => $request->amount,
            'installments' => $request->installments,
            'description' => $request->description,
            'headers' => [
                'Content-Type' => $request
                    ->getRequest()
                    ->headers
                    ->get('Content-Type')
                ,
            ],
        ]);
    }
}

No controller acima é possível ver que não usamos o tradicional Request do HttpFoundation e sim a nossa classe CreateTransactionRequest como dependência e é ali que ocorre a mágica, pois todas as dependências necessárias serão injetadas e a validação será realizada.

Vantagens desta abordagem

Em relação ao exemplo básico, esta abordagem tem duas grandes vantagens.

É possível customizar a estrutura do json e o status code de resposta como desejar.
É possível ter acesso a classe de Request do Smyfony que foi injetada como dependência, com isto é possível acessar qualquer informação da request, como os headers por exemplo. No exemplo básico isto não é possível, a menos que você também coloque a classe Request como dependência na rota, o que seria estranho, pois teria duas fontes de dados distintas da mesma requisição.

Hora do teste!

Com a nossa implementação pronta, vamos para os testes.

A request do exemplo está com erros propositais para nós podemos ver as respostas da validação.

curl --request POST \
  --url http://127.0.0.1:8001/api/v2/transactions \
  --header 'Content-Type: application/json' \
  --data '{
  "last_name": "RedRat",
  "card_number": "1130731304267489",
  "amount": -4,
  "installments": 16
}'

< HTTP/1.1 400 Bad Request
< Content-Type: application/json

{
  "errors": [
    {
      "property": "first_name",
      "value": null,
      "message": "I dont like this field empty."
    },
    {
      "property": "card_number",
      "value": "1130731304267489",
      "message": "Expected valid credit card number."
    },
    {
      "property": "amount",
      "value": -4,
      "message": "This value should be positive."
    },
    {
      "property": "installments",
      "value": 16,
      "message": "Expected to be between 1 and 12, got 16"
    }
  ]
}

Como podemos ver, a validação ocorreu com sucesso e os campos não preenchidos, ou com valores incorretos não passaram pela validação e tivemos a resposta da validação.

Agora, iremos fazer uma request válida e ver que haverá sucesso na response, pois todos os campos estarão dentro do que desejamos.

curl --request POST \
  --url http://127.0.0.1:8001/api/v2/transactions \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Joubert",
  "last_name": "RedRat",
  "card_number": "4130731304267489",
  "amount": 35011757,
  "installments": 2
}'

< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "response": "ok",
  "datetime": "2023-07-01 16:39:48",
  "first_name": "Joubert",
  "last_name": "RedRat",
  "card_number": "4130731304267489",
  "amount": 35011757,
  "installments": 2,
  "description": null
}

Limitações

Os campos opcionais não podem ser readonly, pois caso você queira acessar a informação sem ela ter sido inicializada, o PHP irá disparar uma exceção. Então por ora eu estou usando atributos normais com valores default para estes casos.

Eu ainda estou pesquisando alguma opção como solução para poder usar readonly nos campos opcionais, como usar Reflection por exemplo, e aceito sugestões :)

Por fim, deixo meus agradecimentos ao grande amigo Vinícius Dias que me ajudou na revisão deste artigo.

Então é isto, até a próxima!

Slim, possivelmente o framework ideal para quem vem do Golang

Joubert RedRat — Sat, 14 Jan 2023 20:16:53 +0000

Eu trabalho com programação PHP há pelo menos 13 anos, já usei o PHP puro, frameworks como CodeIgniter, Symfony, Laravel, Laminas/Zend, CakePHP, Yii, já fiz um framework próprio, o Fox, já usei e criei várias bibliotecas também. Enfim, vi muita coisa no mundo do PHP.

Porém, eu sentia a necessidade de ter experiência com uma segunda linguagem de programação e escolhi o Golang como expliquei aqui.

Mas, depois de um tempo, acabei tendo saudades do PHP e como ele evoluiu nestes 4 anos que estive no mundo Golang, decidi fazer uns projetos para me manter atualizado na linguagem, mas aí veio o desafio.

Como trazer a filosofia minimalista do Golang para PHP?

Uma das coisas que mais gosto no mundo do Golang é ter quase total controle sobre o código e queria ter o mesmo controle no PHP, então decidi pesquisar e estudar frameworks para este objetivo.

Slim Framework

Logo de início, escolhi o Slim primeiro para fazer os testes, até porque eu me lembrava bem dele quando também estudei o finado Silex no passado para uso de um micro framework.

Nos primeiros testes eu usei o Skeleton do Slim e vi que ele utiliza somentes bibliotecas realmente necessárias para o funcionamento mínimo, como o PHP-DI, Monolog e o próprio Slim e a lib PSR-7 do Slim, como pode ser visto aqui. Com isto eu tenho um container para injeção de dependências, log, rotas, handlers, middlewares e pronto, tudo que eu preciso! Para conferir o Skeleton do Slim, basta acessar este link.

Com isso, todo o resto fica por minha conta, seja arquitetura em camadas, interfaces, repository, use cases, etc. Isto torna até mais fácil ter uma estrutura para testes unitários. Isto torna o projeto muito mais enxuto.

Porque não Symfony?

Eu vi a evolução do Symfony desde a versão 1 e vi como ele evoluiu de um grande e inchado framework para um micro framework, com o suporte de vários componentes da própria Symfony que você pode instalar opcionalmente e isto é muito bom, pois permite que você escolha somente o que irá precisar.

Um exemplo disto era que lembro que antigamente a gente fazia APIs no Symfony, mas o Twig era instalado como dependência, mesmo sem a gente precisar dele.

Confesso que embora eu seja um grande fã boy do Symfony, eu ainda considero um pouco chatinho lidar com o Kernel e configurações dele, principalmente por ficar em arquivos separados, embora eu entendo que isso é por conta dos bundles, que é algo excelente no ecossistema do Symfony.

Mas, o Symfony seria minha segunda escolha, caso Slim não atendesse minhas expectativas.

Porque não Lumen?

Embora o Lumen faça menos "mágica" que o Laravel, ainda sim eu não tenho o controle que eu gostaria do código, além dele ter muitas, muitas, muitas dependências, como pode ser visto aqui.

Conclusão

Por fim, minha escolha pelo Slim foi por conta da simplicidade e facilidade de implementação do seu código, deixando para ele algumas tarefas como injeção de dependências, rotas e middlewares, enquanto você fica com o resto, ao estilo "Do It Yourself".

Então é isto, até a próxima!

Porque escolhi o Golang como segunda linguagem

Joubert RedRat — Sat, 14 Jan 2023 03:02:38 +0000

Durante a minha carreira uma coisa que eu percebi é que depender somente de uma ferramenta pode não ser uma boa idéia e no meu caso, isto estava aplicado a linguagem de programação, pois até então eu tinha domínio somente de PHP e um pouco de JavaScript.

Porque Golang?

Durante minha busca por uma nova linguagem de programação para "amar" me deparei com uma linguagem que estava sendo muito usada no mundo DevOps, o Golang, e acabei me interessando por ele, principalmente pelos pontos abaixo.

Linguagem Compilada

Eu procurava uma linguagem compilada e o que gostei do Golang é que ele gera um arquivo compilado assembly, não sendo necessário o Golang para execução, diferente de outras linguagens, que gera um binário bytecode, sendo dependente de máquina virtual para execução.

Binário Cross platform

Além de ser uma linguagem compilada, ela é cross platform, ou seja, você consegue gerar binário para Linux, MacOS, Windows, etc, nas arquiteturas i386, x86_64, arm64, etc, e o mais legal, você consegue gerar binário para Windows e MacOS no Linux e vice-versa, isto é fantástico.

Filosofia Minimalista

Uma das coisas que me incomodava um pouco no mundo PHP era o quão "inchado" era os frameworks, além das mágicas que ocorria "debaixo do capô" e que tirava o controle do desenvolvedor e com o Golang isto é justamente o contrário.

No Golang existe um filosofia muito forte na comunidade de que caso você queira, consegue fazer praticamente tudo com a stdlib, ou seja, a idéia é "Do It Yourself".

Claro que você vai usar libs, mas será poucas, somente para o essencial e você mesmo faz todo o resto. No meu caso geralmente uso lib para rotas, log, banco de dados e migrations, cli e pronto, o resto é tudo por minha conta, como a injeção de dependências, e como é gostoso ter controle sobre isto.

Concorrência e Paralelismo

O Golang desde sempre tem suporte nativo a goroutines e outros meios de fazer concorrência e paralelismo e com ele eu começei a conseguir fazer estes processos de forma mais fácil.

Eu e o Golang Hoje

Depois de me aprofundar nos pontos acima, ter cerca de 4 anos de experiência com Golang em vários projetos e até contribuições para o mundo opensource, fico satisfeito em ter esta segunda linguagem na bagagem para ajudar a resolver problemas do mundo real.

Então é isto, até a próxima!

Gerenciando as variáveis de ambiente do seu projeto Golang

Joubert RedRat — Wed, 13 Jul 2022 02:08:28 +0000

Olá pessoas, neste artigo iremos falar sobre uma maneira fácil que eu uso para gerenciar as variáveis de ambiente nos meus projetos Golang, porém, vamos primeiro para os alertas.

Este artigo não é uma cagação de regra

Sim, as vezes é bom lembrar que o artigo é apenas para fins educativos, para passar o conhecimento adiante e levantar o debate, não é uma cagação de regra.

O problema

Por várias vezes eu me deparei com projetos em golang em que tem o seguinte código com o os.Getenv, como no exemplo abaixo.

func dsn() string {
    return fmt.Sprintf(
        "postgres://%s:%s@%s:%s/%s?sslmode=%s",
        os.Getenv("DATABASE_USERNAME"),
        os.Getenv("DATABASE_PASSWORD"),
        os.Getenv("DATABASE_HOST"),
        os.Getenv("DATABASE_PORT"),
        os.Getenv("DATABASE_DBNAME"),
        os.Getenv("DATABASE_SSL_MODE"),
    )
}

Ok, mas qual o problema então? O problema é que esse código está acoplado, o que torna difícil testar, por exemplo. Outro problema é que não seria interessante haver chamadas ao os.Getenv espalhado pelo código, tornaria ele difícil de manter, como já aconteceu comigo antes.

Uma forma fácil de resolver este problema é justamente a Injeção de dependência, o que torna muito mais limpo e organizado o código, já que suas funções, structs e outros terão apenas os recursos que precisam para funcionar, então, pela lógica, o código acima ficaria como o exemplo abaixo.

func dsn(host, port, user, pass, name, sslmode string) string {
    return fmt.Sprintf(
        "postgres://%s:%s@%s:%s/%s?sslmode=%s", 
        user, 
        pass, 
        host, 
        port, 
        name, 
        sslmode,
    )
}

Porém, isto agora cria um novo problema, como obter os dados que estão disponíveis via os.Getenv?

Você no controle das variáveis de ambiente do projeto

Hoje, você pode definir as variáveis de ambiente de duas formas, em um arquivo .env ou definindo elas direto no seu shell, então para termos controle sobre isto, iremos usar 2 bibliotecas em Golang disponíveis no GitHub, que são as que estão abaixo.

A primeira biblioteca permite carregar as variáveis de ambiente de um arquivo .env, enquanto a segunda, permite fazer o parser das variáveis de ambiente para uma struct.

Com isto, poderemos ter nossa struct para fazer o gerenciamento dos dados das nossas variáveis de ambiente, como abaixo.

type DbSSLMode string

type Config struct {
    ApiEnv           string    `env:"API_ENV,required"`
    ApiHost          string    `env:"API_HOST,required"`
    ApiPort          string    `env:"API_PORT,required"`
    DatabaseHost     string    `env:"DATABASE_HOST,required"`
    DatabasePort     string    `env:"DATABASE_PORT,required"`
    DatabaseUsername string    `env:"DATABASE_USERNAME,required"`
    DatabasePassword string    `env:"DATABASE_PASSWORD,required"`
    DatabaseDBName   string    `env:"DATABASE_DBNAME,required"`
    DatabaseSSLMode  DbSSLMode `env:"DATABASE_SSL_MODE,required"`
}

Note que nesta struct temos tags para referenciar a origem dos dados e também quais são obrigatórias e sim, isto é importante, porque acreditem ou não, já vi APIs quebrarem em produção porque justamente um os.Getenv perdido no projeto não teve sua variável de ambiente correspondente definida e isto estava derrubando a API.

Caso você tenha um arquivo .env, você simplesmente pode carregar ele, como abaixo.

const (
    ENV_FILE               = ".env"
)

func loadEnvFile() error {
    if _, err := os.Stat(ENV_FILE); os.IsNotExist(err) {
        return nil
    }

    return godotenv.Load(ENV_FILE)
}

Com isto você pode ter a flexibilidade de usar um arquivo .env caso esteja desenvolvendo seu projeto.

Por fim, temos constantes e funções para você poder fazer validações que você ache interessante para também não ter surpresinhas quando seu projeto for para produção.

const (
    ENV_DEV                = "dev"
    ENV_STAGING            = "staging"
    ENV_PROD               = "prod"
    DB_SSLMODE_DISABLE     = "disable"
    DB_SSLMODE_ALLOW       = "allow"
    DB_SSLMODE_PREFER      = "prefer"
    DB_SSLMODE_REQUIRE     = "require"
    DB_SSLMODE_VERIFY_CA   = "verify-ca"
    DB_SSLMODE_VERIFY_FULL = "verify-full"
)

func envModes() []string {
    return []string{ENV_DEV, ENV_STAGING, ENV_PROD}
}

func dbSSLModes() []string {
    return []string{
        DB_SSLMODE_DISABLE,
        DB_SSLMODE_ALLOW,
        DB_SSLMODE_PREFER,
        DB_SSLMODE_REQUIRE,
        DB_SSLMODE_VERIFY_CA,
        DB_SSLMODE_VERIFY_FULL,
    }
}

Agora vamos para a parte interessante, como obter essas os dados das variáveis de ambiente.

func GetConfig() (Config, error) {
    if err := loadEnvFile(); err != nil {
        return Config{}, err
    }

    customParsers := map[reflect.Type]env.ParserFunc{
        reflect.TypeOf(DbSSLMode("")): func(v string) (interface{}, error) {
            for _, sslmode := range dbSSLModes() {
                if sslmode == string(v) {
                    return DbSSLMode(v), nil
                }
            }

            return nil, errors.New(fmt.Sprintf(
                `Invalid environment variable "DATABASE_SSL_MODE" %s, available options are: %s`,
                v,
                strings.Join(dbSSLModes(), ", "),
            ))
        },
    }

    config := Config{}
    if err := env.ParseWithFuncs(&config, customParsers); err != nil {
        return Config{}, err
    }

    if !slices.Contains(envModes(), config.ApiEnv) {
        return Config{}, errors.New(fmt.Sprintf(
            `Invalid environment variable "API_ENV" %s, available options are: %s`,
            config.ApiEnv,
            strings.Join(envModes(), ", "),
        ))
    }

    return config, nil
}

Na função acima, iremos carregar o arquivo .env, caso você tenha ele na raiz do seu projeto, cria um parser customizado caso queira, sendo que no exemplo, é o SSL Mode do banco de dados, que tem opções estritas.
Depois disto, basta criar a struct, fazer o parse e pronto! Depois disto você ainda pode fazer validações também, tudo para manter o controle sobre os dados das suas variáveis de ambiente.

Executando o projeto

Uma vez criado sua struct com as validações, basta chamar a função e tratar o erro, caso algo esteja errado, como nos exemplos abaixo.

    config, err := pkg.GetConfig()
    if err != nil {
        panic(err)
    }

dev@Devs-MacBook-Pro ~/source/joubertredrat/go-env-management> go run main.go
panic: env: required environment variable "API_PORT" is not set

dev@Devs-MacBook-Pro ~/source/joubertredrat/go-env-management> go run main.go
panic: Invalid environment variable "API_ENV" testing, available options are: dev, staging, prod

dev@Devs-MacBook-Pro ~/source/joubertredrat/go-env-management> go run main.go
panic: env: parse error on field "DatabaseSSLMode" of type "pkg.DbSSLMode": Invalid environment variable "DATABASE_SSL_MODE" deny, available options are: disable, allow, prefer, require, verify-ca, verify-full

Por fim, corrigidos todas as variáveis de ambiente, você terá uma struct com os dados para usar nas funções, métodos e outros que precisar.

func main() {
    config, err := pkg.GetConfig()
    if err != nil {
        panic(err)
    }

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        io.WriteString(w, dsn(
            config.DatabaseHost,
            config.DatabasePort,
            config.DatabaseUsername,
            config.DatabasePassword,
            config.DatabaseDBName,
            string(config.DatabaseSSLMode),
        ))
    })

    listen := fmt.Sprintf("%s:%s", config.ApiHost, config.ApiPort)
    fmt.Printf("Running app %s at %s\n", config.ApiEnv, listen)

    if err := http.ListenAndServe(listen, nil); err != nil {
        panic(err)
    }
}

Projeto em ação

Um exemplo completo desta abordagem funcionando está no Github abaixo.

https://github.com/joubertredrat/go-env-management.

Então é isto, espero ter ajudado, até a próxima!

Pequena dica para o dia a dia, git clone-github repository

Joubert RedRat — Thu, 18 Nov 2021 01:06:00 +0000

Hoje venho trazer uma dica que pode ser útil para vocês, um comando customizado para git que eu criei, o git clone-github repository.

Pra que esse comando Joubert?

Bom, deixa eu explicar como gosto de organizar projetos no meu computador.

Na pasta home do meu usuário, eu tenho uma pasta chamada source, que é a pasta raiz onde eu baixo código, faço clone de projetos, etc, como vocês podem ver abaixo.

Eu gosto de usar esta forma de organizar código inclusive em todo computador que eu programo, tornando fácil identificar de qual projeto a pasta pertence.

Uma das pastas é a opensource, que o próprio nome já diz, contém projetos open source.

Dentro da pasta opensource existe a joubertredrat e joubertredrat-tests que são minhas pastas de trabalho relacionado a meus projetos open source, porém, além delas, eu tenho a pasta other que é justamente onde eu baixo projetos open source eu uso como fonte de conhecimento.

E é ai que vem a utilidade do comando git clone-github repository.

Como assim Joubert?

Como na pasta source/opensource/other tem vários projetos de varias pessoas ou comunidades, as vezes torna difícil saber qual é a origem do projeto, como você pode ver abaixo.

Ou seja, eu tive que entrar na pasta compose e executar git remote -v para descobrir que projeto é este, um projeto do docker. Com poucas pastas pode não ser um problema, mas quando passa das dezenas, pode ficar mais complicado achar o projeto que você deseja.

Com isto, eu criei um comando customizado do git para que sempre que for realizado o clone de um repositório do Github, ele faça para uma pasta contendo o nome do usuário ou organização como prefixo da pasta do clone.

Abaixo, um exemplo do mesmo repositório acima, com o clone feito pelo git clone-github.

Com isto, fica mais fácil e organizado navegar por esta pasta e identificar facilmente projetos, usuários e organizações. Como nos exemplos abaixo.

Fica muito mais fácil você ver uma pasta flutter__samples e entender que é um projeto do flutter do que simplesmente samples, não acha?

Como isto é possível e como fazer isso Joubert?

Isto é possível a comandos customizáveis que você pode adicionar ao git. Um exemplo disto pode ser visto neste artigo.

Com isto, basta criar o script com o nome que você deseja e tendo o prefixo git, no meu caso git-clone-github, colocar permissão de modo executável +x e colocar este script em uma pasta que esteja no $PATH.

Abaixo o snippet do script do git-clone-github.

Feito isto, está pronto, basta executar o seu comando git clone-github repository.

Alternativa

Após ter postado este artigo no Twitter, o Wanderson Camargo @wandersonwhcr postou uma alternativa e solução interessante que gostei tanto que achei interessante postar aqui também, como nos exemplos abaixo.

git clone {https://github.com/,}docker/compose
git clone {git@github.com:,}docker/compose

Essa alternativa é interessante pois diferente do git clone-github que somente aceita url http do GitHub, o comando acima permite usar tanto url, quanto git por ssh.

Outra diferença é que o clone é feito em pastas e subpastas, ou seja, o comando acima irá fazer o clone na pasta docker/compose, enquanto o git clone-github faz o clone na pasta docker__compose.

Por fim, a alternativa acima funciona nos shells mais utilizados, como sh, bash, zsh e fish.

Até a próxima.

Rodando projetos x86_64 no Mac M1 (arm64) com UTM

Joubert RedRat — Thu, 07 Oct 2021 12:06:08 +0000

Desde que a Apple publicou sobre os novos Macs com o chip M1, houve um grande esforço para que vários aplicativos e programas pudessem rodar na nova arquitetura, que é arm64, diferente da tradicional arquitetura x86_64 dos processadores Intel, AMD e outros, tanto de empresas donas dos softwares proprietários, quanto de comunidades de projetos open source.

Muito deste ecossistema tem suporte nos Mac M1, porém, alguns projetos ainda apresentam problemas, como alguns projetos baseados em QEMU ou imagens de docker que ainda não tem suporte multi arquitetura, por exemplo.

Uma forma de poder contornar essa situação é justamente poder executar esses projetos como arquitetura x86_64, e é ai que a virtualização pode nos ajudar.

Para virtualização, iremos usar o UTM, que já escrevi sobre neste link,

Virtualização nos Mac M1? Sim, com UTM

Joubert RedRat ・ Oct 4 '21

#opensource #m1 #virtualization #macbook

Então, vou assumir que você já tenha o UTM instalado no seu Mac M1, então vamos lá.

Para este artigo, vamos usar o Ubuntu 20.04 server, então você pode fazer o download no site da Canonical, ou direto no link abaixo, porém, você pode usar a distro de sua preferência.

https://releases.ubuntu.com/20.04/ubuntu-20.04.3-live-server-amd64.iso

Criando a máquina virtual

Vamos criar nossa máquina virtual clicando no ícone "+" e depois em "Start from Scratch".

Na aba "Information" você vai configurar o nome e o ícone da máquina virtual conforme desejar.

Na aba "System" vem a parte importante, em "Architecture", selecione a opção "x86_64", a opção "System" logo abaixo será alterado automaticamente. Na opção "Memory" você vai selecionar a quantidade de memória que a máquina virtual deverá ter. O mínimo para conseguir rodar é 768Mb, porém, recomendo fortemente que coloque 1Gb ou mais.

Na aba "Drives", você irá criar um disco rígido e uma unidade de CD/DVD. Eu recomendo fortemente criar um disco com pelo menos 30 Gb ou mais.

Na aba "Network", você irá criar um redirecionamento de portas, para que possamos acessar a máquina via SSH.

Vale lembrar que você pode fazer redirecionamento de outras portas que desejar.

Por fim, só clicar em "Save" e pronto, sua máquina virtual estará criada.

Na parte inferior das informações da máquina virtual existe um select na opção de CD/DVD, você irá selecionar a ISO da distro que você escolheu, o que no nosso caso, é o Ubuntu Server 20.04.

Agora é só executar a máquina virtual e instalar a distro linux.

Testando a máquina virtual

Agora que você instalou sua máquina virtual, basta acessar ela por SSH e você verá que na máquina virtual, estará rodando um sistema x86_64, como na imagem abaixo.

Hora da prova de fogo

Para a o exemplo da prova de fogo estou usando o docker e o container de um projeto chamado Kafdrop, que basicamente é uma Web UI para Kafka feito em Java e que também merece uma estrela no GitHub, ~~mesmo que tenha sido feito em java haha~~ o repositório do projeto está abaixo.

https://github.com/obsidiandynamics/kafdrop

Como o container deste projeto ainda não tem suporte a multi arquitetura, tentamos executar ele como se fosse linux/amd64, em outros projetos até funciona, mas neste não.

Como pode ser visto na imagem abaixo, no primeiro console ocorreu o erro qemu: uncaught target signal 11 (Segmentation fault) - core dumped, pois mesmo tentando forçar x86_64 na arch arm64, neste caso não funciona.

Porém, no segundo console o projeto executou normalmente, pois se trata de um container x86_64 rodando em uma distro x86_64.

Ou seja, é perfeitamente possível executar projetos x86_64 mesmo estando com um Mac M1.

Então é isso pessoas, espero ter ajudado com este artigo e se tiverem mais dúvidas, fiquem a vontade para comentar por aqui mesmo ou me caçando em algum lugar da internet :)

Virtualização nos Mac M1? Sim, com UTM

Joubert RedRat — Mon, 04 Oct 2021 22:38:15 +0000

Como todos já sabem, a Apple resolveu inovar mais uma vez e nos trouxe novas máquinas com seu chip M1. Isso é legal? Sim, mas junto com ele, nos trouxe também problemas de compatibilidade, já que a arquitetura do chip M1 é arm64 e não o tradicional x86_64.

Por conta disto, soluções de virtualização já consolidadas no mercado, como o VirtualBox não funcionam, já que este, funciona somente na arquitetura x86_64.

Porém, o mundo open source é lindo e graças a ele, temos uma solução! E esta solução é o UTM.

O UTM foi originalmente criado para virtualização em iPhones, porém, como os novos MacBooks também usam o mesmo chip M1, foi criado a versão desktop também.

A instalação do UTM é muito simples, bastando baixar o .dmg a partir do site ou do repositório do projeto no GitHub, executar e copiar o UTM para a pasta Applications. Uma alternativa interessante também é a instalação pela Mac Apple Store.

No próprio site do UTM tem uma galeria, onde você encontra várias opções de distros linux para instalação e até mesmo algumas versões do Windows pode ser executadas. Você pode consultar tudo isto em https://mac.getutm.app/gallery/

Um projeto lindo desses merece uma star no repositório deles no GitHub, https://github.com/utmapp/UTM.

Mas Joubert, existe alguma alternativa?

Então, até tem, o Parallels Desktop for Mac, porém, não é uma solução open source e você precisa ter uma conta para usar, o que para mim não faz o menor sentido.

Até o momento, só conheço essas duas opções que realmente funcionam no Mac M1, caso eu conheça mais soluções ou novidades, volto com novos posts sobre o assunto.