Esta página foi traduzida pela API Cloud Translation.

Como usar o reCAPTCHA com PHP

Importante: não há mais suporte para a versão 1.0 da API reCAPTCHA. Faça upgrade para a versão 2.0. Saiba mais

A biblioteca PHP do reCAPTCHA oferece uma maneira simples de colocar um CAPTCHA no seu site PHP, o que ajuda a impedir que bots abusem dele. A biblioteca encapsula a API reCAPTCHA.

Para usar o reCAPTCHA com PHP, faça o download da biblioteca reCAPTCHA PHP. Você só precisará de um arquivo a partir desse local (recaptchalib.php). Os outros arquivos são exemplos, arquivos README e conteúdo jurídico. Eles não afetam a funcionalidade.

Início rápido

Depois de se inscrever para receber as chaves de API, confira abaixo as instruções básicas para instalar o reCAPTCHA no seu site. Um guia de referência completo para o plug-in do PHP está disponível abaixo.

Lado do cliente (como fazer a imagem do CAPTCHA aparecer)

Se você quiser usar a biblioteca PHP para exibir o widget reCAPTCHA, será necessário inserir este snippet de código dentro do elemento <form> onde o widget reCAPTCHA será colocado:

  require_once('recaptchalib.php');
  $publickey = "your_public_key"; // you got this from the signup page
  echo recaptcha_get_html($publickey);

Com o código, seu formulário pode ficar assim:

  <html>
    <body> <!-- the body tag is required or the CAPTCHA may not show on some browsers -->
      <!-- your HTML content -->

      <form method="post" action="verify.php">
        <?php
          require_once('recaptchalib.php');
          $publickey = "your_public_key"; // you got this from the signup page
          echo recaptcha_get_html($publickey);
        ?>
        <input type="submit" />
      </form>

      <!-- more of your HTML content -->
    </body>
  </html>

Não se esqueça de definir $publickey substituindo your_public_key pela sua chave pública da API.

Observe que o valor do atributo "action" é "verify.php". Agora, "verify.php" é o arquivo de destino para onde os valores deste formulário são enviados. Portanto, você precisará de um arquivo verify.php no mesmo local que o html do cliente.

A função "require_once" no exemplo acima espera que recaptchalib.php esteja no mesmo diretório que o arquivo de formulário. Se ele estiver em outro diretório, será preciso vinculá-lo adequadamente. Por exemplo, se o recaptchalib.php estiver no diretório chamado "captcha", que está no mesmo nível do arquivo de formulário, a função vai ficar assim: require_once('captcha/recaptchalib.php').

Lado do servidor (como testar se o usuário inseriu a resposta certa)

O código a seguir deve ser colocado na parte superior do arquivo verify.php:

  <?php
  require_once('recaptchalib.php');
  $privatekey = "your_private_key";
  $resp = recaptcha_check_answer ($privatekey,
                                $_SERVER["REMOTE_ADDR"],
                                $_POST["recaptcha_challenge_field"],
                                $_POST["recaptcha_response_field"]);

  if (!$resp->is_valid) {
    // What happens when the CAPTCHA was entered incorrectly
    die ("The reCAPTCHA wasn't entered correctly. Go back and try it again." .
         "(reCAPTCHA said: " . $resp->error . ")");
  } else {
    // Your code here to handle a successful verification
  }
  ?>

No código acima:

recaptcha_check_answer retorna um objeto que representa se o usuário concluiu o desafio com sucesso.

Se $resp->is_valid for verdadeira, o desafio de captcha foi concluído corretamente, e você terá que continuar o processamento do formulário.

Se $resp->is_valid for falso, o usuário não forneceu o texto de captcha correto, e você precisará exibir o formulário novamente para permitir outra tentativa. Nesse caso, $resp->error será um código de erro que pode ser fornecido a recaptcha_get_html. Transmitir o código de erro faz com que o controle reCAPTCHA exiba uma mensagem explicando que o usuário digitou o texto incorretamente e precisa tentar de novo.

Observe que esse código está solicitando a chave private, o que não pode ser confundido com a chave pública. Você consegue essa informação na mesma página que a chave pública.

