Guia de Boas Práticas

Olá, Dev!

Suponho que você seja um iniciante na área de programação. Logo, me arrisco a dizer que na maior parte do tempo em que você está dedicado à aprender mais sobre a área, está sempre à procura de qual a nova tendência, ferramenta, ou tecnologia precisa aprender para conseguir se destacar.

E se te disser que isso é besteira?

Com o passar dos anos, a experiência e a exposição à ambientes desafiadores te mostram que os fundamentos são muito mais importantes que qualquer nova tendência atual.

Manter um software é muito mais trabalhoso, do que criar um do zero. Talvez seja por isso, que tenho certeza que já deve ter ouvido, ou dito algo parecido com:

“E se a gente refizesse isso com [coloque aqui qual a tecnologia da moda]?”

No que Eu acredito? Que software bom, é aquele que é usado. Tecnologia boa é qualquer uma que resolve o seu problema, aliás, o que é uma linguagem, ou framework senão mais uma ferramenta no que deveria ser a sua caixa de ferramentas?

Acredito que o bom código é aquele que possui uma leitura e entendimento simples e óbvio. Que permita uma fácil manutenção e evolução.

Por isso, esse material será focado em ajudar você, desenvolvedor Laravel, a parar de buscar alternativas em outras linguagens, ou frameworks, sem antes ter explorado o que o Laravel tem de melhor a te oferecer. Construindo softwares com alta manutenabilidade e extensibilidade.

Portanto, o conteúdo que você vai encontrar aqui será claro e direto. Você deverá usá-lo como mais uma ferramenta no seu arsenal. Sendo assim, você pode acessar diretamente as seções de interesse, sem ter que ler as anteriores.

Meu objetivo é que Você seja visto como um excelente profissional, que aplica boas práticas e escreve um código com alto nível de manutenabilidade.

Quem criou essa página?

Olá, me chamo José Moraes e já atuo na área de software há alguns anos.

Caso tenha interesse em saber mais sobre mim, recomendo se conectar comigo pelo LinkedIn e visitar meu Github

Sua responsabilidade é uma sóexibir

Já ouviu aquele ditado: “Quem faz tudo, não faz nada bem feito”?

Pois é, o famoso Princípio de Responsabilidade Única trata justamente disso. Suas classes e funções devem ter uma única responsabilidade. Ao fazer isso, a escrita de testes fica mais fácil, e o processo de “debugação” também.

Isso aqui é ruim

protected function fullClientName(): Attribute
{
    if (auth()->user() && auth()->user()->hasRole('client') && auth()->user()->isVerified()) {
        return new Attribute(
            get: fn ($value, $attributes) => "Sr. $attributes['first_name'] $attributes['middle_name'] $attributes['last_name']",
        );
    } else {
        return new Attribute(
            get: fn ($value, $attributes) => "$attributes['first_name'] $attributes['last_name']",
        );
    }
}

Os problemas do código acima são:

Muito verboso. Parece bagunçado; e
Em uma breve leitura você percebe que ele valida se o usuário está “logado”, se seu papel é client e se ele está verificado. O que não tem nada haver com o nome do cliente;

À partir do momento em que o código faz mais do que apenas retornar o nome do usuário (que é o que diz o nome da função), o código esconde de quem o chama, regras de negócio que não tem nada haver com o que o consumidor da função (uma outra classe por exemplo) espera. Na verdade, isso afetaria até a escrita de testes unitários, uma vez que a estratégia de definição de como será retornado o nome está escondida dentro da função.

Como melhorar isso?

protected function fullClientName() : Attribute
{
    return new Attribute(
            get: fn ($value, $attributes) => "Sr. $attributes['first_name'] $attributes['middle_name'] $attributes['last_name']",
        );
}

protected function shortClientName() : Attribute
{
    return new Attribute(
            get: fn ($value, $attributes) => "$attributes['first_name'] $attributes['last_name']",
        );
}

