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
Copyright¶
Extension Key: sr_freecap
Copyright 2005-2018, 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.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/.
Change Log¶
See: https://forge.typo3.org/projects/extension- sr_freecap/repository/revisions/master/entry/ChangeLog
EXT: freeCap CAPTCHA - 9