timehunter / laravel-google-recaptcha-v3
Laravel Package for google reCAPTCHA v3
Installs: 105 290
Dependents: 0
Suggesters: 0
Security: 0
Stars: 135
Watchers: 4
Forks: 21
Open Issues: 2
Requires
- php: >=5.5
Requires (Dev)
- orchestra/testbench: ~3.0
- php-coveralls/php-coveralls: ^2.1
- phpunit/phpunit: ~7.0
- dev-master / 3.0.x-dev
- v2.4.2
- v2.4.1
- v2.4.0
- 2.3.1
- 2.2.30
- 2.2.29
- 2.2.28
- 2.2.27
- 2.2.26
- 2.2.25
- 2.2.24
- 2.2.23
- 2.2.22
- 2.2.21
- 2.2.20
- 2.2.19
- 2.2.18
- 2.2.17
- 2.2.16
- 2.2.15
- 2.2.14
- 2.2.13
- 2.2.12
- 2.2.11
- 2.2.10
- 2.2.9
- 2.2.8
- 2.2.7
- 2.2.6
- 2.2.5
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.9
- 2.0.8
- 2.0.2
- 2.0.1
- 2.0.0
- 1.3.1
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.0
- 0.2.0
- 0.1.4
- 0.1.3
- 0.1.2
- 0.1.1
- 0.1.0
- dev-analysis-7ay662
- dev-analysis-7aPdBE
- dev-analysis-zerJ2r
- dev-analysis-8Kn92A
- dev-analysis-8A09gG
- dev-analysis-8Knk79
- dev-analysis-qoy7eZ
- dev-analysis-XNP1Oy
- dev-analysis-qMY9Zj
- dev-analysis-8L7y2n
- dev-analysis-XWMLkJ
- dev-analysis-zebWJ9
- dev-analysis-XV34EV
- dev-analysis-XabkYY
- dev-analysis-8Lelpl
- dev-analysis-8w1xLN
- dev-analysis-qgbPk6
- dev-analysis-z9BQKl
- dev-analysis-XkblOa
This package is auto-updated.
Last update: 2020-12-21 07:56:35 UTC
README
A star would be a nice encouragement. ^.^
Latest features:
- Refresh Ajax supported
- Content security policy supported
- Multi lang supported
- Vue component supported
- Background mode supported
If you want to use v2, please go to: https://github.com/RyanDaDeng/laravel-google-recaptcha-v2
If you only need to use Vue component, feel free to copy it.
Table of Contents
- Installation
- Configurations
- Facade Usage
- Blade Usage
- Ajax Usage
- Vue Usage
- Validation
- Advanced Usage
- Contributors
Demo code: https://github.com/RyanDaDeng/laravel-google-recaptcha-v3/wiki/Simple-Demo
DEMO
Invisible - hidden
Inline
Corner
Description
Google reCAPTCHA v3 is a new mechanism to verify whether the user is bot or not.
reCAPTCHA v3 is intended for power users, site owners that want more data about their traffic, and for use cases in which it is not appropriate to show a challenge to the user.
For example, a registration page might still use reCAPTCHA v2 for a higher-friction challenge, whereas more common actions like sign-in, searches, comments, or voting might use reCAPTCHA v3.
Please check Google site: https://developers.google.com/recaptcha/docs/faq
Features
- High Test coverage, safe and easy to use
- Score Comparision
- Support invisible, corner and inline badge style
- Support reCAPTCHA to run on every page
- Support multiple actions to be placed on the same page
- Support custom implementation on config interface
- Support custom implementation on request method interface
- Fully supported Vue component
- IP skip list supported
Requirement
This package requires the following dependencies:
-
Laravel >= 5.x
-
If you want to use Validation Class your Laravel version needs to be >= 5.5
-
php > 5
-
Please ensure that you have read basic information from Google reCAPTCHA v3.
Installation
$ composer require timehunter/laravel-google-recaptcha-v3 "~2.4.2" -vvv
'providers'=[ ...., TimeHunter\LaravelGoogleReCaptchaV3\Providers\GoogleReCaptchaV3ServiceProvider::class ]
'aliases'=[ ...., 'GoogleReCaptchaV3'=> TimeHunter\LaravelGoogleReCaptchaV3\Facades\GoogleReCaptchaV3::class ]
If your Laravel framework version is >= 5.5, just run the following command to publish config.
$ php artisan vendor:publish --provider="TimeHunter\LaravelGoogleReCaptchaV3\Providers\GoogleReCaptchaV3ServiceProvider" --tag=googlerecaptchav3.config
$ php artisan vendor:publish --provider="TimeHunter\LaravelGoogleReCaptchaV3\Providers\GoogleReCaptchaV3ServiceProvider" --tag=googlerecaptchav3.vuejs
$ php artisan vendor:publish --provider="TimeHunter\LaravelGoogleReCaptchaV3\Providers\GoogleReCaptchaV3ServiceProvider" --tag=googlerecaptchav3.lang
A lang folder will be created under /resources/lang/vendor/GoogleReCaptchaV3/*
Configurations
Setting up your Google reCAPTCHA details in config file
Please register all details in config for host_name, site_key, secret_key and site_verify_url.
RECAPTCHA_V3_SECRET_KEY=
RECAPTCHA_V3_SITE_KEY=
Specify your Score threshold and action in 'setting', e.g.
'setting' = [ [ 'action' => 'contact_us', // Google reCAPTCHA required paramater 'threshold' => 0.2, // score threshold 'score_comparision' => false // if this is true, the system will do score comparsion against your threshold for the action ], [ 'action' => 'signup', 'threshold' => 0.2, 'score_comparision' => true ], ]
Note: if you want to enable Score Comparision, you also need to enable is_score_enabled to be true.
... 'is_score_enabled' = true ...
For more details please check comments in config file.
Facade Usage
You can directly use registered facade service by calling the following methods.
setAction() is optional only if you want to verify if the action is matched. verifyResponse() which accepts the token value from your form. This returns Google reCAPTCHA Response object. setScore() is optional only if you want to manually verify the score.GoogleReCaptchaV3::setAction($action)->verifyResponse($value,$ip = null);
GoogleReCaptchaV3::verifyResponse($value,$ip)->getMessage(); GoogleReCaptchaV3::verifyResponse($value)->isSuccess(); GoogleReCaptchaV3::verifyResponse($value)->toArray();
GoogleReCaptchaV3::verifyResponse( $request->input('g-recaptcha-response'), $request->getClientIp() ) ->getMessage()
GoogleReCaptchaV3::setAction($action)->verifyResponse($value)->isSuccess();
GoogleReCaptchaV3::setScore($score) ->setAction($action) ->verifyResponse( $request->input('g-recaptcha-response'), $request->getClientIp() ) ->getMessage()
Validation Class (Only support Laravel >= 5.5)
You can use provided Validation object to verify your reCAPTCHA.
use TimeHunter\LaravelGoogleReCaptchaV3\Validations\GoogleReCaptchaV3ValidationRule; $rule = [ 'g-recaptcha-response' => [new GoogleReCaptchaV3ValidationRule('action_name')] ];$actionName: if its NULL, the package won't verify action with google response.
Blade Usage
Display reCAPTCHA v3
Add Google API script
Include the API script at the bottom of your layout page
{!! GoogleReCaptchaV3::init() !!}
Consent Security Policy - Nonce
To add a nonce for content security, pass a params array with your pages nonce.
{!! GoogleReCaptchaV3::init([ 'nonce' => nonce(), ]) !!}
Running script on every page (optional)
... 'background_badge_display' => true, // if false, the badge will be invisible, if true the badge shows at bottom right. 'background_mode' => false, // if true, the script will run on every page (ensure that GoogleReCaptchaV3::init() is placed on layout or homepage) ...
Form & Action
There are three methods to populate the reCAPTCHA within the form.
render() and renderOne() can be placed in anywhere but before init() renderField() needs always to be placed within your form.[
$id=>$action , $id=>$action ...
]
{!! GoogleReCaptchaV3::render(['contact_us_id'=>'contact_us', 'signup_id'=>'signup']) !!}
<form method="POST" action="/verify"> <div id="contact_us_id"></div> // add div with id <input type="submit" value="submit"> </form> <form method="POST" action="/verify"> <div id="signup_id"></div> <input type="submit" value="submit"> </form> {!! GoogleReCaptchaV3::render(['contact_us_id'=>'contact_us', 'signup_id'=>'signup']) !!}
GoogleReCaptchaV3::renderOne($id,$action);
{!! GoogleReCaptchaV3::renderOne('contact_us_id','contact_us') !!}
<form method="POST" action="/verify"> <div id="contact_us_id"></div> // add div with id <input type="submit" value="submit"> </form> {!! GoogleReCaptchaV3::renderOne('contact_us_id','contact_us') !!}
GoogleReCaptchaV3::renderField($id,$action,$class,$style)
{!! GoogleReCaptchaV3::renderField('contact_us_id','contact_us_action') !!}
<form method="POST" action="/verify"> {!! GoogleReCaptchaV3::renderField('contact_us_id','contact_us_action') !!} <input type="submit" value="submit"> </form>
Badge Display for Form & Action
If your settings were not reflected, please run php artisan config:cache to clear cache.
Go to config file, and set[ ... 'inline' => true ... ]Badge will be displayed as inline format within the form. Set inline as true as well Modify your div with style display:none Refer to Google official site: https://developers.google.com/recaptcha/docs/faq , you need to include the following text:
This site is protected by reCAPTCHA and the Google <a href="https://policies.google.com/privacy">Privacy Policy</a> and <a href="https://policies.google.com/terms">Terms of Service</a> apply.
Corner
- Set inline as false
- Your badge will be shown in the bottom right side.
Custom
- Set inline as true
- Do Styling/CSS on its div element
Ajax Usage - Refresh reCAPTCHA Response
getReCaptchaV3Response - this function helps you to get recaptcha response by id
<script> $("#test").click(function (e) { e.preventDefault(); $.ajax({ type: 'POST', url: '/verify', data: { 'g-recaptcha-response':getReCaptchaV3Response('contact_id') }, success: function (data) { refreshReCaptchaV3('contact_id','contact'); }, error: function(err){ refreshReCaptchaV3('contact_id','contact'); } }); }); </script>
Vue Usage (Package version >= 2.2.0)
Step 1 Publish vue component:
$ php artisan vendor:publish --provider="TimeHunter\LaravelGoogleReCaptchaV3\Providers\GoogleReCaptchaV3ServiceProvider" --tag=googlerecaptchav3.vuejs
Step 2 Import vue component and Register reCAPTCHA v3 SiteKey
A BIG thanks to @Fluxlicious who improved the vue component.
The Blade way is no longer useful if you use Vue. We need to manage to assign site key by ourselves. The component supports props below:
Supported: siteKey, id, inline and action, check the original file to see the details.
<google-re-captcha-v3 v-model="gRecaptchaResponse" ref="captcha" site-key="Your Site Key String Here" id="contact_us_id" inline action="contact_us" ></google-re-captcha-v3>
There are two ways you can bind site key to the component.
Use prop
<template> <div> <form @submit.prevent="submit"> <div> <google-re-captcha-v3 v-model="form.gRecaptchaResponse" ref="captcha" :site-key="mySiteKeyVariable" id="contact_us_id" inline action="contact_us" ></google-re-captcha-v3> </div> <button type="submit">Submit</button> </form> </div> </template> <script> import GoogleReCaptchaV3 from '../../components/googlerecaptchav3/GoogleReCaptchaV3'; // location might be diff to your case, ensure that your component location is right export default { components: { GoogleReCaptchaV3 }, data() { return { form: { gRecaptchaResponse: null }, mySiteKeyVariable: 'Your Site Key String', } }, methods: { submit() { axios.post('/verify', this.form).then( response => { this.$refs.captcha.execute(); // every time you submit, the reCAPTCHA token needs to be refreshed } ).catch( error => { this.$refs.captcha.execute(); // every time you submit, the reCAPTCHA token needs to be refreshed }); } } } </script>
Please remember to refresh token every time you submit the form if needed:
this.$refs.captcha.execute();
or Add site key directly into GoogleReCaptchaV3 component
Alternatively, I believe most of cases your site key will never be changed, so you could just modify the original published component to have sitekey hard-coded in.
For instance, open published file and find code below:
.... siteKey: { type: String, required: false, // set to true if you don't want to store the siteKey in this component default: 'Your Site Key Here' // set siteKey here if you want to store it in this component }, ....
Advanced Usage
Custom implementation on Config
TimeHunter\LaravelGoogleReCaptchaV3\Interfaces\ReCaptchaConfigV3Interface
Remember to register it in your own service provider
$this->app->bind( ReCaptchaConfigV3Interface::class, YourOwnCustomImplementation::class );
Custom implementation on Request method
TimeHunter\LaravelGoogleReCaptchaV3\Interfaces\RequestClientInterface
Remember to register it in your own service provider
$this->app->bind( RequestClientInterface::class, YourOwnCustomImplementation::class );
Contributors
Thank you for the following contributors, You guys are the BEST!
@xalunda @Fluxlicious @vinsonyung @demiurge-ash @lxlang @Indianos @ericp-mrelSecurity
If you discover any security related issues, please email ryandadeng@gmail.com instead of using the issue tracker.
License
MIT. Please see the license file for more information.