Package: PHP OAuth API

Na primeira parte deste artigo, vimos que o OAuth é um protocolo muito usado para acessar APIs de determinados sites em nome dos usuários desses sites. Apesar de ele ser relativamente fácil de explicar, não é fácil implementá-lo sem lidar com as dores de cabeça das múltiplas configurações do protocolo, as versões de protocolos diferentes, os detalhes de implementações específicas do local e o pior de tudo: ter de saber mais do que gostaria dos detalhes do protocolo.

Depois de começar com os fundamentos (porque ele é necessário, como funciona e as implementações de consumo PHP OAuth), hoje continuaremos com a parte prática – como utilizar a classe PHP OAuth.

Utilizando a classe PHP OAuth API na prática

1. Não me faça aprender o protocolo OAuth

Esta classe de cliente PHP OAuth foi construída especificamente com a finalidade de que você obtenha velocidade sem conhecer muito sobre o funcionamento do protocolo.

É sempre bom saber como o protocolo funciona internamente, mas se você não tem tempo nem paciência, você não precisa conhecê-lo de modo extensivo.

Existem duas versões principais do protocolo OAuth em uso: a 1.0a e a 2.0. Mas não se preocupe, a classe abstrai todas as diferenças entre elas, para que você não tem que escrever múltiplas seções de código dependendo da versão do protocolo suportado pelo site provedor.

Também há diferenças de implementação e configuração ao acessar sites específicos de provedor OAuth. Na maioria dos casos, essas diferenças serão transparentes para você. A classe é inteligente o suficiente para lidar com pelo menos algumas dessas diferenças, de modo que você não tenha que lidar com elas em seu aplicativo.

Tudo o que você precisa saber é que a classe faz principalmente duas coisas: a) interage com um site de provedor de OAuth para obter um token de acesso, b) chama a API do site de provedor para executar uma função da API utilizando um token de acesso obtido anteriormente.

2. Introdução ao caso de uso de mapping approach

Antes de explicar como usar a classe para fins relacionados ao OAuth, para aqueles que gostam de estudar como as coisas funcionam internamente, pode ser legal dar uma olhada na abordagem que usei nessa classe e em outras que encapsulam funcionalidades do que chamo de componentes de nível de aplicação.

Caso prefira aprender com exemplo de código, você pode pular essa parte para a etapa chamada “Obtendo o Token de Acesso”.

A abordagem é chamada de mapping de caso de uso. Quando você precisa implementar um sistema de software e quando esse sistema é grande o suficiente, normalmente você vai dividi-lo em sub-sistemas. Cada sistema ou sub-sistema implementa um conjunto de casos de uso.

Os casos de uso são situações individuais com que seus sistemas precisam lidar para atingir seus objetivos. Algumas pessoas dão outros nomes para os casos de uso, como telas ou páginas. Por exemplo, em um sistema, podemos ter casos de uso como: página de registro, página de login, opções do usuário, entrega de newsletter etc.

Para aqueles familiarizados com modelagem de desenvolvimento agile, os casos de uso são semelhantes às histórias de usuários. Eu prefiro pensar em termos de casos de uso, porque às vezes você precisa lidar com as interações entre o seu sistema e um agente que não é um usuário real, como um sistema externo que o seu sistema precisa para se comunicar com o uso de algumas APIs.

Enfim, para a implementação real de casos de uso, eu projetei um padrão para implementá-las como classes. Cada caso de uso mapeia para uma classe, por isso o nome mapping de caso de uso para essa abordagem.

A classe cliente de OAuth foi implementada como uma classe de caso de uso. Neste artigo, só vou descrever as funções públicas e as variáveis de classes de casos de uso, pois é tudo que você precisa saber para usar a classe cliente de OAuth.

Basicamente, uma classe de caso de uso possui quatro funções públicas e duas variáveis públicas. Podem existir outras funções públicas e variáveis específicas para o propósito do caso de uso. Por agora, vou explicar o papel das funções públicas e variáveis básicas.

Funções

Initialize() – É a primeira função você precisa chamar após a criação de um objeto de classe. Não é uma função do construtor. É uma função que inicializa o objeto e avalia se certas condições obrigatórias são válidas, como estabelecer uma conexão com o banco de dados.

Essas condições obrigatórias são chamadas de pré-condições. Se uma ou mais pré-condição não for cumprida, a função retorna falso, e uma variável de erro é definida para explicar o motivo da falha ao desenvolvedor.

Process() – É a função onde toda a ação acontece. A sua função é a de processar qualquer entrada e preparar a geração de qualquer saída. Em geral, a saída final não deve ser gerada aqui.

