包简介

The best app to filter bots during the simple page viewing

README 文档

README

This guideline will help you to use CleanTalk check_bot API method via the special library that can be downloaded from this repo.

Usage

Install the package via composer

composer install cleantalk/php-checkbot

Include the composer autoloader into your app

require_once 'vendor/autoloader.php';

Add the CleanTalk Bot-detector JS library wrapper https://fd.cleantalk.org/ct-bot-detector-wrapper.js as <script>tag to the HTML page contains the form you want to protect.

<script src="https://fd.cleantalk.org/ct-bot-detector-wrapper.js"></script>

Prepare config and create a new CleanTalk\CheckBot object, provide $_POST or filtered POST data to the constructor.

$check_bot_config = array(
    'access_key' => "YOUR-CLEANTALK-API-KEY"
);
$config = new \Cleantalk\CheckBot\CheckBotConfig($check_bot_config);
$bot_checker = new \Cleantalk\CheckBot\CheckBot($config, $_POST);

Then perform the check:

$is_bot = $bot_checker->check()->getVerdict();

Then do the actions depending on the verdict.

if ( $is_bot ) {
  die ($bot_checker->getBlockMessage());
}

How it looks in the suggested files structure:

index.html:

<!DOCTYPE html>
<html lang="en">
   <head>
   <meta charset="UTF-8">
   <title>Title</title>
   <!--Bot-detector JS library wrapper. This script must be added to the HTML of the page.-->
   <script src="https://fd.cleantalk.org/ct-bot-detector-wrapper.js"></script>
</head>
<body>
   <form method="post" action="your_form_handler.php">
      <label for="search_field">What do you search?</label>
      <input type="text" name="search_field" id="search_field" /> <br />
      <input type="submit" />
   </form>
</body>
</html>

your_form_handler.php:

<?php

require_once 'vendor/autoload.php';

if ( empty($_POST) ) {
    return;
} else {
    handle_search_form($_POST);
}

/**
 * Main search from handler.
 * @param $post
 * @return void
 */
function handle_search_form($post)
{
    if ( empty($post['search_field']) ) {
        return;
    }

    //create a new CheckBot object 
    $check_bot_config = array(
      'access_key' => "YOUR-CLEANTALK-API-KEY"
    );
    $config = new \Cleantalk\CheckBot\CheckBotConfig($check_bot_config);
    $bot_checker = new \Cleantalk\CheckBot\CheckBot($config, $_POST);

    //call visitor check and make decision
    $is_bot = $bot_checker->check()->getVerdict();
    if ( $is_bot ) {
        die ($bot_checker->getBlockMessage());
    }

    //implement your further search form handlers here replacing echo
    echo('You searched for this: ' . $post['search_field']);
}

Config setup explanation

Available config array elements

<?php
$check_bot_config = array(
    'access_key' => "",
    'trust_cleantalk_decision' => true,
    'block_no_js_visitors' => false,
    'common_block_message' => 'Visitor blocked. It seems to be a bot.',
    'bot_expectation' => 0.5,
    'ip_frequency_24hour' => 50,
    'ip_frequency_1hour' => 15,
    'ip_frequency_10min' => 5,
    'do_log' => false
);

Common params

access_key (string)

Your CleanTalk Anti-Spam access key.
trust_cleantalk_decision (bool)

Set this to true if you do not want to set custom checking settings. Applicable in the most cases.
block_no_js_visitors (bool)

Set this to true if you want to block any visitor that could not execute JS script (bot-like behavior). Applicable in the most cases.
common_block_message (string)

A message for blocked visitor.
do_log (bool)

Set to true if you want to see the log in the PHP error log, false otherwise.

Custom params

Params below affected only if the property "trust_cleantalk_decision is set to false.

bot_expectation

Set 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.
ip_frequency_24hour,ip_frequency_1hour,ip_frequency_10min

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

How to test

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

Examples

Examples of the form with CheckBot integrated can be found in the /examples folder. Note: the examples does not contain the lib itself.

cleantalk/php-checkbot 适用场景与选型建议

cleantalk/php-checkbot 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 1 次下载、GitHub Stars 达 5，最近一次更新时间为 2026 年 03 月 23 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 cleantalk/php-checkbot 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 cleantalk/php-checkbot 我们能提供哪些服务？

定制开发 / 二次开发

基于 cleantalk/php-checkbot 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

cleantalk/php-checkbot

包简介