Este post é para divulgar a primeira versão beta do WSDLDocument, um gerador de WSDL em PHP para webservices.
A forma como determinados assuntos são abordados em TI faz inibir o exímio programador dentro de diversos profissionais da nossa área. Um desses assuntos é webservice. Em PHP fazer um cliente é tranquilo. Já um servidor exige mais trabalho por conta da geração de WSDL. É claro que há diversas outras coisas a se observar na construção ou consumo de webservices.
Mas por que a construção de WSDL em PHP é a pedra no sapato de tanta gente? PHP é uma linguagem com tipagem fraca, o que possibilita que uma variável seja de diversos tipos durante a execução de um script/requisição. A descrição de webservices, entretanto, exige a “tipagem forte” dos parâmetros e retornos de cada um dos serviços disponibilizados.
A missão é “descobrir” quais os tipos de cada um dos parâmetros e o retorno deles para aí sim gerar o WSDL. Portanto gerar WSDL não é uma tarefa trivial, mas também não é tão difícil quanto encontrar bigode em elefante. Então, querido leitor, a construção de um WSDL pode ser feita em dois passos:
- Descobrir os tipos dos parâmetros e retornos dos serviços;
- Gerar o XML.
O ato de “descobrir” na verdade é “encontrar”. O desenvolvedor que implementou cada serviço deve indicar em algum lugar essas informações. No more magic, ok? Não somos magos, somos profissionais de TI. Um bom lugar de se colocar informações para o gerador de WSDL é a documentação dos métodos. Com notations atendemos essa necessidade e mantemos nosso código bem documentado. Com as informações dos tipos dos parâmetros e retornos dos serviços, nos resta a geração de WSDL. A geração do XML deve seguir os padrões W3C de descrição de serviços para webservice.
Lanço hoje o WSDLDocument!
A solução que divulgo aqui não é algo que não existia. Fiz isso - exclusivamente - para exercitar meus conhecimento e entender um pouquinho mais a estrutura desse bixano. Fontes de inspiração/transpiração:
Como percebido por alguns a classe WSDLDocument extende DOMDocument. Você instancia a classe e … vai planeta! A idéia é ter em mãos um XML mesmo, para que você possa - por exemplo - relacionar um arquivo XSLT pra deixar ele bonitinho no navegador. A idéia foi não ser invasivo e obrigar que você altere a arquitetura de sua aplicação. Ela deve ser vista como um funcionalidade a ser acoplada em sua aplicação.
Abaixo um exemplo de como utilizar a classe.
<?php
// generating the wsdl
$class = "MyWebserviceClass";
$url = "http://mydomain.com/?class=" . $class;
$wsdl = new WSDLDocument( $class, $url );
// showing the wsdl
echo $wsdl->saveXml();
<?php
class MyWebserviceClass
{
/**
* Transfering complex type.
*
* @param Person
* @return integer
*/
public function anyMethod( Person $type )
{
// ...
return 100;
}
/**
* Transfering array of complex type.
*
* @param integer
* @return Person[]
*/
public function another( $quantity )
{
$list = array();
for ( $i = 0; $i < $quantity; $i++ )
{
array_push( $list, new Person() );
}
return $list;
}
}
class Person
{
/**
*
* @var string
*/
public $name = "";
/**
*
* @var integer
*/
public $children = "";
}
Tentarei manter essa biblioteca atualizada. Sou mais enrolado que rocambole de goiaba amanhecido, portanto não garanto nada.
faça o download do WSDLDocument aqui
This post was made to release the WSDLDocument, a WSDL generator in PHP to webservices.
The way how some subjects are saying about TI hides the expert developer that exists inside a lot of professionals from our area. One of these subjects is webservices. It’s easy to do a client in PHP. But to do a server it’s necessary more work because the WSDL generation. Of course there are others things to look at during the development with webservices.
Why is to make WSDL in PHP difficult? A variable in PHP change its type during the script running. The webservices needs you declare the returns’ and arguments’ type.
The goal is look out it to generate the WSDL. To do this isn’t easy, but this isn’t as hard as find mustache on Elephant. So dear, the WSDL generation may be made with two steps:
- Find out the type of the parameters and returns of the services;
- Generate the XML.
The developer who implemented each service must to describe any where the types information. No more magic, ok? We’re not mage, we’re TI professionals. A good place to put it is the method documentation. The notations help us to solve this problem and keep our code well documented. With the types information we can generate the WSDL. The WSDL generation must to follow W3C stardards.
I release today the WSDLDocument!
This library isn’t a new thing. I did it - only - to improve my knowledges and to understand the WSDL structure. Some another libraries:
As someone may see the WSDLDocument extends DOMDocument. You create a instance of this and… go planet! You have a XML in your hand. You may - for example - link a XSLT file to show a bit beautiful on the browser. I didn’t want to be intrusive and oblige you change your framework. This have to be saw as a library to be put inside your application.
Above a sample how to use this library.
<?php
// generating the wsdl
$class = "MyWebserviceClass";
$url = "http://mydomain.com/?class=" . $class;
$wsdl = new WSDLDocument( $class, $url );
// showing the wsdl
echo $wsdl->saveXml();
<?php
class MyWebserviceClass
{
/**
* Transfering complex type.
*
* @param Person
* @return integer
*/
public function anyMethod( Person $type )
{
// ...
return 100;
}
/**
* Transfering array of complex type.
*
* @param integer
* @return Person[]
*/
public function another( $quantity )
{
$list = array();
for ( $i = 0; $i < $quantity; $i++ )
{
array_push( $list, new Person() );
}
return $list;
}
}
class Person
{
/**
*
* @var string
*/
public $name = "";
/**
*
* @var integer
*/
public $children = "";
}
I will try keep this library updated. I’m busiest this time, because this I don’t know what it’ll happen.
download the WSDLDocument here
Português
English
Jul 29, 2008 at 3:10 am
Webservice says,
Now, if you wish to update your PHP then the best way will be to upgrade PHP, using the old configuration (php. Webservice
Aug 6, 2008 at 2:17 pm
Cláudio Esperança says,
Olá Renan.
Obrigado por esta biblioteca… Faz precisamente o que disseste e de forma não intrusiva, excelente para o módulo de webservices que estou a desenvolver para o Moodle.
Tomei a liberdade de fazer algumas (pequenas) modificações na biblioteca: a primeira prende-se com a utilização do @method para documentar o que cada método de uma classe faz e inserir essa informação do wsdl; a segunda foi a inclusão da possibilidade de associar um xslt com o wsdl para que o navegador formate o output de acordo com este ficheiro.
Tomei a liberdade de colocar os ficheiros modificados no endereço http://rapidshare.com/files/135322692/WSDLDocument.tar.bz2 para que possas analisar se as alterações te interessam. Se não conseguires descarregar o ficheiro ou tiveres dúvidas sobre as modificações, envia-me uma mensagem de correio electrónico para endereço de email que associei a este comentário.
Obrigado mais uma vez por esta biblioteca.
Um abraço
Aug 6, 2008 at 4:11 pm
Renan de Lima says,
Legal Cláudio,
Eu inclusive também já alterei algumas coisas, em breve deve sair a 0.2 Os métodos estáticos estão indo pro wsdl. Outra novidade que virá é a documentação do método e da classe que serão incluídos no wsdl.
Quanto a folha de estilo xsl eu fiz assim:
# gera wsdl
$oWsdl = new WSDLDocument( “Classe”, “url” );
# aplica estilo
$oEstilo = $oWsdl->createProcessingInstruction( “xml-stylesheet”, “type=\”text/xsl\” href=\”url.xsl\”" );
$oWsdl->insertBefore( $oEstilo, $oWsdl->firstChild );
dessa forma não precisei alterar a classe
vou dar uma olhada nas suas alterações, vamos conversar pra incluir suas novidades e outras funcionalidades na biblioteca
Aug 19, 2008 at 9:48 am
Daniel Costa says,
Renan,
Porque você não divulga essa classe no PHP Classes?
Inclusive por lá eu poderia acompanhar as atualizações que você venha a fazer nela.
Fica a sugestão,
Um abraço!
Aug 19, 2008 at 10:04 am
Renan de Lima says,
Daniel e demais, optei por hospedar o projeto no GoogleCode. A url é:
http://code.google.com/p/wsdldocument
Lá tem todas as versões, documentação e dicas de uso da biblioteca.
Obrigado pela sugestão.