public function isTheLoggedUserAVerifiedClient()
{
    return  auth()->user() && 
            auth()->user()->hasRole('client') && 
            auth()->user()->isVerified()	
}

public function getUserData() 
{
    // Essa seria uma função qualquer que consumiria as demais
    $name = $user->isTheLoggedUserAVerifiedClient() 
                ? $user->full_client_name 
                : $user->short_client_name;

    return new UserDTO($name, ...);
}

Veja que nessa segunda abordagem, é retornado exatamente o valor que a função getUserData espera quando pede pelo nome longo do cliente (full_client_name), ou a versão curta dele (short_client_name). É a função chamadora quem define se quer exibir o nome curto, ou completo. Dessa forma, nenhuma regra de negócio fica oculta dentro de um método que só deveria retornar um nome na versão longa, ou curta.

Uma dica é sempre usar nomes descritivos, que realmente digam o que a função/classe faz. Desse jeito, se você notar que o nome atribuído começa a ficar longo e dizer que faz mais do que o que você pensa que ela deveria fazer, isso é sintoma de que o código em questão está ferindo o Princípio de Responsabilidade Única.

Controllers devem ser "finas"exibir

Existe uma expressão na comunidade Laravel que diz (em tradução livre):

Tenha models “gordos” e controllers “finos”

Na prática, isso quer dizer que você não deve ter regras de negócio, nem consultas de banco nas suas controllers.

Isso aqui é ruim

public function index()
{
    $users = User::verified()
        ->with(['posts' => function ($q) {
            $q->where('created_at', '>', Carbon::today()->subWeek());
        }])
        ->get();

    return view('index', ['users' => $users]);
}

Veja que toda a definição de consulta está definida na controller. Isso é péssimo, pois cruza as fronteiras de responsabilidade de uma controller, que deve apenas direcionar a model/regra de negócio que será entregue para a camada de apresentação.

Como melhorar isso?

// Na Controller
public function index()
{
    return view('index', ['users' => $this->user->getWithNewPosts()]);
}

// Na Model
class Client extends Model
{
    public function getWithNewPosts()
    {
        return $this->verified()
            ->with(['posts' => function ($q) {
                $q->where('created_at', '>', Carbon::today()->subWeek());
            }])
            ->get();
    }
}

Perceba que agora a controller apenas indica que os usuários a serem apresentados devem possuir os posts mais recentes, sem se importar como isso é feito na model.

Isso vai manter seu código muito mais organizado e legível.

Valide suas requisições do jeito certoexibir

Se você estiver validando as requisições diretamente na controller, pare agora mesmo. Lembre-se: “Controllers sempre finas”. Portanto:

Isso aqui é ruim

public function store(Request $request)
{
    $request->validate([
        'name' => 'required|max:255',
        'description' => 'required'
    ]);
    ...
}

A classe Request pode ser estendida e customizada para que contenha as validações que deseja fazer.

Como melhorar isso?

// Crie a classe para extender Request e tratar as validações
class ProductRequest extends Request
{
    public function rules()
    {
        return [
            'name' => 'required|max:255',
                'description' => 'required'
        ];
    }
}

// Aqui é na classe de Controller
public function store(ProductRequest $request)
{
    ....
}

Agora sim 😃

Veja que as regras agora são definidas dentro da função rules da classe ProductRequest e o próprio middleware as executa antes de passar a requisição para a controller em si. Se alguma regra for ferida, o middleware disparará uma exceção.

Já diziam os Menudos: "Não se repita"exibir

Tenho certeza que essa música vai ficar na sua cabeça pelo resto do seu dia: “Não se repita, não se repita (…)”.

O conceito de DRY (Dont Repeat Yourself - Não se Repita) parece óbvio, aliás, quem gosta de escrever o mesmo código em vários lugares diferentes, sem reaproveitar nada? 🤨

Desculpa estragar seu sorrisinho de canto de boca, mas CTRL + C e CTRL + V não é bem reaproveitamento de código no conceito DRY.

