Forem: PHP Rio

Princípios ou Ferramentas - O que estudar

Vinicius Dias — Thu, 23 Apr 2020 20:44:23 +0000

O mundo de desenvolvimento

Quando decidimos entrar para o mundo de desenvolvimento, sofremos um bombardeio de informações e novos termos.

Linguagens, frameworks, bibliotecas, paradigmas, princípios, etc. Não é fácil saber que caminho seguir e o que estudar primeiro.

Obviamente não existe alternativa certa ou errada, então nesse post eu vou somente expor minha opinião. Não tome o que for dito aqui como verdade, mas sim reflita e analise se faz sentido para você.

Mercado de trabalho

É inegável que para atuar no mercado de trabalho nós precisamos de muito mais conhecimento do que nos é passado inicialmente em qualquer livro, curso ou post de blog. Somente a experiência e vivência vai nos dar a bagagem necessária para resolver os problemas e gerar valor para os clientes.

Mas isso não quer dizer que nós só devamos estudar o que o emprego atual nos pede. Pelo contrário. Se nós estudamos além do que nos é pedido, ou no caso do primeiro emprego, estudamos antes de algo nos ser cobrado, quando uma oportunidade ou problema surgir, as chances serão muito maiores de estarmos prontos.

Além de solucionar os problemas ou aproveitar as oportunidades, estudar nos faz conhecer melhores formas de atingir estes objetos, nos dando vantagens competitivas sobre quem simplesmente "resolve o problema".

Ok, até aqui só usei o termo "estudo", mas devemos estudar o que? Ferramentas específicas ou princípios genéricos que podem ser aplicados a várias ferramentas?

Linguagens, bibliotecas e frameworks

Se você quer entrar para a área de desenvolvimento e acredita que seu trabalho vai ser escrever código, você está enganado(a). O nosso trabalho é solucionar problemas. Código é uma ferramenta, um meio para o fim. Linguagens de programação são apenas ferramentas para nós resolvermos determinados problemas. Frameworks e bibliotecas nada mais são do que ferramentas de "alto nível", que nós trazem alguma facilidades e alguns problemas genéricos já resolvidos.

Ah, Vinicius, quer dizer que a escolha da linguagem de programação não é importante? Longe disso! A linguagem de programação é uma ferramenta muito importante para a solução do problema e existem linguagens diferentes para solucionar problemas diferentes. O ponto é: elas são ferramentas.

Se nós tivermos isso em mente, acabamos deixando de lado aquele tipo de briga de "minha linguagem é melhor que a sua" ou "meu framework é melhor do que o seu". Discussões desse tipo são interessantes e até emocionantes (eu mesmo adoro falar mal de Laravel ;-p), mas nós não podemos nos cegar achando que realmente há uma ferramenta melhor do que outra e ponto.

Não existe bala de prata (solução pra qualquer problema)!

Assim como cada linguagem resolve um problema, cada framework tem um propósito, uma identidade. Você vai acabar se identificando mais com um ou outro, mas não faça com que isso seja o foco de todo o seu estudo e trabalho. Conhecer muito bem a linguagem e o framework que você utiliza para trabalhar é importante, mas é o primeiro passo?

Paradigmas

Como eu citei no último parágrafo, "cada linguagem resolve um problema", e cada linguagem faz isso de um jeito. Existem diversos paradigmas de programação, dentre eles:

Declarativos
- Programação funcional
Imperativos
- Programação procedural
- Programação orientada a objetos

Entender bem as vantagens e desvantagens de cada paradigma e as diferenças entre eles é crucial para aprender qualquer linguagem de programação. Diversas linguagens modernas são o que chamamos de "multi-paradigma", ou seja, nos permitem utilizar mais de um paradigma em nosso código, como procedural e Orientado a Objetos, funcional e Orientado a objetos, funcional e procedural, etc.

Este post (em inglês) fala com bem mais de detalhes sobre os principais paradigmas de programação e alguns exemplos de linguagens:

Classification of computer languages (II)

Valentiina VP ・ Apr 13 '20

#webdev #devlive #computerscience #programming

Princípios

