CakePHP Migrations

CakePHP Migrations: Se você já passou pela experiência frustrante de atualizar um site e ele “quebrar” porque você esqueceu de criar uma coluna no banco de dados de produção, este artigo foi escrito para você. Como especialista em CakePHP, posso afirmar: o uso de Migrations é o que separa um programador amador de um engenheiro de software profissional.

Neste sexto capítulo da nossa trilha, vamos aprender a tratar o seu banco de dados como se fosse código. Chega de exportar arquivos .sql ou enviar prints de tabelas para seus colegas. Vamos dominar o controle de versão do banco de dados com Migrations na Prática.

Migrations na Prática: Controlando a versão do seu banco de dados no CakePHP

CakePHP Migrations: Imagine que você está trabalhando em uma equipe. Você cria a tabela de “Comentários”, adiciona três colunas e segue desenvolvendo. Quando seu colega baixa o código pelo Git, o sistema dele para de funcionar. Por quê? Porque o código espera uma tabela que não existe no banco de dados dele.

No passado, resolveríamos isso enviando um dump do banco ou um script SQL via chat. Hoje, usamos Migrations. No CakePHP, isso é feito através do plugin Migrations (baseado no Phinx), que permite que você descreva as alterações no banco de dados usando PHP puro.

1. O que são Migrations e por que usá-las?

Migrations são como um “Git para o seu banco de dados”. Elas permitem que você crie, altere e remova tabelas e colunas de forma incremental e reversível.

As vantagens são claras:

• Histórico: Você sabe exatamente quando e por que uma coluna foi adicionada.
• Sincronização: Toda a equipe (e o servidor de produção) terá exatamente a mesma estrutura de banco.
• Segurança: Se algo der errado, você pode dar um “rollback” e voltar o banco ao estado anterior em segundos.
• Independência de Banco: Você escreve em PHP, e o CakePHP traduz para o SQL do MySQL, PostgreSQL ou SQL Server.

2. Instalando e Configurando o Plugin

Embora o esqueleto padrão do CakePHP já traga o plugin de Migrations, é sempre bom garantir que ele está carregado no seu arquivo src/Application.php.

Para verificar se você tem a CLI pronta, rode:

Bash

bin/cake migrations --help

Se o comando retornar uma lista de opções, seu “forno” está pronto para processar as migrações.

3. Criando sua Primeira Migration

Vamos supor que precisamos criar a tabela artigos que mencionamos nos artigos anteriores. Em vez de abrir o phpMyAdmin, vamos usar o terminal.

O Comando de Geração

Execute:

Bash

bin/cake bake migration CreateArtigos titulo:string corpo:text publicado:boolean created modified

O CakePHP é inteligente: ao usar o prefixo Create, ele já entende que você quer criar uma nova tabela. Ele gerará um arquivo dentro de config/Migrations/ com um nome parecido com 20260405120000_CreateArtigos.php.

Anatomia do Arquivo de Migration

Abra o arquivo gerado. Você verá algo assim:

PHP

use Migrations\AbstractMigration;

class CreateArtigos extends AbstractMigration
{
    public function change(): void
    {
        $table = $this->table('artigos');
        $table->addColumn('titulo', 'string', ['limit' => 150, 'null' => false])
              ->addColumn('corpo', 'text', ['null' => true])
              ->addColumn('publicado', 'boolean', ['default' => false])
              ->addColumn('created', 'datetime')
              ->addColumn('modified', 'datetime')
              ->create();
    }
}

Perceba que não há SQL aqui. É uma linguagem fluída e fácil de ler. O método change() é mágico: ele sabe como criar a tabela e, se você pedir um rollback, ele sabe como deletá-la automaticamente.

4. Executando as Migrações (Migrate)

Criar o arquivo não altera o banco de dados ainda. Para aplicar as mudanças, você precisa rodar o comando:

Bash

bin/cake migrations migrate

O CakePHP criará a tabela artigos e também uma tabela auxiliar chamada phinxlog, onde ele anota quais migrações já foram executadas para nunca repetir o mesmo processo.

5. Alterando Tabelas Existentes

E se, daqui a um mês, você decidir que os artigos precisam de uma coluna autor_id? Você nunca deve editar a migration original que já foi executada. Em vez disso, crie uma nova:

Bash

bin/cake bake migration AddAutorIdToArtigos autor_id:integer

O arquivo gerado usará o método update() na tabela artigos para adicionar o novo campo. Simples e seguro.

6. O Poder do Rollback: Voltando no Tempo

Cometeu um erro? A nova coluna quebrou o sistema? Não entre em pânico.

Rode:

Bash

bin/cake migrations rollback

O CakePHP desfará a última migração executada, removendo a coluna ou tabela que você acabou de criar e devolvendo o banco ao estado estável anterior.

7. Seeds: Alimentando o Banco de Dados

Além da estrutura (DDL), muitas vezes precisamos de dados iniciais (DML), como um usuário administrador padrão ou uma lista de categorias. Para isso, usamos os Seeds.

Crie um Seed:

Bash

bin/cake bake seed CategoriasSeed

No arquivo config/Seeds/CategoriasSeed.php, você define os dados:

PHP

public function run(): void
{
    $data = [
        ['nome' => 'Desenvolvimento Web', 'slug' => 'web-dev'],
        ['nome' => 'Infraestrutura', 'slug' => 'infra'],
    ];

    $table = $this->table('categorias');
    $table->insert($data)->save();
}

Para executar e popular seu banco:

Bash

bin/cake migrations seed

8. Boas Práticas de Migrations no CakePHP

Para manter seus projetos saudáveis, siga estas regras:

1. Migrations são Imutáveis: Uma vez que uma migration foi para o servidor de produção, jamais a edite. Se precisar mudar algo, crie uma nova migration.
2. Nomes Descritivos: Use nomes como AddPrecoToProdutos ou RenameDescricaoToResumo.
3. Check-in no Git: Os arquivos de migration devem obrigatoriamente subir para o seu repositório Git.
4. Cuidado com Dados Existentes: Ao adicionar uma coluna NOT NULL em uma tabela que já tem dados, lembre-se de definir um valor default para não dar erro na execução.

Conclusão: A Paz de Espírito de um Banco Versionado

Dominar as Migrations no CakePHP transforma a forma como você encara o deploy. Aquele medo de “esqueci de rodar o SQL no servidor” desaparece. Agora, seu processo de atualização se resume a dois comandos: git pull e bin/cake migrations migrate.

Com o banco de dados versionado e organizado, você está pronto para o próximo passo técnico: configurar a conexão real do seu código com esse banco. No próximo artigo, veremos: “Conectando ao Banco: Configurando o app_local.php.”

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.

Se você já usava migrations em outros frameworks (como Laravel ou Django), vai se sentir em casa. Se nunca usou, parabéns: você acaba de dar o passo mais importante para a automação profissional dos seus projetos.