Web Services em PHP

APIs para a web moderna

Lorna Jane Mitchell

Novatec

Authorized Portuguese translation of the English edition of titled PHP Web Services, ISBN 9781449356569
2013 Lorna Jane Mitchell. This translation is published and sold by permission of O'Reilly Media, Inc.,
the owner of all rights to publish and sell the same.
Traduo em portugus autorizada da edio em ingls da obra PHP Web Services, ISBN 9781449356569
2013 Lorna Jane Mitchell. Esta traduo publicada e vendida com a permisso da O'Reilly Media,
Inc., detentora de todos os direitos para publicao e venda desta obra.
Novatec Editora Ltda. [2013].
Todos os direitos reservados e protegidos pela Lei 9.610 de 19/02/1998. proibida a reproduo
desta obra, mesmo parcial, por qualquer processo, sem prvia autorizao, por escrito, do autor e da
Editora.
Editor: Rubens Prates
Traduo: Lcia Ayako Kinoshita
Reviso tcnica: Aurelio Jargas
Reviso gramatical: Marta Almeida de S
Editorao eletrnica: Carolina Kuwabata
ISBN: 978-85-7522-369-7
Histrico de impresses:
Junho/2013

Primeira edio

Novatec Editora Ltda.

Rua Lus Antnio dos Santos 110
02460-000 So Paulo, SP Brasil
Tel.: +55 11 2959-6529
Fax: +55 11 2950-8869
E-mail: novatec@novatec.com.br
Site: www.novatec.com.br
Twitter: twitter.com/novateceditora
Facebook: facebook.com/novatec
LinkedIn: linkedin.com/in/novatec
VC20130610

captulo 1

HTTP

HTTP o acrnimo de HyperText Transfer Protocol (Protocolo de Transferncia de Hipertexto), e a base sobre a qual a web est construda.
Toda transao HTTP consiste em uma solicitao e uma resposta. O protocolo HTTP por si s composto de vrias partes: a URL para a qual a
solicitao foi direcionada, o verbo usado, outros cabealhos e cdigos
de status e, claro, o corpo das respostas, que o que geralmente vemos
quando navegamos pela web usando um navegador.
Ao navegar pela web, no plano ideal, experimentamos uma jornada tranquila, passando pelos vrios locais que queremos visitar. No entanto isso
representa um contraste marcante com o que est acontecendo por trs das
cortinas, medida que fazemos essa jornada. Ao prosseguirmos, clicando
em links ou fazendo o navegador criar solicitaes para ns, uma srie de
pequenos passos ocorre nos bastidores. Cada passo composto de um
par solicitao/resposta; o cliente (geralmente, seu navegador ou telefone,
se voc estiver navegando na web) faz uma solicitao ao servidor, e o
servidor processa a solicitao e envia a resposta de volta. A cada passo
ao longo do caminho, o cliente faz uma solicitao e o servidor envia a
resposta.
Como exemplo, insira o endereo http://oreilly.com/ em um navegador e voc
ver uma pgina semelhante quela mostrada na figura 1.1; as informaes desejadas podero ser encontradas na pgina, ou os hiperlinks nessa
pgina nos direcionaro para o caminho em direo a elas.
A pgina de web chega no corpo da resposta HTTP, mas ela conta somente parte da histria. O restante est em outros locais no trfego HTTP.
Considere os exemplos a seguir.
14

Captulo 1 HTTP

15

Figura 1.1 Pgina inicial da OReilly.

Cabealho da solicitao:
GET / HTTP/1.1
User-Agent: Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.8 (KHTML, like Gecko)
Chrome/23.0.1246.0 Safari/537.8
Host: oreilly.com
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-GB,en-US;q=0.8,en;q=0.6

Cabealho da resposta:
HTTP/1.1 200 OK
Date: Thu, 15 Nov 2012 09:36:05 GMT
Server: Apache
Last-Modified: Thu, 15 Nov 2012 08:35:04 GMT
Accept-Ranges: bytes
Content-Length: 80554
Content-Type: text/html; charset=utf-8
Cache-Control: max-age=14400
Expires: Thu, 15 Nov 2012 13:36:05 GMT
Vary: Accept-Encoding