Cada paradigma de programação (e suas respectivas linguagens suportadas) sugerem diversos princípios para que seu código seja de fácil manutenção, testável, legível, etc.

Princípios muito comuns da programação orientada a objetos (paradigma que estudo mais a fundo) são:

Tell, don't ask;
Least astonishment;
*Fail fast;
*Early return;
SOLID (conjunto de princípios);
etc.

* Princípios também aplicáveis a outros paradigmas

Estudar os princípios referentes ao paradigma que você escolher é fundamental para manter seu código saudável. Não aplicá-los pode dar a falsa impressão de que você está sendo mais produtivo(a), mas a longo prazo a verdade sempre surge e nós acabamos nos arrependendo.

Padrões

Tendo entendido o que são paradigmas e que cada um deles possui princípios, baseando-se nestes princípios surgem padrões. Os famosos Padrões de Projeto são basicamente soluções padrões para problemas genéricos. São sugestões de como proceder em determinadas situações.

Certos problemas são tão comuns de acontecer, que pessoas através dos anos já estudaram e discutiram muito sobre as melhores formas de resolvê-los.

Alguns dos padrões mais famosos seguindos os princípios da programação orientada a objetos são:

Padrões da "turma dos 4" (Gang of Four "GoF")
- 24 padrões (super famosos) separados em 3 categorias
Object calisthenics
- 9 regras para exercitar em seus códigos
Sugeridos pelo "desenvolvimento guiado a domínio" (DDD)
- Conhecidos como blocos de construção do DDD como Entity, Value Object, etc.

Como citado no início do capítulo, cada padrão visa resolver problemas bem comuns e genéricos, e devem ser aplicados quando fazem sentido. Os padrões exemplificados estão em níveis bem diferentes de sua aplicação e explicá-los individualmente é impossível através de um único post.

O que estudar primeiro?

Como foi dito lá no início, esse post é para que eu expressar minha opinião.

Na minha visão, devemos estudar o básico dos paradigmas de programação, entendendo qual problema cada um resolve e em que casos são usados. Após entendê-los, normalmente nos aprofundamos em 1 deles, mas existe um porém:
Antes de aprender Orientação a Objetos, é importante conhecermos o paradigma procedural, visto que o primeiro surgiu para resolver determinados problemas do último.

Para estudar um dos paradigmas, obviamente precisamos de uma linguagem de programação, então este estudo acontece em paralelo: Conhecemos uma linguagem enquanto conhecemos um paradigma.

Após dominar razoavelmente bem os conceitos da linguagem e do paradigma em questão, podemos começar a estudar os princípios sugeridos, entendendo suas propostas, quais problemas resolvem, porque surgiram, etc.

Estes princípios, normalmente nos levam naturalmente para o estudo de alguns padrões. O estudo de padrões já é um estudo mais avançado, porém muito recompensante.

Se você tem um bom conhecimento de um paradigma (e consequentemente, uma linguagem), alguns de seus princípios e padrões, pode ser o momento de aprender a utilizar ferramentas que auxiliem no processo.

Frameworks e bibliotecas são ferramentas que facilitam a resolução de problemas que você deveria saber resolver sem elas. Richard Feynman, ganhador do Nobel de física, escreveu uma vez: “What I cannot create I do not understand”. Traduzindo: "O que eu não consigo criar eu não entendo".

Então antes de utilizar um framework, sabia resolver o problema sem ele. Antes de utilizar uma biblioteca mais específica, saiba resolver o problema sem ela. Isso faz com que você consiga resolver um problema nas ferramentas, caso aconteça.

Programação procedural orientada a classes - Parte 2

Vinicius Dias — Thu, 16 Apr 2020 16:37:50 +0000

Design de código

Uma vez eu ouvi uma frase mas não me lembro o autor: "Não existe código sem design. Existe código com design ruim". Inclusive adaptei esta frase para "arquitetura" na primeira parte desta publicação.

Antes de falarmos sobre as péssimas decisões de design que tomamos, vamos falar sobre o que é design de código.

Uma analogia interessante foi feita pelo Junior Grossi em um workshop maravilhoso de qualidade de código que fiz com ele. Foi mais ou menos assim (não com essas exatas palavras):

