Forem: Felipe Dumont De Sa Costa

Object Calisthenics

Felipe Dumont De Sa Costa — Fri, 20 Mar 2026 17:26:28 +0000

Object Calisthenics na prática — PHP, Laravel e Vue.js

9 regras para escrever código orientado a objetos mais limpo, com exemplos reais de domínio. Sem teoria de livro didático.

Object Calisthenics é um conjunto de 9 restrições criadas por Jeff Bay, publicadas no livro ThoughtWorks Anthology (2008). A ideia é simples: aplicar essas regras como exercício disciplinado força você a produzir código com alta coesão, baixo acoplamento e responsabilidade única — mesmo sem pensar conscientemente em SOLID.

O nome vem de calistenia — exercício usando o próprio corpo, sem equipamento. Aqui, o "equipamento" são as abstrações desnecessárias. Você se exercita com restrições para desenvolver o instinto certo de design.

Os exemplos abaixo usam um domínio real de gestão de contratos de locação — análise de crédito, garantias, cobranças, notificações. Nada de Foo e Bar.

Os 9 princípios

#	Regra
01	Um nível de indentação por método
02	Não use `else`
03	Envolva primitivos e strings
04	Coleções de primeira classe
05	Um ponto por linha
06	Não abrevia nomes
07	Mantenha entidades pequenas
08	No máximo 2 variáveis de instância
09	Sem getters e setters

01 — Um nível de indentação por método

Se um método tem um for dentro de um if, ele já está fazendo coisas demais. Extraia o conteúdo de cada bloco para um método privado com nome que descreva a intenção.

❌ Ruim

public function processOverdueContracts(Collection $contracts): void
{
    foreach ($contracts as $contract) {
        if ($contract->isOverdue()) {
            foreach ($contract->payments() as $payment) {
                if ($payment->isPending()) {
                    $payment->markAsLate(); // 3 níveis de indentação
                }
            }
        }
    }
}

✅ Bom

public function processOverdueContracts(Collection $contracts): void
{
    $contracts
        ->filter(fn($c) => $c->isOverdue())
        ->each($this->markPendingPaymentsAsLate(...));
}

private function markPendingPaymentsAsLate(Contract $contract): void
{
    $contract
        ->payments()
        ->filter(fn($p) => $p->isPending())
        ->each(fn($p) => $p->markAsLate());
}

Por quê funciona: cada método tem uma responsabilidade isolada e pode ser testado individualmente. O nome markPendingPaymentsAsLate documenta a intenção sem necessitar de comentário.

02 — Não use `else`

Use early return: verifique os casos inválidos primeiro e retorne. O caminho feliz fica no final, sem aninhamento. Essa é provavelmente a regra de maior impacto imediato no dia a dia.

❌ Ruim

public function approve(Application $app): ApprovalResult
{
    if ($app->hasValidDocuments()) {
        if ($app->creditScore() >= 600) {
            if (!$app->hasActiveDenial()) {
                return ApprovalResult::approved();
            } else {
                return ApprovalResult::denied('Bloqueio ativo');
            }
        } else {
            return ApprovalResult::denied('Score insuficiente');
        }
    } else {
        return ApprovalResult::denied('Documentos inválidos');
    }
}

✅ Bom

public function approve(Application $app): ApprovalResult
{
    if (!$app->hasValidDocuments()) {
        return ApprovalResult::denied('Documentos inválidos');
    }

    if ($app->creditScore() < 600) {
        return ApprovalResult::denied('Score insuficiente');
    }

    if ($app->hasActiveDenial()) {
        return ApprovalResult::denied('Bloqueio ativo');
    }

    return ApprovalResult::approved();
}

Por quê funciona: lê-se como um checklist. Cada guarda elimina um caso inválido. O caminho feliz fica explícito no final. Zero aninhamento, fácil de adicionar novas validações.

03 — Envolva primitivos e strings

Strings, inteiros e floats soltos não carregam regras de negócio. Um Value Object garante que um CPF inválido nunca existirá no sistema — a validação fica no construtor, não espalhada em 20 lugares.

❌ Ruim

