ARTIGOS

Migrations com Phinx no PHP

Aprenda a usar o Phinx com PHP

-  Fonte [https://phinx.org/](https://phinx.org/)
- Documentação completa [http://docs.phinx.org/en/latest/](http://docs.phinx.org/en/latest/)

O `Phinx` é uma ferramenta de código aberto que funciona na linha de comando e é usado para gerenciar migrações de banco de dados. O seu principal objetivo é tornar trivial a tarefa de gerenciar alterações em um bando de dados. Em menos de 5 minutos você instala e cria sua primeira migração.

---

## Introdução

Ao entrar no mundo do desenvolvimento de sistemas, os profissionais da área logo se deparam com a necessidade de versionar seus projetos, para essa finalidade a ferramenta mais famosa do mundo é o `git`, e quanto ao esquema da base de dados? Como os desenvolvedores versionam seus bancos? Usando ferramentas de migração como o `Phinx`.

**A importância do uso de migrações**

Imaginando um cenário onde um ERP foi desenvolvido e todas as alterações da estrutura do banco de dados foram mantidas através de arquivos de migrações. Se a necessidade de uma troca de banco de dados surgir será possível rodar todas as migrações na ordem que foram criadas e você terá o mesmo banco em outra plataforma.

Se a equipe de desenvolvedores não tivessem as migrações, seria necessário aplicar engenharia reversa na aplicação afim de extrair todos os comandos necessários para a reconstrução da base.

O `Phix`  oferece maneiras para que os desenvolvedores manipulem e alterem o banco de dados facilmente. Para atingir esse objetivo o `Phinx` evita a escrita de comandos `SQL` oferecendo uma poderosa API para criar migrações pelo uso de código-fonte `PHP`.

A API do `Phinx` gera classes que contém todas as manipulações de um sistema, podendo assim integrar as alterações do banco de dados a um versionador de código-fonte. Isso simplifica as migrações entre banco de dados, o `Phinx` fica responsável por saber quais migrações foram ou devem ser executadas tirando essa responsabilidade do desenvolvedor que pode focar todas sua energia para criar programas ainda mais incríveis.

---

## Recursos

Os principais recursos que o `Phinx` oferecem são:

- Escrever migrações de banco de dados usando código-fonte `PHP` independente do tipo do banco de dados.  
- Reverter migrações em ordem decrescente, ou seja `rollback` para um estado específico do bando de dados.
- Migrar no momento de deploy da aplicação.
- Inserir dados iniciais após a criação de um banco de dados.  
- Integração com qualquer aplicativo.

### Suporte a tipos de banco de dados**

Embora o `Phinx` seja uma ferramenta open source é importante saber quais são os tipos de bancos de dados suportados nativamente:

-   MySQL
-   PostgreSQL
-   SQLite
-   Microsoft SQL Server

Se o seu banco de dados não estiver listado acima você pode procurar mais informações na página do git hub da ferramenta ([https://github.com/cakephp/phinx](https://github.com/cakephp/phinx)) ou alterar o código-fonte para atingir os seus objetivos.

## Instalação

O `Phinx` deve ser instalado usando o Composer. Caso você não conheça o Composer, ele é uma ferramenta que gerencia pacotes para `PHP`. Você pode descobrir mais pelo site da ferramenta: https://getcomposer.org/.

### Pré requisitos

- Composer
- PHP 5.4 ou superior

Para instalar o `Phinx` basta executar o seguinte comando em seu terminal, dentro do projeto desejado:

```bash
$ composer require robmorgan/phinx
```

Você deve criar um diretório onde as migrações serão mantidas, note que esse diretório deve ter permissão de escrita. Por padrão a estrutura recomendada pelo `Phinx` é `db/migrations/` você pode usar uma estrutura já existente.

> Caso você optar pode usar uma estrutura diferente da padrão, será necessário alterar o path no arquivo de configuração do `Phinx` mais informações nos próximos capítulos.

Para criar a estrutura padrão execute o seguinte comando dentro da pasta do seu projeto:

```bash
$ mkdir db/migrations -p
```

### Testar a instalação

Para verificar se a instalação foi concluída com sucesso  você pode executar o seguinte comando:

```bash
$ vendor/bing/phinx
```

Se você obter um retorno semelhante significa que sua instalação está completa!

```bash
Phinx by CakePHP - https://phinx.org. 0.11.1

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  breakpoint   Manage breakpoints
  create       Create a new migration
  help         Displays help for a command
  init         Initialize the application for Phinx
  list         Lists commands
  migrate      Migrate the database
  rollback     Rollback the last or to a specific migration
  status       Show migration status
  test         Verify the configuration file
 seed
  seed:create  Create a new database seeder
  seed:run     Run database seeders
```

Pronto agora você tem o `Phinx` instalado em seu projeto.

---

## Primeiros passos e Configuração

Com a instalação concluída iremos inicializar o `Phinx`, durante esse processo um arquivo de configurações será criado com um template de configurações comuns. O arquivo de permissões pode ser criado em 3 diferentes formatos:

- PHP
- json
- yml*

> `*` yml é o formato padrão escolhido pelo `Phinx` você pode alterar essa opção com o parâmetro `-p`

Como a ferramenta em questão gera migrações em código `PHP` nada mais justo que a configuração também seja, o comando de inicialização do `Phinx` é:

```bash
$ vendor/bin/phinx init -f php
```

A inicialização criará um arquivo chamado `phix.php` na raiz do projeto, esse arquivo contém diversas configurações e será usado nos processos da ferramenta.

O arquivo padrão criado pelo `Phix` deve ser assim:

```php
<?php

return
[
    'paths' => [
        'migrations' => '%%PHINX_CONFIG_DIR%%/db/migrations',
        'seeds' => '%%PHINX_CONFIG_DIR%%/db/seeds'
    ],
    'environments' => [
        'default_migration_table' => 'phinxlog',
        'default_database' => 'development',
        'production' => [
            'adapter' => 'mysql',
            'host' => 'localhost',
            'name' => 'production_db',
            'user' => 'root',
            'pass' => '',
            'port' => '3306',
            'charset' => 'utf8',
        ],
        'development' => [
            'adapter' => 'mysql',
            'host' => 'localhost',
            'name' => 'development_db',
            'user' => 'root',
            'pass' => '',
            'port' => '3306',
            'charset' => 'utf8',
        ],
        'testing' => [
            'adapter' => 'mysql',
            'host' => 'localhost',
            'name' => 'testing_db',
            'user' => 'root',
            'pass' => '',
            'port' => '3306',
            'charset' => 'utf8',
        ]
    ],
    'version_order' => 'creation'
];
```

### Entendendo o arquivo de configuração

Se você não conhece a ferramenta pode até se assustar com as configurações iniciais, no entanto basta ler o código gerado para perceber que ele é mais simples do que parecer.

- `paths` → vetor contendo os diretórios onde as migrações ficam, note que além da pasta `migrations` também foi criada o apontamento para `seeds`  que serão explicadas em outro capítulo.

- `environments` → vetor contendo a configuração de todos os ambientes que o seu projeto possa ter, na demonstração são criados três ambientes: produção, desenvolvimento e testes. Se o seu projeto não possuir tantos ou possuir mais ambientes basta que a configuração seja compatível com o seu cenário. 
	- `default_migration_table` → contém o nome da tabela que será criada pelo `Phinx` ela é responsável por controlar quais migrações foram aplicadas e quando. 
	- `default_database` → contém o nome do ambiente padrão esse ambiente será usado quando o argumento de ambiente for omitido em uma execução de comando usando `Phinx`
- `version_order` → Durante um rollback, o `Phinx` executa os comandos de migração de acordo com  esta configuração, que pode assumir 2 valores
	-   `creation`  (padrão): as migrações são ordenadas pelo horário de criação, que também faz parte do nome do arquivo.
	-   `execution`: as migrações são ordenadas pelo momento da execução, também conhecido como horário de início.

> **Atenção**
> `%%PHINX_CONFIG_DIR%%`  é um token especial  que é substituído automaticamente pelo diretório raiz do seu projeto.

### Testando o arquivo de configuração

Depois de configurar o seu `phinx.php` você pode testar suas configurações com o seguinte comando:

```bash
$ vendor/bin/phinx test
```

Um retorno de sucesso deve ser assim:

```bash
Phinx by CakePHP - https://phinx.org. 0.11.1

using config file ./phinx.php
using config parser php
success!
```

---

## Escrevendo a primeira migração

Criar uma migração é muito simples, para criar a sua primeira migração use o comando a seguir em seu projeto:

```bash
$ vendor/bin/phinx create TabelaTeste
```

> O comando `create` criar uma migração e recebe um argumento, ele deve ser informado no padrão `CamelCase` e será usado como nome e identificador da migração.

O retorno para a criação de uma migração é:

```bash
Phinx by CakePHP - https://phinx.org. 0.11.1

using config file ./phinx.php
using config parser php
using migration paths 
 - /var/www/html/changeman/db/migrations
using seed paths 
using migration base class Phinx\Migration\AbstractMigration
using default template
created db/migrations/20191127182940_tabela_teste.php
```

Note que o arquivo criado foi: `20191127182940_tabela_teste.php` no diretório padrão `db/migrations/`, o nome do arquivo conta com um timestamp do momento da criação. Se você abrir o arquivo criado verá um código da seguinte maneira:

```php
<?php

use Phinx\Migration\AbstractMigration;

class TabelaTeste extends AbstractMigration
{
    /**
     * Change Method.
     *
     * Write your reversible migrations using this method.
     *
     * More information on writing migrations is available here:
     * http://docs.phinx.org/en/latest/migrations.html#the-abstractmigration-class
     *
     * The following commands can be used in this method and Phinx will
     * automatically reverse them when rolling back:
     *
     *    createTable
     *    renameTable
     *    addColumn
     *    addCustomColumn
     *    renameColumn
     *    addIndex
     *    addForeignKey
     *
     * Any other destructive changes will result in an error when trying to
     * rollback the migration.
     *
     * Remember to call "create()" or "update()" and NOT "save()" when working
     * with the Table class.
     */
    public function change()
    {

}
}

```

O `Phinx` monta um arquivo pronto para receber as instruções de gerenciamento do banco de dados. Ele cria apenas uma função `change`, ela é responsável por receber os comandos `SQL`, precisamos criar apenas os comandos de alteração o `Phinx` é inteligente o suficiente para identificar qual é o comando oposto para ser executado em um `rollback`. Um exemplo seria, a criação de uma tabela e durante uma operação de `rollback` o `Phinx` sabe como removê-la.

No momento de montar a sua migração você deve usar a sintaxe do `Phinx` e para isso você deverá ler a documentação para se familiarizar com as funcionalidades oferecidas. No exemplo a seguir vemos os comandos necessários para criar uma tabela.

```php
public  function  change()
{
	$users = $this->table('users');
	$users->addColumn('username', 'text')
	      ->addColumn('password', 'string', ['limit' => 40])
	      ->create();
}
```

Esse função irá criar uma tabela com três colunas, note que apenas duas delas estão explicitas. O `Phinx` criar automaticamente uma colunas `id` como chave primária com incremento automático.

## Executar a primeira migração

Para executar migrações você deve executar o seguinte comando:

```bash
$ vendor/bin/phinx migrate
```

Se a migração for executada com sucesso você terá o seguinte retorno:

```bash
Phinx by CakePHP - https://phinx.org. 0.11.1

using config file ./phinx.php
using config parser php
using migration paths 
 - /var/www/html/changeman/db/migrations
using seed paths 
warning no environment specified, defaulting to: development
using adapter sqlite
using database app/database/changeman

== 20191127182940 TabelaTeste: migrating
 == 20191127182940 TabelaTeste: migrated 0.0142s

All Done. Took 0.0196s
```

Pronto, com essa migração executada você acabou de adicionar uma tabela em seu banco de dados!

## Revertendo migrações

O `Phinx` fornece diversas configurações para serem usadas quando o usuário precisa reverter migrações.

#### Reverter a última migração:

```bash
$ vendor/bin/phinx rollback
```

#### Reverter todas as migrações para uma versão específica, é necessário usar o parâmetro `-t` (*target*)

```bash
$ vendor/bin/phinx rollback -t 20191127182940
```

O valor passado no parâmetro `-t` é o valor que o `Phinx` atribui no momento da criação da migração, nesse exemplo o `Phinx` irá reverter todas as modificações posteriores ao valor informado.

#### Reverter todas as migrações

Usar o valor `0` no parâmetro `-t`

```bash
$ vendor/bin/phinx rollback -t 0
```

#### Reverter todas as migrações para uma data específica

É possível informar uma data determinada e reverter todas as migrações executadas posteriormente a data informada, para isso basta usar o argumento `-d` ou `--date`

```bash
$ vendor/bin/phinx rollback -d 2019
$ vendor/bin/phinx rollback -d 201901
$ vendor/bin/phinx rollback -d 20190131
$ vendor/bin/phinx rollback -d 20190103120530
```

### Retorno de um rollback

Ao encontrar migrações para reverter o `Phinx` retornará o seguinte:

```bash
Phinx by CakePHP - https://phinx.org. 0.11.1

using config file ./phinx.php
using config parser php
using migration paths 
 - /var/www/html/changeman/db/migrations
using seed paths 
warning no environment specified, defaulting to: development
using adapter sqlite
using database app/database/changeman
ordering by creation time

== 20191127182940 TabelaTeste: reverting
 == 20191127182940 TabelaTeste: reverted 0.0107s

All Done. Took 0.0164s
```

## Seeds

O `Phinx` oferece aos usuários um sistema de inserção de dados automatizada para testes em bancos de dados. Funciona da mesma maneira que as migrações, no entanto focado em dados. Para criar `seeds` você deve ter o diretório criados, se o caminho padrão no foi alterado, você deve criar `db/seeds/`

```bash
$ mkdir db/seeds/ 
```

Para criar uma `seed` você deve usar o seguinte comando:

```bash
$ vendor/bin/phinx seed:create TesteSeed
```

Você deve ter o seguinte retorno:

```bash
Phinx by CakePHP - https://phinx.org. 0.11.1

using config file ./phinx.php
using config parser php
using migration paths 
 - /var/www/html/changeman/db/migrations
using seed paths 
 - /var/www/html/changeman/db/seeds
using seed base class Phinx\Seed\AbstractSeed
```

O `Phinx` criará automaticamente o arquivo `TesteSeed.php` em `db/seeds/`.

```php
<?php

use Phinx\Seed\AbstractSeed;

class TesteSeed extends AbstractSeed
{
    /**
     * Run Method.
     *
     * Write your database seeder using this method.
     *
     * More information on writing seeders is available here:
     * http://docs.phinx.org/en/latest/seeding.html
     */
    public function run()
    {

}
}
```

### Usando `seeds`

Para inserir dados usando `seeds`  você deve programar o método `run()`, abaixo um exemplo de como popular a tabela teste criada no exemplo anterior:

```php
public function run()
{
    $data = [
        [
            'username' => 'foo',
            'password' => 'password',
        ],[
            'username' => 'bar',
            'password' => 'teste123',
        ]
    ];

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

### Executando `seeds`

Para rodar os `seeds` criados basta executar o seguinte comando:

```bash
$ vendor/bin/phinx seed:run
```

Retorno:

```bash
Phinx by CakePHP - https://phinx.org. 0.11.1

using config file ./phinx.php
using config parser php
using migration paths 
 - /var/www/html/changeman/db/migrations
using seed paths 
 - /var/www/html/changeman/db/seeds
warning no environment specified, defaulting to: development
using adapter sqlite
using database app/database/changeman

== TesteSeed: seeding
 == TesteSeed: seeded 0.0228s

All Done. Took 0.0238s
```

## Integração com Faker

O `Phinx` incentiva o uso da biblioteca `Faker` na própria documentação, e com ela conseguimos gerar dados fictícios para os nossos testes. Mais informações sobre a biblioteca podem ser encontradas no link: [https://github.com/fzaninotto/Faker](https://github.com/fzaninotto/Faker).

Se você tem o `Phinx` rodando você já atende a todos os requisitos do `Faker` basta instalar usando o composer.

```bash
$ composer require fzaninotto/faker
```

Com o `Faker` instalado basta você criar uma novo `seed`.

```bash
$ vendor/bin/phinx seed:create UsersFaker
```

Dentro do método `run()` você usará as gerações de dados do `Faker` conforme o exemplo abaixo, para os tipos de dados não demonstrados visite o repositório do `Faker` para aprofundamentos na ferramenta.

```php
public function run()
{
    $faker = \Faker\Factory::create("pt_BR");
    $users = $this->table("users");
    $data  = [];

for ($i=0; $i < 20; $i++)
    { 
        $data[] = [
            "username" => $faker->name(),
            "password" => $faker->password(),
        ];
    }

$users->insert($data)
          ->save();
}
```

O código-fonte acima irá gerar 20 usuários com nome e senha aleatórios. Para rodar o seed basta usar o comando `seed:run` note que todos as `seeds` serão executados, mesmo que já tenham rodado anteriormente. No entanto você pode especificar qual `seed` será executado.

```bash
# Executar todos os seeds criados
$ vendor/bin/phinx seed:run

# Executar seed específico
$ vendor/bin/phinx seed:run -s UsersFaker
```

ARTIGOS

Migrations com Phinx no PHP

Aprenda a usar o Phinx com PHP

COMENTE SOBRE