Ela deve ser chamada apenas depois de chamar a função Initialize(). Se por algum motivo o processamento falhar, esta função retorna falso, e uma variável de erro é definida.

Finalize() – Esta função foi feita para limpar quaisquer recursos alocados durante as chamadas Initialize e Process. Normalmente, é utilizada para assegurar que certas condições sejam satisfeitas no final do caso de uso. Essas condições são chamadas de pós-condições. Gerar entradas de log de todos os eventos que aconteceram durante o processamento é um exemplo de uma pós-condição.

Esta função não deve ser chamada se a função Initialize falhou. É preciso um parâmetro que é geralmente o valor de retorno da chamada para a função de Process. Mais uma vez, se por algum motivo a finalização falhar, esta função retorna falso, e uma variável de erro é definida.

Output() – Este é o lugar onde qualquer saída se o caso de uso deve ser emitido. A saída pode ser gerada a partir de informação produzida durante a chamada para a função Process. Quando necessário, as variáveis de classe privada podem ser usadas para compartilhar informações entre as chamadas Process e Output.

Dessa forma, você pode implementar a separação de preocupações. Nenhuma saída acontece durante o processamento, ou qualquer processamento ocorre durante a produção.

Normalmente, a função Output não retorna nada, porque a saída é exibida para o usuário, mas em alguns casos ela pode retornar uma string com os dados de saída reais, caso seja conveniente.

Variáveis

$error – Esta é a variável que armazena uma mensagem de erro se qualquer uma das funções Initialize, Process e Finalize falhar. A mensagem de erro não é para ser exibida para os usuário, se sim para permitir que o desenvolvedor saiba por que ele falhou.

$exit – Esta variável booleana pode ser definida pela classe de caso de uso para dizer se o script deve sair imediatamente, sem retornar nada. Quando esta variável for verdadeira, o script deve sair sem chamar a função Output. Normalmente, isso significa que a classe emitiu cabeçalhos especiais, como aqueles que redirecionam o navegador para outra página.

3. Obtendo o token de acesso

OAuth é um protocolo complexo que exige acesso à API do site de provedor e redireciona o navegador do usuário para frente e para trás entre sites consumidores e provedores. Essa interação requer a definição de vários parâmetros, como as URLs do site de provedor para acessar cada coisa.

Felizmente, essa classe fornece suporte built-in de alguns dos sites provedores mais populares. Você só precisa definir uma única variável chamada $server com o tipo de servidor que você deseja acessar. Dessa forma, a classe configura automaticamente diversas de suas variáveis, de modo que você não tem que fazê-lo manualmente.

A classe fornece suporte built-in para muitos sites provedores. Outros serão acrescentados no futuro. No entanto, se você precisar acessar um servidor OAuth que é suportado diretamente pela classe, você ainda pode usar a classe para acessá-lo. Você só precisa configurar algumas variáveis manualmente.

Configurar a classe de acesso a esses outros servidores está fora do escopo deste artigo. Leia a documentação da classe para saber o que você precisa fazer. Fique à vontade para fazer perguntas no fórum de suporte da classe, se você tiver qualquer dificuldade.

Então, o seu do script básico de autorização OAuth começa assim:

$client = new OAuth_client_class;
$client->server = 'Twitter';

A próxima coisa que você precisa fazer é configurar a identidade de seus aplicativos. Primeiro, você precisa ir ao site provedor e registrar um aplicativo. O registro fornecerá os valores para o identificador e de um segredo do mesmo. Por razões de segurança, você não deve compartilhar esse segredo com ninguém.

$client->client_id = 'Application identifier goes here';
$client->client_secret = 'Application secret goes here';

Os servidores OAuth 2.0 podem deixar que você solicite a permissão para acessar seções específicas da API do site provedor. Essas permissões devem ser configuradas usando a variável $scope. Para sites provedores OAuth de 1.0, elas são normalmente configuradas na página de opções do aplicativo.

Os valores das permissões para solicitar dependem do site provedor. Você precisa verificar a documentação da API do do site provedor para determinar os valores de permissão que o seu aplicativo precisa.

$client->scope = 'API permissions list goes here';

Durante o processo de autorização OAuth, o navegador do usuário é redirecionado para o site provedor. Em seguida, o browser é redirecionado para o site consumidor, após o usuário conceder acesso ao seu aplicativo. O site provedor precisa saber para qual página o usuário deve ser redirecionado.

Normalmente, você pode configurar a URL da página para redirecionar o navegador do usuário para seu site consumidor usando a variável $redirect_uri. Alguns servidores exigem que essa URL esteja sob um domínio público válido. Assim, domínios privados podem não ser aceitos.