// Controller, Service, Job... cada um valida do seu jeito
$cpf  = $request->input('cpf');        // string qualquer
$rent = $request->input('rent_value'); // float sem garantia

if (strlen(preg_replace('/\D/', '', $cpf)) !== 11) {
    throw new InvalidArgumentException('CPF inválido');
}
if ($rent <= 0) {
    throw new InvalidArgumentException('Valor inválido');
}

✅ Bom

final class Cpf
{
    private readonly string $value;

    public function __construct(string $raw)
    {
        $digits = preg_replace('/\D/', '', $raw);
        CpfValidator::ensureValid($digits); // lança exceção se inválido
        $this->value = $digits;
    }

    public function formatted(): string
    {
        return preg_replace(
            '/(\d{3})(\d{3})(\d{3})(\d{2})/',
            '$1.$2.$3-$4',
            $this->value
        );
    }
}

final class Money
{
    public function __construct(
        private readonly int $cents // sempre em centavos
    ) {
        if ($this->cents < 0) {
            throw new DomainException('Valor monetário não pode ser negativo');
        }
    }

    public function times(int $multiplier): self
    {
        return new self($this->cents * $multiplier);
    }

    public function isLessThan(self $other): bool
    {
        return $this->cents < $other->cents;
    }
}

// No controller: tipagem garante integridade
$cpf  = new Cpf($request->input('cpf'));
$rent = Money::fromFloat($request->input('rent_value'));

Por quê funciona: impossível criar um Cpf inválido no sistema. A validação existe em um único lugar. O tipo já documenta a intenção — Money é muito mais expressivo que float.

04 — Coleções de primeira classe

Se você tem uma classe que contém uma coleção, ela não deve ter outros atributos. Encapsule arrays e collections em classes próprias com comportamento de domínio — em vez de espalhar a lógica de filtragem por todos os services.

❌ Ruim

// ReportService.php
$overdueTotal = Contract::all()
    ->filter(fn($c) => $c->status === 'overdue')
    ->sum('value');

// DashboardService.php — mesma lógica duplicada
$overdueByAgency = Contract::all()
    ->filter(fn($c) => $c->status === 'overdue')
    ->groupBy('agency_id');

✅ Bom

final class ContractCollection
{
    public function __construct(
        private readonly Collection $items
    ) {}

    public function overdue(): self
    {
        return new self(
            $this->items->filter(fn($c) => $c->isOverdue())
        );
    }

    public function totalValue(): Money
    {
        return Money::fromFloat($this->items->sum('value'));
    }

    public function groupedByAgency(): Collection
    {
        return $this->items->groupBy('agency_id');
    }
}

// Uso — expressivo e reutilizável
$contracts = new ContractCollection(Contract::all());

$overdueTotal    = $contracts->overdue()->totalValue();
$overdueByAgency = $contracts->overdue()->groupedByAgency();

Por quê funciona: a definição de "overdue" existe em um único lugar. Se a regra mudar, você altera o método overdue() e todos os consumidores ganham automaticamente.

05 — Um ponto por linha

A Lei de Deméter: um objeto só deve falar com seus vizinhos imediatos, não com os amigos dos seus amigos. Navegar pela estrutura interna de um objeto cria acoplamento invisível — se Contact muda, tudo que acessa $contract->tenant()->contact()->email() quebra.

❌ Ruim

// 4 dependências acopladas em 1 linha
$email = $contract
    ->tenant()
    ->contact()
    ->primaryEmail()
    ->address();

$this->mailer->to($email)->send(new DueDateMail());

✅ Bom

// Contract.php — expõe apenas o que é necessário
class Contract
{
    public function tenantEmail(): string
    {
        return $this->tenant()->primaryEmail();
    }
}

// NotificationJob.php — apenas um ponto
$this->mailer
    ->to($contract->tenantEmail())
    ->send(new DueDateMail($contract));

Exceção válida: o Laravel Query Builder e Collections foram projetados para chaining. Contract::query()->where(...)->with(...)->get() é Fluent Interface intencional, não navegação acidental. A regra se aplica a traversal de estruturas internas, não a builders.

06 — Não abrevia nomes