A verdade é que “Não se Repetir” aqui é abstrair alguma lógica em um escopo com fronteiras bem definidas e acessar esse escopo por uma instância dele. Veja:

Isso aqui é ruim

public function getActive()
{
    return $this->where('verified', 1)->get();
}

public function getPosts()
{
    return $this->whereHas('user', function ($q) {
            $q->where('verified', 1);
        })->get();
}

Veja que nas duas funções, é feita uma query para verificar se o usuário foi verificado.

Como melhorar isso?

public function scopeVerified($q)
{
    return $q->where('verified', 1);
}

public function getActive()
{
    return $this->verified()->get();
}

public function getArticles()
{
    return $this->whereHas('user', function ($q) {
            $q->verified();
        })->get();
}

Veja que aqui, usei o conceito de query scopes (escopos de consulta) do Eloquent ORM usado pelo Laravel, e abstraí a lógica de consulta que aplica o filtro de usuário verificado e apenas reaproveitei o uso do escopo nas demais funções.

Vale lembrar que aqui só usei o conceito de query scopes, para aproveitar a oportunidade de mostrar como eles funcionam e explicar o conceito ao mesmo tempo, porém, o conceito de DRY deve ser aplicado toda vez que você perceber que um mesmo trecho de código está sendo usado em outros lugares. Se você estiver fazendo muito CTRL + C e CTRL + V de um trecho de código, certamente é uma oportunidade clara de aplicar o DRY.

Fique sempre atento e refatore quando necessário.

Coloque um nome decente!exibir

Isso aqui vem direto dos ensinamentos do Uncle Bob (Robert C. Martin). Use sempre nomes expressivos em variáveis, funções, classes, constantes, e assim por diante.

Nomes expressivos vão tornar seu código óbvio e simples de ser lido. E no mundo do código, ser simples é coisa fina. Por exemplo:

Isso aqui é ruim

if (count((array) $b->getQuery()->joins) > 0)
{
    ...
}

Isso aqui é pior

// Verifica se a query possui joins
if (count((array) $b->getQuery()->joins) > 0)
{
    ...
}

Por que é pior? Você deve estar se perguntando, afinal, você está dizendo o que o código faz.

É que comentários em códigos, podem esconder detalhes e ao longo do tempo, se essa declaração for modificada, será que a pessoa que a modificou se dará o trabalho de alterar o comentário? Nos meus anos de prática nunca vi isso acontecer (talvez seja a bolha né?).

Como melhorar isso?

if ($this->hasJoins()) 
{
    ...
}

Viu como a declaração fica tão óbvia ao ponto de ser bobo? Não precisei de nenhum comentário explicando o que significa a declaração. O própria nome já diz: hasJoins (possuiLigacoes - em tradução livre).

Pare hoje de colocar nome de variável como x ou t. Veja seu código como um filho seu e coloque bons nomes (a não ser que tu seja o Elon Musk. Se for, ignore o comentário anterior).

Ainda sobre este tópico vale ressaltar que o framework Laravel possui uma convenção de nomes que recomendo ser respeitada. Ela não é obrigatória, mas seu uso potencializará as comodidades que o framework oferece como: Geração de códigos usando o artisan cli; Acesso à recursos sem a necessidade de configurações extras; e o mais importante, um padrão de escrita que se respeitado, beneficiará toda a equipe no longo prazo, reduzindo a curva de aprendizagem e acelerando a geração de valor.

