Lumine Database

Mapping for PHP

Treinamento Bsico

Conhecendo as caractersticas bsicas de um dos

frameworks de mapeamento de banco de dados
relacionais mais fceis de ser utilizado.
Hugo Ferreira da Silva
13/12/2010

Sumrio
Etapa 1 ..................................................................................................................................... 4
Caractersticas do Lumine ......................................................................................................... 4
Vantagens do Lumine ................................................................................................................ 4
Etapa 2 ..................................................................................................................................... 5
Modelagem de um banco de dados de exemplo ...................................................................... 5
Instalao do Lumine ................................................................................................................ 5
Engenharia Reversa ................................................................................................................... 7
Dados Principais .................................................................................................................... 7
Personalizao....................................................................................................................... 8
Integrao ............................................................................................................................. 9
Tabelas .................................................................................................................................. 9
Log de gerao ...................................................................................................................... 9
Importar configurao .......................................................................................................... 9
Anlise do arquivo de configurao ........................................................................................ 10
Anlise do mapeamento das tabelas ...................................................................................... 11
Inicializando a configurao .................................................................................................... 13
Inicializando um objeto ........................................................................................................... 13
Etapa 3 ................................................................................................................................... 13
Mtodos de consulta............................................................................................................... 13
get........................................................................................................................................ 14
find ...................................................................................................................................... 14
Select ................................................................................................................................... 14
selectAs ............................................................................................................................... 15
join ....................................................................................................................................... 15
where .................................................................................................................................. 15
group ................................................................................................................................... 15
order .................................................................................................................................... 15
having .................................................................................................................................. 15
limit ..................................................................................................................................... 15
Mtodos de persistncia ......................................................................................................... 15
save ..................................................................................................................................... 15
insert ................................................................................................................................... 15
addMultiInsertItem ............................................................................................................. 15
multiInsert ........................................................................................................................... 15
Mtodos de manipulao de dados ........................................................................................ 15
fetch .................................................................................................................................... 15
toArray ................................................................................................................................ 16

allToArray ............................................................................................................................ 16
toXML .................................................................................................................................. 16
allToXML .............................................................................................................................. 16
toObject............................................................................................................................... 16
allToObject .......................................................................................................................... 16
toJson .................................................................................................................................. 16
allToJson .............................................................................................................................. 16
addFormatter ...................................................................................................................... 16
setFieldOption ..................................................................................................................... 16
Utilizando Joins ....................................................................................................................... 16
Utilizando Union ...................................................................................................................... 16
Etapa 4 ................................................................................................................................... 16
Validaes com XML ............................................................................................................... 16
Validaes com PHP ................................................................................................................ 16
Criando validaes personalizadas em PHP ............................................................................ 16
Classe de utilidades Lumine_Util.......................................................................................... 16
EventListeners ......................................................................................................................... 17
Monitorando consultas (Lumine_Log) .................................................................................... 17
Capturando erros .................................................................................................................... 17

Etapa 1
Caractersticas do Lumine
Lumine nasceu no ano de 2005, devido a uma necessidade que havia na poca de trabalhar
com as informaes obtidas do banco de dados em forma de programao orientada a
objetos. Existiam outras bibliotecas, porm com configuraes complexas ou que no
ofereciam os recursos desejados para o desenvolvimento.
Em sua primeira verso, Lumine utilizava arquivos em XML para fazer o mapeamento das
tabelas, como fazia ento o Hibernate para o Java. Com o passar do tempo, foi notado que
trabalhando-se com um nmero muito grande de tabelas/colunas, o parse do arquivo XML
deixava o processo lento. Ento nasceu o Lumine 1.5, onde o mapeamento passou a ser
atravs de uma configurao dentro da prpria classe.
Diferentemente de outras bibliotecas e frameworks para mapeamento de banco de dados,
Lumine trabalha com o conceito de ActiveRecord, onde o prprio objeto que realizou a
consulta armazena os resultados encontrados, mas tambm lhe permite exportar os dados
de outras maneiras e formatos, dando ao desenvolvedor a liberdade de trabalhar com os
dados obtidos do jeito que mais lhe agrada/convm.
Para criao de Lumine foram seguidos alguns conceitos:

Ser um framework de fcil utilizao;

Write less, do more (escreva menos e faa mais);
Tentar abstrair ao mximo a linguagem SQL do desenvolvedor;
Trabalhar com as tabelas como se fossem objetos (POO);
Oferecer mtodos e ferramentas que acelerem o desenvolvimento e garantam a
integridade;
Atender ao pblico nacional.

Vantagens do Lumine

Cdigo aberto e LGPL;

Baixa curva de aprendizagem;
Configurao e inicializao fcil;
Permite o trabalho com orientao a objetos;
Cdigo bem documentado e com comentrios em portugus;
Ferramenta de engenharia reversa;
Possui mtodos para que o usurio no se preocupe com o tipo de dados informado,
Lumine o converter para o tipo correto;
Permite exportar de maneira simples o resultado para vrios formatos (JSON, Array,
XML e Objetos DTO Data Transfer Objects);
Permite a instalao e utilizao de plug-ins para as classes geradas;
Permite a instalao e utilizao de add-ons para a engenharia reversa;
Facilmente portvel para um SGBDR que no est no pacote padro de Lumine;
Fcil integrao com outras ferramentas de desenvolvimento (Ajax, Flex, Flash);
Trabalha com disparo de eventos, o que d ainda mais flexibilidade ao desenvolvedor;
Fcil e flexvel implementao de validao de dados;

Etapa 2
Modelagem de um banco de dados de exemplo
Para comearmos o estudo de Lumine, vamos criar um banco de dados de exemplo.
Nele, iremos trabalhar com os trs tipos de relacionamento suportados por Lumine (umpara-muitos, muitos-para-um e muitos-para-muitos).
Criaremos um sistema de gerenciamento de permisses de usurios, seguindo a seguinte
lgica:

Um usurio possui: cdigo, nome, e-mail e status;

Um grupo possui: cdigo e nome;
Uma funo possui: cdigo, nome e ordem de execuo;
Um usurio pertence a um grupo;
Um grupo possui uma ou mais funes;
Uma funo pode estar em um ou mais grupos;

Com esta lgica, temos o seguinte mapeamento:

Para este exemplo, iremos utilizar o banco de dados PostgreSQL.

As DDLs geradas esto no arquivo anexo create.sql. O nome do banco de dados que iremos
utilizar para este exemplo ser lumine_basico e estar rodando no servidor local (localhost).

Instalao do Lumine
A instalao de Lumine simples. Basta baixar o pacote disponvel no site
http://www.hufersil.com.br/lumine/downloads e descompactar no diretrio da aplicao
Web que est sendo criada.
Voc pode tambm baixar a verso mais recente disponvel no repositrio SVN do projeto,
que tem acesso publico: https://lumine.svn.sourceforge.net/svnroot/lumine/lumine-1.5
Para este exemplo, vamos utilizar utilizar a verso do SVN; basta fazer o checkout do
projeto utilizando a ferramenta de sua preferncia.

Aps baixar, vamos criar o diretrio para nossos arquivos de exemplo. Todos os nossos
arquivos estaro na pasta: C:\www\treinamentos\basico.
Descompacte Lumine dentro da pasta acima. O caminho dever ficar como o semelhante
ao abaixo:

A pasta arquivos contm os dados auxiliares a este treinamento.

Este diretrio deve estar acessvel atravs de um navegador. O servidor web, bem como o
mdulo PHP devero estar devidamente instalados.
Neste treinamento, o diretrio raiz dos documentos web do servidor HTTP c:\www.
A URL para acesso, neste caso, ser http://127.0.0.1/treinamentos/basico.
A tela que segue dever ser semelhante a abaixo:

Engenharia Reversa
Lumine vem com uma ferramenta que lhe permite gerar todas as classes de mapeamento,
bem como os arquivos de configurao a partir de uma interface amigvel e de fcil
compreenso. Ela tambm permite que outros arquivos, como de integrao com outros
frameworks, possam ser gerados tambm de forma fcil e rpida.
Alm disto, esta interface tambm lhe permite que sejam criadas ferramentas
personalizadas e as mesmas possam ser plugadas na interface de engenharia reversa,
dando flexibilidade ao desenvolvedor de gerar os cdigos que lhe forem convenientes em
uma nica tela.
Para acessar a ferramenta de engenharia reversa em nosso exemplo, acesse a URL:
http://127.0.0.1/treinamentos/basico/lumine/lib/ui/reverse.php

Atravs desta interface, voc poder informar todos dados necessrios para que seus
arquivos possam ser gerados, lhe poupando todo o trabalho de mapeamento manual.
Lumine tambm capaz de traduzir os relacionamentos desde que eles estejam
devidamente criados nas tabelas de seu banco de dados.
Dados Principais

Modelo de configurao: Lumine permite que voc crie modelos de configurao.

Estes modelos so opes pr-definidas para acelerar o processo de engenharia
reversa.
Estes
modelos
esto
disponveis
no
arquivo:
C:\www\treinamentos\basico\lumine\lib\Templates\Configurations.php.
Dialeto: define qual o driver de banco de dados ser utilizado. Em nosso caso,
escolheremos PostgreSQL.
Nome do banco de dados: informe qual ser o banco de dados que ser utilizado
para que as informaes sejam extradas e geradas as classes.
Usurio do banco de dados: nome de usurio para conexo com o banco de dados.
Senha do banco de dados: senha de acesso para conexo com o banco de dados.
Porta do banco de dados: porta de acesso para conexo com o banco de dados.
Para o PostgreSQL, o padro a porta 5432.
Host do banco de dados: nome do servidor onde est instalado SGBDR e tambm
configurado o banco de dados.

Class path (diretrio raiz da aplicao): esta uma das mais importantes
configuraes. Ela indica onde estaro os arquivos gerados pelo Lumine. a partir
dela que o framework procurar todos os arquivos relacionados aos mapeamentos
gerados para o seu banco de dados.
Pacote das classes: indica qual ser o pacote de classes. Esta deve ser informado no
estilo de pacotes do Java (br.com.dominio.entidades). Um diretrio que reflete este
pacote dever existir dentro do diretrio definido em classpath
(br/com/dominio/entidades) ou a opo de gerar os diretrios dever estar
habilitada (veremos na prxima seo).
Tipo de gerao dos arquivos: Lumine permite que os arquivos possam ser gerador
diretamente nos diretrios definidos ou ainda serem enviados para um arquivo ZIP
dentro do diretrio definido em class-path.
Recuperar tabelas: efetua a conexo com o banco de dados e lista as tabelas para
iniciar o processo de engenharia reversa.

Personalizao

Remover prefixo das tabelas: em alguns casos, podemos ter banco de dados onde
todas as tabelas tm um prefixo. Caso no queira que suas classes utilizem este
prefixo, basta informar o prefixo utilizado neste campo e ele ser removido dos
nomes das classes geradas.
Remover ... caracteres do inicio das tabelas: caso no seja um prefixo, mas um
nmero determinado de caracteres de cada tabela, voc pode remove-los dos
nomes das classes utilizando esta opo.
Remover ... caracteres do fim das tabelas: semelhante a anterior, mas remove do
final das tabelas.
Formatar nome da classe: voc ainda pode aplicar um formatador ao nome da
classe, podendo acrescentar prefixo, sufixo ou ambos.
Schema (experimental): utilizado para identificar o schema que est sendo usado
para as tabelas.
Formato para identificar tabelas M-N: por padro, Lumine utiliza o formato
tabela1_tabela2 para encontrar um relacionamento M-N. Caso queira mudar, basta
alterar nesta configurao:
String para converter em plural relac. M-N e 1-N: permite adicionar uma string
para converter em plural os campos destes tipos de relacionamento, desde que a
opo Dicionrio de plural? no esteja selecionada.
Usar controles usando: cria controles para que seja feito o scaffolding (formulrios
prontos para insero de dados) das tabelas.
Utilizar sufixo na criao dos arquivos: acrescenta nos nomes fsicos dos arquivos
um sufixo, por exemplo: Pessoa.class.php, Carro.inc.php.
Gerar getters/setters: cria os mtodos de recuperar e alterar as propriedades da
entidade.
Gerar entidades para tabelas M-N: por padro, Lumine no gera as classes para as
tabelas de relacionamento M-N. Caso queira cri-las, basta marcar esta opo.
Manter nomes das colunas nas chaves estrangeiras?: Lumine permite que voc
converta uma coluna para o nome da entidade relacionada. Supondo que na tabela
de usurio tenha uma coluna chamada codgrupo. Voc pode manter este nome ou
permitir que a engenharia reversa renomeie este campo para grupo (nome da
outra entidade).