Código é lido muito mais vezes do que é escrito. Abreviações economizam segundos na digitação e custam minutos em cada leitura. Se você precisa de contexto para entender um nome, ele está errado.

❌ Ruim

public function upd(UpdCtrReq $req, int $id)
{
    $ctr = Ctr::findOrFail($id);
    $svc = new CtrSvc();
    $res = $svc->upd($ctr, $req->validated());
    return $res->toApiResp();
}

// Vue — ilegível sem contexto
const hdlSubm = async () => {
    const r = await postCtrUpd(frm.val);
    updCtrLst(r.d);
}

✅ Bom

public function update(UpdateContractRequest $request, int $id)
{
    $contract = Contract::findOrFail($id);
    $service  = new ContractService();
    $result   = $service->update($contract, $request->validated());
    return $result->toApiResponse();
}

// Vue — autoexplicativo
const handleFormSubmit = async () => {
    const updatedContract = await updateContract(form.value);
    refreshContractList(updatedContract);
}

Teste do contexto: mostre o nome isolado para alguém do time. Se precisar explicar o que significa, o nome falhou.

07 — Mantenha entidades pequenas

Classes com menos de 50 linhas, métodos com menos de 5 linhas, pacotes com menos de 10 arquivos. Esses números são restritivos por design — o objetivo é forçar a pergunta: "esta responsabilidade pertence aqui?"

❌ Ruim

class ContractService // 800+ linhas
{
    public function approve() { ... }
    public function generateBoleto() { ... }
    public function sendWhatsAppReminder() { ... }
    public function cancel() { ... }
    public function generateNfe() { ... }
    public function calculateCommission() { ... }
    public function buildDashboardReport() { ... }
    // + 20 métodos...
}

✅ Bom

// App/Services/Contract/
ContractApprovalService     // aprova, nega, audita
ContractBillingService      // boleto, PIX, Asaas
ContractNotificationService // WhatsApp, e-mail
ContractCancellationService // cancela + estorno
ContractInvoiceService      // NFe.io

// Ou Actions (single-action, mais Laravel-idiomatic):
ApproveContractAction
CancelContractAction
GenerateContractInvoiceAction

// Binding no AppServiceProvider:
$this->app->bind(
    ContractApprovalService::class,
    SerasaContractApprovalService::class
);

Sinal de alerta: se você precisa de Ctrl+F para achar um método dentro da própria classe, ela está grande demais.

08 — No máximo 2 variáveis de instância

Essa é a regra mais radical — e a mais reveladora. Quando você tenta limitar para 2 variáveis, percebe que o que parecia uma classe coesa é, na verdade, três conceitos distintos vivendo no mesmo endereço.

❌ Ruim

class TenantAnalysis
{
    public function __construct(
        private string $name,
        private string $cpf,
        private float  $income,
        private int    $serasaScore,
        private float  $totalDebt,
        private string $analysisStatus,
        private Carbon $analysisDate,
    ) {}
}

✅ Bom

final class TenantProfile   // identidade do inquilino
{
    public function __construct(
        private readonly TenantName $name,
        private readonly Cpf        $cpf,
    ) {}
}

final class CreditSnapshot  // snapshot de crédito
{
    public function __construct(
        private readonly SerasaScore $score,
        private readonly Money       $totalDebt,
    ) {}

    public function isEligibleFor(Money $rentValue): bool
    {
        return $this->score->isAboveMinimum()
            && $this->totalDebt->isLessThan($rentValue->times(3));
    }
}

final class TenantAnalysis  // une os dois conceitos
{
    public function __construct(
        private readonly TenantProfile  $profile,
        private readonly CreditSnapshot $credit,
    ) {}
}

Efeito colateral positivo: o método isEligibleFor() surgiu naturalmente na decomposição — o comportamento encontrou o dado certo para viver junto.

09 — Sem getters e setters

"Tell, Don't Ask": em vez de buscar os dados de um objeto para decidir por ele, diga ao objeto o que fazer. Getters e setters transformam objetos em DTOs glorificados — a lógica de negócio acaba vivendo fora de onde o dado está.

❌ Ruim

// Service busca os dados e decide por fora
$status    = $contract->getStatus();
$startDate = $contract->getStartDate();