"Podemos fazer uma analogia da arquitetura de software com a arquitetura de uma casa. Onde fica cada cômodo, como se encaixam juntos, etc. É uma visão de bem alto nível. Já o design de código pode ser considerado análogo aos móveis de uma casa. É uma visão de mais baixo nível sobre nossas decisões sobre o código".

Então, basicamente (beem basicamente), arquitetura diz respeito a como você vai separar sua aplicação em camadas, por exemplo, onde cada camada pode ter sua responsabilidade bem definida. Já o design de código diz respeito a como você vai organizar suas classes e métodos em cada uma das camadas. Quais padrões você vai seguir, como cada classe vai se comportar sozinha ou em conjunto com suas respetivas dependências, etc.

Escolhas corriqueiras

Agora que já entendemos basicamente o que é Design de Código, vamos falar sobre escolhas que fazemos frequentemente e que talvez não sejam as mais interessantes sob a ótica da programação orientada a objetos, ou melhor, sob a ótica do design orientado a objetos.

Como já foi discutido no post anterior, é muito comum termos um modelo anêmico: Classes que apenas possuem getters e setters, ou seja, meros sacos de dados. Para quem já estudou C sabe que no fundo isso não é uma classe, mas sim uma struct.

O fato de termos modelos anêmicos onde classes que deveriam ser do nosso domínio na verdade acabam sem nenhuma regra de negócio, geralmente faz com que nós transfiramos essas regras para lugares "errados" (entre aspas porque quem sou eu pra dizer o que é certo ou errado?).

Que lugares errados seriam esses?

Helpers ou Utils

Quem nunca viu uma classe chamada StringHelper ou DateUtils? São classes que claramente estão perdidas em nosso sistema. O que seria, no mundo real, um(a) StringHelper? Se não existe no mundo real, tem certeza que deveria existir no código?

Esse tipo de classe é uma herança clara da programação procedural em nosso código onde estamos separando o comportamento dos seus dados, quando a orientação a objetos tem todas as ferramentas necessárias para nós os juntarmos.

Possível solução

Se você possui uma classe StringHelper, talvez ela esteja fazendo validações bem genéricas. Nesse caso, nada mais justo do que transformá-la em uma classe bem genérica, como String. Nessa classe você pode ter comportamentos e verificações pertinentes a uma string em seu código.

Mas na maioria das vezes as verificações nesse tipo de classe são específicas de regras de negócio. Ex.: Garantir que nome possua pelo menos 10 letras.

Se é uma regra de negócio, deveria estar na classe de negócio. Talvez na classe Pessoa. Talvez numa classe mais específica, como Nome. Depende do seu sistema.

Services inúteis

O livro do Eric Evans sobre DDD é certamente uma obra que revolucionou o mundo do desenvolvimento. Eu particularmente ainda não o li, mas li obras inspiradas por este livro, então sei que: Neste livro foram definidos alguns conceitos sobre classes chamadas de Services.

Uma das possíveis "categorias" desse tipo de classe é Application Service. Este tipo de classe tem como propósito receber informações de fora do domínio do sistema (da web, linha de comando, etc) e orquestrar as chamadas a regras de domínio.

Um exemplo clássico:

<?php

class AddUser
{
    private UserRepository $repository;
    private PasswordHasher $hasher;

    public function __cosntruct(UserRepository $repository, PasswordHasher $hasher)
    {
        $this->repository = $repository;
        $this->hasher = $hasher;
    }

    public function execute(AddUserDto $data): void
    {
        $hashedPassword = $this->hasher
            ->hash($data->password());
        $user = new User($dados->email(), $hashedPassword);

        $this->repository->add($user);
    }
}

Há pontos de melhoria nesse código (sempre há), mas basicamente: Ele recebe os dados de algum mecanismo de entrega através de um DTO (objeto de transferência de dados, que serve basicamente para transferir dados entre camadas no sistema), e passa para o domínio que sabe cifrar a senha, armazenar o usuário no repositório, etc.

Problema comum

Essa definição de Application Service em algum momento foi tomada por alguém como "Classe obrigatória para adicionar indireção desnecessária no sistema".

