Manipulação de dados no CakePHP

Manipulação de dados no CakePHP: Se você já usou o comando Bake que vimos no artigo anterior, deve ter notado que o CakePHP criou dois arquivos diferentes dentro da pasta src/Model/: um dentro de Table e outro dentro de Entity. Para quem vem de outros frameworks ou do PHP estruturado, essa divisão pode causar uma certa confusão inicial. Afinal, por que dois arquivos para representar “o banco de dados”?

Como especialista em CakePHP, preparei este nono artigo para desmistificar o coração do ORM (Object-Relational Mapping). Vamos entender a diferença vital entre Table Objects e Entities e como essa separação eleva a organização do seu código a um nível profissional.

Table Objects vs Entities: Entendendo a manipulação de dados no CakePHP

No CakePHP, a camada de Model não é uma classe única e gigante. Ela é dividida para respeitar o princípio da responsabilidade única. Enquanto o Table Object cuida da “coleção” de dados (a tabela como um todo), a Entity cuida do “item” individual (uma linha específica daquela tabela).

Entender essa dualidade é a chave para manipular dados com elegância, criar validações poderosas e manter a lógica de negócio no lugar certo.

1. O que é um Table Object? (A Visão da Tabela)

Imagine o Table Object como o guardião da tabela do banco de dados. Ele é o responsável por tudo o que envolve o conjunto de dados e as regras de como esses dados entram e saem do banco.

Localizado em src/Model/Table/, o Table Object é onde você define:

• Configurações de Schema: Qual o nome da tabela e qual a chave primária.
• Associações: Como esta tabela se relaciona com outras (HasMany, BelongsTo).
• Validações: Regras de integridade (ex: “o campo e-mail é obrigatório”).
• Behaviors: Comportamentos reutilizáveis (ex: “Timestamp” para datas automáticas).
• Finders Customizados: Consultas personalizadas (ex: find('publicados')).

Exemplo de Table Object (ArtigosTable.php)

PHP

namespace App\Model\Table;

use Cake\ORM\Table;
use Cake\Validation\Validator;

class ArtigosTable extends Table 
{
    public function initialize(array $config): void
    {
        parent::initialize($config);
        
        $this->setTable('artigos');
        $this->setDisplayField('titulo');
        $this->setPrimaryKey('id');

        $this->addBehavior('Timestamp');

        // Relacionamento: Um artigo pertence a uma categoria
        $this->belongsTo('Categorias', [
            'foreignKey' => 'categoria_id',
        ]);
    }

    public function validationDefault(Validator $validator): Validator
    {
        $validator
            ->scalar('titulo')
            ->minLength('titulo', 10, 'O título é muito curto')
            ->notEmptyString('titulo', 'Ei, esqueceu o título!');

        return $validator;
    }
}

2. O que é uma Entity? (A Visão do Registro)

Se o Table Object é o “gerente da biblioteca”, a Entity é o “livro individual”. A Entity representa uma única linha do seu banco de dados transformada em um objeto PHP vivo.

Localizada em src/Model/Entity/, a Entity é o lugar perfeito para:

• Acessores e Mutadores: Criar propriedades virtuais ou formatar dados na hora de exibir.
• Lógica de Objeto Único: Verificar se um usuário específico tem permissão para algo.
• Tratamento de Dados Sensíveis: Esconder campos como “senha” ao converter para JSON.

Exemplo de Entity (Artigo.php)

PHP

namespace App\Model\Entity;

use Cake\ORM\Entity;

class Artigo extends Entity
{
    // Define quais campos podem ser preenchidos em massa (Mass Assignment)
    protected array $_accessible = [
        'titulo' => true,
        'corpo' => true,
        'categoria_id' => true,
        'created' => true,
        'modified' => true,
        'id' => false, // Segurança: ID não pode ser alterado via formulário
    ];

    // Propriedade Virtual: Gera um slug ou título formatado automaticamente
    protected function _getTituloFormatado(): string
    {
        return strtoupper($this->titulo);
    }
}