Usar CamelCase?: esta opo far com que os nomes dos campos utilizem a
notao CamelCase, onde um underscore seguido de uma letra minscula ser
substituda para letra maiscula (cod_usuario ficar como codUsuario).
Dicionrio de plural?: Lumine tentar automaticamente transformar os nomes de
relacionamentos M-N e 1-N em plurais utilizados na lngua portuguesa. Em nosso
exemplo, a entidade Grupo ter um relacionamento chamado usurios e outro
chamado funcoes, devido ao relacionamento com a tabela de usurios (1 grupo
para M usurios) e ao relacionamento com a tabela de funo (M grupos para N
funes).
Deseja criar os diretrios?: permite que Lumine tente criar toda estrutura de
diretrio necessria para gerar os arquivos. Do contrrio, todas as pastas devero
ser criadas previamente.

Integrao

Criar DTOs: permite ao usurio criar os arquivos DTOs (Data Transfer Object) para
integrao com outras tecnologias (como AMF).
Auto-Cast para o DTO quando usar toObject/allToObjec: far com que o mtodo
allToObject utilize a classe DTO relacionada no momento de gerar os dados.
Formato do nome do DTO: altera o formato de como os nomes dos DTOs sero
gerados.
Nome do pacote para DTOs: opo semelhante a pacote das classes na aba Dados
Principais, com exceo que esta configurao somente para os arquivos DTOs
gerados.
Criar models?: quando estamos trabalhando no contexto de MVC, esta opo ir
gerar as classes que compe a camada de Models de sua aplicao.
Pasta para as models: diretrio onde os arquivos das classes models iro ser
gerados.
Formato de nome para models: permite que seja alterado o formato do nome final
do arquivo. Por padro, utilizado o nome da entidade seguido de Model, por
exemplo: UsuarioModel, GrupoModel, FuncaoModel.
Criar aquivo de contexto para MVC: gerar o arquivo que, geralmente, frameworks
MVC utilizam para inicializar bibliotecas (a exemplo do CodeIgniter). Esta opo ir
gerar um outro arquivo que abrange toda a inicializao do framework.
Pasta para gravao do arquivo de contexto: diretrio onde ser gerado o arquivo
de contexto para inicializao das configuraes de Lumine dentro da sua aplicao
MVC.

Tabelas

Exibe todas as tabelas encontradas no banco de dados, conforme configuraes

definidas na aba Dados Principais. Aps a listagem, permite que voc inicie o
processo de engenharia reversa e gerao dos arquivos.

Log de gerao

Local onde voc pode acompanhar passo a passo o processo de criao dos
arquivos.

Importar configurao

Permite que voc importe um arquivo de configurao de Lumine previamente

criado. Assim, caso voc precise refazer a engenharia reversa, basta carregar o

arquivo de configurao gerado anteriormente e todas as opes sero

preenchidas no formulrio.

Anlise do arquivo de configurao

O arquivo de configurao divido em duas sees principais: propriedades e opes.
Praticamente todas as propriedades e opes esto presentes na engenharia reversa,
discutido no tpico anterior.
Fazem parte das propriedades as seguintes configuraes.

dialect: SGBD utilizado

database: Nome do banco de dados
user: Nome de usurio para conexo
password: Senha para conexo
port : Porta do servidor para conexo
host: Host para conexo
class_path: Caminho base de onde estaro os arquivos de Lumine
package: Pacote de onde estaro as classes geradas/utilizadas