Na prática é muito comum vermos código onde um Controller chama um método de uma classe com Service no nome, e esse método não faz nada além de chamar um método de outra classe. Essa chamada extra de um método é conhecida como indireção, de forma resumida.

Algo parecido com isso:

<?php

class UserService
{
    private UserRepository $repository;

    public function __construct(UserRepository $repository)
    {
        $this->repository = $repository;
    }

    public function add(User $user): void
    {
        $this->repository->add($user);
    }

    // todos os outros métodos públicos que também existem em UserRepository
}

Agora me responda: O que ganhamos ao ter a classe UserService? Ganhamos apenas mais indireções em nosso sistema. Mais um lugar que nossa IDE vai nos fazer passar até chegar no código que de fato executa algo.

Além de parecerem ser classes conhecidas como God classes, já que aparentam fazer tudo no sistema, são inúteis na prática.

Esse é mais um exemplo de programação procedural sendo aplicada, onde temos apenas funções sem nenhum significado pro negócio agrupadas em uma classe que simplesmente chama outras funções.

Outra característica de programação procedural nesse caso é que muito comumente temos métodos não tão relacionados na mesma classe Service.

É comum um UserService ter um método com uma chamada para salvar um usuário e outro método para enviar um e-mail para ele. Responsabilidades que deveriam estar em classes separadas.

No canal Dev Eficiente, do Aberto Souza, tem um vídeo falando um pouco mais sobre o problema deste tipo de classe, mas sob uma outra ótica. Vale a pena conferir:

Camada Model do MVC

Um ponto que tem levantado bastante discussão em comunidades que participo é: O que é a camada Model no MVC?

Discutir sobre MVC é assunto pra outro post, mas o que tenho visto como consenso é: Camada que faz a persistência dos dados.

E a regra de negócio? Uma galera tem colocado nos Controllers. E aí? Se essa lógica precisar ser reaproveitada, como fazemos? Como chamamos um Controller dentro de outro? Complicado, né?

Em nossos Controllers é muito comum ver aquele código super famoso da programação procedural cheio de IFs e verificações em tipos primitivos, sem nenhum significado para o negócio.

Padrões arquiteturais

Para "resolver" esse problema, diversos padrões arquiteturais existem, e eu falei um pouquinho (bem pouquinho) sobre arquitetura nesse meu outro post:

O que é arquitetura

Vinicius Dias for PHP Rio ・ Apr 10 '20

#php #architecture

Conclusão

Por mais que a gente estude muito sobre ferramentas, frameworks, hypes e modinhas, os princípios da programação orientada a objetos mudam muito pouco e merecem MUITA atenção.

Estude conceitos, princípios, padrões... Tudo isso vai poder ser aplicado naquele framework que foi lançado semana passada e você está doido pra usar pra fazer um CRUD. Acredite.

Infelizmente eu ainda vejo muito código utilizando estas "técnicas" procedurais utilizando classes, e pessoas acreditando que isso é desenvolver utilizando a programação orientada a objetos.

Você costuma ver código assim no seu dia a dia? Compartilha aqui nos comentários algum caso que você tenha visto recentemente.

Programação procedural orientada a classes

Vinicius Dias — Mon, 13 Apr 2020 12:34:06 +0000

Farsa da programação Orientada a Objetos

Acredito que todos concordamos que a programação Orientada a Objetos torna nosso código mais legível e permite arquiteturas mais interessantes do que a programação procedural, além de permitir recursos interessantes de reutilização de código.

Partindo desse pressuposto, também acredito que seja intenção de qualquer pessoa que trabalhe com desenvolvimento aprender mais e mais as técnicas e boas práticas deste paradigma de programação.

O problema acontece quando a gente vem de um aprendizado de programação procedural e tenta aplicar as mesmas técnicas fazendo uso de classes e objetos.

Exemplo clássico

Há um exemplo muito clássico de um código que claramente, embora utilize classes e objetos, é procedural:

Definição de uma classe

<?php

class Pessoa
{
    private string $primeiroNome;
    private string $ultimoNome;
    private \DateTimeInterface $dataNascimento;

    public function setPrimeiroNome(string $primeiroNome): void
    {
        $this->primeiroNome = $primeiroNome;
    }