$client->redirect_uri = 'http://'.$_SERVER['HTTP_HOST'].
dirname(strtok($_SERVER['REQUEST_URI'],'?')).
'/change_this_to_the_name_of_this_script.php';

Agora você está pronto para iniciar o processo OAuth.

if(($success = $client->Initialize()))
{
  if(($success = $client->Process()))
  {

Depois de chamar a função Process, o processo de autorização OAuth pode ou não ter sido concluído. Caso tenha sido, a variável $access_token é definida como uma string não vazia.

Talvez você queira armazenar o valor do token de acesso em algum lugar para utilização posterior. Normalmente, aplicativos armazenam o token em um banco de dados para que eles possam usá-lo para chamar a API do site provedor depois, eventualmente quando o usuário não estiver presente.

Para sites provedores de OAuth 1.0a, existe um token com valor secreto adicional que você também precisa manter. Ele é armazenado na variável $access_token_secret.

if(strlen($client->access_token))
{
// Do something useful with the access token
}

Se houvesse um erro ao recuperar o token de acesso, a variável $authorization_error seria definida como a mensagem de erro.

 elseif(strlen($client->authorization_error))
 {
   $client->error = $client->authorization_error;
   $success = false;
 }
}

No final, sempre chame a função Finalize, independentemente de o processo de autorização ter sido concluído com sucesso ou não.

 $success = $client->Finalize($success);
}

Então, você precisa verificar a variável $exit para determinar se o seu script precisa sair imediatamente para que o processo OAuth possa funcionar corretamente.

if($client->exit)
 exit;

Se o processo foi concluído com sucesso, é legal que você mostre uma mensagem útil para o usuário.

if($client->access_token)
{
 echo '<h1>API access was authorized successfully!</h1>';
}

Seria legal também se você apresentasse mensagens úteis para o usuário, caso o processo tiver falhado por algum motivo.

if($client->authorization_error)
{
 echo '<h1>It was not possible to obtain API access',
      ' authorization!</h1>,
      '<p>Please <a href="?">try again</a>.</p>';
}

4. Chamando o fornecedor do site API

Depois de ter obtido o token de acesso, você pode chamar a API do site de provedor imediatamente, usando a função CallAPI logo após retornar da função Process e antes de chamar a função Finalize.

Alguns sites provedores também permitem o acesso a suas APIs em nome do usuário, mesmo quando o usuário não está presente. Você só precisa utilizar a função CallAPI passando os valores de $access_token e $access_token_secret obtidos anteriormente.

$client->access_token = 'Access token here';
$client->access_token_secret = 'Access token secret here';
$url =
  'https://api.twitter.com/1.1/account/verify_credentials.json';
$method = 'GET';
$parameters = array();
$options = array();
$success = $client->CallAPI($url, $method, $parameters, $options,
  $response)))

Os parâmetros $url e $method da chamada da API são definidos na documentação da API do site provedor. O parâmetro $options é um array com opções eventuais que você pode precisar definir para configurar a forma como a chamada da API é processada. Verifique essa documentação de classe para obter mais detalhes sobre essas opções.

O parâmetro $response retorna os resultados da chamada da API. Se os resultados forem formulário de URL codificada ou JSON codificado, o valor CallAPI decodifica a resposta para você.

Se a chamada API falhou devido a algum problema relacionado com os parâmetros ou com o token de acesso, a variável $access_token_error é definida como a mensagem de erro que você precisa verificar.

Conclusão

Apesar da complexidade do protocolo OAuth e suas diferentes implementações, essa classe tenta abstrair, tanto quanto possível, todos os detalhes para que os aplicativos exijam apenas uma quantidade mínima de código para obter autorização para chamar as APIs do site de provedor.

Em parte, essa simplificação do processo foi conseguida pela adição de suporte built-in para alguns OAuth mais populares baseados em servidores de APIs. Não é possível adicionar suporte built-in para todas as APIs existentes. No entanto, a classe continuará evoluindo para cobrir o máximo possível de APIs.

Outra parte da presente simplificação está relacionada ao fato de que a classe é auto-contida. Isso significa que você só precisa carregar essa classe para usar todas as funcionalidades fornecidas. A dependência externa está apenas em uma classe HTTP para enviar solicitações HTTP para o servidor web do provedor. Não existem outras classes que você precisa para usar toda a funcionalidade de cliente OAuth.

***

Texto original disponível em http://www.phpclasses.org/blog/package/7700/post/1-Painless-OAuth-with-PHP.html