Introdução
Olá pessoal!
Estou mas uma vez aqui para contribuir com o crescimento da comunidade PHP-MS. E hoje vamos mais a no fundo Doctrine.
Para quem teve a oportunidade de ver a apresentação passada, onde falei sobre "Utilizando Zend Framework e Doctrine ORM", já deve ter se interessado pelo Doctrine CLI quando viu a geração de SQL via linha de comando. Mas o Doctrine CLI não possibilita apenas isso, há muitos outros comando que lhe auxiliam na criação de banco, tabelas e modelos.
Pois é! Hoje vamos mais a fundo nisso.
Mãos a obra...
Baixando arquivos
Página de download: http://www.doctrine-project.org/download
Há dois arquivos:
- Doctrine-1.0.*.tgz
- Código fonte
- Exemplos
- Doctrine-1.0.*-Sandbox.tgz
- Código fonte
- Arquitetura de diretorios
- Doctrine CLI
O que vamos utilizar será o "Sandbox". Ele já vem pronto para uma começar a programar e com um conjunto de directórios muito bem estruturado.
Depois de baixado é só descompactar em um directório do seu "htdocs". A estrutura ficará da seguinte forma:
drwxr-xr-x 7 raphael raphael 4096 2008-12-06 11:29 .
drwxr-xr-x 9 raphael raphael 4096 2008-12-04 20:25 ..
-rw-r--r-- 1 raphael raphael 2376 2008-12-06 10:38 config.php
drwxr-xr-x 4 raphael raphael 4096 2008-12-06 10:37 data
-rwxr-xr-x 1 raphael raphael 75 2008-11-25 20:07 doctrine
-rw-r--r-- 1 raphael raphael 522 2008-11-25 20:07 doctrine.php
-rw-r--r-- 1 raphael raphael 66 2008-11-25 20:07 index.php
drwxr-xr-x 3 raphael raphael 4096 2008-12-06 11:51 lib
drwxr-xr-x 2 raphael raphael 4096 2008-12-06 11:49 migrations
drwxr-xr-x 3 raphael raphael 4096 2008-12-06 10:41 models
drwxr-xr-x 2 raphael raphael 4096 2008-12-06 10:40 schema
Configurando banco de dados:
O Doctrine e seu CLI não fazem distinção e apenas tem suporte aos seguintes bancos:
- FreeTDS / Microsoft SQL Server / Sybase
- Firebird/Interbase 6
- Informix
- Mysql
- Oracle
- Odbc
- PostgreSQL
- Sqlite
Com isso podemos apenas alterar o DSN da configuração e caso não haja tipos de tabelas, colunas ou SQL especifico de cada SGBD, não será necessário mais nada para migração entre outros SGBD. É interessante também pesquisar sobre o DQL (Doctrine Query Language) que auxilia nessa abstração entre SGBD.
Na linha 45 do arquivo config.php vc vai encontra o seguinte código:
define('DSN', 'sqlite:///' . DB_PATH);
O padrão do Sandbox é utilizar o SqlLite, mas proponho utilizar MySQL. Então é só alterar a linha 45 para:
define('DSN', 'mysql://usuario:senha@localhost/nome_do_banco');
Com isso não é necessário criar a base de dados. Será possível caso o usuário utilizado tenha permissão, criar a base direto pro linha de comando.
Comandos e help
Será listado a seguir os comandos possíveis via linha de comando oferecido pelo Doctrine CLI e logo abaixo será explicado de forma mais clara.
Comandos
./doctrine
Doctrine Command Line Interface
./doctrine generate-migrations-models
./doctrine compile
./doctrine generate-sql
./doctrine generate-migrations-db
./doctrine build-all-load
./doctrine load-data
./doctrine drop-db
./doctrine generate-yaml-db
./doctrine generate-models-yaml
./doctrine generate-yaml-models
./doctrine dump-data
./doctrine build-all-reload
./doctrine create-tables
./doctrine dql
./doctrine rebuild-db
./doctrine migrate
./doctrine create-db
./doctrine build-all
./doctrine generate-migration
Help
Veja Anexo 01
Para que servem?
Atenção!Todos os comandos estão relacionados ao banco de dados e usuário inseridos no DSN alterado no arquivo "config.php".
Em minha singela opinião recomendo a utilização de arquivos Schema (Veja um exemplo) e arquivo de Fixtures (Veja um exemplo).
SQL e data base
./doctrine create-db
create-db - Successfully created database for connection "sandbox" named
"doctrine_app"
Cria um banco de dados com o nome passado ao arquivo "config.php".
./doctrine drop-db
drop-db - Are you sure you wish to drop your databases? (y/n) y
drop-db - Successfully dropped database for connection "sandbox" named
"doctrine_app"
Remove o banco de dados
Caso não exista a base será informado uma mensagem avisando.
./doctrine rebuild-db
rebuild-db - Are you sure you wish to drop your databases? (y/n) y
rebuild-db - Successfully dropped database for connection "sandbox" named
"doctrine_app"
rebuild-db - Generated models successfully from YAML schema
rebuild-db - Successfully created database for connection "sandbox" named
"doctrine_app"
rebuild-db - Created tables successfully
Se você responder que sim ("y") o sistema removerá seu banco, criará um novo e irá inserir novamente as tabelas.
Caso não exista a base será informado uma mensagem avisando.
./doctrine create-tables
create-tables - Created tables successfully
Insere as tabelas mapeados dos modelos na base de dados
Caso não existam modelos o comando não será executado, pois a geração de SQL é feita através do modelo e não do "schema.yml".
./doctrine generate-sql
generate-sql - Generated SQL successfully for models
Caso não existam modelos o comando não será executado, pois a geração de SQL é feita através do modelo e não do "schema.yml".
Gera um arquivo sql no diretório "./data/sql/". Esse comando não é de muita ajuda, pois é possível gerar suas tabelas sem executá-lo. Mas pode ser utilizado para analisar possíveis erros no seu "schema.yml".
Modelos
./doctrine generate-models-yaml
generate-models-yaml - Generated models successfully from YAML schema
Gera os arquivos de modelo baseado no arquivo "./schema/schema.yml".
./doctrine generate-yaml-db
generate-yaml-db - Generate YAML schema successfully from database
Gera o "schema.yml" baseado nas tabelas do banco de dados.
Auxilia também para ver o jeito certo de se escrever schemas.
./doctrine generate-yaml-models
generate-yaml-models - Generated YAML schema successfully from models
Gera o "schema.yml" baseado nos modelos. Isso porque além do "schema.yml" é possível gerar seus modelos definindo nas classes a estrutura de suas respectivas tabelas.
./doctrine generate-models-db
Gera os modelos baseado no banco
Ainda tem esse, mas também não faz muito sentido já que você pode gerar primeiramente o Schema baseado no banco e depois gerar os modelos.
Fixtures
Fixtures armazenam registros de tabelas para que através do comando "load-data" você possa carregar informações de testes ou defaults. Veja um exemplo de arquivo de fixtures.
./doctrine load-data
load-data - Data was successfully loaded
Insere valores em sua tabela dados os arquivos .yml encontrados no diretorio "./data/fixtures".
./doctrine dump-data
dump-data - Dumped data successfully to: /var/www/doctrine_app_2/data/fixtures
Varre todo o banco de dados e gera um arquivo de fixtures chamado "data.yml". Esse arquivo irá armazenar todos os registros que estiverem inseridos no banco atualmente. É interessante ser utilizado para gerar informaçẽoes detes.
Migrates
./doctrine generate-migrations-models
generate-migrations-models - Generated migration classes successfully
from models
Gera arquivos de migrates um pra cada modelo mais outro para definição de foreing keys. Baseandosse nos arquivos de modelos.
./doctrine generate-migrations-db
generate-migrations-db - Generated migration classes successfully
from database
Gera arquivos de migrates um pra cada modelo mais outro para definição de foreing keys. Baseandosse nas tabelas do banco de dados.
./doctrine generate-migration Novo
generate-migration - Generated migration class:
Novo successfully to /var/www/doctrine_app_2/migrations
Serve para você criar uma nova atualização no banco de dados sem independencia de alterações em modelos ou Schema.
./doctrine migrate 1
migrate - migrated successfully to version #1
./doctrine migrate 2
migrate - migrated successfully to version #2
./doctrine migrate 3
migrate - migrated successfully to version #3
Na versão do Doctrine 1.1 (Até hoje me alpha) há possibilidade de gerar migrations baseada nas diferenças entre o schema e os modelos.
Atenção: Se você não utilizar migrates para gerar seu banco e gerar suas tabelas através de outros script diferentes do migrate, não será possível ao sistema identificar qual versão de migrate o banco esta e poderá haver conflitos de versionamento.
Rápidos
./doctrine build-all
build-all - Generated models successfully from YAML schema
build-all - Successfully created database for connection "sandbox"
named "doctrine_app"
build-all - Created tables successfully
Com esse comando você irá gerar modelos, criar base e inserir as tabelas no banco.
./doctrine build-all-load
build-all-load - Generated models successfully from YAML schema
build-all-load - Successfully created database for connection
"sandbox" named "doctrine_app"
build-all-load - Created tables successfully
build-all-load - Data was successfully loaded
Com esse comando você irá gerar modelos, criar base, inserir as tabelas no banco e inserir os dados de suas fixtures em suas tabelas.
./doctrine build-all-reload
build-all-reload - Are you sure you wish to drop your databases? (y/n) y
build-all-reload - Successfully dropped database for connection
"sandbox" named "doctrine_app"
build-all-reload - Generated models successfully from YAML schema
build-all-reload - Successfully created database for connection
"sandbox" named "doctrine_app"
build-all-reload - Created tables successfully
build-all-reload - Data was successfully loaded
Com esse comando você irá remover o banco de dados, gerar modelos, criar base, inserir as tabelas no banco e inserir os dados de suas fixtures em suas tabelas.
Outros
./doctrine dql "FROM Usuario"
dql - executing: "FROM Usuario" ()
./doctrine dql "FROM Usuario WHERE id = 1"
dql - executing: "FROM Usuario WHERE id = 1" ()
Serve para executar comando de consulta no padrão DQL (Doctrine Query Language).
./doctrine compile compile - Compiled Doctrine successfully to:
/var/www/doctrine_app_2/lib/Doctrine.compiled.php
Com esse comando você unirá em um único arquivo toda a biblióteca do Doctrine. Isso vai compactar todo o código do Doctrine e devido a se localizar em um único arquivo haverá menos includes de arquivos e melhorá sua performance.
Observação: Demora um pouco a executar.
Exemplo de uma rotina padrão de desenvolvimento
- Configurar banco de dados (Ver)
- Criar arquivo de schema com a estrutura de seus modelos (Veja um exemplo). Inisira um novo arquivo chamado "schema.yml" no diretório "./schema/schema.yml".
- Gerar modelos
- ./doctrine generate-models-yaml
- Gerar migrations baseadas nos modelos
- ./doctrine generate-migrations-models
- Criar banco de dados
- ./doctrine create-db
- Inserir migrations
- ./doctrine migrate
Com isso feito é só começar a criar seu sistema, pois todo o banco e seus modelos já estão prontos pra consulta, inserção, remoção e atualização.
Schema YAML
Exemplo
---
Usuario:
columns:
nome: string(255)
email: string(255)
Grupo:
columns:
nome: string(255)
Fixtures
Exemplo
---
Usuario:
Usuario_1:
nome: raphael
email: raphox.araujo@gmail.com
Usuario_2:
nome: phpms
email: phpms@phpms.org
Grupo:
um:
nome: Administrador
dois:
nome: Visitante
Anexo 01
./doctrine help
Doctrine Command Line Interface
./doctrine generate-migrations-models - Generate migration classes for an existing
set of models
Arguments:
migrations_path - /var/www/doctrine_app_2/migrations
models_path - /var/www/doctrine_app_2/models
./doctrine compile - Compile doctrine classes in to one single php file
Arguments:
drivers - Specify list of drivers you wish to compile. Ex: mysql|mssql|sqlite
compiled_path - The path where you want to write the compiled doctrine libs.
./doctrine generate-sql - Generate sql for all existing database connections.
Arguments:
models_path - /var/www/doctrine_app_2/models
sql_path - /var/www/doctrine_app_2/data/sql
./doctrine generate-migrations-db - Generate migration classes for an existing database
Arguments:
migrations_path - /var/www/doctrine_app_2/migrations
./doctrine build-all-load - Calls build-all, and load-data
Arguments:
yaml_schema_path - /var/www/doctrine_app_2/schema
models_path - /var/www/doctrine_app_2/models
data_fixtures_path - /var/www/doctrine_app_2/data/fixtures
generate_models_options - Array of options for generating models
./doctrine load-data - Load data from a yaml data fixture file.
Arguments:
data_fixtures_path - /var/www/doctrine_app_2/data/fixtures
models_path - /var/www/doctrine_app_2/models
./doctrine drop-db - Drop database for all existing connections
Arguments:
force - Whether or not to force the drop database task
./doctrine generate-yaml-db - Generates a Yaml schema file from an existing database
Arguments:
yaml_schema_path - /var/www/doctrine_app_2/schema
./doctrine generate-models-yaml - Generates your Doctrine_Record definitions from a Yaml
schema file
Arguments:
yaml_schema_path - /var/www/doctrine_app_2/schema
models_path - /var/www/doctrine_app_2/models
generate_models_options - Array of options for generating models
./doctrine generate-yaml-models - Generates a Yaml schema file from existing
Doctrine_Record definitions
Arguments:
yaml_schema_path - /var/www/doctrine_app_2/schema
models_path - /var/www/doctrine_app_2/models
./doctrine dump-data - Dump data to a yaml data fixture file.
Arguments:
data_fixtures_path - /var/www/doctrine_app_2/data/fixtures
models_path - /var/www/doctrine_app_2/models
./doctrine build-all-reload - Calls rebuild-db and load-data
Arguments:
yaml_schema_path - /var/www/doctrine_app_2/schema
models_path - /var/www/doctrine_app_2/models
data_fixtures_path - /var/www/doctrine_app_2/data/fixtures
force - Whether or not to force the drop database task
generate_models_options - Array of options for generating models
./doctrine create-tables - Create tables for all existing database connections.
If table exists nothing happens.
Arguments:
models_path - /var/www/doctrine_app_2/models
./doctrine dql - Execute dql query and display the results
Arguments:
models_path - /var/www/doctrine_app_2/models
dql_query - Specify the complete dql query to execute.
params - Comma separated list of the params to replace the ? tokens in the dql
./doctrine rebuild-db - Drops and re-creates databases
Arguments:
yaml_schema_path - /var/www/doctrine_app_2/schema
models_path - /var/www/doctrine_app_2/models
force - Whether or not to force the drop database task
generate_models_options - Array of options for generating models
./doctrine migrate - Migrate database to latest version or the specified version
Arguments:
migrations_path - /var/www/doctrine_app_2/migrations
version - Version to migrate to. If you do not specify, the db will be migrated from
the current version to the latest.
./doctrine create-db - Create all databases for your connections. If the database
already exists, nothing happens.
./doctrine build-all - Calls generate-models-from-yaml, create-db, and create-tables
Arguments:
yaml_schema_path - /var/www/doctrine_app_2/schema
models_path - /var/www/doctrine_app_2/models
generate_models_options - Array of options for generating models
./doctrine generate-migration - Generate new migration class definition
Arguments:
class_name - Name of the migration class to generate
migrations_path - /var/www/doctrine_app_2/migrations
./doctrine generate-models-db - Generates your Doctrine_Record definitions
from your existing database connections.
Arguments:
models_path - /var/www/doctrine_app_2/models
connection - Optionally specify a single connection to generate the models for.