EXT: freeCap CAPTCHA

Table of Contents

Copyright	2

Credits	2

Introduction	3

What does it do?	3

Requirements	3

Support	3

Users Manual	4

Installing the extension	4

Inserting the CAPTCHA in an Extbase/Fluid plugin	4

Adding the CAPTCHA to the domain model	4

Adding the CAPTCHA to the Fluid template	4

Translating the wrong CAPTCHA string error	5

Inserting the CAPTCHA in a “pi_base” plugin	5

Inserting the CAPTCHA in the HTML template	5

Invoking the CAPTCHA methods	5

Configuration	6

TYPO3 Configuration	6

TypoScript Constants	6

TypoScript Setup	8

Creating GD fonts	8

Change Log	9

Copyright

Extension Key: sr_freecap

Copyright 2005-2013, Stanislas Rolland, <typo3(arobas)sjbr.ca>

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.com

Credits

Open source scripts freeCap v1.4.1 and GD fontMaker v1 are authored by Howard Yeend.

This extension incorporates a wav files joining script roduced by Andreas Gohr.

This extension incorporates a script borrowed from extension Salutation Switcher (salutationswitcher) authored by Oliver Klee.

The optional audio output feature is based on initial ideas by Philip Almeida.

Thanks to Thomas Schlüter for incorporating the use of TYPO3 API for session data handling.

Introduction

What does it do?

Extension freeCap CAPTCHA (extension key: sr_freecap) is a library that integrates into the TYPO3 framework the open source script freeCap v1.4.1.

Citing the author of freeCap: «It can be used to prevent comment spam, guestbook spam, automated signups or any area of your website where you fear the evil spammers may target.»

The extension provides Fluid view helpers that allow to integrate the CAPTCHA into an Extbase/Fluid plugin.

The extension aso provides an API that allows to add the CAPTCHA on a frontend form rendered by a “pi_base” plugin.

The extension features optional audio output in order to produce an accessible CAPTCHA.

The extension also includes an Extbase backend module to create GD font files that are used to create the CAPTCHA images.

For more information on CAPTCHA, see http://en.wikipedia.org/wiki/Captcha.

Requirements

Version 2.0.1 requires TYPO3 6.0.5 and PHP 5.3.

Version 2.0.0 requires TYPO3 6.0.0 and PHP 5.3.

Version 1.3.0 is the last version that will work with TYPO3 4.3-4-7.

Version 1.2.2 is the last version that will work with TYPO3 4.0-4.2.

Version 0.2.3 is the last version of this extension that will work with TYPO3 3.7-3.8.

The extension requires PHP to be compiled with gd. The use of GDlib by TYPO3 should also be properly configured with the TYPO3 Install Tool.

The audio rendering feature requires PHP to be compiled with the mcrypt module and requires the file system to be configured to support utf-8 file names ([SYS][UTF8filesystem] must be set using the TYPO3 Install Tool).

In order for the audio captcha to work with IE8, [SYS][cookieDomain] must be set using the TYPO3 Install Tool.

Rendering of the audio version of the CAPTCHA may be blocked by IE8 depending on the browser seurity settings.

Support

Please report issues on TYPO3 Forge: http://forge.typo3.org/projects/show/extension-sr_freecap

Users Manual

Extension freeCap CAPTCHA (extension key: sr_freecap) is a library for use by other extensions.

Installing the extension

Install the extension using the Extension Manager.

A configuration variable allows to select the encryption algorithm to be used by the extension among the algorithms availlable on the PHP installation. This may be set with the Extension Manager.

The audio captcha rendering feature requires the file system to be configured to support utf-8 file names: [SYS][UTF8filesystem] must be set using the TYPO3 Install Tool.

In order for the audio captcha to work with IE8, [SYS][cookieDomain] must be set using the TYPO3 Install Tool.

Include static template “freeCap CAPTCHA” in the TypoScript template of the page on which the CAPTCHA is to be shown.

Some default values may be configured using the TS Template Constant Editor. See the Configuration section.

If the page containing the CAPTCHA is loaded inside an iframe contained in a page from another domain, then it may be necessary to add a P3P header for Internet Explorer. See the Configuration section.

Inserting the CAPTCHA in an Extbase/Fluid plugin

Adding the CAPTCHA to the domain model

Add the following field to your domain model class:

/**

* @var string

* @validate \SJBR\SrFreecap\Validation\Validator\CaptchaValidator

*/

protected $captchaResponse;

as well as the corresponding getter and setter functions:

/**

* Sets the captchaResponse

*

* @param string $captchaResponse

* @return void

*/

public function setCaptchaResponse($captchaResponse) {

$this->captchaResponse = $captchaResponse;

}

/**

* Getter for captchaResponse

*

* @return string

*/

public function getCaptchaResponse() {

return $this->captchaResponse;

}

Adding the CAPTCHA to the Fluid template

Add and adapt the following partial template to your Resources/Private/Partials directory as CaptchaElement.html:

{namespace freeCap=SJBR\SrFreecap\ViewHelpers}

<dt class="tx-srfreecap-captcha">