16

Web Services em PHP

Como voc pode ver, h uma quantidade enorme de outras informaes

teis sendo trocadas via HTTP, que geralmente no so vistas quando
usamos um navegador. Compreender essa separao entre cliente e servidor, e os passos executados pelos pares solicitao e resposta, fundamental para entender o HTTP e trabalhar com web services. Aqui est
um exemplo do que acontece quando consultamos o Google procura
de kittens (gatinhos):

1. Fazemos uma solicitao para http://www.google.com/ e a resposta con-

tm um cabealho Location e um cdigo de status igual a 301 que nos

envia para uma pgina regional de pesquisas; para mim, essa pgina
http://www.google.co.uk/ (no Brasil, http://www.google.com.br).

2. O navegador segue a instruo de redirecionamento (sem confirmao do usurio; os navegadores redirecionam por padro), faz
uma solicitao para http://www.google.co.uk/ e recebe a pgina com a
caixa de pesquisas (Somente por diverso, veja o cdigo-fonte dessa
pgina. H muita coisa acontecendo!). Ns preenchemos o campo
e acionamos a pesquisa.

3. Fazemos uma solicitao para https://www.google.co.uk/search?q=kittens

(com mais alguns parmetros) e obtemos uma resposta que mostra
os resultados de nossa pesquisa.

Na histria mostrada aqui, todas as solicitaes foram feitas pelo navegador, em resposta a aes do usurio, embora algumas ocorram nos bastidores, tais como seguir os redirecionamentos ou solicitar componentes
adicionais. Todos os componentes de uma pgina, como imagens, folhas
de estilo e outros, so acessados por meio de solicitaes separadas, tratadas por um servidor. Qualquer contedo carregado assincronamente
(pelo JavaScript, por exemplo) tambm gera mais solicitaes. Quando
trabalhamos com APIs, ns nos aproximamos mais das solicitaes e as
fazemos de modo mais deliberado, mas os mecanismos so os mesmos
que usamos para criar pginas de web bem bsicas. Se voc j estiver
criando sites, ento j deve conhecer tudo o que necessrio para criar
web services!

Captulo 1 HTTP

17

Clientes e servidores
Anteriormente, neste captulo, falamos sobre uma solicitao e uma resposta entre um cliente e um servidor. Quando criamos sites usando PHP,
a parte em PHP sempre corresponde ao servidor. Quando usamos APIs,
construmos o servidor em PHP, mas podemos tambm consumir APIs
a partir do PHP. aqui que a situao comea a ficar confusa. Podemos
criar tanto um cliente quanto um servidor em PHP, e as solicitaes e as
respostas podem ser tanto de entrada quanto de sada ou ambas!
Quando construmos um servidor, seguimos padres semelhantes
maneira pela qual criamos pginas de web. Quando uma solicitao
chega, usamos o PHP para descobrir o que foi solicitado e elaboramos
a resposta correta. Por exemplo, se desenvolvssemos uma API para que
os clientes pudessem obter atualizaes sobre seus pedidos de maneira
programtica, estaramos construindo um servidor.
Usar o PHP para consumir APIs significa que estamos criando um cliente.
Nosso aplicativo PHP faz solicitaes a servios externos via HTTP e,
ento, usa as respostas para seus prprios propsitos. Um exemplo de
um cliente poderia ser uma pgina que busca seus tutes mais recentes
e os apresenta.
No incomum que um aplicativo seja ambos, um cliente e um servidor,
conforme mostrado na figura 1.2. Um aplicativo que aceite uma solicitao
e, em seguida, chame outros servios para obter as informaes de que
necessita para gerar a resposta estar atuando tanto como cliente quanto
como servidor.

Figura 1.2 Aplicativo da web atuando como um servidor para o usurio, mas tambm
como cliente para acessar outras APIs.

18

Web Services em PHP

Quando estiver trabalhando em aplicativos como esse, tome cuidado
com a maneira pela qual voc d nome s variveis que envolvam
a palavra request (solicitao) para evitar confuso!