3. Na Prática: Onde eu coloco minha lógica?

Esta é a dúvida campeã de 10 entre 10 desenvolvedores iniciantes. Vamos usar uma regra simples:

Coloque no Table Object se:

• Você precisa buscar dados (find, get).
• Você precisa salvar ou deletar dados.
• Você quer validar se o e-mail é único no banco de dados.
• Você quer aplicar uma regra que afeta todas as inserções daquela tabela.

Coloque na Entity se:

• Você quer criar uma propriedade “nome_completo” juntando “nome” + “sobrenome”.
• Você quer formatar uma data para o padrão brasileiro d/m/Y sempre que ela for exibida.
• Você quer uma função isPublicado() que retorna true/false baseado no status do registro.

4. Manipulando Dados: O Fluxo de Trabalho

Quando você usa o CakePHP para salvar algo, o processo envolve as duas partes:

1. O Controller recebe os dados do formulário.
2. O Table Object transforma esses dados brutos em uma Entity (patchEntity).
3. Durante essa transformação, as Validações do Table Object são executadas.
4. Se tudo estiver OK, o Table Object persiste a Entity no banco de dados.

PHP

// No Controller
$artigo = $this->Artigos->newEmptyEntity(); // Cria uma Entity vazia
$artigo = $this->Artigos->patchEntity($artigo, $this->request->getData()); // Transforma dados em Entity

if ($this->Artigos->save($artigo)) {
    // Aqui o $artigo agora tem o 'id' preenchido pelo banco!
}

5. Propriedades Virtuais e Acessores: A Mágica da Entity

Imagine que no seu blog você tem um campo corpo que é muito longo. Você quer mostrar um resumo de 100 caracteres na home. Em vez de fazer isso no HTML (View), você cria na Entity.

PHP

// src/Model/Entity/Artigo.php
protected function _getResumo(): string
{
    return mb_substr(strip_tags($this->corpo), 0, 100) . '...';
}

No seu template, basta chamar: <?= $artigo->resumo ?>. Note que você não chama a função, mas sim o nome da propriedade sem o _get. O CakePHP faz o mapeamento automático!

6. Validação vs Regras de Aplicação (Application Rules)

O CakePHP separa validação de integridade de regras de negócio.

• Validator: Verifica o formato (é um e-mail? tem 10 caracteres?). Roda antes dos dados virarem uma Entity.
• BuildRules: Verifica o contexto (este e-mail já existe? este autor_id é válido?). Roda na hora do save.

Ambas ficam no Table Object, garantindo que o seu banco de dados nunca receba lixo.

Conclusão: Organização que Gera Escalabilidade

Manipulação de dados no CakePHP: A separação entre Table Objects e Entities é o que permite que o seu projeto cresça sem se tornar um caos. Ao entender que o Table cuida do “onde e como” e a Entity cuida do “o quê”, você cria um código limpo, testável e fácil de manter.

Para um blog com centenas de artigos, essa estrutura garante que as formatações de texto e as regras de publicação estejam centralizadas. Se você precisar mudar a regra de resumo amanhã, muda em um único arquivo (a Entity) e todo o site se atualiza.

Agora que você domina a manipulação de dados, é hora de aprender a conectar essas peças de forma mais complexa. No próximo artigo, veremos: “Associações (HasMany, BelongsTo): Relacionando tabelas como um profissional.”

Mas antes de dominar o CakePHP, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no CakePHP, você precisará dominar as seguintes tecnologias:

E se você gosta do nosso conteúdo, não deixe de contribuir adquirindo os serviços e produtos dos nossos apoiadores e empresas que somos associados.

Dica de Ouro: Sempre que o Bake gerar seus arquivos, abra a Entity e configure corretamente o array $_accessible. Isso previne ataques de Mass Assignment, garantindo que usuários mal-intencionados não alterem campos como “permissao_admin” através de formulários comuns.