Fazem parte das opes as seguintes configuraes:

remove_prefix: indica o prefixo a ser removido das tabelas para gerar as classes
remove_count_chars_start: indica o nmero de caracteres para remover do inicio
do nome da tabela para gerar o nome das classes
remove_count_chars_end: indica o nmero de caracteres para remover do final do
nome da tabela para gerar o nome das classes
format_classname: formato para criar os nomes das classes
schema_name (experimental): nome do esquema onde esto as tabelas
many_to_many_style: estilo para auto-identificar tabelas M-N
plural: String para adicionar a relacionamentos 1-M e M-N
create_controls: indica o tipo de controles bsicos que sero criados para
scaffolding.
class_sufix: Sufixo para os nomes dos arquivos gerados
keep_foreign_column_name: Indica que para manter os nomes das colunas nas
chaves estrangeiras
camel_case: Indica que para utilizar CamelCase nos nomes dos arquivos,
propriedades e relacionamentos
usar_dicionario: Indica que para utilizar o dicionrio de plural para gerar nomes
em plural nos casos de relacionamentos 1-M e M-N
create_paths: Indica que para criar os diretrios
dto_format: Formato para os nomes dos arquivos DTO
dto_package: Pacote para os arquivos DTO
create_models: Indica que para criar as models
model_path: Pasta onde ficaro gravados os arquivos gerados para as models
model_format: Formato para o nome das classes e arquivos de models
model_context: Indica se para criar ou no o arquivo de contexto para models
model_context_path: Pasta onde ficar gravado o arquivo de contexto para models
generateAccessors: Ondica que para criar os getters/setters
create_entities_many_to_many: Indica se para criar ou no as classes para
tabelas de relacionamento M-N

generate_files: Indica se para gerar os arquivos diretamente

generate_zip: Indica se para criar um arquivo ZIP contendo as classes geradas
charset: Charset de conexo com o banco de dados

Anlise do mapeamento das tabelas

Para anlise do mapeamento, vamos utilizar como exemplo a classe gerada para a tabela
grupo. Para facilitar, os comentrios foram removidos:

Vamos nos atentar primeiramente aos atributos criados.

Lumine trabalha sempre com os atributos da classe com a visibilidade public. Isto visa
facilitar e acelerar o desenvolvimento.
Tambm so gerados dois atributos com visibilidade protected: $_tablename e $_package.
Estes dois atributos indicam o nome da tabela e a conexo que Lumine ir utilizar,
respectivamente. atravs do pacote que Lumine identifica a qual conexo esta classe
pertence.
O mtodo initialize chamado internamente no construtor da classe pai, Lumine_Base. Ele
responsvel por inicializar o mapeamento da classe.
O mtodo _addField adiciona um atributo que representa um campo na tabela do banco de
dados. Seus argumentos so:

$name: nome do membro na classe;

$column: nome da coluna na tabela do banco de dados;
$type: tipo de dados que esta coluna armazena;
$length: comprimento do campo na tabela do banco de dados;
$options: array multimensional contendo configuraes extras para o membro.
Algumas opes so:
o primary: indica que uma chave primria;
o notnull: indica que o campo no pode ser nulo;

o
o

o
o
o
o
o
o

o
o

