DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: freeCap CAPTCHA

Author:Stanislas Rolland
Created:2008-01-08T21:34:16
Changed by:Stanislas Rolland
Changed:2018-10-18T19:48:47.370000000
Email:typo3(arobas)sjbr.ca
Info 2:Stanislas Rolland
Info 3:
Info 4:

EXT: freeCap CAPTCHA

((generated))

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

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.5.0 requires TYPO3 9 LTS.

Version 2.4.4 is the last version that will work with TYPO3 7 LTS or TYPO3 8 LTS.

Version 2.3.1 is the last version that will work with TYPO3 6.2 LTS.

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 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 security settings.

The backend GD Font Maker module requires the PHP configuration directive zend.multibyte to be set to On.

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.

Since PHP 5.4, the GD Font Maker backend module requires the PHP directive zend.multibyte to be set to On. This has to be set in php.ini, root .htaccess, httpd.conf or .user.ini, because the setting zend.multibyte is of type PHP_INI_PERDIR (see http://php.net/manual/en/configuration.changes.modes.php ). If zend.multibyte is not enabled, the BE module will not be enabled.

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_freec ap/Resources/Private/Partials/CaptchaHtmlTemplateInsert.html.

Invoking the CAPTCHA methods

Class instantiation

The class SJBRSrFreecapPiBaseApi 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 ‘SJBRSrFreecapPiBaseApi’.

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.

imageHeight

Property

imageHeight

Data type

int+

Description

CAPTCHA image height: height of the generated image in pixels.

Note: Before changing this default, read section “Creating GD fonts”.

Default

90

imageAdditionalWidth

Property

imageAdditionalWidth

Data type

int+

Description

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.

Default

30

maxWordLength

Property

maxWordLength

Data type

int[5-50]

Description

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.

Default

5

textHorizontalPosition

Property

textHorizontalPosition

Data type

int+

Description

Horizontal (X) starting position of the word relative to the left of the image, in pixels.

Default

1

textVerticalPosition

Property

textVerticalPosition

Data type

int+

Description

Vertical (Y) starting position of the word relative to the top of the image, in pixels.

Default

15

textColor

Property

textColor

Data type

boolean

Description

Color of the text

Possible values:

0 = one random color for all letters

1 = different random color for each letter

Default

0

colorMaximumDarkness

Property

colorMaximumDarkness

Data type

int[0-255]

Description

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.

Default

5

colorMaximumLightness

Property

colorMaximumLightness

Data type

int[0-255]

Description

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.

Default

50

fontFiles

Property

fontFiles

Data type

list of strings

Description

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_fon t1.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freecap_exten ded_font2.gdf, EXT:sr_freecap/Resources/Private/Captcha/Fonts/freeca p_extended_font3.gdf, EXT:sr_freecap/Resources/Private/Captcha/Font s/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, such as the default French or German word lists. 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.

Default

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

Property

imageFormat

Data type

string

Description

CAPTCHA image format: Format of the generated image.

Possible values: png, gif, jpg

Note: jpg does not support background transparency.

Default

png

useWordsList

Property

useWordsList

Data type

boolean

Description

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.

Default

0

generateNumbers

Property

generateNumbers

Data type

boolean

Description

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.

Default

0

defaultWordsList

Property

defaultWordsList

Data type

fileResource

Description

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!).

Default

EXT:sr_freecap/Resources/Private/Captcha/Words/default_freecap_word s

maxAttempts

Property

maxAttempts

Data type

int+

Description

Maximum attempts: Maximum times a user can refresh the image.

Default

100

backgroundType

Property

backgroundType

Data type

string

Description

Background type.

Possible values:

Transparent

White with grid

White with squiggles

Morphed image blocks

Default

White with grid

backgroundBlur

Property

backgroundBlur

Data type

boolean

Description

Background blurring: If enabled, the background will be blurred. The string should be easier to read.

Default

0

backgroundMorh

Property

backgroundMorh

Data type

boolean

Description

Background morphing: If enabled, the background will be morphed (recommended).

Default

0

mergeWithBackground

Property

mergeWithBackground

Data type

boolean

Description

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.

Default

0

morphFactor

Property

morphFactor

Data type

decimal

Description

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.

Default

0.1

salutation

Property

salutation

Data type

string

Description

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.

Default

accessibleOutput

Property

accessibleOutput

Data type

boolean

Description

Include audio output for accessible CAPTCHA: If set, the audio output feature will be enabled.

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.

Default

0

accessibleOutputImage

Property

accessibleOutputImage

Data type

fileResource

Description

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.

Default

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. However, if the PHP configuration option zend.multibyte is not enabled, the BE module will not be enabled.

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/.