DEV Community: Meriéli Manzano

Dê significado aos seus dados: Objetos de Valor na prática

Meriéli Manzano — Thu, 28 May 2026 20:29:58 +0000

Pare de usar string para tudo e comece a expressar suas regras de negócio com clareza e segurança

Você já se pegou repetindo as mesmas validações de CPF, e-mail ou telefone em várias partes do sistema? Sentiu que seus modelos de domínio estão anêmicos, cheios de getters e setters, mas sem comportamento real? Se sim, é hora de conhecer o verdadeiro poder dos Objetos de Valor (Value Objects).

Neste artigo, vamos mergulhar fundo nesse conceito transformador. Você vai entender por que Objetos de Valor garantem consistência, eliminam duplicação e tornam seu código mais expressivo e seguro. Prepare-se para elevar o nível da sua modelagem de domínio!

Imagine um CPF: 123.456.789-00. O que importa é o número em si, não uma identidade única que o acompanhe. Se dois CPFs têm o mesmo número, eles são iguais – não importa se foram instanciados em momentos diferentes ou em lugares distintos. Essa é a alma do Objeto de Valor.

Definição: Um Objeto de Valor é um tipo de classe que representa um conceito abstrato, sem identidade própria (não possui ID). Ele é definido apenas por suas propriedades, encapsulando dentro de si um ou mais valores e suas respectivas regras de negócio.

Características fundamentais:

Imutável: uma vez criado, nunca muda. Para alterar, cria-se uma nova instância.
Comparado por atributos: dois Value Objects são iguais se todos os seus atributos forem iguais.
Auto-validado: ao ser instanciado, já garante que o valor é consistente com as regras do domínio.

Exemplos clássicos:

CPF, CNPJ, CEP, telefone
Endereço (composto por logradouro, número, cidade, CEP)
Email, senha hash, duração de tempo, preço, nome próprio, cor, moeda

Por que priorizar Objetos de Valor?

Muitos desenvolvedores, quando pensam em DDD, correm imediatamente para as Entidades. Mas o próprio Eric Evans traz uma orientação poderosa:

Devemos nos esforçar para modelar utilizando Objetos de Valor, em vez de Entidades, sempre que possível. Mesmo quando um conceito de domínio precisa ser modelado como uma Entidade, o projeto da Entidade deve favorecer o uso de um contêiner de valores, em vez de um contêiner de Entidades filho.

Isso significa que o primeiro local para armazenar nossas regras de negócio é no Objeto de Valor, e por isso uma Entidade precisa compor Objetos de Valor, evitando ter Entidades dentro de Entidades.

Os benefícios do Objeto de Valor são enormes:

Reuso imediato: Um Email ou CPF pode ser usado em qualquer lugar (Usuário, Cliente, Fornecedor) sem repetir regras.
Código mais expressivo: Em vez de string $email, temos Email $email. O tipo já revela a intenção e as restrições.
Testabilidade facilitada: Testar as regras de um Value Object isolado é trivial.
Imutabilidade e segurança: Sem side-effects; objetos podem ser compartilhados sem risco.

Mesmo que seu projeto não adote formalmente o DDD (Domain-Driven Design, uma abordagem que coloca o negócio e seu vocabulário no centro do código), usar objetos de valor vale a pena porque eles eliminam a duplicação de validações e garantem consistência em qualquer arquitetura.

Se até aqui você já aprendeu algo, compartilhe este artigo com quem precisa de mais consistência e menos duplicação.

Sinal de alerta para extrair um Value Object

Quando você perceber várias classes com os mesmos atributos (ex.: string $cpf, string $email, string $telefone), cada uma validando do seu próprio jeito, é um forte indicativo de que esses atributos merecem se tornar Objetos de Valor.

Objetos de Valor vs Entidades: quando usar cada um?

Entidades

Identidade: Possui um ID único que a rastreia ao longo do tempo e o que a distingue de outras entidades.
Mutabilidade: Mutável (seus atributos podem mudar, mas a identidade permanece).
Igualdade: Comparação por identidade (ID)
Exemplos de uso: Pessoa, Pedido, Conta Bancária, Produto

Objetos de Valor

Identidade: Não tem identificador único; é definido por seus atributos ou por seu valor.
Mutabilidade: Imutável.
Igualdade: Comparação estrutural (todos os atributos/valores).
Exemplos de uso: CPF, Email, Endereço, Cor, Dinheiro

Construindo um Value Object na Prática

Vamos implementar um Email, usando uma classe abstrata genérica para reaproveitar o método equals e definir por padrão o $value como readonly.

// Shared/ValueObject.php
namespace Shared;

/**
 * @template TInput
 */
abstract class ValueObject
{
    /**
     * @param  TInput  $value
     */
    public function __construct(public readonly mixed $value) {}

    /**
     * @param  self<TInput>  $other
     */
    public function equals(self $other): bool
    {
        return static::class === $other::class && $this->value === $other->value;
    }

    /**
     * @param  self<TInput>  $other
     */
    public function notEquals(self $other): bool
    {
        return !$this->equals($other);
    }
}

