Criando um Web Service PHP com NuSoap e acessando-o com NCLua Soap

by Johnny Moreira Gomes

Neste tutorial, apresentarei passo-a-passo o processo de criao de um Web Service PHP utilizando a biblioteca NuSoap (voc pode baix-la atravs da seo de links ao final deste arquivo) de modo que o mesmo possa ser consumido por uma aplicao de tv digital em Ncl/Lua. Primeiramente criaremos um Web Service de exemplo, para que posteriormente montemos o seu cliente em NCL/Lua, utilizando o mdulo NCLua SOAP, criado por Manoel Campos. Este ltimo pode ser baixado em nossa seo de links ou atravs da pgina do Manoel Campos referente a este mdulo, pelo link http://ncluasoap.manoelcampos.com .

Parte I Criao do Web Service

Vamos criar um Web Service em PHP baseado em SOAP contendo uma simples funo que retorna a classificao de um tringulo de acordo com os tamanhos de seus lados, passados como parmetros. Para isso, utilizaremos a biblioteca PHP NuSoap, tambm encontrada na seo de links deste tutorial. Esta biblioteca uma alternativa ao mdulo SOAP Extension, nativo do PHP, que foi escolhida para esta situao pelo fato de oferecer suporte criao automtica do WSDL. Para que o mdulo NuSoap funcione em sua verso atual, necessria a utilizao do PHP verso dentre 5.0 at 5.25. E para o teste de nosso cliente NCLua em uma mquina local, necessrio configurar o Apache para o modo online. Para facilitar o nosso trabalho por aqui, foi utilizado o WampServer 1.7.4 (tambm disponvel para download ao final deste documento) para Windows, que um software que rene o Apache, o PHP 5.25 e o MySql 5.0.45, automaticamente configurados aps a instalao para o uso em mquina local. O nosso Web Service estar contido em uma pasta de nome mywebservice no diretrio raiz de nosso servidor Apache. Dentro desta pasta estar a pasta lib, referente ao mdulo NuSoap, e o arquivo server.php, que consiste no arquivo principal de nosso Web Service. O arquivo iniciado da seguinte maneira:

Nesse incio, ns simplesmente inclumos o arquivo principal do mdulo NuSoap, instanciamos a varivel $server como um objeto soap_server e inicializamos o suporte ao WSDL, batizando o nosso servio com o namespace server.triangle nas linhas 6 e 7. A diretiva urn: indica que estamos utilizando um identificador de recurso ao invs de um caminho, como ocorre em URL's ou URI's. Na listagem abaixo, registramos a funo de nosso Web Service utilizando o mtodo register,

cujos parmetros so explicados nos comentrios.

Agora, escreveremos a funo de nosso Web Service, ou seja, implementaremos o mtodo registrado acima, recebendo os parmetros indicados e retornando o valor esperado.

Finalmente, incluiremos as linhas referentes ao processamento da requisio enviada pelo cliente

ao nosso Web Service, conforme mostrado na listagem abaixo:

Antes de iniciarmos nossos trabalhos com o NCL/Lua, podemos testar o funcionamento do nosso Web Service atravs de um cliente PHP. Para tanto, basta executar o script PHP listado abaixo, lembrando que localhost se refere mquina local e pode ser substitudo por um ip ou um domnio, conforme o ambiente onde est hospedado o nosso servio.

Caso haja interesse em acessar o WSDL do nosso Web Service, basta acessar a url do arquivo principal em adio do parmetro ?wsdl. Por exemplo, se a aplicao estiver rodando na mquina local, conseguiremos visualizar o WSDL no navegador atravs do endereo http://localhost/mywebservice/server.php?wsdl.

Observaes e Cuidados a serem tomados:

O arquivo principal do Web Service e os demais arquivos includos no mesmo no devem conter absolutamente nada no exterior dos delimitadores de cdigo PHP, incluindo espaos e quebras de linha. Isso porque h mtodos do mdulo NuSoap que enviam HTTP Headers, exigindo que nenhuma informao prvia tenha sido enviada via HTTP. O cdigo de implementao do mtodo de retorno no pode conter comandos echo ou print, pois toda a informao de sada do Web Service ser transformada em contedo XML. Isso implica que a presena desses comandos pode vir a comprometer a codificao do arquivo a ser gerado.

Parte II Criao do cliente NCLua

Como foi dito anteriormente, utilizaremos o mdulo NCLua Soap para a comunicao de nossa aplicao de tv digital com o nosso recm-criado Web Service PHP. O mdulo em questo utiliza as bibliotecas Lua TCP, LuaXML, HTTP e base64, alm de alguns mtodos de propsito geral presentes no arquivo util.lua. O cdigo fonte da aplicao que criaremos aqui est presente na nossa seo de links e contm todos os arquivos conforme a especificao acima. Caso haja interesse em entender com mais profundidade as extenses utilizadas, sugiro que acesse a pgina do Manoel Campos para a obteno de maiores informaes (link presente no incio deste tutorial ou na seo de fontes). A nossa aplicao NCLua conter, alm dos arquivos essenciais para o funcionamento do NCLua SOAP, um arquivo NCL com apresentao em branco. Optei por essa estratgia para que o nosso cdigo lua fique mais limpo, contendo apenas comandos de sada print, ou seja, gerando sada apenas para o cliente de SSH que se comunicar com a mquina virtual Ginga-NCL. Alm disso, haver o arquivo main.lua, que ser executado assim que a aplicao NCL se iniciar. Comearemos o nosso main.lua com a inicializao das variveis contendo os parmetros a serem passados para o Web Service e o ip de onde o mesmo est hospedado. Caso o mesmo esteja em sua mquina local, o servidor Apache deve estar configurado para o modo online e a diretiva localhost no ir servir, pois agora o escopo da aplicao uma mquina virtual. Portando, basta informar o ip atual de sua conexo com a internet. Abaixo est uma imagem mostrando como ativar o modo online do Apache atravs do WampServer.