if ($status === 'active' && $startDate->diffInDays(now()) < 30) {
    $contract->setStatus('cancelled');
    $contract->setCancelledAt(now());
    $contract->save();
}

✅ Bom

// Contract.php — regra encapsulada no objeto
class Contract
{
    public function cancelWithinCoolingPeriod(): void
    {
        if (!$this->isWithinCoolingPeriod()) {
            throw new CancellationNotAllowedException(
                'Período de cancelamento encerrado'
            );
        }

        $this->status      = ContractStatus::CANCELLED;
        $this->cancelledAt = now();
    }

    private function isWithinCoolingPeriod(): bool
    {
        return $this->isActive()
            && $this->startedAt->diffInDays(now()) < 30;
    }
}

// No Service: uma linha, sem acoplamento
$contract->cancelWithinCoolingPeriod();
$contract->save();

Por quê funciona: a regra dos "30 dias" existe em um lugar. Se o prazo mudar, você altera isWithinCoolingPeriod() e todos os consumers são atualizados automaticamente.

Bônus — Os mesmos princípios no Vue.js

Composables são o equivalente de services no frontend. As mesmas regras se aplicam — especialmente as de tamanho, nomeação e responsabilidade única.

❌ Ruim — composable que faz tudo

// useContract.ts
export function useContract() {
  const contracts    = ref([])
  const filter       = ref('all')
  const isModalOpen  = ref(false)
  const isApproving  = ref(false)
  const errorMessage = ref('')

  async function fetchAll() { ... }
  async function approve(id) { ... }
  function       openModal() { ... }
  function       filterByStatus() { ... }
  // + 10 outros...
}

✅ Bom — composables focados

// useContractList.ts — lista e filtro
export function useContractList() {
  const contracts    = ref([])
  const activeFilter = ref('all')

  const filteredContracts = computed(() =>
    contracts.value.filter(c => {
      if (activeFilter.value === 'all') return true
      return c.status === activeFilter.value
    })
  )

  return { contracts, activeFilter, filteredContracts }
}

// useContractApproval.ts — só aprovação
export function useContractApproval() {
  const isApproving   = ref(false)
  const approvalError = ref('')

  async function approve(contractId: number) {
    isApproving.value = true
    try {
      await approveContract(contractId)
    } catch {
      approvalError.value = 'Falha ao aprovar contrato'
    } finally {
      isApproving.value = false
    }
  }

  return { isApproving, approvalError, approve }
}

// No componente: combina apenas o que precisa
const { filteredContracts, activeFilter } = useContractList()
const { isApproving, approve }            = useContractApproval()

Quando aplicar — e quando não

Object Calisthenics não é lei sagrada. É um termômetro. Quando uma regra parece errada, pergunte: "estou com preguiça, ou realmente não faz sentido aqui?"

Aplique quando:

Código de domínio crítico (aprovação, cobrança, análise de crédito)
Código que vai crescer e ser mantido por vários devs
Lógica que precisa ser testada com confiança
Onboarding — código como documentação viva
Refatorando God Classes e métodos longos

Cuidado com:

Scripts descartáveis — custo não compensa
Migrations e seeders — linearidade é mais clara
CRUD simples sem regra de negócio
Hotfix urgente em produção — refatore depois
Time sem contexto dos princípios — alinhe antes

Código limpo não é perfeccionismo — é respeito pelo próximo dev.

Tags: php laravel vue clean-code object-calisthenics solid boas-praticas

Porque você deve usar tratamento de exceções em seus projetos PHP.

Felipe Dumont De Sa Costa — Mon, 02 Aug 2021 00:44:55 +0000

Para ter mensagens bonitas para o usuário.

É claro que mensagens bem tratadas para o usuário final da aplicação é algo importante, mas não é apenas por isso que você deveria utilizar tratamentos de exceções, e claro, melhor que só usar, é usar bem. Mas antes de irmos para o motivo, vamos entender um pouco mais sobre.

O que são Exceções no PHP?

