Code. Examples refactored.

Author: alexandergull

CleantalkValidate.php

@@ -27,19 +27,21 @@ You can unpack the archive with the plugin to the root of the site or install it
 composer require cleantalk/php-antispam
 ```
 
-### Sample SPAM test for text comment and user signup
+### Sample SPAM test for text comment
+
+Notice: You can use the example PHP file from <code>./examples/form_with_handler</code>
 
 ```php
 <?php
 session_start();
 
-$apikey = 'your_cleantalk_api_key';
+$apikey = '';
 $email_field = 'name_email_form_field';
 $user_name_field = 'name_user_name_form_field';
 $message_field = 'name_message_form_field';
 $type_form = 'contact'; // use 'signup' for user signup form
 
-// if downloaded, unzip and include the app:
+// if downloaded, unzip and include the app, take your own relative path:
 require_once 'php-antispam/cleantalk-antispam.php';
 // if install the app by composer package:
 use Cleantalk\CleantalkAntispam;
@@ -48,6 +50,19 @@ use Cleantalk\CleantalkAntispam;
 
 $cleantalk_antispam = new CleantalkAntispam($apikey, $email_field, $user_name_field, $message_field, $type_form);
 $api_result = $cleantalk_antispam->handle();
+if ($api_result) { // the check fired
+    if ($api_result->account_status !== 1) {
+        // something wrong with your key or license, to know why read $api_result->codes
+        echo 'Allowed. Spam protection disabled.'; // or do nothing
+    } else {
+        if ($api_result->allow === 1) {
+            echo 'Allowed. Spam protection OK.'; // or do nothing
+        } else {
+            die('Blocked. Spam protection OK. Reason: ' . $api_result->comment); // or make your own handler
+        }
+    }
+}
+// your further code flow here
 ?>
 
 <form method="post">

README.md

@@ -5,3 +5,4 @@
 require_once "lib/CleantalkRequest.php";
 require_once "lib/CleantalkResponse.php";
 require_once "lib/CleantalkAntispam.php";
+require_once "lib/CleantalkApi.php";

cleantalk-antispam.php

@@ -1,14 +1,9 @@
 <?php
 
-require_once "lib/Cleantalk.php";
-require_once "lib/CleantalkRequest.php";
-require_once "lib/CleantalkResponse.php";
-require_once "lib/CleantalkHelper.php";
-require_once "lib/CleantalkAPI.php";
-require_once "lib/cleantalk-php-patch.php";
+require_once "../../cleantalk-antispam.php";
 
 /**
- * Cleantalk example
+ * Cleantalk PHP example
  *
  * @package Cleantalk Example
  * @copyright (C) 2011 - 2025 CleanTalk team (https://cleantalk.org)
@@ -24,6 +19,10 @@
 // Take params from config
 $config_url = 'https://moderate.cleantalk.org';
 $auth_key   = ''; // Set Cleantalk auth key
+
+/**
+ * Key validation example.
+ */
 $validation = CleantalkAPI::method__notice_validate_key($auth_key, 'php-api');
 $validation = json_decode($validation) ? json_decode($validation) : false;
 $is_valid = is_object($validation) && $validation->valid;

example.php renamed to examples/direct_php/example.php

@@ -0,0 +1,47 @@
+<?php
+session_start();
+
+$apikey = '';
+$email_field = 'name_email_form_field';
+$user_name_field = 'name_user_name_form_field';
+$message_field = 'name_message_form_field';
+$type_form = 'contact'; // use 'signup' for user signup form
+
+// if downloaded, unzip and include the app, take your own relative path:
+require_once '../../cleantalk-antispam.php';
+// if install the app by composer package:
+use Cleantalk\CleantalkAntispam;
+
+//require_once "lib/cleantalk-php-patch.php"; -- PHP-FPM
+
+$cleantalk_antispam = new CleantalkAntispam($apikey, $email_field, $user_name_field, $message_field, $type_form);
+$api_result = $cleantalk_antispam->handle();
+if ($api_result) { // the check fired
+    if ($api_result->account_status !== 1) {
+        // something wrong with your key or license, to know why read $api_result->codes
+        echo 'Allowed. Spam protection disabled.'; // or do nothing
+    } else {
+        if ($api_result->allow === 1) {
+            echo 'Allowed. Spam protection OK.'; // or do nothing
+        } else {
+            die('Blocked. Spam protection OK. Reason: ' . $api_result->comment); // or make your own handler
+        }
+    }
+}
+// your further code flow here
+?>
+
+    <form method="post">
+        <label for="login">Login:</label>
+        <input type="text" name="name_user_name_form_field" id="login" />
+        <br />
+        <label for="email">Email:</label>
+        <input type="text" name="name_email_form_field" id="email" value="" />
+        <br />
+        <label for="message">Message:</label>
+        <textarea name="name_message_form_field" id="message"></textarea>
+        <br />
+        <input type="submit" />
+    </form>
+
+<?php $cleantalk_antispam->frontendScript(); ?>

examples/form_with_handler/form_with_handler.php

@@ -92,13 +92,13 @@ class Cleantalk
     public $ssl_path = '';
 
     /**
-     * Minimal server response in miliseconds to catch the server
+     * Minimal server response in milliseconds to catch the server
      *
      */
     public $min_server_timeout = 50;
 
     /**
-     * Maximal server response in miliseconds to catch the server
+     * Maximal server response in milliseconds to catch the server
      *
      */
     public $max_server_timeout = 1500;

lib/Cleantalk.php

@@ -24,12 +24,16 @@ public function __construct(
         $this->type_form       = $type_form;
     }
 
+    /**
+     * @return CleantalkResponse|null
+     * @throws TransportException
+     */
     public function handle()
     {
         if ( count($_POST) === 0 ) {
             $_SESSION['ct_submit_time'] = time();
 
-            return;
+            return null;
         }
 
         $sender_email    = isset($_POST[$this->email_field]) ? $_POST[$this->email_field] : '';