{"id":21597397,"url":"https://github.com/cleantalk/cleantalk-api-docs-check-bot-example","last_synced_at":"2025-05-05T22:07:47.897Z","repository":{"id":218025578,"uuid":"743379865","full_name":"CleanTalk/cleantalk-api-docs-check-bot-example","owner":"CleanTalk","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-28T11:59:04.000Z","size":50,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-24T18:08:52.397Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CleanTalk.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-15T05:26:54.000Z","updated_at":"2024-10-24T07:28:18.000Z","dependencies_parsed_at":"2024-02-02T15:46:59.412Z","dependency_job_id":"416b7d7b-e06b-484d-af6a-9c87036da9e6","html_url":"https://github.com/CleanTalk/cleantalk-api-docs-check-bot-example","commit_stats":null,"previous_names":["cleantalk/docs_api_check_bot","cleantalk/cleantalk-api-docs-check-bot-example"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanTalk%2Fcleantalk-api-docs-check-bot-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanTalk%2Fcleantalk-api-docs-check-bot-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanTalk%2Fcleantalk-api-docs-check-bot-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CleanTalk%2Fcleantalk-api-docs-check-bot-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CleanTalk","download_url":"https://codeload.github.com/CleanTalk/cleantalk-api-docs-check-bot-example/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235481686,"owners_count":18997121,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-24T18:08:55.666Z","updated_at":"2025-01-24T17:40:32.864Z","avatar_url":"https://github.com/CleanTalk.png","language":"PHP","readme":"This guideline will help you to use CleanTalk check_bot API method via the special library that can be downloaded from this repo.\n## Usage\n1. Download the lib and unpack it to your website filesystem. Look at the suggested files structure with unpacked data highlighted:\n\u003cbr\u003e\u003cbr\u003e![files_structure.png](files_structure.png)\n   \u003cbr\u003e\u003cbr\u003e\n2. Add the CleanTalk Bot-detector JS library wrapper `https://moderate.cleantalk.org/ct-bot-detector-wrapper.js` as `\u003cscript\u003e`tag to the HTML page contains the form you want to protect.\n```html\n\u003cscript src=\"https://moderate.cleantalk.org/ct-bot-detector-wrapper.js\"\u003e\u003c/script\u003e\n```\n3. Fill the [config.php](src%2FCleantalk%2Fconfig.php). \n```php\nsrc/FCleantalk/config.php\n```\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Obligatory properties are:\n   * access_key - your CleanTalk Anti-Spam access key. If you do not have a key, [register the new account](https://cleantalk.org/register?utm_source=github\u0026utm_medium=article\u0026utm_campaign=instructions\u0026utm_content=link\u0026utm_term=create+account) or [access dashboard](https://cleantalk.org/my?utm_source=github\u0026utm_medium=referral\u0026utm_campaign=bot_detector\u0026utm_content=link\u0026utm_term=dashboard) to an existing account to get it.\n   * trust_cleantalk_decision - set this to true if you do not want to set custom checking settings\n\n4. To start use CheckBot library, include \"yourpath/src/autoloader.php\" into the top of codepage where you want to perform the check.\n```php\nrequire_once 'yourpath/src/autoloader.php';\n```\n5. Then create a new CleanTalk\\CheckBot object, provide $_POST or filtered POST data to the constructor.\n\n```php\n$bot_checker = new \\Cleantalk\\CheckBot($_POST);\n```\n\n6. Then perform the check:\n```php\n$is_bot = $bot_checker-\u003echeck()-\u003egetVerdict();\n```\n\n7. Then do the actions depending on the verdict.\n```php\nif ( $is_bot ) {\n  die ($bot_checker-\u003egetBlockMessage());\n}\n```\n\n8. How it looks in the suggested files structure:\n- `index.html`:\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n   \u003chead\u003e\n   \u003cmeta charset=\"UTF-8\"\u003e\n   \u003ctitle\u003eTitle\u003c/title\u003e\n   \u003c!--Bot-detector JS library wrapper. This script must be added to the HTML of the page.--\u003e\n   \u003cscript src=\"https://moderate.cleantalk.org/ct-bot-detector-wrapper.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n   \u003cform method=\"post\" action=\"your_form_handler.php\"\u003e\n      \u003clabel for=\"search_field\"\u003eWhat do you search?\u003c/label\u003e\n      \u003cinput type=\"text\" name=\"search_field\" id=\"search_field\" /\u003e \u003cbr /\u003e\n      \u003cinput type=\"submit\" /\u003e\n   \u003c/form\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n- `your_form_handler.php`:\n```php\n\u003c?php\n//your_libs\\cleantalk_check_bot\\src\nrequire_once 'your_libs/cleantalk_check_bot/src/autoloader.php';\n\nif ( empty($_POST) ) {\n    return;\n} else {\n    handle_search_form($_POST);\n}\n\n/**\n * Main search from handler.\n * @param $post\n * @return void\n */\nfunction handle_search_form($post)\n{\n    if ( empty($post['search_field']) ) {\n        return;\n    }\n\n    //create a new CheckBot object \n    $bot_checker = new \\Cleantalk\\CheckBot($post);\n\n    //call visitor check and make decision\n    $is_bot = $bot_checker-\u003echeck()-\u003egetVerdict();\n    if ( $is_bot ) {\n        die ($bot_checker-\u003egetBlockMessage());\n    }\n\n    //implement your further search form handlers here replacing echo\n    echo('You searched for this: ' . $post['search_field']);\n}\n```\n## Config setup explanation\n\n### Default config.php\n```php\n\u003c?php\nglobal $check_bot_config;\n$check_bot_config = array(\n    'access_key' =\u003e \"\",\n    'trust_cleantalk_decision' =\u003e true,\n    'block_no_js_visitors' =\u003e true,\n    'common_block_message' =\u003e 'Visitor blocked. It seems to be a bot.',\n    'bot_expectation' =\u003e 0.5,\n    'ip_frequency_24hour' =\u003e 50,\n    'ip_frequency_1hour' =\u003e 15,\n    'ip_frequency_10min' =\u003e 5,\n    'do_log' =\u003e false\n);\n```\n\n### Common params\n\n- `access_key (string)`\n  \u003cbr\u003e\u003cbr\u003e\nYour CleanTalk Anti-Spam access key.\n  \u003cbr\u003e\u003cbr\u003e\n- `trust_cleantalk_decision (bool)`\n  \u003cbr\u003e\u003cbr\u003e\nSet this to true if you do not want to set custom checking settings. Applicable in the most cases. \n  \u003cbr\u003e\u003cbr\u003e\n- `block_no_js_visitors (bool)`\n  \u003cbr\u003e\u003cbr\u003e\nSet this to true if you want to block any visitor that could not execute JS script (bot-like behavior). Applicable in the most cases.\n  \u003cbr\u003e\u003cbr\u003e\n- `common_block_message (string)`\n  \u003cbr\u003e\u003cbr\u003e\nA message for blocked visitor.\n  \u003cbr\u003e\u003cbr\u003e\n- `do_log (bool)`\n  \u003cbr\u003e\u003cbr\u003e\nSet to true if you want to see the log in the PHP error log, false otherwise.\n\n### Custom params\n\u003cem\u003eParams below affected only if the property \"trust_cleantalk_decision is set to false.\u003c/em\u003e\n\n- `bot_expectation`\n\u003cbr\u003e\u003cbr\u003e\nSet maximum bot probability percentage. For example, 0.5 is 50%. If CleanTalk API responsed with bot_expectation 0.53 - visitor will be blocked, if 0.47 - passed.\n\u003cbr\u003e\u003cbr\u003e\n- `ip_frequency_24hour`,`ip_frequency_1hour`,`ip_frequency_10min`\n\u003cbr\u003e\u003cbr\u003e\nCustom checks - set how to block a visitor whose IP address detected by CleanTalk service in the period. For example, if CleanTalk response contains ip_frequency_24hour = 1000, and the config property ip_frequency_24hour = 500, visitor will be blocked.\n\n## How to test\n1. Disable JavaScript implementation in your web-browser. If the param `trust_cleantalk_decision` is set to `true`, you are blocked when you try to send the form.\n2. Install the solution on a dev site with visiting opened. Then set the param `do_log` to `true`. You will see how the CheckBot works in the PHP error log.\n\n## Examples\nExamples of the form with CheckBot integrated can be found in the `/examples` folder. Note: the examples does not contain the lib itself.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcleantalk%2Fcleantalk-api-docs-check-bot-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcleantalk%2Fcleantalk-api-docs-check-bot-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcleantalk%2Fcleantalk-api-docs-check-bot-example/lists"}