Exceções são como uma saída final. É como se seu código estive em um fluxo, e por algum motivo esse fluxo foi quebrado e precisa ser interrompido. Essa interrupção é chamado de exceção.
No PHP existe uma classe Exception, que implementa uma interface Throwable. Talvez você já tenha se deparado com o seguinte trecho de código:

<?php

try {
    // Something
} catch (Throwable $e) {
    echo $e->getMessage() . PHP_EOL;
}

Isso funciona bem quando queremos capturar qualquer tipo de erro ou exceção. E talvez ter um carinha assim no final deva ser uma boa pratica. Mas se for pra colocar esse cara em todos os lugares que queremos tratar exceções, é melhor não colocar. O real motivo de tratar exceções foi banalizado dessa maneira. Afinal de contas, agora só vai mostrar uma mensagem mais bonitinha realmente.

Mas vamos com calma, vamos entender essas palavras que foram ditas e outras mais:

Throwable é uma interface que somente o próprio PHP pode implementar.
Error é uma classe base do PHP de qualquer erro que pode ser emitido.
Exception também é uma classe base, mas no PHP não existem exceções. Ele conta com uma biblioteca padrão chamada SPL Exceptions.
SPL Exceptions fornece um conjunto de Exceptions padrões, que são dividas em exceções logicas e exceções em tempo de execução.

Não se preocupe em decorar cada uma. O que vamos utilizar e precisamos de mais atenção são as SPL Exceptions, mais especificamente a exceções em tempo de execução.

Isso não significa que as outras não são importantes, elas vão te ajudar no momento em que seu código for interpretado, se alguma exceção for jogada você terá um problema em alguma parte de seu código.

Já as exceções de tempo de execução não poderão ser "adivinhadas" pelo PHP quando seu código estiver sendo interpretado. Por isso a importância maior nesse tipo.

Como então seria o jeito certo de usar?

Jeito certo?

Talvez não existe um jeito certo, existe o jeito que vai te ajudar a resolver problemas, e isso é especifico para cada projeto ou sistema. Mas eu vou passar algumas dicas que fui aprendendo no dia a dia de uso.

Não precisa usar em tudo:

Não precisa definir um bloco try catch em todas as funções de todas as classes do seu sistema.

Você pode definir apenas quando chama-las.
Tente ser o mais especifico possível:

Use como parâmetro do catch exceções mais especificas, como exemplo InvalidArgumentException, que é utilizada quando um argumento é invalido.

Ou até mesmo as suas próprias exceções criadas.
Utilize para tentar resolver o problema:

Quando você define um exceção especifica, tecnicamente você sabe qual foi o erro, por isso da para tentar corrigi-lo ali mesmo.

Crie um registro de log quando a exceção for capturada
Não recrie a roda:

Utilize o máximo da exceções padrões de que o PHP oferece.

Encontre aqui uma lista com todas as exceções já disponíveis.

Espera, Tem como criar minha própria Exceção?

Sim, e além de ser uma mão na roda, deixa seu código mais elegante.

Imagine uma situação onde é necessário validar se o campo tem nome e sobrenome.

<?php

class NomeSemSobrenomeException extends DomainException
{
    public function __construct($campo, $nome)
    {
        $mensagem = "O campo {$campo} com valor {$nome} não contem nome e sobrenome.";
        parent::__construct($mensagem);
    }
}

Aqui criamos uma classe, e repare que no final do nome da classe existe um "Exception", isso não é necessário, mas pode ser um padrão legal a se seguir.
Essa classe estende a classe DomainException. Eu costumo utilizar essa classe ao invés da Exception por se tratar de uma exceção que compete somente ao meu domínio de aplicação.
Dentro da classe eu reescrevo a função de construção para passar dois parâmetros, e personalizar uma mensagem que é passada ao construtor do seu parente, que no caso é a classe DomainException.

<?php 

/**
 * @throws Exception
 */
function salvaFormulario()
{
    $inputNome = "Felipe";
    $valida = explode(" ", $inputNome);

    if (count($valida) <= 1) {
        throw new NomeSemSobrenomeException("Nome", $inputNome);
    }

    // persiste a informação...
    echo "Salvando...";
}

try {
    salvaFormulario();
} catch (NomeSemSobrenomeException $e) {
    echo $e->getMessage() . PHP_EOL;
}

