Lumine Database Mapping fr PHP Treinament Básic Cnhecend as características básicas de um ds framewrks de mapeament de banc de dads relacinais mais fáceis de ser utilizad. Hug Ferreira da Silva 13/12/2010
Sumári Etapa 1... 4 Características d Lumine... 4 Vantagens d Lumine... 4 Etapa 2... 5 Mdelagem de um banc de dads de exempl... 5 Instalaçã d Lumine... 5 Engenharia Reversa... 7 Dads Principais... 7 Persnalizaçã... 8 Integraçã... 9 Tabelas... 9 Lg de geraçã... 9 Imprtar cnfiguraçã... 9 Análise d arquiv de cnfiguraçã... 10 Análise d mapeament das tabelas... 11 Inicializand a cnfiguraçã... 13 Inicializand um bjet... 13 Etapa 3... 13 Métds de cnsulta... 13 get... 14 find... 14 Select... 14 selectas... 15 jin... 15 where... 15 grup... 15 rder... 15 having... 15 limit... 15 Métds de persistência... 15 save... 15 insert... 15 addmultiinsertitem... 15 multiinsert... 15 Métds de manipulaçã de dads... 15 fetch... 15 tarray... 16
alltarray... 16 txml... 16 alltxml... 16 tobject... 16 alltobject... 16 tjsn... 16 alltjsn... 16 addfrmatter... 16 setfieldoptin... 16 Utilizand Jins... 16 Utilizand Unin... 16 Etapa 4... 16 Validações cm XML... 16 Validações cm PHP... 16 Criand validações persnalizadas em PHP... 16 Classe de utilidades Lumine_Util... 16 EventListeners... 17 Mnitrand cnsultas (Lumine_Lg)... 17 Capturand errs... 17
Etapa 1 Características d Lumine Lumine nasceu n an de 2005, devid a uma necessidade que havia na épca de trabalhar cm as infrmações btidas d banc de dads em frma de prgramaçã rientada a bjets. Existiam utras biblitecas, prém cm cnfigurações cmplexas u que nã fereciam s recurss desejads para desenvlviment. Em sua primeira versã, Lumine utilizava arquivs em XML para fazer mapeament das tabelas, cm fazia entã Hibernate para Java. Cm passar d temp, fi ntad que trabalhand-se cm um númer muit grande de tabelas/clunas, parse d arquiv XML deixava prcess lent. Entã nasceu Lumine 1.5, nde mapeament passu a ser através de uma cnfiguraçã dentr da própria classe. Diferentemente de utras biblitecas e framewrks para mapeament de banc de dads, Lumine trabalha cm cnceit de ActiveRecrd, nde própri bjet que realizu a cnsulta armazena s resultads encntrads, mas também lhe permite exprtar s dads de utras maneiras e frmats, dand a desenvlvedr a liberdade de trabalhar cm s dads btids d jeit que mais lhe agrada/cnvém. Para criaçã de Lumine fram seguids alguns cnceits: Ser um framewrk de fácil utilizaçã; Write less, d mre (escreva mens e faça mais); Tentar abstrair a máxim a linguagem SQL d desenvlvedr; Trabalhar cm as tabelas cm se fssem bjets (POO); Oferecer métds e ferramentas que acelerem desenvlviment e garantam a integridade; Atender a públic nacinal. Vantagens d Lumine Códig abert e LGPL; Baixa curva de aprendizagem; Cnfiguraçã e inicializaçã fácil; Permite trabalh cm rientaçã a bjets; Códig bem dcumentad e cm cmentáris em prtuguês; Ferramenta de engenharia reversa; Pssui métds para que usuári nã se precupe cm tip de dads infrmad, Lumine cnverterá para tip crret; Permite exprtar de maneira simples resultad para váris frmats (JSON, Array, XML e Objets DTO Data Transfer Objects); Permite a instalaçã e utilizaçã de plug-ins para as classes geradas; Permite a instalaçã e utilizaçã de add-ns para a engenharia reversa; Facilmente prtável para um SGBDR que nã está n pacte padrã de Lumine; Fácil integraçã cm utras ferramentas de desenvlviment (Ajax, Flex, Flash); Trabalha cm dispar de events, que dá ainda mais flexibilidade a desenvlvedr; Fácil e flexível implementaçã de validaçã de dads;
Etapa 2 Mdelagem de um banc de dads de exempl Para cmeçarms estud de Lumine, vams criar um banc de dads de exempl. Nele, irems trabalhar cm s três tips de relacinament suprtads pr Lumine (umpara-muits, muits-para-um e muits-para-muits). Criarems um sistema de gerenciament de permissões de usuáris, seguind a seguinte lógica: Um usuári pssui: códig, nme, e-mail e status; Um grup pssui: códig e nme; Uma funçã pssui: códig, nme e rdem de execuçã; Um usuári pertence a um grup; Um grup pssui uma u mais funções; Uma funçã pde estar em um u mais grups; Cm esta lógica, tems seguinte mapeament: Para este exempl, irems utilizar banc de dads PstgreSQL. As DDL s geradas estã n arquiv anex create.sql. O nme d banc de dads que irems utilizar para este exempl será lumine_basic e estará rdand n servidr lcal (lcalhst). Instalaçã d Lumine A instalaçã de Lumine é simples. Basta baixar pacte dispnível n site http://www.hufersil.cm.br/lumine/dwnlads e descmpactar n diretóri da aplicaçã Web que está send criada. Vcê pde também baixar a versã mais recente dispnível n repsitóri SVN d prjet, que tem acess public: https://lumine.svn.surcefrge.net/svnrt/lumine/lumine-1.5 Para este exempl, vams utilizar utilizar a versã d SVN; basta fazer checkut d prjet utilizand a ferramenta de sua preferência.
Após baixar, vams criar diretóri para nsss arquivs de exempl. Tds s nsss arquivs estarã na pasta: C:\www\treinaments\basic. Descmpacte Lumine dentr da pasta acima. O caminh deverá ficar cm semelhante a abaix: A pasta arquivs cntém s dads auxiliares a este treinament. Este diretóri deve estar acessível através de um navegadr. O servidr web, bem cm módul PHP deverã estar devidamente instalads. Neste treinament, diretóri raiz ds dcuments web d servidr HTTP é c:\www. A URL para acess, neste cas, será http://127.0.0.1/treinaments/basic. A tela que segue deverá ser semelhante a abaix:
Engenharia Reversa Lumine vem cm uma ferramenta que lhe permite gerar tdas as classes de mapeament, bem cm s arquivs de cnfiguraçã a partir de uma interface amigável e de fácil cmpreensã. Ela também permite que utrs arquivs, cm de integraçã cm utrs framewrks, pssam ser gerads também de frma fácil e rápida. Além dist, esta interface também lhe permite que sejam criadas ferramentas persnalizadas e as mesmas pssam ser plugadas na interface de engenharia reversa, dand flexibilidade a desenvlvedr de gerar s códigs que lhe frem cnvenientes em uma única tela. Para acessar a ferramenta de engenharia reversa em nss exempl, acesse a URL: http://127.0.0.1/treinaments/basic/lumine/lib/ui/reverse.php Através desta interface, vcê pderá infrmar tds dads necessáris para que seus arquivs pssam ser gerads, lhe pupand td trabalh de mapeament manual. Lumine também é capaz de traduzir s relacinaments desde que eles estejam devidamente criads nas tabelas de seu banc de dads. Dads Principais Mdel de cnfiguraçã: Lumine permite que vcê crie mdels de cnfiguraçã. Estes mdels sã pções pré-definidas para acelerar prcess de engenharia reversa. Estes mdels estã dispníveis n arquiv: C:\www\treinaments\basic\lumine\lib\Templates\Cnfiguratins.php. Dialet: define qual driver de banc de dads será utilizad. Em nss cas, esclherems PstgreSQL. Nme d banc de dads: infrme qual será banc de dads que será utilizad para que as infrmações sejam extraídas e geradas as classes. Usuári d banc de dads: nme de usuári para cnexã cm banc de dads. Senha d banc de dads: senha de acess para cnexã cm banc de dads. Prta d banc de dads: prta de acess para cnexã cm banc de dads. Para PstgreSQL, padrã é a prta 5432. Hst d banc de dads: nme d servidr nde está instalad SGBDR e também cnfigurad banc de dads.
Class path (diretóri raiz da aplicaçã): esta é uma das mais imprtantes cnfigurações. Ela indica nde estarã s arquivs gerads pel Lumine. É a partir dela que framewrk prcurará tds s arquivs relacinads as mapeaments gerads para seu banc de dads. Pacte das classes: indica qual será pacte de classes. Esta deve ser infrmad n estil de pactes d Java (br.cm.dmini.entidades). Um diretóri que reflete este pacte deverá existir dentr d diretóri definid em class path (br/cm/dmini/entidades) u a pçã de gerar s diretóris deverá estar habilitada (verems na próxima seçã). Tip de geraçã ds arquivs: Lumine permite que s arquivs pssam ser geradr diretamente ns diretóris definids u ainda serem enviads para um arquiv ZIP dentr d diretóri definid em class-path. Recuperar tabelas: efetua a cnexã cm banc de dads e lista as tabelas para iniciar prcess de engenharia reversa. Persnalizaçã Remver prefix das tabelas: em alguns cass, pdems ter banc de dads nde tdas as tabelas têm um prefix. Cas nã queira que suas classes utilizem este prefix, basta infrmar prefix utilizad neste camp e ele será remvid ds nmes das classes geradas. Remver... caracteres d inici das tabelas: cas nã seja um prefix, mas um númer determinad de caracteres de cada tabela, vcê pde remve-ls ds nmes das classes utilizand esta pçã. Remver... caracteres d fim das tabelas: semelhante a anterir, mas remve d final das tabelas. Frmatar nme da classe: vcê ainda pde aplicar um frmatadr a nme da classe, pdend acrescentar prefix, sufix u ambs. Schema (experimental): utilizad para identificar schema que está send usad para as tabelas. Frmat para identificar tabelas M-N: pr padrã, Lumine utiliza frmat tabela1_tabela2 para encntrar um relacinament M-N. Cas queira mudar, basta alterar nesta cnfiguraçã: String para cnverter em plural relac. M-N e 1-N: permite adicinar uma string para cnverter em plural s camps destes tips de relacinament, desde que a pçã Dicinári de plural? nã esteja selecinada. Usar cntrles usand: cria cntrles para que seja feit scafflding (frmuláris prnts para inserçã de dads) das tabelas. Utilizar sufix na criaçã ds arquivs: acrescenta ns nmes físics ds arquivs um sufix, pr exempl: Pessa.class.php, Carr.inc.php. Gerar getters/setters: cria s métds de recuperar e alterar as prpriedades da entidade. Gerar entidades para tabelas M-N: pr padrã, Lumine nã gera as classes para as tabelas de relacinament M-N. Cas queira criá-las, basta marcar esta pçã. Manter nmes das clunas nas chaves estrangeiras?: Lumine permite que vcê cnverta uma cluna para nme da entidade relacinada. Supnd que na tabela de usuári tenha uma cluna chamada cdgrup. Vcê pde manter este nme u permitir que a engenharia reversa renmeie este camp para grup (nme da utra entidade).
Usar CamelCase?: esta pçã fará cm que s nmes ds camps utilizem a ntaçã CamelCase, nde um underscre seguid de uma letra minúscula será substituída para letra maiúscula (cd_usuari ficará cm cdusuari). Dicinári de plural?: Lumine tentará autmaticamente transfrmar s nmes de relacinaments M-N e 1-N em plurais utilizads na língua prtuguesa. Em nss exempl, a entidade Grup terá um relacinament chamad usuáris e utr chamad funces, devid a relacinament cm a tabela de usuáris (1 grup para M usuáris) e a relacinament cm a tabela de funçã (M grups para N funções). Deseja criar s diretóris?: permite que Lumine tente criar tda estrutura de diretóri necessária para gerar s arquivs. D cntrári, tdas as pastas deverã ser criadas previamente. Integraçã Criar DTO s: permite a usuári criar s arquivs DTO s (Data Transfer Object) para integraçã cm utras tecnlgias (cm AMF). Aut-Cast para DTO quand usar tobject/alltobjec: fará cm que métd alltobject utilize a classe DTO relacinada n mment de gerar s dads. Frmat d nme d DTO: altera frmat de cm s nmes ds DTO s serã gerads. Nme d pacte para DTO s: pçã semelhante a pacte das classes na aba Dads Principais, cm exceçã que esta cnfiguraçã é smente para s arquivs DTO s gerads. Criar mdels?: quand estams trabalhand n cntext de MVC, esta pçã irá gerar as classes que cmpõe a camada de Mdels de sua aplicaçã. Pasta para as mdels: diretóri nde s arquivs das classes mdels irã ser gerads. Frmat de nme para mdels: permite que seja alterad frmat d nme final d arquiv. Pr padrã, é utilizad nme da entidade seguid de Mdel, pr exempl: UsuariMdel, GrupMdel, FuncaMdel. Criar aquiv de cntext para MVC: gerará arquiv que, geralmente, framewrks MVC utilizam para inicializar biblitecas (a exempl d CdeIgniter). Esta pçã irá gerar um utr arquiv que abrange tda a inicializaçã d framewrk. Pasta para gravaçã d arquiv de cntext: diretóri nde será gerad arquiv de cntext para inicializaçã das cnfigurações de Lumine dentr da sua aplicaçã MVC. Tabelas Exibe tdas as tabelas encntradas n banc de dads, cnfrme cnfigurações definidas na aba Dads Principais. Após a listagem, permite que vcê inicie prcess de engenharia reversa e geraçã ds arquivs. Lg de geraçã Lcal nde vcê pde acmpanhar pass a pass prcess de criaçã ds arquivs. Imprtar cnfiguraçã Permite que vcê imprte um arquiv de cnfiguraçã de Lumine previamente criad. Assim, cas vcê precise refazer a engenharia reversa, basta carregar
arquiv de cnfiguraçã gerad anterirmente e tdas as pções serã preenchidas n frmulári. Análise d arquiv de cnfiguraçã O arquiv de cnfiguraçã é divid em duas seções principais: prpriedades e pções. Praticamente tdas as prpriedades e pções estã presentes na engenharia reversa, discutid n tópic anterir. Fazem parte das prpriedades as seguintes cnfigurações. dialect: SGBD utilizad database: Nme d banc de dads user: Nme de usuári para cnexã passwrd: Senha para cnexã prt : Prta d servidr para cnexã hst: Hst para cnexã class_path: Caminh base de nde estarã s arquivs de Lumine package: Pacte de nde estarã as classes geradas/utilizadas Fazem parte das pções as seguintes cnfigurações: remve_prefix: indica prefix a ser remvid das tabelas para gerar as classes remve_cunt_chars_start: indica númer de caracteres para remver d inici d nme da tabela para gerar nme das classes remve_cunt_chars_end: indica númer de caracteres para remver d final d nme da tabela para gerar nme das classes frmat_classname: frmat para criar s nmes das classes schema_name (experimental): nme d esquema nde estã as tabelas many_t_many_style: estil para aut-identificar tabelas M-N plural: String para adicinar a relacinaments 1-M e M-N create_cntrls: indica tip de cntrles básics que serã criads para scafflding. class_sufix: Sufix para s nmes ds arquivs gerads keep_freign_clumn_name: Indica que é para manter s nmes das clunas nas chaves estrangeiras camel_case: Indica que é para utilizar CamelCase ns nmes ds arquivs, prpriedades e relacinaments usar_dicinari: Indica que é para utilizar dicinári de plural para gerar nmes em plural ns cass de relacinaments 1-M e M-N create_paths: Indica que é para criar s diretóris dt_frmat: Frmat para s nmes ds arquivs DTO dt_package: Pacte para s arquivs DTO create_mdels: Indica que é para criar as mdels mdel_path: Pasta nde ficarã gravads s arquivs gerads para as mdels mdel_frmat: Frmat para nme das classes e arquivs de mdels mdel_cntext: Indica se é para criar u nã arquiv de cntext para mdels mdel_cntext_path: Pasta nde ficará gravad arquiv de cntext para mdels generateaccessrs: Ondica que é para criar s getters/setters create_entities_many_t_many: Indica se é para criar u nã as classes para tabelas de relacinament M-N
generate_files: Indica se é para gerar s arquivs diretamente generate_zip: Indica se é para criar um arquiv ZIP cntend as classes geradas charset: Charset de cnexã cm banc de dads Análise d mapeament das tabelas Para análise d mapeament, vams utilizar cm exempl a classe gerada para a tabela grup. Para facilitar, s cmentáris fram remvids: Vams ns atentar primeiramente as atributs criads. Lumine trabalha sempre cm s atributs da classe cm a visibilidade public. Ist visa facilitar e acelerar desenvlviment. Também sã gerads dis atributs cm visibilidade prtected: $_tablename e $_package. Estes dis atributs indicam nme da tabela e a cnexã que Lumine irá utilizar, respectivamente. É através d pacte que Lumine identifica a qual cnexã esta classe pertence. O métd initialize é chamad internamente n cnstrutr da classe pai, Lumine_Base. Ele é respnsável pr inicializar mapeament da classe. O métd _addfield adicina um atribut que representa um camp na tabela d banc de dads. Seus arguments sã: $name: nme d membr na classe; $clumn: nme da cluna na tabela d banc de dads; $type: tip de dads que esta cluna armazena; $length: cmpriment d camp na tabela d banc de dads; $ptins: array multimensinal cntend cnfigurações extras para membr. Algumas pções sã: primary: indica que é uma chave primária; ntnull: indica que camp nã pde ser nul;
autincrement: indica que camp é aut-incrementável (u serial n cas d PstgreSQL). Em tds s bancs que tiverem camps de autnumeraçã, deverá ser indicad cm autincrement => true. label: Rótul para ser utilizad ns frmuláris gerads pela engenharia reversa. Assim vcê pde persnalizar frmulári; displayfield: Cas camp seja um relacinament cm utra tabela, vcê pderá indicar nme d camp da utra tabela que cnterá valr a ser exibid na cmb de valres; freign: Indica que este camp que cntém valr de uma utra tabela (chave-estrangeira); nupdate: Açã que banc tma em quand valr da chave estrangeira fr atualizad; ndelete: Açã que banc tma em quand valr da chave estrangeira fr remvid; linkon: Nme d membr da entidade estrangeira a qual camp está vinculad; class: Nme da classe de relacinament cm este camp; frmat: Frmat de saída d camp (s mesms suprtads pela funçã sprintf (em cas de strings e númers) e strftime (em cas de datas e temp). lazy: permite carregar valres de chaves estrangeiras assim que registr da entidade que está send manipulada fr carregad. frmatter: Permite definir uma funçã para ser executada quand valr d camp fr requerid. Além d mapeament ds membrs, Lumine permite também mapear relacinaments 1- N e M-N. Em nss exempl, tems estes dis tips de relacinaments: usuaris e funces. O métd utilizad para mapear estes tips de relacinaments é _addfreignrelatin. Ele pssui s seguintes parâmetrs: $name: Nme d relacinament; $type: Tip d relacinament; $class: Nme da classe que será relacinada; $linkon: Nme d camp da entidade que será referenciada; $table: Nme da tabela de relacinaments M-N; $clumn: Nme da cluna da tabela M-N que referencia a chave primária da classe atual; $lazy: Carrega s valres ds relacinaments assim que carregad valr atual da classe chamadra; Lumine também gera um métd estátic para tdas as classes, nmead de staticget. Este métd permite carregar de frma prática e rápida um registr d banc de dads. Verems sua funcinalidade n tópic métds de cnsulta. Pr últim é criad destrutr da classe. Lumine permite que vcê faça a engenharia reversa quantas vezes desejar, sem perder s dads que vcê havia feit manualmente em sua classe. Para iss, basta clcar tds s seus métds persnalizads abaix d cmentári:
Inicializand a cnfiguraçã Inicializar a cnfiguraçã de Lumine é bem simples. Vcê precisa smente: Incluir framewrk Lumine; Incluir arquiv de cnfiguraçã gerad pel prcess de engenharia reversa. Abaix um exempl de inicializaçã (crie um arquiv chamad índex.php e clque na mesma pasta que arquiv lumine-cnf.php gerad): Agra basta carregar as classes geradas e usar de maneira fácil e descmplicada. Inicializand um bjet Após inicializar a cnfiguraçã, é necessári imprtar as classes para pder utilizá-las. A imprtaçã é um prcess simples. Abaix um exempl de utilizaçã: Etapa 3 Métds de cnsulta Lumine têm váris métds para que vcê pssa realizar suas cnsultas de frma fácil e eficiente. Abaix estã listads estes métds:
get Recupera um registr basead n valr da chave primária u em uma cmbinaçã de chave/valr. Exempls: Ambs exempls irã gerar a seguinte cnsulta: Assim que s valres sã recuperads d banc de dads eles ficam dispníveis para serem usads a partir d própri bjet, pr exempl: find Semelhante a métd get, prém ele smente efetua a pesquisa baseand-se ns valres das prpriedades, cndições, jin s etc. Pr padrã, este métd nã vai para primeir registr assim que recuperad resultset, cm métd get. Cas queira, passe TRUE cm primeir argument. Exempls: Ambas chamadas gerarã a seguinte cnsulta: Select Permite determinar quais camps serã recuperads na cnsulta que está send realizada. A primeira chamada a este métd reinicia tdas as cnfigurações anterires. Exempl: Gerará a seguinte cnsulta
selectas Permite a vcê selecinar tds s camps da entidade, frmatand s camps. Pr exempl: Resultará na seguinte cnsulta: jin where grup rder having limit Métds de persistência save insert addmultiinsertitem multiinsert Métds de manipulaçã de dads fetch
tarray alltarray txml alltxml tobject alltobject tjsn alltjsn addfrmatter setfieldoptin Utilizand Jins Utilizand Unin Etapa 4 Validações cm XML Validações cm PHP Criand validações persnalizadas em PHP Classe de utilidades Lumine_Util
EventListeners Mnitrand cnsultas (Lumine_Lg) Capturand errs