Added passes and fails methods

CHANGELOG.md

@@ -1,4 +1,9 @@
 # Release Notes for Cloudflare Turnstile
 
+## 1.0.1 - 2023-04-13
+
+- Added `passes` and `fails` methods
+- Updated readme with new methods and on how to flag the message as spam
+
 ## 1.0.0 - 2023-01-06
 - Initial release

README.md

@@ -99,23 +99,25 @@ If you would provide HTML attributes to Cloudflare Turnstile's script:
 
 ## Verify form submissions
 
-To validate the Turnstile response, use:
+To validate the Turnstile response, you can use one of this methods:
 ```php
-// returns `true` if passes
-Turnstile::getInstance()->validator->verify();
+Turnstile::getInstance()->validator->verify(); // returns `true` if passes
+Turnstile::getInstance()->validator->passes();
+Turnstile::getInstance()->validator->fails();
 ```
 
-This is an example on how validate a [Contact Form](https://plugins.craftcms.com/contact-form) submission. Add the following code in your project module:
+This is an example on how to flag the message as spam using [Contact Form](https://plugins.craftcms.com/contact-form). Add the following code in your project module:
 ```php
-Event::on(
-    Submission::class,
-    Submission::EVENT_AFTER_VALIDATE, function(Event $e) {
-        /** @var Submission $submission */
-        $submission = $e->sender;
+use billmn\turnstile\Turnstile;
+use craft\contactform\events\SendEvent;
+use craft\contactform\Mailer;
+use yii\base\Event;
 
-        if (! Turnstile::getInstance()->validator->verify()) {
-            $submission->addError('turnstile', __('Please, prove you are human.'));
-        }
+Event::on(
+    Mailer::class,
+    Mailer::EVENT_BEFORE_SEND,
+    function(SendEvent $e) {
+        $e->isSpam = Turnstile::getInstance()->validator->fails();
     }
 );
 ```
@@ -129,7 +131,5 @@ If you use the [`response-field-name`](https://developers.cloudflare.com/turnsti
 ```
 
 ```php
-if (! Turnstile::getInstance()->validator->verify('custom-field')) {
-    // ...
-}
+Turnstile::getInstance()->validator->fails('custom-field');
 ```

src/services/Validator.php

@@ -49,12 +49,12 @@ protected function sendRequest(string|null $responseField = null): \Psr\Http\Mes
     }
 
     /**
-     * Verifiy if request is valid.
+     * Verify if request is valid.
      *
      * @param string|null $responseField
-     * @return boolean|ConnectException
+     * @return boolean
      */
-    public function verify(string|null $responseField = null): bool|ConnectException
+    public function verify(string|null $responseField = null): bool
     {
         try {
             $response = $this->sendRequest($responseField);
@@ -80,4 +80,26 @@ public function verify(string|null $responseField = null): bool|ConnectException
 
         return false;
     }
+
+    /**
+     * Check if verification passes.
+     *
+     * @param mixed ...$args
+     * @return boolean
+     */
+    public function passes(...$args): bool
+    {
+        return $this->verify(...$args);
+    }
+
+    /**
+     * Check if verification fails.
+     *
+     * @param mixed ...$args
+     * @return boolean
+     */
+    public function fails(...$args): bool
+    {
+        return $this->passes(...$args) === false;
+    }
 }