Recurso	Qual a convenção?	Isso aqui é Ruim	Isso aqui é Excelente
Model	singular	Users	User
Propriedade de uma Model	snake_case	$model->createdAt	$model->created_at
Migrações	nome expressivo	2017_01_01_000000_articles	2017_01_01_000000_create_articles_table
Tabelas	plural	article_comment, articleComments	article_comments
Colunas em tabelas	snake_case sem o nome da model	MetaTitle; article_meta_title	meta_title
Chaves primárias	-	custom_id	id
Chaves estrangeiras	singular com nome da model e com o sufixo _id	ArticleId, id_article, articles_id	article_id
relacionamentos hasOne ou belongsTo	singular	articleComments, article_comment	articleComment
Todos os outros relacionamentos	plural	articleComment, article_comments	articleComments
Tabela Pivot	nomes das models no singular e em ordem alfabética	user_article, articles_users	article_user
Collection	descritiva e no plural	$active, $data	$activeUsers = User::active()->get()
Controller	singular	ArticlesController	ArticleController
Route	plural	article/1	articles/1
Named route	snake_case sem notação de ponto	users.show-active, show-active-users	users.show_active
Métodos	camelCase	get_all	getAll
Métodos em controllers	convenção: store, view, list, update, destroy	saveArticle	store
Métodos em classes de teste	camelCase	test_guest_cannot_see_article	testGuestCannotSeeArticle
Variáveis	camelCase	$articles_with_author	$articlesWithAuthor
Object	descritiva no singular	$users, $obj	$activeUser = User::active()->first()
Config e arquivos de linguagem	snake_case	ArticlesEnabled; articles-enabled	articles_enabled
View	kebab-case	showFiltered.blade.php, show_filtered.blade.php	show-filtered.blade.php
Config	snake_case	googleCalendar.php, google-calendar.php	google_calendar.php
Contract (interface)	adjetivo ou substantivo	AuthenticationInterface, IAuthentication	Authenticatable
Trait	adjetivo	NotificationTrait	Notifiable

Não acesse variáveis de ambiente diretamente pelo .envexibir

Você deve estar se perguntando o porquê não pode simplesmente usar o helper env diretamente. Isso está ligado à estratégia de caching que o Laravel usa para otimizar o acesso a recursos. Uma vez que as configurações foram armazenadas em cache, o helper env não retornará nada além de null. Por isso a recomendação de configurar o acesso à variáveis de ambiente por meio do arquivo de configuração.

Isso aqui é ruim

$apiKey = env('API_KEY');

Como melhorar isso?

// No arquivo de configuração: config/api.php
'key' => env('API_KEY'),

// Acessando o valor
$apiKey = config('api.key');

Ainda adiciono que configurar variáveis de ambiente em arquivos de configuração, permitirá um acesso mais legível à informação, e você poderá ter configurações de natureza diferentes, organizadas em domínios mais semânticos, como no caso acima, em que todas as informações relacionadas à API estarão em um arquivo específico de configurações de API.

Não acabe com a memória! Use chunkexibir

Se você é iniciante na área, talvez não tenha se deparado com tarefas que exigiam implementações que precisassem realizar processamentos em grandes volumes de informações, ou certamente, se nasceu nos anos 2000, talvez nunca tenha desenvolvido algo e se preocupado com quanta memória uma operação está consumindo.

Isso não é ruim não. Ainda bem que hoje nossa preocupação hoje em dia seja mais com design de arquitetura e capacidade de manutenção do que detalhes de mais baixo nível (isso em âmbito geral), se bem que performance e escalabilidade ainda são assuntos relevantes e sempre terão seu espaço nas discussões dos profissionais da área.

Meu ponto aqui é te dizer que com Laravel, quando tu precisar executar uma operação em grandes volumes, cuidado, pois:

Isso aqui é ruim

$users = User::where('active', 1)->get(); // Suponha que há 10 mil usuários

$users->each(function($user){
    // Envie um e-mail
});

Como melhorar isso?

User::where('active', 1)
->chunkById(200, function ($users) {
    $users->each(function($user){
                // Envie um e-mail
            });
}, $column = 'id');

Veja que na função acima, é invocada uma função chamada chunkById que recebe como parâmetros: O número de resultados recuperados por iteração; e um callback para processar os resultados.

Isso vai permitir consumir menos memória do que executar um eager loading retornando todos os itens da tabela como na primeira opção, uma vez que a execução será executada em lotes de 200 resultados por consulta, conforme o exemplo apresentado.