Fazendo solicitaes HTTP

H algumas maneiras diferentes de se comunicar via HTTP. Nesta seo,
abordaremos trs delas: Curl, ferramentas em seu navegador e o prprio
PHP. A ferramenta que voc escolher depender totalmente de sua experincia e do que voc est tentando realizar. Tambm daremos uma
olhada em ferramentas para inspecionar e depurar o HTTP no captulo 9.
Os exemplos aqui utilizam um site que est configurado para registrar as
solicitaes feitas a ele (http://requestb.in), o que perfeito para explorar a
forma como diferentes solicitaes de API so vistas por um servidor. Para
us-lo, acesse o site e crie um novo request bin (continer de solicitaes).
Voc ver a URL necessria para a qual dever fazer solicitaes e ser
redirecionado para uma pgina que mostra o histrico das solicitaes
feitas a esse continer.
Outra maneira excelente de tentar fazer diferentes tipos de solicitaes
usar os endereos reservados (http://example.com, http://example.net e http://
example.org), definidos pelo IANA (Internet Assigned Numbers Authority)
em http://www.iana.org/domains/special.

Curl
O Curl uma ferramenta de linha de comando disponvel em todas as
plataformas. Ele nos permite fazer qualquer solicitao imaginvel de web
em qualquer formato, repetir essas solicitaes e observar, com detalhes,
quais informaes, exatamente, so trocadas entre cliente e servidor. Com
efeito, a sada de exemplo no incio deste captulo foi gerada pelo Curl.
uma ferramenta brilhante e rpida para inspecionar o que est acontecendo com uma solicitao web, particularmente quando lidamos com
aquelas que esto fora do escopo usual de um navegador.

Captulo 1 HTTP

19

Em sua forma mais bsica, uma solicitao Curl pode ser feita desta
maneira (substitua as URLs pelas suas):
curl http://requestb.in/example

Podemos controlar todos os aspectos da solicitao a ser enviada; alguns

dos recursos mais comumente usados sero apresentados aqui e usados
ao longo de todo este livro para ilustrar e testar as vrias APIs mostradas.
Se voc j criou sites antes, ento saber a diferena entre solicitaes GET
e POST usadas na criao de formulrios web. A mudana entre GET, POST e
outros verbos HTTP usando Curl realizada por meio da opo -X, de
modo que uma solicitao POST pode ser feita especificamente usando o
comando a seguir:
curl -X POST http://requestb.in/example

Existem algumas opes teis que podem ser usadas para obter mais informaes do Curl, alm do corpo da resposta. Experimente usar a opo
v, pois ela mostrar de tudo: cabealhos das solicitaes, cabealhos das
respostas e todo o corpo da resposta! Porm ela divide a resposta, enviando as informaes de cabealho para STDERR e o corpo para STDOUT.
Se a resposta for razoavelmente extensa, poder ser difcil encontrar uma
determinada informao quando estiver usando Curl. Para ajudar nesse
caso, possvel combinar o Curl com outras ferramentas, como o less ou
o grep; contudo o Curl mostra uma barra de progresso na sada quando
est em operao normal, o que pode causar confuso para essas outras
ferramentas. Para inibir a barra de progresso, utilize a opo s (mas
tome cuidado, pois ela tambm inibe a apresentao dos erros do Curl).
Pode ser produtivo usar -s em combinao com v para criar uma sada
que possa ser enviada a um paginador, como o less, para que ela possa
ser examinada de modo detalhado, por meio de um comando como este:
curl -s -v http://requestb.in/example 2>&1 | less

O 2>&1 extra est presente para enviar a sada de STDERR para STDOUT,
de modo que voc possa ver os cabealhos e o corpo; por padro, somente
o STDOUT seria visvel ao less.
Trabalhar com a web em geral, e com APIs em particular, significa trabalhar com dados. O Curl nos permite fazer isso de algumas maneiras

20

Web Services em PHP

diferentes. O modo mais simples enviar os dados juntamente com uma

solicitao em pares chave/valor exatamente como ocorre quando um
formulrio submetido na web utilizando a opo d. A opo usada
tantas vezes quantos forem os campos a serem includos:
curl -X POST http://requestb.in/example -d name="Lorna" -d email="lorna@example.
com" -d message="gostei desse tal HTTP"

As APIs aceitam seus dados em diferentes formatos; s vezes, os dados

no podem ser POSTados como um formulrio, mas devem ser criados em
formato JSON ou XML, por exemplo. Em casos como esse, todo o corpo
de uma solicitao pode ser organizado em um arquivo e passado para
o Curl. Inspecione a solicitao anterior, e voc ver que seu corpo foi
enviado como:
name=Lorna&email=lorna@example.com&message=gostei desse tal HTTP

Em vez de enviar os dados como pares chave/valor na linha de comando,

eles podem ser colocados em um arquivo chamado data.txt (por exemplo).
Esse arquivo pode, ento, ser fornecido sempre que a solicitao for feita.
Essa tcnica especialmente til para evitar linhas de comando muito
extensas ao trabalhar com uma grande quantidade de campos, e ao enviar
dados que no so de formulrios, tais como JSON ou XML. Para usar o
contedo de um arquivo como corpo de uma solicitao, fornecemos o
nome do arquivo precedido por @ com uma nica opo d para o Curl:
curl -X POST http://requestb.in/example -d @data.txt

Trabalhar com os recursos estendidos do HTTP exige a capacidade de

trabalhar com vrios cabealhos. O Curl permite enviar qualquer cabealho desejado ( por isso que, do ponto de vista de segurana, nunca
podemos confiar no cabealho!), usando a opo H, seguida do cabealho
completo a ser enviado. O comando para definir o cabealho Accept para
solicitar uma resposta HTML :
curl -H "Accept: text/html" http://requestb.in/example

Antes de passar do Curl para outras ferramentas, vamos dar uma olhada
em mais um recurso: como lidar com cookies. Os cookies sero discutidos
com mais detalhes em um captulo posterior, mas, por enquanto, importante saber que os cookies so armazenados pelo cliente e enviados com
as solicitaes, e que novos cookies podem ser recebidos juntamente com

Captulo 1 HTTP

21

cada resposta. Os navegadores enviam cookies com as solicitaes como

comportamento padro, mas no Curl preciso fazer isso manualmente,
pedindo ao Curl que armazene os cookies em uma resposta e depois os
utilize na prxima solicitao. O arquivo que armazena os cookies chama-se "cookie jar (pote de biscoitos); est claro que at mesmo os geeks em
HTTP possuem senso de humor.
Para receber e armazenar cookies de uma solicitao digite:
curl -c cookiejar.txt http://requestb.in/example

A essa altura, cookiejar.txt pode ser alterado da maneira que voc julgar
adequada (novamente, nunca confie em informaes provenientes de fora
do aplicativo!) e, em seguida, enviado ao servidor com a prxima solicitao que voc fizer. Para isso, use a opo b e especifique o arquivo no
qual os cookies podero ser encontrados:
curl -b cookiejar.txt http://requestb.in/example

Para capturar cookies e envi-los novamente junto a cada solicitao, use

as opes -b e -c, fazendo referncia ao mesmo arquivo cookiejar. Dessa
maneira, todos os cookies de entrada sero capturados e enviados para
um arquivo e sero enviados de volta ao servidor em qualquer solicitao
subsequente, comportando-se exatamente como em um navegador.

Ferramentas para navegadores

Todas as verses mais recentes dos navegadores modernos (Chrome, Firefox, Opera, Safari, Internet Explorer) possuem ferramentas embutidas ou
plug-ins disponveis para ajudar a inspecionar o HTTP que estiver sendo
transferido; para servios simples, talvez voc ache que as ferramentas de
seu navegador sejam uma maneira acessvel de trabalhar com uma API.
Essas ferramentas variam entre os navegadores e so constantemente
atualizadas, mas aqui esto algumas ferramentas favoritas para que voc
possa ter uma ideia.
No Firefox, essa funcionalidade proporcionada pelo Developer Toolbar
(Barra de Ferramentas do Desenvolvedor) e por vrios plug-ins. Muitos
desenvolvedores de web esto familiarizados com o FireBug (http://getfirebug.com/), que possui algumas ferramentas teis, mas h outra ferramenta
desenvolvida especificamente para mostrar todos os cabealhos de todas

22

Web Services em PHP

as solicitaes feitas pelo seu navegador: o LiveHTTPHeaders (http://livehttpheaders.mozdev.org/). Ao us-lo, podemos observar todos os detalhes
de cada solicitao, conforme pode ser visto na figura 1.3.

Figura 1.3 LiveHTTPHeaders mostrando detalhes do HTTP.

Todos os navegadores oferecem alguma maneira de inspecionar e alterar

os cookies que estiverem sendo usados para solicitaes em um determinado site. No Chrome, por exemplo, essa funcionalidade oferecida por
uma extenso que se chama Edit This Cookie (Editar este cookie) e por
outras extenses similares. Ela mostra os cookies j criados e permite que
voc os edite ou apague e tambm permite adicionar novos cookies. D
uma olhada nas ferramentas de seu navegador favorito e veja os cookies
enviados pelos sites que voc visita com mais frequncia.
s vezes, cabealhos adicionais devem ser includos em uma solicitao,
como, por exemplo, quando enviamos cabealhos de autenticao ou
cabealhos especficos para indicar ao servio que queremos fazer uma
depurao extra. Com frequncia, o Curl ser a ferramenta correta para
esse tipo de tarefa, mas tambm possvel adicionar os cabealhos em
seu navegador. Diferentes navegadores possuem diferentes ferramentas;
no Chrome, experimente usar uma extenso chamada ModHeader, vista
na figura 1.4.

Captulo 1 HTTP

23

Figura 1.4 O plug-in ModHeader no Chrome.

PHP
No de se surpreender que haja mais de uma maneira de lidar com solicitaes HTTP usando PHP, e cada um dos frameworks tambm oferece
suas prprias contribuies. Esta seo est focada no PHP bsico e analisa
trs diferentes maneiras de trabalhar com APIs: usando a extenso Curl
que j vem com o PHP, usando a extenso pecl_http e fazendo chamadas
HTTP usando o tratamento de streams do PHP.
Anteriormente neste captulo, discutimos uma ferramenta de linha de
comando chamada Curl (veja Curl na pgina 18). O PHP possui seus
prprios wrappers (empacotadores) para o Curl, portanto podemos usar
a mesma ferramenta de dentro do PHP. Uma solicitao GET simples tem
o seguinte aspecto:
<?php
$url = "http://oreilly.com";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

O exemplo anterior representa o modo mais simples, definindo a URL,

fazendo uma solicitao para sua localizao (por padro, essa uma
solicitao GET) e capturando a sada. Observe o uso de curl_setopt();
essa funo usada para definir vrias opes diferentes sobre o

24

Web Services em PHP

funcionamento do Curl e possui uma documentao excelente e bastante

abrangente em http://php.net. Nesse exemplo, ela foi usada para configurar a
opo CURLOPT_RETURNTRANSFER para true, o que faz o Curl retornar os resultados
da solicitao HTTP, em vez de apresent-los. Na maioria dos casos, essa
opo deve ser usada para capturar a resposta, em vez de deixar que o
PHP a ecoe medida que ocorrer.
Podemos usar essa extenso para fazer todos os tipos de solicitaes HTTP,
incluindo enviar cabealhos personalizados, enviar dados no corpo e
usar diferentes verbos para fazer nossa solicitao. D uma olhada neste
exemplo, que envia alguns campos de formulrio e um cabealho ContentType com a solicitao POST:
<?php
$url = "http://requestb.in/example";
$data = array("name" => "Lorna", "email" => "lorna@example.com");
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

Novamente, curl_setopt() usado para controlar os vrios aspectos da

solicitao que enviamos. Nesse caso, uma solicitao POST feita configurando-se a opo CURLOPT_POST com 1 e passando os dados que pretendemos
enviar na forma de um array para a opo CURLOPT_POSTFIELDS. Tambm
definimos um cabealho Content-Type, que indica ao servidor o formato
em que esto os dados do corpo; os vrios cabealhos sero discutidos
com mais detalhes no captulo 3.
A extenso Curl do PHP no a interface mais fcil de ser usada, embora
tenha a vantagem de estar disponvel de maneira confivel. Uma tima
alternativa, caso voc controle suas prprias plataformas, adicionar a
extenso pecl_http do PECL (http://pecl.php.net/package/pecl_http). Ela oferece
uma maneira muito mais intuitiva de trabalhar e possui tanto funes
quanto interfaces orientadas a objetos. Por exemplo, aqui est o exemplo
anterior, dessa vez usando pecl_http:

Captulo 1 HTTP

25

<?php
$url = "http://requestb.in/example";
$data = array("name" => "Lorna", "email" => "lorna@example.com");
$request = new HTTPRequest($url, HTTP_METH_POST);
$request->setPostFields($data);
$request->setHeaders(array("Content-Type" => "application/json"));
$request->send();
$result = $request->getResponseBody();

Essa extenso funciona de maneira mais elegante por meio da criao de

um objeto HTTPRequest, em seguida trabalhando com as propriedades desse
objeto, antes de chamar seu mtodo send(). Uma vez que a solicitao tiver
sido enviada, o corpo da resposta ser acessado por meio da chamada ao
mtodo getResponseBody().
Por fim, vamos dar uma olhada em mais uma maneira de fazer solicitaes
HTTP a partir do PHP: usando as capacidades do PHP de lidar com streams, juntamente com as funes de arquivo. Em sua forma mais bsica,
isso significa que, se allow_url_fopen estiver habilitado (consulte o manual
do PHP em http://www.php.net/manual/en/filesystem.configuration.php#ini.allow-url-fopen), ser possvel fazer uma solicitao GET usando file_get_contents():
<?php
$result = file_get_contents("http://oreilly.com");

Podemos tirar vantagens do fato de o PHP conseguir lidar com uma variedade de protocolos diferentes (HTTP, FTP, SSL e outros) e com arquivos usando streams. As solicitaes GET simples so fceis, mas e quando
houver algo mais complicado? Aqui est um exemplo que faz a mesma
solicitao POST com cabealhos, ilustrando como usar vrios aspectos da
funcionalidade de streams:
<?php
$url = "http://requestb.in/example";
$data = array("name" => "Lorna", "email" => "lorna@example.com");
$context = stream_context_create(array(
'http' => array(
'method' => 'POST',

26

Web Services em PHP

'header' => array('Accept: application/json',
'Content-Type: application/x-www-form-urlencoded'),
'content' => http_build_query($data)
)
));
$result = file_get_contents($url, false, $context);

As opes so definidas como parte do contexto que criamos para determinar como a solicitao dever funcionar. Em seguida, quando o PHP
abrir o stream, ele usar as informaes fornecidas para determinar como
lidar corretamente com o stream incluindo enviar os dados fornecidos
e definir os cabealhos corretos.
Como voc pode observar, h algumas opes diferentes para lidar com
o HTTP, tanto a partir do PHP quanto da linha de comando, e voc ver
todas elas sendo usadas ao longo deste livro. Todas essas abordagens
esto voltadas para o PHP padro, mas se voc estiver trabalhando com
um framework, provavelmente ele ir oferecer algumas funcionalidades
parecidas; todos os frameworks estaro encapsulando um desses mtodos, portanto ser til ter um bom domnio do que est acontecendo
por dentro desses encapsulamentos. Aps experimentar vrios exemplos,
comum eleger um com o qual voc trabalhar mais do que com os
demais; todos eles podem executar a mesma tarefa, de modo que aquele
que voc eleger ser o resultado tanto de sua preferncia pessoal quanto
das ferramentas que estiverem disponveis (ou que podem se tornar disponveis) em sua plataforma.