<label for="sjbr-freecap-captcha-response">{freeCap:translate(key: 'notice')} {freeCap:translate(key: 'explain')}</label>

</dt>

<dd>

<f:form.textfield id="sjbr-freecap-captcha-response" property="captchaResponse" size="15" title="{freeCap:translate(key: 'notice')}{freeCap:translate(key: 'explain')}" />

<freeCap:image />

<freeCap:audio />

</dd>

The source code of this partial may be found in file: Ext:sr_freecap/Resources/Private/Partials/CaptchaElement.html.

Insert the CAPTCHA element wherever you want in your Fluid template with the following line:

<f:render partial="CaptchaElement" />

Translating the wrong CAPTCHA string error

You may want to translate the error that is displayed when the wrong word is entered by the user. This may be done in the TypoScript setup of your plugin:

somePluginName._LOCAL_LANG.languageKey.error.code.9221561048 = translated-message-text

Inserting the CAPTCHA in a “pi_base” plugin

Inserting the CAPTCHA in the HTML template

Insert in your HTML template a subpart marker similar to the following:

<!--###CAPTCHA_INSERT### this subpart is removed if CAPTCHA is not enabled! -->

<div class="tx-your-extension-id-pi1-captcha">

<label for="tx_your_extension_id_pi1_captcha_response">###SR_FREECAP_NOTICE###</label>

<input type="text" size="15" id="tx_your_extension_id_pi1_captcha_response" name="tx_your_extension_id_pi1[captcha_response]" title="###SR_FREECAP_NOTICE###" value="">

###SR_FREECAP_IMAGE###

###SR_FREECAP_ACCESSIBLE###

</div>

<!--###CAPTCHA_INSERT###-->

The source of this example subpart may be found in file: Ext:sr_freecap/Resources/Private/Partials/CaptchaHtmlTemplateInsert.html.

Invoking the CAPTCHA methods

Class instantiation

The class SJBR\SrFreecap\PiBaseApi may be used in any TYPO3 front end plugin.

Insert statements similar to the following in order to instantiate it in your script:

if (t3lib_extMgm::isLoaded('sr_freecap')) {

$this->freeCap = t3lib_div::makeInstance('SJBR\\SrFreecap\\PiBaseApi');

}

For backward compatibility, 'tx_srfreecap_pi2' may be used in place of 'SJBR\SrFreecap\PiBaseApi'.

Filling the CAPTCHA subpart marker

Insert statements similar to the following in order to fill the CAPTCHA subpart marker:

if (is_object($this->freeCap)) {

$markerArray = array_merge($markerArray, $this->freeCap->makeCaptcha());

} else {

$subpartArray['###CAPTCHA_INSERT###'] = '';

}

Method makeCaptcha() returns a marker array with filled in values for markers: ###SR_FREECAP_NOTICE###, ###SR_FREECAP_IMAGE### and ###SR_FREECAP_ACCESSIBLE###.

Checking the input string against the CAPTCHA string

Insert statements similar to the following in order to validate the string entered by the user in the CAPTCHA input field:

if (is_object($this->freeCap) && !$this->freeCap->checkWord($your-form-data['captcha_response'])) {

do-something about-it

}

Method checkWord($string) returns true if the correct string was entered or false otherwise.

Configuration

TYPO3 Configuration

Include static template “freeCap CAPTCHA” in the TypoScript template of the page on which the CAPTCHA is to be shown.

In order for the audio captcha to work with IE8+, [SYS][cookieDomain] must be set using the TYPO3 Install Tool.

TypoScript Constants

Use the Constant Editor template tool to set these properties. If you are not using the Constant editor to configure the extension, you should analyze carefully the use of these constants in the default setup file.