Se você pesquisar na documentação oficial verá que há ainda uma função chunk que pode ser usada. Não a utilizei no exemplo acima, porque como realizei um filtro na consulta, a função chunkById realiza um trabalho melhor, uma vez que usa a coluna ID para identificar o último item retornado na consulta anterior e em ordem crescente será o ponto de partida da próxima consulta.

De quebra, ainda usei a função each que possui uma legibilidade melhor que escrever uma declaração foreach, embora isso tenha haver apenas com legibilidade e não com performance, ou algo dessa natureza.

E para fechar, certamente se você é alguém com um conhecimento um pouco mais avançado, deve estar se perguntando: “Por que ele não falou que os resultados poderiam ser executados em uma fila?”. E sim, poderiam, isso faria sentido na execução do comando (enviar o e-mail, conforme proposto no exemplo). Você pode configurar uma fila de envio de e-mails e ao invés de realizar a operação de envio de forma síncrona, um por um, você pode enfileirar as operações para que aconteçam de forma assíncrona.

Pesquise na documentação do Laravel as funções: lazy e lazyById , pois elas internamente usam a mesma estratégia de chunk, porém retornam uma LazyCollection que te permite interagir com os resultados individualmente. Por exemplo: foreach (User::lazy() as $user) { ... }

Seja esperto! Use acessors e mutatorsexibir

Falei que evitaria criar relações diretas entre os tópicos para serem um guia de bolso para consultas rápidas, mas esse é um assunto que conversa bem com o tópico em que discutimos o “Não se Repita”.

Isso porque, acessors e mutators foram implementados no Laravel justamente para melhorar o seu dia-a-dia e evitar que fique reescrevendo coisas verbosas o tempo todo em tudo quanto é lugar, veja:

Isso aqui é ruim

// Aqui seria uma página Blade
{{ Carbon::createFromFormat('Y-d-m H-i', $product->ordered_at)->format('m-d') }}

Como melhorar isso?

protected function orderedAt(): Attribute
{
    return Attribute::make(
        get: fn ($value) => 
                    Carbon::createFromFormat(
                        'Y-d-m H-i',
                        $value
                    )->format('m-d'),
    );
}

// Quando for usar, o atributo já estará formatado, 
// pois o Acessor já fez o trabalho pesado
{{ $product->ordered_at }}

Se você estiver seguindo as convenções de nomes do Laravel, isso funcionará como mostrei acima, pois entende-se que a função orderedAt dentro da model Product refere-se ao atributo ordered_at. Caso você queira criar um acessor com nome de função personalizada, com mais semântica, faça desse jeito:

protected function orderedAtPtBrFormat(): Attribute
{
    return Attribute::make(
        get: fn ($value, $attributes) => 
                    Carbon::createFromFormat(
                        'Y-d-m H-i', 
                        $attributes['ordered_at']
                    )->format('d-m-Y H-i'),
    );
}

Mas qual a diferença entre um Acessor e um Mutator?

A diferença é que um Acessor, irá formatar o valor antes de exibí-lo e não irá alterar o registro original, uma vez que seu único objetivo é permitir abstrair as apresentações de dados.

Já um Mutator, é o contrário, seu papel é formatar a informação para armazenar no banco. Vamos supor que você salva as datas no seu banco no formato Y-m-d, porém, o formulário no front-end do seu sistema envia a informação no formato d-m-Y. Neste caso, o Mutator vai ser usado para preparar a data antes de salvá-la no banco. Veja:

protected function orderedAt(): Attribute
{
    return Attribute::make(
        set: fn ($value) => 
                Carbon::createFromFormat(
                    'd-m-Y',
                    $value
                )->format('Y-m-d'),
    );
}

Se olhar com atenção, os acessors são definidos como um callback de get e mutators são definidos como um callback de set que são atributos da classe Attribute que abstrai o tratamento customizado de atributos no Laravel.

Um Blade sem consultas, por favorexibir

