.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ==================== 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: ((generated)) ============= .. _Table-of-Contents: 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: Copyright ========= Extension Key: **sr\_freecap** Copyright 2005-2018, Stanislas Rolland, 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: 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: Introduction ============ .. _What-does-it-do: 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: 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: Support ------- Please report issues on TYPO3 Forge: `http://forge.typo3.org/projects/show/extension-sr\_freecap `_ .. _Users-Manual: Users Manual ============ Extension freeCap CAPTCHA (extension key: sr\_freecap)is a library for use by other extensions. .. _Installing-the-extension: 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: Inserting the CAPTCHA in an Extbase/Fluid plugin ------------------------------------------------ .. _Adding-the-CAPTCHA-to-the-domain-model: 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: 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}
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: :: .. _Translating-the-wrong-CAPTCHA-string-error: 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 a “pi\_base” plugin -------------------------------------------- .. _Inserting-the-CAPTCHA-in-the-HTML-template: Inserting the CAPTCHA in the HTML template ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Insert in your HTML template a subpart marker similar to the following: ::
###SR_FREECAP_IMAGE### ###SR_FREECAP_ACCESSIBLE###
The source of this example subpart may be found in file: Ext:sr\_freec ap/Resources/Private/Partials/CaptchaHtmlTemplateInsert.html. .. _Invoking-the-CAPTCHA-methods: Invoking the CAPTCHA methods ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _Class-instantiation: 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: 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: 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: Configuration ============= .. _TYPO3-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: 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. .. ### BEGIN~OF~TABLE ### .. _imageHeight: imageHeight ^^^^^^^^^^^ .. container:: table-row 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: imageAdditionalWidth ^^^^^^^^^^^^^^^^^^^^ .. container:: table-row 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: maxWordLength ^^^^^^^^^^^^^ .. container:: table-row 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: textHorizontalPosition ^^^^^^^^^^^^^^^^^^^^^^ .. container:: table-row 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: textVerticalPosition ^^^^^^^^^^^^^^^^^^^^ .. container:: table-row 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: textColor ^^^^^^^^^ .. container:: table-row 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: colorMaximumDarkness ^^^^^^^^^^^^^^^^^^^^ .. container:: table-row 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: colorMaximumLightness ^^^^^^^^^^^^^^^^^^^^^ .. container:: table-row 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: fontFiles ^^^^^^^^^ .. container:: table-row 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: imageFormat ^^^^^^^^^^^ .. container:: table-row 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: useWordsList ^^^^^^^^^^^^ .. container:: table-row 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: generateNumbers ^^^^^^^^^^^^^^^ .. container:: table-row 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: defaultWordsList ^^^^^^^^^^^^^^^^ .. container:: table-row 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: maxAttempts ^^^^^^^^^^^ .. container:: table-row Property maxAttempts Data type int+ Description Maximum attempts: Maximum times a user can refresh the image. Default 100 .. _backgroundType: backgroundType ^^^^^^^^^^^^^^ .. container:: table-row 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: backgroundBlur ^^^^^^^^^^^^^^ .. container:: table-row 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: backgroundMorh ^^^^^^^^^^^^^^ .. container:: table-row Property backgroundMorh Data type boolean Description Background morphing: If enabled, the background will be morphed (recommended). Default 0 .. _mergeWithBackground: mergeWithBackground ^^^^^^^^^^^^^^^^^^^ .. container:: table-row 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: morphFactor ^^^^^^^^^^^ .. container:: table-row 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: salutation ^^^^^^^^^^ .. container:: table-row 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: accessibleOutput ^^^^^^^^^^^^^^^^ .. container:: table-row 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: accessibleOutputImage ^^^^^^^^^^^^^^^^^^^^^ .. container:: table-row 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 .. ###### END~OF~TABLE ###### .. _TypoScript-Setup: 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: 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: Change Log ========== See: `https://forge.typo3.org/projects/extension- sr\_freecap/repository/revisions/master/entry/ChangeLog `_ |img-1| EXT: freeCap CAPTCHA - 9 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102