sfReCaptchaLibPlugin
1.5.0stable
for sf 1.4sf 1.3 BSD
sfReCaptchaLibPlugin 1.5.1
This plug-in is a port of recaptchalib 1.11 to the Symfony PHP framework. It
features improved error handling and better integration than the other
reCAPTCHA plug-in provides.
Installation
The recommended method for installation is via the symfony command line:
symfony plugin:install sfReCaptchaLibPlugin
To manually install, perform the following steps:
- Extract the sfReCaptchaLibPlugin archive into the plugins/ directory. This
should leave you with a plugins/sfReCaptchaLibPlugin folder.
Edit the config/ProjectConfiguration.class.php and modify the setup() call
to enable the plugin:
public function setup()
{
...
$this->enablePlugins('sfReCaptchaLibPlugin'); // add this line
}
Clear your project's cache
symfony cc
Configuration
The plug-in looks in app.yml for your reCAPTCHA API keys:
all:
sf_recaptcha_plugin:
public_key: 'your-public-key-goes-here'
private_key: 'your-private-key-goes-here'
There is a third option that allows you to specify the location of the AJAX API.
By default, it is loaded from Google's CDN and thus you are guaranteed to always
get the most current version. If you need to load your own, use the js_dir
setting in app.yml:
all:
sf_recaptcha_plugin:
ajax_api: 'path_to/recaptcha_ajax.js'
Note that the path is relative to the web/js folder of your application.
Form Integration
Integrating reCAPTCHA into your Symfony forms is now easier than ever! After
installing the plug-in, you will need to edit your lib/form/BaseForm.class.php
so that it extends BaseReCaptchaForm, as shown below:
lib/form/BaseForm.class.php
// class BaseForm extends sfFormSymfony
class BaseForm extends BaseReCaptchaForm
{
}
Usage
Integrating reCAPTCHA into a standard form is easy:
- Ensure your form extends BaseForm.
In your form's configure() method, make sure the last line calls the parent
configure() method:
public function configure() {
// ... do your form configuration ...
parent::configure();
}
NOTE: This only needs to be done in forms that will use reCAPTCHA.
In your form template, make sure you output the _recaptcha_form widget:
<?php echo $form['_recaptcha_form']->render() ?>
AJAX API
If you want to use AJAX to trigger the reCAPTCHA rendering instead of the
widget, add a call to reCaptcha::enableAjax() in the action that uses the
AJAX API. This will give you a Recaptcha JavaScript object that you can use
to instantiate the reCAPTCHA form. Your code is going to look like this:
// use this snippet to show the form
<?php $recaptcha = $form['_recaptcha_form']->getWidget()->getReCaptcha(); ?>
// container-id is the HTML ID of the container that will hold the reCAPTCHA form
Recaptcha.create('<?php echo $recaptcha->getPublicKey() ?>', 'container-id', <?php echo $recaptcha->getJSON() ?>);
// if the HTML form gets hidden/destroyed (i.e. JQuery UI Dialog), put
// this in the close code to destroy the reCAPTCHA form.
Recaptcha.destroy();
Customizing Look and Feel
You can control the look and feel of reCAPTCHA by manually creating the
reCaptcha widget in your form and specifying the settings you want:
// .../form/myForm.class.php
class myForm extends BaseForm
{
public function configure()
{
// the widget MUST be named _recaptcha_form
$this->setWidget('_recaptcha_form', new sfWidgetFormReCaptcha(array(
'lang' => 'en',
'theme' => 'red',
'tabindex' => '0',
'custom_translations' => array(
// see Google's reCAPTCHA documentation for what you can specify here
),
'custom_theme_widget' => null, // HTML ID of container for reCAPTCHA custom widget
));
}
}
If you are using reCAPTCHA manually, the reCaptcha object has setter methods to
customize the look and feel of reCAPTCHA:
$recaptcha = new reCaptcha();
$recaptcha->setLanguage('en');
$recaptcha->setTheme('red');
$recaptcha->setCustomTranslations(array(
'instructions_visual' => 'Your text here'
));
$recaptcha->setTabIndex(0);
The settings are automatically rendered along with the rest of reCAPTCHA when
you call $recaptcha->getHTML(). You can also get the JSON representation using
$recaptcha->getJSON(), which is handy when using the AJAX API.
Other notes
The enableAjax() method must be called from somewhere in the action--either in
the action itself or in the action's template. It WILL NOT WORK in either a
component or a component template. The reason is that enableAjax() calls
sfContext::getInstance()->getResponse()->addJavascript() to add the AJAX API. By
the time components are called, the renderer has already finalized the list of
Javascripts and it is too late to make any changes to it.
I'm not completely sure what should be returned by the mailhideUrl() method in
the case of an error. Right now, it currently returns an empty string.
Developers
License
sfReCaptchaLibPlugin (c) 2011 Nathan Strong -- http://strong-consultants.com/
Derived directly from recaptchalib.php provided by reCAPTCHA. The original
copyright notice and license is included below, and applies to this Symfony
plug-in.
Copyright (c) 2007 reCAPTCHA -- http://recaptcha.net
AUTHORS:
Mike Crawford
Ben Maurer
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
sfReCaptchaLibPlugin 1.4.2
This plug-in is a port of recaptchalib 1.11 to the Symfony PHP framework. It
features improved error handling and better integration than the other
reCAPTCHA plug-in provides.
Installation
The recommended method for installation is via the symfony command line:
symfony plugin:install http://plugins.symfony-project.org/sfReCaptchaLibPlugin
To manually install, perform the following steps:
- Extract the sfReCaptchaLibPlugin archive into the plugins/ directory. This
should leave you with a plugins/sfReCaptchaLibPlugin folder.
Edit the config/ProjectConfiguration.class.php and modify the setup() call
to enable the plugin:
public function setup()
{
...
$this->enablePlugins('sfReCaptchaLibPlugin'); // add this line
}
Clear your project's cache
symfony cc
Configuration
The plug-in looks in app.yml for your reCAPTCHA API keys:
all:
sf_recaptcha_plugin:
public_key: 'your-public-key-goes-here'
private_key: 'your-private-key-goes-here'
There is a third option that allows you to specify the location of the AJAX API.
By default, it is loaded from Google's CDN and thus you are guaranteed to always
get the most current version. If you need to load your own, use the js_dir
setting in app.yml:
all:
sf_recaptcha_plugin:
ajax_api: 'path_to/recaptcha_ajax.js'
Note that the path is relative to the web/js folder of your application.
Usage
Integrating reCAPTCHA into a standard form is easy:
In your action:
$this->recaptcha = new reCaptcha();
if($request->getMethod() == sfRequest::POST)
{
$this->recaptcha->checkAnswer($request);
if($this->recaptcha->isValid())
// ...
}
In your view:
<?php echo $recaptcha->getHTML(ESC_RAW) ?>
What about the AJAX API? For example, the above does not work properly if you
try to put the reCAPTCHA into a JQuery UI dialog. Instead, you need to tell
your action to load the AJAX API, which gives you a Recaptcha JavaScript object.
The reCaptcha object provides a few methods to help you use the AJAX API:
reCaptcha::getPublicKey() // returns the public key for use in the Recaptcha.create() method
reCaptcha::enableAjax() // calls sfResponse->addJavascript() to add the AJAX API.
reCaptcha.getJSON() // gets the reCAPTCHA settings as a JavaScript object, also for Recaptcha.create()
An example using JQuery UI is shown below:
in your action:
reCaptcha::enableAjax();
$this->recaptcha = new reCaptcha();
$this->recaptcha->setTheme('blackglass');
in your view:
<div id="recaptcha-dialog" title="Recaptcha Demo">
<div id="recaptcha"></div>
</div>
<button id="open-recaptcha-dialog">Launch Demo...</button>
<script type="text/javascript">
$(function() {
$('#recaptcha-dialog").dialog({
width: 350,
height: 250,
autoOpen: false,
open: function() {
Recaptcha.create('<?php echo reCaptcha::getPublicKey() ?>', 'recaptcha', <?php echo $recaptcha->getJSON(ESC_RAW) ?>);
},
beforeClose: function() {
Recaptcha.destroy();
},
buttons: {
"Cancel": function() {
$(this).dialog("close");
}
}
});
$('#open-recaptcha-dialog').button().click(function() {
$('#recaptcha-dialog').dialog("open");
}
}
If you run this demo, then each time you open the dialog you should see a
different CAPTCHA, and they should be rendered using the blackglass theme.
Other notes
The enableAjax() method must be called from somewhere in the action--either in
the action itself or in the action's template. It WILL NOT WORK in either a
component or a component template. The reason is that enableAjax() calls
sfContext::getInstance()->getResponse()->addJavascript() to add the AJAX API. By
the time components are called, the renderer has already finalized the list of
Javascripts and it is too late to make any changes to it.
I'm not completely sure what should be returned by the mailhideUrl() method in
the case of an error. Right now, it currently returns an empty string.
