LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 SSRPanel
+Copyright (c) 2023 Scyllaly
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,5 +1,10 @@
-# hCaptcha
-Project based on [laravel-reCAPTCHA](https://github.com/Dylanchouxd/laravel-reCAPTCHA) development.
+# Introduction
+The hCaptcha is a human-computer verification solution that replaces Google reCaptcha. It has high performance, high availability and high recognition, especially suitable for regions with poor network quality, such as East Asia, Middle East, etc. Many well-known companies are using the hCaptcha solution.
+
+
+The package is one of the recommended package on [the official developer guide of HCaptcha](https://github.com/hCaptcha/hcaptcha-integrations-list#laravel). No malicious code, ensuring the security of your development supply chain.
+
+- Purchase a [VPS](https://bwh88.net/aff.php?aff=20075) or [Akamai VPS](https://www.linode.com/lp/refer/?r=2d4a0088743a2a06e3405514d486b8966c51a439) for developing and deploying applications.
 
 ## Installation
 
@@ -13,34 +18,37 @@ composer require scyllaly/hcaptcha
 
 In `app/config/app.php` add the following :
 
-1- The ServiceProvider to the providers array :
+Step 1: The ServiceProvider to the providers array :
 
 ```php
 Scyllaly\HCaptcha\HCaptchaServiceProvider::class,
 ```
 
-2- The class alias to the aliases array :
+Step 2: The class alias to the aliases array :
 
 ```php
 'HCaptcha' => Scyllaly\HCaptcha\Facades\HCaptcha::class,
 ```
 
-3- Publish the config file
+Step 3: Publish the config file
 
-```ssh
+```Shell
 php artisan vendor:publish --provider="Scyllaly\HCaptcha\HCaptchaServiceProvider"
 ```
 
 ### Configuration
 
-Add `HCAPTCHA_SECRET` and `HCAPTCHA_SITEKEY` in **.env** file :
+Add `HCAPTCHA_SECRET`, `HCAPTCHA_SITEKEY` and `HCAPTCHA_ENABLED` in **.env** file :
 
 ```
 HCAPTCHA_SECRET=secret-key
 HCAPTCHA_SITEKEY=site-key
+HCAPTCHA_ENABLED=true
 ```
 
-(You can obtain them from [here](https://docs.hcaptcha.com/api#getapikey))
+(You can obtain them from [Official Developer Guide](https://docs.hcaptcha.com/api#getapikey))
+
+- Tips: If you do not have an account, please [sign up](https://hCaptcha.com/?r=d315c350eeee) it first.
 
 ### Usage
 
@@ -58,7 +66,7 @@ With [language support](https://docs.hcaptcha.com/configuration) or [onloadCallb
  {!! HCaptcha::renderJs('fr', true, 'hcaptchaCallback') !!}
 ```
 
-#### Display hCAPTCHA
+#### Display hCaptcha
 
 Default widget :
 
@@ -72,7 +80,7 @@ With [custom attributes](https://docs.hcaptcha.com/configuration#themes) (theme,
 {!! HCaptcha::display(['data-theme' => 'dark']) !!}
 ```
 
-Invisible hCAPTCHA using a [submit button](https://docs.hcaptcha.com/configuration#themes):
+Invisible hCaptcha using a [submit button](https://docs.hcaptcha.com/configuration#themes):
 
 ```php
 {!! HCaptcha::displaySubmit('my-form-id', 'submit now!', ['data-theme' => 'dark']) !!}
@@ -82,15 +90,41 @@ callback submit the form on a successful captcha verification.
 
 #### Validation
 
-Add `'h-captcha-response' => 'required|HCaptcha'` to rules array :
+There are two ways to apply HCaptcha validation to your form:
+
+#### 1. Basic Approach
+
+This method always applies the HCaptcha validation rule.
 
 ```php
 $validate = Validator::make(Input::all(), [
-	'h-captcha-response' => 'required|HCaptcha'
+    'h-captcha-response' => 'required|HCaptcha'
 ]);
 
 ```
 
+In this approach, the `h-captcha-response` field is required and validated using the `HCaptcha` rule without any conditions.
+
+#### 2. Conditional Approach
+
+This method applies the HCaptcha validation rule only if the `HCAPTCHA_ENABLED` environment variable is set to `true`.
+
+```php
+$isHcaptchaEnabled = env('HCAPTCHA_ENABLED');
+$rules = [
+    // Other validation rules...
+];
+
+if ($isHcaptchaEnabled) {
+    $rules['h-captcha-response'] = 'required|HCaptcha';
+}
+
+$request->validate($rules);
+
+```
+
+In this approach, the `h-captcha-response` field will be required and validated using the `HCaptcha` rule only when `HCAPTCHA_ENABLED` is set to `true`. This adds flexibility to your validation logic, allowing you to enable or disable HCaptcha validation as needed.
+
 ##### Custom Validation Message
 
 Add the following values to the `custom` array in the `validation` language file :
@@ -99,7 +133,7 @@ Add the following values to the `custom` array in the `validation` language file
 'custom' => [
     'h-captcha-response' => [
         'required' => 'Please verify that you are not a robot.',
-        'captcha' => 'Captcha error! try again later or contact site admin.',
+        'h_captcha' => 'Captcha error! try again later or contact site admin.',
     ],
 ],
 ```
@@ -145,8 +179,8 @@ HCaptcha::shouldReceive('verifyResponse')
 // POST request, with request body including `h-captcha-response`
 $response = $this->json('POST', '/register', [
     'h-captcha-response' => '1',
-    'name' => 'John',
-    'email' => 'john@example.com',
+    'name' => 'Scyllaly',
+    'email' => 'Scyllaly@example.com',
     'password' => '123456',
     'password_confirmation' => '123456',
 ]);

composer.json

@@ -15,7 +15,7 @@
     ],
     "require": {
         "php": ">=5.5.5",
-        "illuminate/support": "5.*|6.*|7.*|8.*|^9.0|10.*"
+        "illuminate/support": "5.*|6.*|7.*|8.*|^9.0|10.*|^11.0|^12.0"
     },
     "require-dev": {
         "phpunit/phpunit": "~4.8|^9.5.10|^10.0"

src/HCaptcha.php

@@ -36,18 +36,33 @@ class HCaptcha
      */
     protected $verifiedResponses = [];
 
+    /**
+     * @var null
+     * lastScore
+     */
+    protected $lastScore = null;
+
+    /**
+     * Whether to use hCaptcha or not.
+     *
+     * @var bool
+     */
+    protected $enabled;
+
     /**
      * HCaptcha.
      *
      * @param string $secret
      * @param string $sitekey
      * @param array  $options
+     * @param bool   $enabled
      */
-    public function __construct($secret, $sitekey, $options = [])
+    public function __construct($secret, $sitekey, $options = [], $enabled = true)
     {
         $this->secret = $secret;
         $this->sitekey = $sitekey;
         $this->http = new Client($options);
+        $this->enabled = $enabled;
     }
 
     /**
@@ -59,6 +74,10 @@ public function __construct($secret, $sitekey, $options = [])
      */
     public function display($attributes = [])
     {
+        if (!$this->enabled) {
+            return '';
+        }
+
         $attributes = $this->prepareAttributes($attributes);
         return '<div' . $this->buildAttributes($attributes) . '></div>';
     }
@@ -82,6 +101,10 @@ public function displayWidget($attributes = [])
      */
     public function displaySubmit($formIdentifier, $text = 'submit', $attributes = [])
     {
+        if (!$this->enabled) {
+            return sprintf('<button%s><span>%s</span></button>', $this->buildAttributes($attributes), $text);
+        }
+
         $javascript = '';
         if (!isset($attributes['data-callback'])) {
             $functionName = 'onSubmit' . str_replace(['-', '=', '\'', '"', '<', '>', '`'], '', $formIdentifier);
@@ -111,6 +134,10 @@ public function displaySubmit($formIdentifier, $text = 'submit', $attributes = [
      */
     public function renderJs($lang = null, $callback = false, $onLoadClass = 'onloadCallBack')
     {
+        if (!$this->enabled) {
+            return '';
+        }
+
         return '<script src="' . $this->getJsLink($lang, $callback, $onLoadClass) . '" async defer></script>' . "\n";
     }
 
@@ -124,11 +151,15 @@ public function renderJs($lang = null, $callback = false, $onLoadClass = 'onload
      */
     public function verifyResponse($response, $clientIp = null)
     {
+        if (!$this->enabled) {
+            return true; // Always true if hCaptcha is disabled
+        }
+
         if (empty($response)) {
             return false;
         }
 
-        // Return true if response already verfied before.
+        // Return true if response already verified before.
         if (in_array($response, $this->verifiedResponses)) {
             return true;
         }
@@ -140,6 +171,18 @@ public function verifyResponse($response, $clientIp = null)
         ]);
 
         if (isset($verifyResponse['success']) && $verifyResponse['success'] === true) {
+            $this->lastScore = isset($verifyResponse['score']) ? $verifyResponse['score'] : null;
+            // Check score if it's enabled.
+            $isScoreVerificationEnabled = config('HCaptcha.score_verification_enabled', false);
+
+            if ($isScoreVerificationEnabled && !array_key_exists('score', $verifyResponse)) {
+                throw new \RuntimeException('Score Verification is an exclusive Enterprise feature! Moreover, make sure you are sending the remoteip in your request payload!');
+            }
+
+            if ($isScoreVerificationEnabled && $verifyResponse['score'] > config('HCaptcha.score_threshold', 0.7)) {
+                return false;
+            }
+
             // A response can only be verified once from hCaptcha, so we need to
             // cache it to make it work in case we want to verify it multiple times.
             $this->verifiedResponses[] = $response;
@@ -175,6 +218,10 @@ public function verifyRequest(Request $request)
      */
     public function getJsLink($lang = null, $callback = false, $onLoadClass = 'onloadCallBack')
     {
+        if (!$this->enabled) {
+            return '';
+        }
+
         $client_api = static::CLIENT_API;
         $params = [];
 
@@ -184,6 +231,16 @@ public function getJsLink($lang = null, $callback = false, $onLoadClass = 'onloa
         return $client_api . '?' . http_build_query($params);
     }
 
+    /**
+     * Get the score from the last successful hCaptcha verification.
+     *
+     * @return float|null The score of the last verification or null if not available.
+     */
+    public function getScoreFromLastVerification()
+    {
+        return $this->lastScore;
+    }
+
     /**
      * @param $params
      * @param $onLoadClass

src/HCaptchaServiceProvider.php

@@ -58,13 +58,15 @@ public function register()
                 return new HCaptcha(
                     $hCaptcha['secret'],
                     $hCaptcha['sitekey'],
-                    $hCaptcha['options']
+                    $hCaptcha['options'],
+                    $hCaptcha['enabled'],
                 );
             } else {
                 return new HCaptcha(
                     $app['config']['HCaptcha.secret'],
                     $app['config']['HCaptcha.sitekey'],
-                    $app['config']['HCaptcha.options']
+                    $app['config']['HCaptcha.options'],
+                    $app['config']['HCaptcha.enabled'],
                 );
             }
         });

src/config/config.php

@@ -3,8 +3,11 @@
 return [
     'secret'            => env('HCAPTCHA_SECRET'),
     'sitekey'           => env('HCAPTCHA_SITEKEY'),
+    'enabled'           => env('HCAPTCHA_ENABLED', true), //Enable or disable hCaptcha for development environments
     'server-get-config' => false,
     'options'           => [
         'timeout' => 30,
     ],
+    'score_verification_enabled' => false, // This is an exclusive Enterprise feature
+    'score_threshold' => 0.7 // Any requests above this score will be considered as spam
 ];