= sfReCaptcha plugin =

The `sfReCaptcha` plugin integrates the reCAPTCHA library in symfony.
It comes with a slightly modified version of the reCAPTCHA library, a custom validator and an example module which demonstrates the usage of the plugin.

For more information on reCAPTCHA visit [http://www.recaptcha.net recaptcha.net].

== Installation == 

First, go into your symfony project directory and install the plugin:

  {{{
  symfony plugin-install http://plugins.symfony-project.com/sfReCaptchaPlugin
  }}}

In order to use the reCAPTCHA or Mailhide service you must first sign up and get an API key. 
You can do this [http://recaptcha.net/api/getkey?app=php here] for reCAPTCHA or [http://mailhide.recaptcha.net/apikey here] for Mailhide.

'''Note:''' If you've created a host like `http://askeet/` for your application, the registration will fail because the reCAPTCHA service doesn't recognize it as a valid url. To handle this, simply rename your development host and attach a .tld to it (like `askeet.org`).

After you've got the keys, navigate to you applications `app.yml` file and paste them there:

	{{{
	all:
		recaptcha:
			publickey: "foo"
			privatekey: "bar"
		mailhide:
			publickey: "foo"
			privatekey: "bar"
	}}}

To use the example module that comes with the plugin, activate it in your applications `settings.yml` file:

	{{{
	all:
		.settings:
			enabled_modules:        [default, recaptcha]
	}}}

Then clear your cache:

  {{{
  symfony cc
  }}}

And finally, open the example in your web browser:

	{{{
	http://foobar.com/recaptcha
	}}}

Or for the Mailhide service:

	{{{
	http://foobar.com/recaptcha/mailhide
	}}}

== reCAPTCHA usage ==

To get a better knowledge of how the plugin works, take a look at the example module which is shipped with the plugin.
The `actions.class.php` is pretty simple and just needs to include the `recaptchalib.php`.

	{{{
	public function executeIndex()
	{
		if ($this->getRequest()->getMethod() == sfRequest::POST)
		{
			// captcha correct; do whatever you want here

			return sfView::SUCCESS;
		}

		require(dirname(__FILE__).'/../../../lib/recaptchalib.php');
	}

  public function handleErrorIndex()
  {
    return sfView::SUCCESS;
  }
	}}}

Please note not to include the library if the captcha is correct, since the `sfReCaptchaValidator` already includes the library and generates a `ReCaptchaResponse` instance. Reincluding will double instance it and result in a fatal error.

The template needs to have a form with a call to `recaptcha_get_html` and the publickey as well as the error returned by the validator as the parameters.

	{{{
	<?php use_helper('Validation'); ?>

	<?php echo form_tag('recaptcha/index'); ?>
		<?php echo recaptcha_get_html(sfConfig::get('app_recaptcha_publickey'), $sf_request->getError('recaptcha_response_field', null)); ?>
		<?php echo submit_tag('submit'); ?>
	</form>
	}}}

Now, the only thing left is to validate the reCAPTCHA. Create a validation file for your action (here `index.yml`).

	{{{
	fields:
		recaptcha_response_field:
			sfReCaptchaValidator:
	}}}

The `sfReCaptchaValidator` is included in the plugin. 

That's it, your reCAPTCHA should work now. 

== Mailhide usage ==

Mailhide is even simpler to use than reCAPTCHA.
Just make sure you include the `recaptchalib.php` in your action.

	{{{
	public function executeMailhide()
	{
		require_once(dirname(__FILE__).'/../../../lib/recaptchalib.php');
	}
	}}}

and in you template, call the `recaptcha_mailhide_html` function with your Mailhide API keys and the email address you wish to hide:

	{{{
	<?php echo recaptcha_mailhide_html(sfConfig::get('app_mailhide_publickey'), sfConfig::get('app_mailhide_privatekey'), "foo@bar.de"); ?>
	}}}

== Notes ==

Since the reCAPTCHA php library uses global variables which doesn't work with symfony, the library shipped with this plugin is slightly modified in order to make it work. sfReCaptchaPlugin 1.0.0 includes version 1.6 of the reCAPTCHA php library.