Evite inserir consultas em arquivos blade, pois eles são responsáveis apenas pela camada de apresentação. Mover consultas para essa camada, cria acoplamentos desnecessários, sem falar que você estará espalhando lógica de negócio para tudo quanto é lado. Tenha bom senso 😺

Isso aqui é horrível

@foreach (User::all() as $user)
    {{ $user->profile->name }}
@endforeach

Por que é horrível? Além do motivo que abriu a discussão do tópico, a consulta acima faz N + 1 consultas (famoso problema N + 1), ou seja, se tu for listar os perfis de 100 usuários, serão 101 consultas.

Agora imagine essa página sendo acessada por mil pessoas. Esse aí seria um claro gargalo de performance.

Mas falando sério, evite esse tipo de código.

Como melhorar isso?

// Na controller
$users = User::with('profile')->get();

// No blade

@foreach ($users as $user)
    {{ $user->profile->name }}
@endforeach

Veja que o blade template só sabe que existem usuários com perfis para apresentar, não sabe a regra aplicada na filtragem, ou qualquer outra regra, e… são apenas 2 consultas.

Como assim, N + 1?

Em uma visão mais simplificada do problema, tente visualizar o seguinte cenário:

Você possui uma base com 100 usuários;
Você vai acessar uma página que exibe o nome do perfil de cada usuário (relação 1:N);
Por debaixo dos panos, o que o exemplo N + 1 faz é:

SELECT * FROM users;
SELECT * FROM profiles WHERE user_id = 1;
SELECT * FROM profiles WHERE user_id = 2;
SELECT * FROM profiles WHERE user_id = 3;
...
SELECT * FROM profiles WHERE user_id = 100;

Porque ele primeiro pega a referência de usuários em 1 consulta e a do perfil nas outras 100.

No segundo caso, ele faz uma consulta para retornar os usuários e uma segunda consulta que permitirá retornar os dados do perfil, dessa forma:

SELECT * FROM users;   
SELECT * FROM profiles WHERE user_id in (1, 2, 3, 4, 5, ...)

Isso porque a função all vai retornar todos os usuários de uma vez, e toda vez que no loop você acessar a variável profile será feita uma nova consulta para pegar a informação de perfil do usuário. A função with usa a estratégia de eager loading, que exemplifiquei acima, por isso são realizadas apenas 2 consultas.

Use atribuição em massaexibir

Quando passar dados de uma requisição para uma model realizar um novo registro, tire proveito das convenções de nomes, e faça uma atribuição em massa, que basicamente vai parametrizar os atributos de requisição e refletir nos atributos da model.

Isso aqui é ruim

$post = new Post;
$post->title = $request->title;
$post->content = $request->content;
$post->verified = $request->verified;
$post->save();

Como melhorar isso?

$post->create($request->all());

Isso reduz muito a quantidade de linhas escritas, sem perder a legibilidade.

Guia de Boas Práticas com Laravel

( para iniciantes )

Quem criou essa página?

Sua responsabilidade é uma sóexibir

Isso aqui é ruim

Como melhorar isso?

Controllers devem ser "finas"exibir

Isso aqui é ruim

Como melhorar isso?

Valide suas requisições do jeito certoexibir

Isso aqui é ruim

Como melhorar isso?

Já diziam os Menudos: "Não se repita"exibir

Isso aqui é ruim

Como melhorar isso?

Coloque um nome decente!exibir

Isso aqui é ruim

Isso aqui é pior

Como melhorar isso?

Não acesse variáveis de ambiente diretamente pelo .envexibir

Isso aqui é ruim

Como melhorar isso?

Não acabe com a memória! Use chunkexibir

Isso aqui é ruim

Como melhorar isso?

Seja esperto! Use acessors e mutatorsexibir

Isso aqui é ruim

Como melhorar isso?

Mas qual a diferença entre um Acessor e um Mutator?

Um Blade sem consultas, por favorexibir

Isso aqui é horrível

Como melhorar isso?

Como assim, N + 1?

Use atribuição em massaexibir

Isso aqui é ruim

Como melhorar isso?

Referênciasexibir