Property:	Data type:	Description:	Default:
imageHeight	int+	CAPTCHA image height: height of the generated image in pixels. Note: Before changing this default, read section “Creating GD fonts”.	90
imageAdditionalWidth	int+	CAPTCHA image additional width: The width, in pixels, of the generated image is based on the maximum possible length of the word plus the value of this property.	30
maxWordLength	int[5-50]	Maximum word length: maximum length of the CAPTCHA string when randomly generated. Note: The minimum word length is 5. Therefore, the maximum word length cannot be lower than 5.	5
textHorizontalPosition	int+	Horizontal (X) starting position of the word relative to the left of the image, in pixels.	1
textVerticalPosition	int+	Vertical (Y) starting position of the word relative to the top of the image, in pixels.	15
textColor	boolean	Color of the text Possible values: 0 = one random color for all letters 1 = different random color for each letter	0
colorMaximumDarkness	int[0-255]	Maximum darkness of the text color: the lower the number, the darker the color of the text be may. In other words, this defines the lower boundary of each of the randomly-generated color components (r-g-b). Note: If no value is specified, a number will be applied depending on the type of background.	5
colorMaximumLightness	int[0-255]	Maximum lightness of the text color: the higher the number, the lighter the color of the text be may. In other words, this defines the upper boundary of each of the randomly-generated color components (r-g-b). Note: If no value is specified, a number will be applied depending on the type of background.	50
fontFiles	list of strings	List of GD font files: a coma-separated list of GD font files located in directory uploads/tx_srfreecap/ or in some extension directory using the usual syntax EXT:extensionKey/ etc. Note: A different default file is used when property generateNumbers is set: EXT:sr_freecap/Resources/Private/Captcha/Fonts/anonymous.gdf Note: The default fonts support only ASCII small letters. You may specify: EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_extended_font1.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_extended_font2.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_extended_font3.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_extended_font4.gdf These fonts will support ANSI-extended ASCII small letters (a-z, ß-ÿ) that may appear in word lists. These should be used if you are using a word list that contains non-ASCII letters. Note that GD supports only Latin1 and Latin2 character sets. Note: The default files provided with the extension were created for use on computers with little-endian architecture. If the computer on which TYPO3 is installed has a big-endian architecture, you will need to create your own GD font files. Note: You may use backend module GD Font Maker to create those files.	EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_font1.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_font2.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_font3.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_font4.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_font5.gdf
imageFormat	string	CAPTCHA image format: Format of the generated image. Possible values: png, gif, jpg Note: jpg does not support background transparency.	png
useWordsList	boolean	Use list of words: If enabled, the CAPTCHA string will be selected from a list of words. If not, it will be randomly generated. Note: See note on fontFiles property.	0
generateNumbers	boolean	Generate CAPTCHA with numbers only. This option is ignored if property useWordsList is enabled. Note: If this option is set, one must make sure that the font files can render numbers.	0
defaultWordsList	fileResource	Words list file for default language: All words lists should be in the same directory. Note: All words list files should be in the same directory as the default one. Note: The file name must end with .ht_default_freecap_words Note: If you create a file for another language, give it a similar name replacing “default” with the TYPO3 language code (and send it to the author of this extension!).	EXT:sr_freecap/Resources/Private/Captcha/Words/default_freecap_words
maxAttempts	int+	Maximum attempts: Maximum times a user can refresh the image.	100
backgroundType	string	Background type. Possible values: Transparent White with grid White with squiggles Morphed image blocks	White with grid
backgroundBlur	boolean	Background blurring: If enabled, the background will be blurred. The string should be easier to read.	0
backgroundMorh	boolean	Background morphing: If enabled, the background will be morphed (recommended).	0
mergeWithBackground	boolean	Merge string with background: If enabled, the CAPTCHA string will be merged with any non-transparent background. The string should be more difficult to read.	0
morphFactor	decimal	Text morphing factor: Morphing factor applied to each character of the CAPTCHA string. Note: for example, could be .8 or 1.1 Note: larger than 1 could make the text difficult to read.	0.1
salutation	string	If set, should be either 'formal' or 'informal'. Note: this property will change the salutation mode used in the labels displayed in the front end, provided that this is meaningful in the language being displayed and that translators have provided the informal version.	
accessibleOutput	boolean	Include audio output for accessible CAPTCHA: If set, the audio output feature will be enabled. Note: the property is silently ignored if PHP is not compiled with the mcrypt module. Note: In order for the audio captcha to work with IE8, [SYS][cookieDomain] must be set using the TYPO3 Install Tool. Note: Rendering of the audio version of the CAPTCHA may be blocked by IE8 depending on the browser seurity settings.	0
accessibleOutputImage	fileResource	Accessible output image: File name of the accessible output image. The image is displayed next to the CAPTCHA image. Clicking on the image produces an audio version of the CAPTCHA word or number. Note: If the property is null, a clickable localized textual message will be used instead of an image.	EXT:sr_freecap/Resources/Public/Images/ audio.png

TypoScript Setup

If the page containing the CAPTCHA is loaded inside an iframe contained in a page from another domain, then it may be necessary to add a P3P header for Internet Explorer. This may be done by adding the following line to the setup field of the TypoScript template of the page containing the CAPTCHA:

config.additionalHeaders = P3P: CP="NON CUR OUR NOR"

Creating GD fonts

The frontend scripts use GD font files. GD fonts do not scale well. Therefore, if you want to change the height of the CAPTCHA image, you will probably need to create some GD font files to replace the default files provided with the extension.

The backend module GD Font Maker is automatically installed and made available to admin users when the the extension is installed.

The module allows to create a GD font file from a ttf font file (True Type Font).

The default font files were created with characters width of 34 and characters height of 50.

Words lists may contain words with accents or other language-dependent characters. GD supports only Latin1 and Latin2 character sets. You may need to create your GD fonts from True Type fonts that can render such characters. The extension provides some font files supporting all ANSI-extended ASCII small letters (a-z, ß-ÿ). See fontFiles property in TypoScript Constants section.

The structure of a GD font file has a dependency on computer architecture. You need to create your GD font files with the endianness corresponding to the endianness of the computer on which TYPO3 is installed. The default font files were created for little-endian computer architecture.

The font files created by the module will be inserted in directory uploads/tx_srfreecap/.

Change Log

See: http://forge.typo3.org/projects/extension-sr_freecap/repository/entry/trunk/ChangeLog

EXT: freeCap CAPTCHA - 9

EXT: freeCap CAPTCHA

Stanislas Rolland

2008-01-08T21:34:16