    public function getPrimeiroNome(): string
    {
        return $this->primeiroNome;
    }

    public function setUltimoNome(string $ultimoNome): void
    {
        $this->ultimoNome = $ultimoNome;
    }

    public function getUltimoNome(): string
    {
        return $this->ultimoNome;
    }

    public function setDataNascimento(\DateTimeInterface $dataNascimento): void
    {
        $this->dataNascimento = $dataNascimento;
    }

    public function getDataNascimento(): \DateTimeInterface
    {
        return $this->dataNascimento;
    }
}

Utilização dela

$pessoa = new Pessoa();
$pessoa->setPrimeiroNome('Vinicius');
$pessoa->setUltimoNome('Dias');
$pessoa->setDataNascimento(new \DateTimeImmutable('1997-10-15')); // aceito presentes

$idade = $pessoa->getDataNascimento()->diff(new \DateImmutable())->y;

echo "{$pessoa->getPrimeiroNome()} {$pessoa->getUltimoNome()} tem $idade anos";

Problema

Olhando esse simples exemplo:

Você nota algum problema?
Identifica semelhança com algum pedaço de código que você tenha escrito recentemente?

Depois de você refletir um pouco, vamos continuar.

O código exemplificado utiliza uma classe Pessoa e a partir desta classe, cria um objeto. Logo, está utilizando do paradigma de programação orientada a objetos, certo? Errado!

Esse exemplo é claramente um código procedural que usa uma classe. Nada além disso.

Proposta

Se você possui uma classe, os objetos gerados através dela devem ter seus comportamentos descritos (através de métodos) e não apenas fornecer os dados para realizar essas ações.

O código anterior poderia ser escrito da seguinte forma para usar o paradigma Orientado a Objetos:

<?php

class Pessoa
{
    private string $primeiroNome;
    private string $ultimoNome;
    private \DateTimeInterface $dataNascimento;

    public function __construct(
        string $primeiroNome,
        string $segundoNome,
        \DateTimeInterface $dataNascimento
    ) {
        $this->primeiroNome = $primeiroNome;
        $this->ultimoNome = $ultimoNome;
        $this->dataNascimento = $dataNascimento;
    }

    public function nomeCompleto(): string
    {
        return "{$this->primeiroNome} {$this->ultimoNome}";
    }