Agora sempre que eu tenho um formulário que preciso validar se o campo nome tem o nome e sobrenome eu só preciso criar minha validação e se o valor não atender minha condição eu jogo a nova exceção personalizada.

Repare que eu chamo a função salvaFormulario() dentro do bloco try. Se você utilizar um IDE, talvez ela te ajude nesses momentos. Quando você escreve uma função e coloca uma anotação (@throws Exception) acima da sua declaração, sempre que você chamar essa função sua IDE lhe dirá que você precisa utilizar o bloco try para chama-la.

Mas não se limite apenas a isso. Você pode criar uma função dentro da classe de exceção que registra o log, ou que tenta tratar o dados, ou até mesmo da um tipo de solução ao cliente, entre outras.

Por que considero que criar exceções e trata-las é importante?

Erros existem em todos os sistemas, sejam eles simples ou complexos. Mas é importante que esses erros sejam encontrados e corrigidos. Por isso eu listei alguns motivos:

Log de erros

Você pode pensar em alguma maneira melhor de acompanhar os erros que poder analisar e escolher qual o mais critico ou mais ocorrente? Log pode salvar seu sistema.
Manutenibilidade

A facilidade de corrigir um problema quando você sabe exatamente da onde vem esse problema. Isso não tem preço.
Validações

Quando eu pego um código hadouken para dar manutenção, isso me da uma tristeza, mas eu penso: "tudo bem, esse é meu trabalho". Quando você pode escrever exceções separadas, ou utilizar uma exceção especifica que vão fazer com que o fluxo e a logica do seu sistema seja obedecida, isso te eleva um nível de profissionalismo maior.
Pense na sua equipe de suporte

Quando o usuário do sistema passa aquela mensagem: "estou clicando mil vezes no botão de salvar aqui e não acontece nada", ou então: "Tentei fazer o lançamento aqui e apareceu esse erro. Segue em anexo o print do erro". E quando você abre o print tem uma mensagem do tipo: "PHP Fatal error: Uncaught RuntimeException: Index invalid or out of range in...". Bom isso me da muita dor de cabeça.

Boa, agora vou usar isso em tudo!

Vamos com calma meu jovem. Talvez toda essa leitura tenha te trazido ideias de como fazer uma implementação super da hora e tudo mais.

Sim, isso é ótimo e eu te encorajo muito a não acreditar em tudo que eu disse, mas ir testar e experimentar por conta própria.

Mas eu preciso te deixar um pensamento que vem me rodeado a um bom tempo.
Existem milhões de praticas, milhões de ferramentas e tudo mais, e sempre parece que precisamos aprender mais e mais sobre tudo e usar tudo isso que vamos aprendendo. Mas é claro não entenda isso errado, quanto mais você estudar e mais souber, mais preparado para resolver os problemas você estará, então por favor, NUNCA PARA DE ESTUDAR.

Mas a questão é saber resolver o problema de maneira simples. Eu mesmo já cai no erro de querer colocar tudo que aprender nos cursos e livros para resolver um problema simples, mas isso me causou problemas ainda maiores depois quando eu precisei dar manutenção ou modificar algo.
Só tome cuidado para não acabar criando problemas maiores para resolver um problema simples.

Forem: Felipe Dumont De Sa Costa

Object Calisthenics

Object Calisthenics na prática — PHP, Laravel e Vue.js

Os 9 princípios

01 — Um nível de indentação por método

02 — Não use else

03 — Envolva primitivos e strings

04 — Coleções de primeira classe

05 — Um ponto por linha

06 — Não abrevia nomes

07 — Mantenha entidades pequenas

08 — No máximo 2 variáveis de instância

09 — Sem getters e setters

Bônus — Os mesmos princípios no Vue.js

Quando aplicar — e quando não

Porque você deve usar tratamento de exceções em seus projetos PHP.

Para ter mensagens bonitas para o usuário.

O que são Exceções no PHP?

Como então seria o jeito certo de usar?

Espera, Tem como criar minha própria Exceção?

Por que considero que criar exceções e trata-las é importante?

Boa, agora vou usar isso em tudo!

02 — Não use `else`