Captcha Plugin Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.

This utility provides CAPTCHA verification in the MODX Manager login and elsewhere.

Captcha uses the following System Settings:

Setting Usage
captcha.enabled If set, CAPTCHA is used for Manager login (off when installed)
captcha.use_mathstring If set, the image is a simple equation for the user to solve (on when installed)
captcha.words Selection of words used for the image if captcha_use_mathstring is off
captcha.height Height of image (default: 80)
captcha.width Width of image (default: 200)
captcha.words Words to use in CAPTCHA challenge


I recommend leaving the captcha.use_mathstring setting on. Bots have broken regular CAPTCHA images and they are no longer very secure. The mathstring option is much more difficult for them to get through.

You may add or delete fonts from the core/components/captcha/fonts directory as long as there is at least one .ttf file there.

You may add or delete images from the core/components/captcha/noise directory as long as there is at least one file there.

Locked out of the Manager by Captcha?

If for any reason Captcha locks you out of the Manager. You can disable it with these actions:

  • In the database, edit the modx_site_plugins table.
  • Click on the "name" field heading to sort by plugin name.
  • Edit the Captcha plugin record and set the disabled field to 1.
  • Click on the "Go" button.
  • Also in the database, edit the modx_system_settings table.
  • Click on the "key" field heading to sort the list.
  • Edit the captcha.enabled record and set the value to 0.
  • Click on the "Go" button.
  • In File Manager, delete all files in the core/cache directory.

At this point, you should be able to log in to the MODX Manager.

Captcha can also be used in other login forms that require captcha.

You can roll your own function by placing the code below where you want the CAPTCHA image to appear and then, when processing the form, comparing the user's input to the $_SESSION['veriword'] variable.

<img src="[[++assets_path]]components/captcha/captcha.php" alt="Captcha Image" />

See the code in the core/components/captcha/captcha.plugin.php file.


My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book may still be available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting

  —  Bob Ray