Agora, o Value Object concreto Email:

namespace Domain\Account\User\Domain\ValueObjects;

use Domain\Account\User\Domain\Exceptions\InvalidEmailException;
use Shared\ValueObject;

/**
 * Email value object handles domain validation for emails.
 *
 * @extends ValueObject<string>
 */
final class Email extends ValueObject
{
    public function __construct(string $value)
    {
        $trimmed = mb_strtolower(mb_trim($value));

        if (!filter_var($trimmed, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException("The email '{$value}' is invalid.");
        }

        parent::__construct($trimmed);
    }

    public string $local {
        get => explode('@', $this->value)[0];
    }

    public string $domain {
        get => explode('@', $this->value)[1];
    }
}

Observações importantes:

O construtor já valida e normaliza (minúsculas, trim).
As propriedades $local e $domain são derivadas do valor.
O objeto é readonly – imutável por design.
A comparação equals verifica tanto o tipo quanto o valor.

Cuidado: a lógica de negócio dentro do Value Object deve ser autossuficiente e baseada apenas no valor recebido, e não deve depender de contexto externo (como banco de dados, por exemplo).

Objetos de Valor em uso

Uma Entidade no DDD deve ser um contêiner de valores, não uma colcha de retalhos de tipos primitivos. Veja como fica uma UserEntity:

class UserEntity extends Entity  // Entity pai fornece $id e clone()
{
    private function __construct(
        public readonly Name $name,
        public readonly Email $email,
        public readonly ?HashedPassword $password,
        string $id,
    ) {
        parent::__construct($id);
    }
    // Restante do código: factory methods, comportamentos...
}

Note que $name, $email e $password são Objetos de Valor e cada um carrega suas próprias regras. E a Entidade User não precisa se preocupar com essas validações – elas já foram resolvidas no momento da criação.

Dicas para usar Objetos de Valor

Comece pelos primitivos obcecados: qualquer lugar onde você vê string $cpf, string $cep, string $telefone é candidato a Value Object.
Seja imutável: depois de construído, nada pode mudar. Para alterar, crie um novo objeto.
Valide no construtor: lance exceções específicas do domínio se os dados forem inválidos. Assim, um objeto de valor sempre representa um estado consistente.
Implemente equals corretamente: compare o valor na classe e todos os atributos relevantes.

Ao adotar Value Objects, você:

Elimina duplicação de validações.
Torna o código autodocumentado.
Previne estados inválidos.
Facilita a evolução do domínio.

Desafio: Liste 3 atributos do seu sistema atual que são primitivos mas deveriam ser Value Objects e deixe aqui nos comentários. Exemplo: placaVeiculo, numCartaoCredito, intervaloData.

Objetos de Valor não são exclusivos para quem adota o DDD – são uma ferramenta prática para acabar com a bagunça dos tipos primitivos e validações repetidas. Eles transformam regras de negócio escondidas em código limpo, seguro e reutilizável.

Então lembre-se: todo CPF, e-mail ou telefone no seu sistema é um valor que merece respeito. Trate-os como objetos – e eles tratarão bem o seu domínio.

Agora vá, identifique um atributo extraia seu primeiro Value Object, e sinta a diferença na consistência. Seu eu do futuro vai agradecer.

Gostou? Então não perca os próximos. Me siga e receba mais artigos sobre código de qualidade e arquitetura de software de verdade.

🔔 Compartilhe com quem ainda valida CPF com if solto no código.

Vamos juntos construir softwares mais expressivos e robustos! Até a próxima, galerinha.

Facades no Laravel entregam velocidade, mas cobram o preço em acoplamento

Meriéli Manzano — Thu, 14 May 2026 15:15:00 +0000

As Facades do Laravel são algo que o framework disponibiliza e que vejo muitos projetos usando em controllers, services, entities e até mesmo em repositories. Eu pessoalmente já usei e ainda uso Facade, a produtividade inicial é maravilhosa, o código fica enxuto e você entrega valor rápido porque não precisa instanciar, é só usar a Facade direto, é lindo.

Só que tenho refletido sobre uma coisa que não aparece no curto prazo, especialmente quando a aplicação cresce e a manutenção se estende por anos.

Pense num cenário real:

Você tem uma classe de serviço que usa várias outras Facades internas. Funciona perfeitamente bem, até o dia que você precisar reaproveitar aquela lógica num script isolado fora do Laravel. Ou testar aquela classe sem o framework inteiro carregado.

Aí você percebe: a classe não diz o que ela precisa. Você só descobre abrindo o código linha por linha. E cada facade é um fio invisível conectado ao Laravel.

Não é que Facade seja errada. É que elas resolvem um problema (velocidade) e criam outro silencioso (acoplamento implícito). Cada time escolhe seu trade-off. Esse acoplamento forte com o framework vai justamente contra as regras de dependência da Clean Architecture.

Para entender por que, precisamos saber que Facades do Laravel funcionam como “proxies estáticos” que fornecem acesso a objetos registrados no service container. São uma “ponte” entre uma chamada de método estático e a instância real de um objeto, resolvido em tempo de execução pelo container de injeção de dependência do Laravel.

Abaixo separei algumas vantagens e desvantagens que vai te ajudar a decidir quando realmente devemos usá-las.

Vantagens:

Código mais rápido de escrever e mais fácil de ler, acelerando drasticamente o desenvolvimento e a prototipagem.
Facilidade para testar usando shouldReceive() e Fakes para garantir que a lógica real não seja acionada, diferente de métodos estáticos tradicionais. “Obs: Mas já que a IA está criando testes com maestria, será que isso faz realmente a diferença?”
Tem comportamento Singleton, sendo resolvida uma única vez por requisição.
Pode ser usada em qualquer lugar, sem a necessidade de passar dependência manualmente pelo construtor.

Desvantagens:

Acoplamento que não quebra a testabilidade, mas suja as dependências “ou seja, não é declarada a dependência, ela fica implícita e só é descoberta olhando o corpo dos métodos”. O que dificulta manutenção e reuso.
Viola a Inversão de Dependência, a classe depende diretamente de uma implementação concreta ou de uma interface resolvida pela Facade, não de uma abstração definida pelo domínio, injetada de fora.
Lógica acoplada ao Framework, porque Facades só funcionam com o Facade Root inicializado. Se um dia pretender reutilizar aquela classe em um script isolado, pacote PHP puro ou outro framework, precisará reescrever tudo.
Por serem muito convenientes, facilitam a violação silenciosa do SRP: desenvolvedores adicionam novas responsabilidades indiretas sem que o construtor da classe sinalize o inchaço.

Deixo mais dois pontos de atenção que não são necessariamente desvantagens, mas devem ser conhecidos:

Embora sejam testáveis, os mocks são aplicados globalmente – afetam todas as chamadas à facade durante o teste, não apenas uma instância específica. Sem uma limpeza explícita (como clearResolvedInstances() no tearDown), pode haver vazamento de comportamento entre testes. É um ponto de atenção, mas contornável.
A facade não é mais rápida que a injeção direta. Cada chamada paga o custo do __callStatic() e da resolução da chave no container – é tecnicamente mais lenta, mas na prática você nunca vai medir essa diferença.

Facades são ótimas em Controllers, Commands, Jobs (camadas mais próximas da infra). E podem até ser usadas em protótipos e MVPs, são uma excelente escolha para garantir velocidade de entrega.

Já nas camadas de domínio, serviços de aplicação, objetos de valor, entidades... faz mais sentido injetar uma interface no construtor para desacoplar sua lógica de negócio.

Tá tudo bem usar Facades. Esse post não é uma regra. É só uma lente que eu peguei dos meus estudos e que, de vez em quando, me faz perguntar: “será que aqui vale a pena declarar a dependência?”

Fico curiosa pra saber como vocês lidam com isso. Já sentiu alguma dificuldade prática com Facades para testar, evoluir ou reaproveitar lógica? Ou acham que eliminar Facades do Laravel da camada de negócio é uma sofisticação desnecessária?

Produtividade com Testes e Vue usando VSCode

Meriéli Manzano — Mon, 26 Sep 2022 14:18:02 +0000

Criar testes bem organizados, separados e com uma boa descrição no Jest ou inserir toda estrutura inicial padrão de um componente Vue, pode ser verboso. Mas configurando o VS Code é possível inserir automaticamente toda pré-estrutura com a escrita de apenas uma palavra.

Desenvolvendo com o Visual Studio Code você pode turbinar sua produtividade de uma forma muito simples com Snippets!

Como funciona?

Os snippets salvos no seu VS Code geram códigos pré-definidos ao digitar uma determinada palavra escolhida na sua configuração.

Como criar um snippet

Com o VS Code aberto vá em File -> Preferences -> Configure User Snippets

Na paleta de comandos aberta digite a linguagem para qual deseja exibir o snippet, no caso de testes Jest digite typescript se for sua linguagem utilizada.

Será aberto um arquivo typescript.json com instruções para criar seu snippet.

Cada snippet tem a seguinte estrutura:

"Nome do Snippet": {
        "prefix": // Palavra que chama o snippet,
        "body": [
            // Corpo com o código a ser gerado         
        ],
        "description": // Descrição com detalhes do código
},

Ao escrever o body, em linhas que houver indentação use \t para aplicar a tabulação necessária. Cada \t representa um Tab.

Para indicar as pausas do Tab para digitação de texto pelo código use $1, substituindo o número pela ordem de inserção desejada em cada trecho.

Também é possível indicar o tipo de conteúdo a ser inserido em cada pausa com ${1:conteudo} dando uma ideia do que escrever. E para definir um texto igual a ser usado em várias partes do código use o mesmo número de ID em todas partes que o texto for repetir.

Abaixo montei um snippet completo para Jest usando BDD que você pode aproveitar nos seus códigos ou adaptar como preferir:

O snippet de Vue é para uso com composition Api usando Typescript e Sass scoped, mas você pode adaptar como preferir:

O artigo é para produtividade com Testes e Vue, mas também é possível criar snippets para outras linguagens.

Espero ter ajudado! 😊