SimpleCaptcha for mongoid and Rails 3
Pull request Compare This branch is 2 commits ahead of kares:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

This code is a fork


Copyright (c) 2008 [Sur]

Author: Sur

Original Contributors:, Kei Kusakari, nap

"Update" Contributors: Marek de Heus, Karol Bucek

Main Updates

Support for a lighter "backend" such as mini_magick seems desired, however mini_magick is not really an option due to it's nature of manipulating existing images (it's API cannot create an image from scratch). Besides RMagick doesn't play well with ruby platforms such as JRuby. Luckily, there still is an option called quick_magick that works on the command line similar to mini_magick but supports a richer API familiar to RMagick users.

This version of SimpleCaptcha introduces a notion of a configurable backend for generating captcha images. The default backend behaves, depending on RMagick, as the original plugin, but one might switch to another (built-in) quick_magick backend as required (or create it's own backend if in the need).

See SETUP / STEP 4 bellow for how to configure the backend.

Besides the plugin now works under Rails 3.0.0+ as well as Rails 2.2.3+ !

Other Updates

Merged changes from

This forked version is different in a few ways. I changed it so that the captcha validation is just that: another validation. This makes it much easier to use it in combination with things like resource_controller.

The original version does all kinds of method aliasing and requires you to write code specifically for handling the captcha validation. This version accepts the usual :if, :unless and :on options.

This version does not bypass the validation if in test mode. It behaves the same in all environments, allowing you to actually test it.

To disable the validations in test mode, You should now state it explicitly:

class User < ActiveRecord::Base
  validates_captcha :unless => lambda { Rails.env.test? }

NOTE: This will validate captcha every-time You do a !

There's an API that allows You to (temporary) disable captcha validation for classes, individual instances or even blocks :

User.captcha_validation = false # disables validation globally
user =
# force captcha validation for the given instance and block
user.captcha_validation(true) do!
# enable captcha validation for the given instance
# reset captcha validation - fallback to the class setting
user.captcha_validation(nil) # validates captcha if User.captcha_validation?

Old Validation

A backward compatible validation for Your model classes is as well available. The original captcha validation code was different from standard validation in a way that it did not validate the captcha on "regular" save calls, one has to explicitly state captcha validation is desired by calling save_with_captcha.

class User < ActiveRecord::Base
  apply_simple_captcha :message => 'WTF?!'

NOTE: The "old" behavior is emulated using the captcha_validation flags.


SimpleCaptcha is the simplest and a robust captcha plugin. Its implementation requires adding up a single line in views and in controllers/models. SimpleCaptcha is available to be used with Rails 2.0 or above and also it provides the backward compatibility with previous versions of Rails.


  • Zero FileSystem usage(secret code moved to db-store and image storage removed).
  • Provides various image styles.
  • Provides three level of complexity of images.
  • Works absolutely fine in distributed environment(session and db based implementation works fine in distributed environment).
  • Implementation is as easy as just writing a single line in your view. <%= show_simple_captcha %> within the 'form' tags.
  • Flexible DOM and CSS handling(There is a separate view partial for rendering SimpleCaptcha DOM elements).
  • Automated removal of 1 hour old unmatched simple_captcha data.


RMagick or quick_magick should be installed on your machine to use this plugin.


ruby script/plugin install git://


After installation, follow these simple steps to setup the plugin. The setup will depend on the version of rails your application is using.


for Rails 2.x :

script/generate simple_captcha

for Rails 3.x :

rails generate simple_captcha


rake db:migrate

STEP 3 (required only for Rails < 2.3.0)

add the following code into config/routes.rb :

ActionController::Routing::Routes.draw do |map|
  map.simple_captcha '/simple_captcha/:action', :controller => 'simple_captcha'

This is a mandatory route used for rendering the simple_captcha image on the fly without storing on the filesystem.

STEP 4 (Optional)

configure simple_captcha e.g. in app/config/initializers/simple_captcha.rb

SimpleCaptcha.backend = :quick_magick # default is :RMagick

SimpleCaptcha.image_options = {
    :image_color => 'white',
    :image_size => '110x30',
    :text_color => 'black',
    :text_font => 'arial',
    :text_size => 22
} # these are the defaults

Please note that some image options such as color might change when using some of the pre-built captcha image styles available.


Controller Based

Include SimpleCaptcha::ControllerValidation into Your captcha validating controller or put the include into app/controllers/application.rb

ApplicationController < ActionController::Base
  include SimpleCaptcha::ControllerValidation

in the view file within the form tags add this code

<%= show_simple_captcha %>

and in the controller's action authenticate it as

if simple_captcha_valid?
  do this
  do that

Model Based

In the view file within the form tags write this code

<%= show_simple_captcha(:object=>"user") %>

and in the model class include SimpleCaptcha::ModelValidation and setup the validation

class User < ActiveRecord::Base
  include SimpleCaptcha::ModelValidation

  validates_captcha :on => :create, :message => 'invalid captcha'

or if You prefer the old version which doesn't trigger the captcha validation on save (one have to call save_with_captcha)

class User < ActiveRecord::Base
  include SimpleCaptcha::ModelValidation

  apply_simple_captcha :message => :'invalid_captcha'

Options & Examples

View Options

  provides the custom text b/w the image and the text field,
  the default is "type the code from the image"

  Provides the specific image style for the captcha image.
  There are eight different styles available with the plugin as...
  1) simply_blue
  2) simply_red
  3) simply_green
  4) charcoal_grey
  5) embosed_silver
  6) all_black
  7) distorted_black
  8) almost_invisible

  See the included samples <>.
  You can also specify 'random' to select the random image style.

  Handles the complexity of the image. The :distortion can be set to 'low',
  'medium' or 'high'. Default is 'low'.

  the name of the object of the model class, to implement the model based

How to change the CSS for SimpleCaptcha DOM elements ?
You can change the CSS of the SimpleCaptcha DOM elements as per your need
in this file.
For Rails >= 2.0 the file wiil reside as...
For Rails < 2.0 the file will reside as...

View's Examples

Controller Based Example
  <%= show_simple_captcha(:label => "human authentication") %>

  <%= show_simple_captcha(:label       => "human authentication",
                          :image_style => 'embosed_silver') %>

  <%= show_simple_captcha(:label       => "human authentication",
                          :image_style => 'simply_red',
                          :distortion  => 'medium') %>

Model Based Example

  <%= show_simple_captcha(:object => 'user',
                          :label  => "human authentication") %>

Model Options

  provides the custom message on failure of captcha authentication
  the default is "Secret Code did not match with the Image"

  if set to true, appends the error message to the base.

Model's Example

  class User < ActiveRecord::Base
    apply_simple_captcha # the "old" way using save_with_captcha

  class User < ActiveRecord::Base
    validates_captcha :message => "Are you a bot?", :add_to_base => true