Listagem contendo as primeiras linhas de main.lua:

Agora, criaremos uma Table Lua contendo as informaes necessrias para a criao da requisio ao Web Service. Tais informaes so: Endereo do arquivo principal do Web Service; o namespace do servio, anteriormente escolhido (sem o urn:); o nome do mtodo e os parmetros do mesmo.

Julgo importante ressaltar um fato interessante com relao aos parmetros em nossa Table Lua. Um Web Service PHP baseado em NuSoap no considera o nome dos parmetros, somente a ordem em que eles aparecem no xml de requisio. No nosso exemplo, com a Table Lua considerada, o mdulo NCLua soap ir gerar um xml de requisio contendo o seguinte fragmento, referente aos parmetros a serem passados para a funo do servio:

Apesar de nosso Web Service ter sido registrado com os parmetros de nomes a, b e c, o mesmo comportamento ser evidenciado se o fragmento acima for substitudo por:

Isso ocorre porque, conforme dito antes, o NuSoap simplesmente joga o valor da primeira tag de parmetros no primeiro argumento do mtodo de servio, e assim por diante. O mdulo NCLua SOAP, por sua vez, ao gerar o xml de requisio, escreve as tags de parmetros em ordem arbitrria. Poderia acontecer, por exemplo, de o fragmento xml mostrado acima ter sido gerado da seguinte forma:

Quando o NuSoap fosse executar o trabalho de interpretao da requisio, a nossa funo seria chamada da seguinte maneira: triangle(4, 5, 3); Ou seja, se no nosso caso a ordem em que os lados do tringulo aparecessem na funo importasse , ocorreria um resultado inesperado (para o nosso Web Service a ordem no importar, pois dentro do mtodo triangle os lados so postos em ordem crescente de medida). Portando, para evitar maiores problemas, aconselho sempre a se conhecer a ordem em que aparecem os argumentos da funo de servio e, ao se gerar a Table Lua de requisio, especific-los respectivamente da seguinte forma:

Como cada elemento da tabela params no possui identificador explcito, ou seja, os seus elementos so sub-tabelas sem nome, o mesmo passa a ter o formato de um array. Deste modo, seus elementos so associados biunivocamente com ndices numricos, garantindo assim que a ordem de declarao dos parmetros seja respeitada no momento de montagem do xml de requisio por parte do mdulo NCLua SOAP. Voltando ao nosso main.lua, aps especificarmos o Table Lua de requisio, implementaremos a funo que ir receber e tratar a resposta obtida do Web Service. Esta funo obrigatoriamente deve receber um parmetro referente resposta a ser obtida do Web Service.

Finalmente, chamamos o mtodo call do mdulo NCLua SOAP, passando como argumentos o Table Lua de requisio, o nome da funo de retorno que acabamos de criar e a verso do SOAP utilizada pelo Web Service, que no caso do NuSoap ser 1.1.

Concluso
Por aqui, terminamos mais um tutorial sobre aplicaes em Tv Digital, desta vez buscando mostrar um pouco sobre o funcionamento da comunicao entre um Web Service PHP e uma aplicao NCL/Lua. Espero que, de modo geral, o que foi exposto aqui tenha sido proveitoso, uma vez que Web Services se mostram bastante adequados para fornecer informaes s mais variadas plataformas, podendo constituir uma ferramenta de interatividade poderosssima nas mais diversas aplicaes de Tv Digital. E esse recurso, quando somado s vantagens oferecidas pela tecnologia PHP, torna-se um instrumento gratuito e de fcil manuseio, que atende desde as aplicaes mais simples at as mais engenhosas.

Links
Mdulo NuSoap PHP: http://sourceforge.net/projects/nusoap/ WampServer 1.7.4: http://www.soft-go.com/view/WAMP5_20010.html Cdigo Fonte Web Service PHP (Inclui a NuSoap 0.9.5) http://www.ufjf.br/lapic/files/2010/05/mywebservice.zip Cdigo Fonte Cliente NCLua SOAP (Inclui mdulo NCLua SOAP 0.5.6 e dependncias) http://www.ufjf.br/lapic/files/2010/05/client-triangle.zip

Fontes
http://www.scottnichol.com/nusoapintro.htm http://www.scottnichol.com/nusoapprogwsdl.htm http://ncluasoap.manoelcampos.com Outros Projetos Interessantes em TV Digital (por Manoel Campos) http://enquetetvd.manoelcampos.com http://ncluatweet.manoelcampos.com http://ncluarss.manoelcampos.com

Johnny Moreira Gomes Aluno do curso de Cincias Exatas da Universidade Federal de Juiz de Fora (UFJF) e Bolsista do Grupo de Tv Digital do Laboratrio de Aplicaes e Inovao em Computao (LApIC) da UFJF