Verifique também se o formulário está configurado para obter as variáveis do formulário usando $_POST em vez de $_REQUEST e se o próprio formulário está usando o método POST.

Pronto. O reCAPTCHA agora deve estar funcionando no seu site.

Leitura complementar

Como personalizar a aparência

Dicas e diretrizes

Solução de problemas

Guia de referência do plug-in PHP

Veja abaixo uma lista abrangente de todos os métodos do plug-in reCAPTCHA PHP.

Função recaptcha_get_html

A função recaptcha_get_html exibe o HTML que apresenta o reCAPTCHA ao usuário.

recaptcha_get_html
Parâmetro
$pubkey -- string. obrigatória.	Sua chave pública reCAPTCHA na página de inscrição da API
$error -- string. opcional (null é o padrão)	Se essa string for definida, a área reCAPTCHA vai mostrar o código de erro fornecido. Esse código de erro vem de ReCaptchaResponse->$error
$use_ssl -- booleano. opcional (false é o padrão)	A API baseada em SSL deve ser usada? Se você estiver exibindo uma página ao usuário por SSL, defina essa opção como "true" para que uma caixa de diálogo de erro não apareça no navegador do usuário.
Valor de retorno	String com HTML que será colocado na página da Web.

Função recaptcha_check_answer

Depois que o usuário preenche o formulário HTML, incluindo a resposta para o captcha, queremos verificar a resposta quando ele envia o formulário usando a função recaptcha_check_answer. A resposta do usuário terá dois campos de formulário, recaptcha_challenge_field e recaptcha_response_field. A biblioteca reCAPTCHA faz uma solicitação HTTP para o servidor reCAPTCHA e verifica a resposta do usuário.

recaptcha_check_answer
Parâmetro
$privkey -- string. obrigatória.	Sua chave privada reCAPTCHA, na página de inscrição da API.
$remoteip -- string. obrigatória.	Endereço IP do usuário, no formato 192.168.0.1
$challenge -- string. obrigatório.	O valor do campo do formulário recaptcha_challenge_field
$response -- string. obrigatório	O valor do campo de formulário recaptcha_response_field
Valor de retorno	Uma instância da classe ReCaptchaResponse

ReCaptchaResponse
Campo
$is_valid -- booleano	O reCAPTCHA acreditava que a resposta era válida?
$error -- string	Se a resposta for inválida, qual foi o problema? Esse código do erro pode ser usado no recaptcha_get_html
Valor de retorno	O URL HTML ou bruto para decodificar o endereço de e-mail, dependendo da função que você chamou.

Corredor de correio

A biblioteca PHP do reCAPTCHA inclui vinculações para a API Mailhide. Essa API permite encapsular um e-mail em um reCAPTCHA para evitar que os criadores de spam o vejam: exame...@example.com.

A parte Mailhide da biblioteca PHP requer o módulo mcrypt do PHP.

A API Mailhide consiste em duas funções, recaptcha_mailhide_html e recaptcha_mailhide_url. As funções têm os mesmos parâmetros. A versão _html retorna códigos HTML que podem ser inseridos diretamente na sua página da Web. A parte do nome de usuário do e-mail que é transmitida é truncada e substituída por um link que chama o Mailhide. A versão "_url" fornece o URL para decodificar o e-mail e deixa para você colocar o e-mail em HTML.

recaptcha_mailhide_url / recaptcha_mailhide_html
Parâmetro
$pubkey -- string	A chave pública do Mailhide na página de inscrição
$privkey -- string	A chave privada do Mailhide na página de inscrição
$email -- string	O endereço de e-mail que você quer ocultar.

O exemplo a seguir mostra como usar o Mailhide:

<html><body>
<?
require_once ("recaptchalib.php");
// get a key at http://www.google.com/recaptcha/mailhide/apikey
$mailhide_pubkey = '';
$mailhide_privkey = '';
?>
The Mailhide encoding of example@example.com is
<?
echo recaptcha_mailhide_html ($mailhide_pubkey,
                              $mailhide_privkey,
                              "example@example.com");
?>.
<br>
The url for the email is:
<?
echo recaptcha_mailhide_url ($mailhide_pubkey,
                             $mailhide_privkey,
                             "example@example.com");
?>
<br>
</body></html>