    public function idade(): int
    {
        $hoje = new DateTimeImmutable();

        return $this->dataNascimento->diff($hoje)->y;
    }

E assim poderíamos utilizar esta classe:

<?php

$pessoa = new Pessoa('Vinicius', 'Dias', new \DateTimeImmutable('1997-10-15'));

echo "{$pessoa->nomeCompleto()} tem {$pessoa->idade()} anos.";

Motivação da mudança

Com essa simples modificação nós não temos mais instâncias inválidas, já que agora toda Pessoa tem seu primeiro e último nome e sua data de nascimento. Antes, primeiro nós estávamos criando uma Pessoa em um estado inconsistente, sem seus dados, para depois defini-los.

Além disso, agora qualquer método que receba uma Pessoa por parâmetro não precisa saber se nesse objeto o nome completo está separado em primeiro e segundo nome ou não. Não precisa saber como o cálculo da idade é feito.

Caso a forma de apresentar o nome precise ser modificado (de "Vinicius Dias" para "Dias, Vinicius", por exemplo), podemos ir direto no ponto correto: O método nomeCompleto.

Embora seja um exemplo muito simples, ele mostra com clareza como normalmente escrevemos código acreditando estar utilizando a programação orientada a objetos.

Caso você tenha algum outro exemplo desse tipo em mente, já tenha visto algum código procedural com classes assim, ou tenha alguma outra sugestão de melhoria pra esse exemplo, que tal compartilhar com a gente aqui nos comentários?

Princípios e padrões

Para nos ajudar a utilizar de forma mais "correta" a orientação a objetos, existem diversos padrões e princípios. Uns mais simples como o Tell, Don't ask, outros mais completos e complexos como os princípios SOLID.

Todos os princípios merecem uma atenção especial, porém isso foge do escopo deste artigo, mas uma rápida busca te mostra uma imensidão de conteúdo a respeito.

Conclusão

Muito frequentemente nós utilizamos o paradigma procedural em nosso código e só pelo fato de termos classes definidas no código, achamos que estamos utilizando a Orientação a Objetos.

Este paradigma é muito mais do que apenas definir classes, atributos e métodos, logo, precisa de muito mais estudo do que apenas a leitura da documentação da sua linguagem favorita para aprender a sintaxe.

O que é arquitetura

Vinicius Dias — Fri, 10 Apr 2020 18:45:05 +0000

Problema

Imagine que no momento da escrita desse artigo (ano de 2020) você esteja criando um sistema para a empresa que te contratou como desenvolvedor(a). Nesse sistema você pode utilizar todas as novas tecnologias, pode decidir como vai organizar o código, enfim, o sonho de qualquer pessoa que trabalha na área.

Como você trabalha com PHP, escolhe o framework que está "na boca do povo": Laravel. Começa o desenvolvimento e rapidamente entrega uma primeira versão do projeto. A equipe de negócios está feliz com toda a velocidade de entrega e a equipe técnica está feliz de utilizar um framework da moda.

Os anos se passam. No futuro, você precisa dar manutenção em um sistema que usa uma versão mega desatualizada do framework já que eles decidiram trocar a ferramenta que fazia o acesso ao banco de dados, e toda a regra de negócios da aplicação está em "models" do Eloquent.

Mundo real

Parece irreal, né!?

"Ah, mas o Laravel não vai deixar de usar o Eloquent. Não faz sentido esse exemplo"

Bom, hoje eu trabalho em uma empresa que tem um software funcionando desde o PHP 3.

Em algum momento da vida desse software, acharam uma boa ideia atrelar as regras de negócio a um projeto conhecido como Pear DB. Esse projeto hoje não recebe atualizações (apenas correções de segurança), além de nos deixar "amarrados" a sua filosofia de código, que difere do que temos nos mundos atuais de PSRs, Composer, etc.

Resultado: O sistema evolui. Novas funcionalidades são adicionadas todo dia. A equipe de negócios continua recebendo suas demandas, mas como a forma de desenvolver não evoluiu junto com o conhecimento e ferramentas atuais, o prazo já não é o mesmo.

Além disso, novos integrantes da equipe sofrem para entender todo o espaguete que o código virou. Caos!

Como poderia ter sido?

Se os arquitetos desse sistema pudessem voltar no tempo, o que fariam, você pode se perguntar. Minha ideia aqui é levantar algumas opções.

Em termos de código, entidades poderiam ter sido criadas sem nenhum conhecimento da infraestrutura que cuida da persistência. Se é utilizado Pear DB, PDO, Doctrine, Eloquent, uma API, um arquivo com os dados, tanto faz. A lógica de negócios estaria intacta.

E para salvar no banco? Classes especializadas nessa tarefa, também conhecidas como repositórios, poderiam ter sido utilizadas. Essas classes saberiam lidar com as entidades e fazerem a tradução necessária para o sistema de persistência (usando SQL, por exemplo).

E se a ferramenta usada fosse descontinuada? Bom, simples: Poderíamos criar uma interface que define o que um repositório deve saber fazer. Quando o Pear DB deixasse de receber suporte, nossa classe PearDbQuestionRepository (repositório de perguntas) poderia ser fácilmente substituída por uma classe PdoQuestionRepository, ou até mesmo DoctrineQuestionRepository. Isso não faria diferença para as regras de negócio, que precisavam de qualquer implementação da interface QuestionRepository.

O que isso tem a ver com arquitetura?

— Essa solução proposta é perfeita?
— Longe disso! Tem suas vantagens e desvantagens

Decisões de como organizar nosso código de forma que ele continue "utilizável" após determinado período é o propósito mais simples de uma arquitetura.

Arquitetura, segundo nosso querido Google, é: "arte e técnica de organizar espaços e criar ambientes para abrigar os diversos tipos de atividades humanas, visando tb. a determinada intenção plástica."

Se trazemos isso para o mundo do desenvolvimento temos uma definição semelhante à seguinte: "A arquitetura de software de um sistema consiste na definição dos componentes de software, suas propriedades externas, e seus relacionamentos com outros softwares."

Você pode encontrar inúmeras definições para esse termo, mas em sua essência, arquitetura de software nos ajuda a definir como organizar nosso código, torná-lo mais compreensível, manutenível a longo prazo, e separar a responsabilidades de domínio (regras de negócio) da infraestrutura (banco de dados, log, envio de e-mails, etc).

Padrões arquiteturais

O exemplo que eu dei é bem raso e cita apenas um pequeno problema que uma arquitetura bem feita visa resolver. Para resolver diversos outros problemas, padrões arquiteturais surgiram ao longo do tempo.

Você muito provavelmente conhece pelo menos um (nem que seja de nome), e aqui cito nomes de padrões arquiteturais bem famosos:

MVC (o famoso Model-View-Controller)
ADR (Action-Domain-Response, uma espécie de evolução do MVC para web)
SOA (Arquitetura orientada a serviços)
Clean Architecture (em português, Arquitetura Limpa)
Hexagonal Architecture (em português, Arquitetura Hexagonal)
Onion Architecture (em português, Arquitetura em Camadas (cebola))

Citar especificidades de cada padrão e suas semelhanças / diferenças fogem do escopo desse post, mas é interessante conhecer e se adaptar com alguns nomes.

Conclusão

Não existe sistema sem arquitetura, só sistema com arquitetura ruim.

Mesmo que no desenvolvimento de um sistema você não siga nenhum padrão arquitetural, há decisões de arquitetura no código, e se mal feitas, essas decisões podem te assombrar por muito (MUITO) tempo.

The state of Laravel-based APIs - a personal research

Igor Santos — Tue, 12 Jun 2018 08:02:33 +0000

Friendly disclaimer: this is a quick and dirty post that I'm putting together as I research API resources to build an API for a project I'm working on, so I'm sorry for being so direct and to the point, and also for the number of levels and bullet points :)
It was written in the order of "here only for the sake of completeness" down to "probably what we're going to use".

TL;DR

GraphQL should be the way to go only if your frontend sort of requires it. Needs a lot of boilerplate and manual sync between your Eloquent models and GraphQL-related code.
JSON-API is the most respected standard that could face GraphQL, but on Laravel-land it renders you documentation-less. You'll probably have to write separate documentation on API Blueprint or something like that, and it might take you some time as well. You can also discover how to get Blueprint generated through a specific package (that bridges JSON-API with Dingo), but... good luck on that.
Handwritten RESTful API... Do I need to comment on that? It's handwritten. Certainly not a good option for a medium or big API. EOF.

Prologue: basic API requirements we had

should have built-in documentation, that's not dependent on the developer to manually write it (think PHPDocs that magically autocomplete in your IDE)
it needs to be blazing fast, as it will be used on a speed-sensitive user interface
- here the features of field-selection from GraphQL or JSON-API come to my mind
- obviously, a simple cache layer might also be helpful

Research and comparisons

API type option 1: GraphQL

Short conclusion. Doesn't seem trivial to be built, as there's a lot of boilerplate to be written that repeats information from Eloquent: GraphQL Types, Queries, and Mutations. That happens on both packages found, and neither of them helps by having a boilerplate-generator.

Helpful Packages

By Folkore Atelier
By Rebing, based on Folklore's

API type option 2: RESTful

Subtype 1: JSON-API

Conclusion: also not that trivial to work with, but seems simpler than GraphQL. However, documentation might be a weak point.

Helpful packages

Nil's Laravel5-json-api

Implements include, fields, sort, page
Almost boilerplate-free with generic controllers
- However, you still need to configure Transformers, although they don't repeat much information from the Eloquent model
No support for documentation generation. At all.

Laravel5-json-api-dingo

Good points

Theoretically, brings together the best of both packages, including Dingo's features (Dingo is discussed later) such as Auth, Versioning, Rate limiting, Docs and Routes into laravel5-json-api (called L5JA from now on).

Bad points

it's not clear how documentation could be generated, as Dingo depends on annotations and L5JA is ideally based on a generic controller implementation. There might be other integration issues, as the examples do not clearly define how to bring both packages together, besides a basic routing sample.
support also seems to be lacking behind.

cloudcreativity's Laravel-json-api

This one has very long documentation; while seems complete, it might take a while to read everything and implement (took me a while reviewing the docs to see what features were available). And there are at least two empty pages, with a simple "todo" note.

Good points

also sort of boilerplate-free with generic controllers, and basic code generation for the other things (Adapters, Schemas)
Adapters and Schemas will still need some filling and manual sync with the Eloquent model, though
Also sports first-class validation rules for the API (which might end up being duplicated on your code, just like Eloquent details....)
seems to have a decent Auth infrastructure

Bad points

no clear mention on the docs about the selection of fields, and missing docs for sorting and "sparse fieldsets" (if that what I called "selection of fields"?) (issue on the topic)
filtering must be hand-written as well, there's no automatic API to turn filter parameters into Eloquent queries (much like GraphQL queries are built... sad).
also, no mention about documentation generation. There's an old issue that states Swagger can't work together with JSON-API, and the main developer doesn't have time to dedicate to that (we all know how open-source is born and dies, right? Free developer time during the lifecycle of a related project...)

Subtype 2: Plain "bring-your-own-standard" JSON API

Conclusion: the easiest to be built in our case, as we might end up needing only a couple of read-only endpoints. Might need some boilerplate to allow for field selection or advanced querying capabilities, but generates Blueprint documentation files and might even generate HTML docs with other generators.

Helpful Packages

Dingo

Good points

complete feature-set: auth, rate limiting helpers, errors, routing, doc generator (through Blueprint files)
Blueprint files can be used with a number of parsers to, then, generate HTML documentation or similar. Options and related resources are listed at the bottom of this post.

Bad points

Well... you'll have to write all your controllers and actions by hand. And define all your filters, if any. And whatnot.

Restler

This is actually unrelated to Laravel, but Eloquent can be easily made to work with it, so it's worth mentioning as a companion project to your main Laravel application.

Good points

complete feature-set, including Swagger documentation based on PHP Doc blocks and method parameters (that are also used for automatic request validation)

Bad points

Got abandoned:

stopped on PHP 5.4 support, while could have a great usage of PHP 7 first-class types
stopped on an old version of Swagger, missing some of its features - probably one of the reasons the package got abandoned, as Swagger is sometimes referred as a very complicated beast to deal with.

Sample implementation

Once upon a time, I started working on an API Server build with an Eloquent extension (also sort of abandoned) and Restler. It included some base controllers that made CRUD actions only a couple of lines away.

Other useful resources

Apiary - complete toolset (needs clarification!) to define, document and work on APIs.
Apimatic's transformer - UI and API that can translate to/from almost any doc format. Could be integrated in the API generation pipeline.
Dredd - parses Blueprint/Swagger docs and automatically runs tests to ensure the Backend complies with the defined documentation.
Blueman [probably outdated] - Generates Postman collections based on Blueprint files
PHPDraft - basic HTML generator from Blueprint files
Laravel Blueprint docs - generates integrated documentation inside your Laravel project, using its routing, and Blade templates for further customization.

Quick tip on Git diffs for PHP files

Igor Santos — Thu, 15 Sep 2016 23:00:00 +0000

Every time a PHP developer runs git diff on the command line a kitten dies:

Hell no! This piece of code is inside a method, not the class :(

Those @@ snippets are called Hunk Headers - because every part of a diff is called a hunk, duh. Unfortunately, git is too stupid to figure out PHP files should be diff'd according to PHP syntax, so you need to give it a hand by using a rule on git attributes.

Unfortunately(2), git attributes are not that easy to configure user-wide as config options are (no git global commands), thus here's the tip:

create the folder if it doesn't exist: ~/.config/git (or whatever is in $XDG_CONFIG_HOME)
write in ~/.config/git/attributes this: *.php diff=php
Save and diff away

This can also be configured per project by adding the same text inside a .gitattributes file.

There you have it! A decent Hunk Title on PHP files

It's quite weird why Git doesn't understand out of the box that through the file extension, as there are pre-baked settings to understand several syntaxes (such as TeX, Fortran, HTML, etc). Go figure!

References

http://stackoverflow.com/questions/28026767/where-should-i-place-my-global-gitattributes-file