autoincrement: indica que o campo auto-incrementvel (ou serial no

caso do PostgreSQL). Em todos os bancos que tiverem campos de autonumerao, dever ser indicado como autoincrement => true.
label: Rtulo para ser utilizado nos formulrios gerados pela engenharia
reversa. Assim voc pode personalizar o formulrio;
displayField: Caso o campo seja um relacionamento com outra tabela, voc
poder indicar o nome do campo da outra tabela que conter o valor a ser
exibido na combo de valores;
foreign: Indica que este campo que contm valor de uma outra tabela
(chave-estrangeira);
onUpdate: Ao que o banco toma em quando o valor da chave estrangeira
for atualizado;
onDelete: Ao que o banco toma em quando o valor da chave estrangeira
for removido;
linkOn: Nome do membro da entidade estrangeira a qual o campo est
vinculado;
class: Nome da classe de relacionamento com este campo;
format: Formato de sada do campo (os mesmos suportados pela funo
sprintf (em caso de strings e nmeros) e strftime (em caso de datas e
tempo).
lazy: permite carregar valores de chaves estrangeiras assim que o registro
da entidade que est sendo manipulada for carregado.
formatter: Permite definir uma funo para ser executada quando o valor
do campo for requerido.

Alm do mapeamento dos membros, Lumine permite tambm mapear relacionamentos 1N e M-N. Em nosso exemplo, temos estes dois tipos de relacionamentos: usuarios e
funcoes. O mtodo utilizado para mapear estes tipos de relacionamentos o
_addForeignRelation. Ele possui os seguintes parmetros:

$name: Nome do relacionamento;

$type: Tipo do relacionamento;
$class: Nome da classe que ser relacionada;
$linkOn: Nome do campo da entidade que ser referenciada;
$table: Nome da tabela de relacionamentos M-N;
$column: Nome da coluna da tabela M-N que referencia a chave primria da classe
atual;
$lazy: Carrega os valores dos relacionamentos assim que carregado o valor atual da
classe chamadora;

Lumine tambm gera um mtodo esttico para todas as classes, nomeado de staticGet.
Este mtodo permite carregar de forma prtica e rpida um registro do banco de dados.
Veremos sua funcionalidade no tpico mtodos de consulta.
Por ltimo criado o destrutor da classe.
Lumine permite que voc faa a engenharia reversa quantas vezes desejar, sem perder os
dados que voc havia feito manualmente em sua classe. Para isso, basta colocar todos os
seus mtodos personalizados abaixo do comentrio:

Inicializando a configurao
Inicializar a configurao de Lumine bem simples. Voc precisa somente:

Incluir o framework Lumine;

Incluir o arquivo de configurao gerado pelo processo de engenharia reversa.

Abaixo um exemplo de inicializao (crie um arquivo chamado ndex.php e o coloque na

mesma pasta que o arquivo lumine-conf.php gerado):

Agora basta carregar as classes geradas e usar de maneira fcil e descomplicada.

Inicializando um objeto
Aps inicializar a configurao, necessrio importar as classes para poder utiliz-las. A
importao um processo simples. Abaixo um exemplo de utilizao:

Etapa 3
Mtodos de consulta
Lumine tm vrios mtodos para que voc possa realizar suas consultas de forma fcil e
eficiente. Abaixo esto listados estes mtodos:

get
Recupera um registro baseado no valor da chave primria ou em uma combinao de
chave/valor. Exemplos:

Ambos exemplos iro gerar a seguinte consulta:

Assim que os valores so recuperados do banco de dados eles ficam disponveis para serem
usados a partir do prprio objeto, por exemplo:

find
Semelhante ao mtodo get, porm ele somente efetua a pesquisa baseando-se nos valores
das propriedades, condies, joins etc.
Por padro, este mtodo no vai para o primeiro registro assim que recuperado o resultset,
como o mtodo get. Caso queira, passe TRUE como primeiro argumento. Exemplos:

Ambas chamadas geraro a seguinte consulta:

Select
Permite determinar quais campos sero recuperados na consulta que est sendo realizada.
A primeira chamada a este mtodo reinicia todas as configuraes anteriores. Exemplo:

Gerar a seguinte consulta

selectAs
Permite a voc selecionar todos os campos da entidade, formatando os campos. Por
exemplo:

Resultar na seguinte consulta:

join

where

group

order

having

limit

Mtodos de persistncia
save

insert

addMultiInsertItem

multiInsert

Mtodos de manipulao de dados

fetch

toArray

allToArray

toXML

allToXML

toObject

allToObject

toJson

allToJson

addFormatter

setFieldOption

Utilizando Joins

Utilizando Union

Etapa 4
Validaes com XML

Validaes com PHP

Criando validaes personalizadas em PHP

Classe de utilidades Lumine_Util

EventListeners

Monitorando consultas (Lumine_Log)

Capturando erros