PHPackages                             simplonprod/craft-google-recaptcha - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. simplonprod/craft-google-recaptcha

Abandoned → [jub/craft-google-recaptcha](/?search=jub%2Fcraft-google-recaptcha)Craft-plugin[Utility & Helpers](/categories/utility)

simplonprod/craft-google-recaptcha
==================================

Google reCAPTCHA for Craft CMS

2.0.2(3y ago)17.6k3[3 issues](https://github.com/Simplon-Prod/craft-google-recaptcha/issues)1MITPHPPHP ^8.0.2

Since Apr 1Pushed 1y ago1 watchersCompare

[ Source](https://github.com/Simplon-Prod/craft-google-recaptcha)[ Packagist](https://packagist.org/packages/simplonprod/craft-google-recaptcha)[ RSS](/packages/simplonprod-craft-google-recaptcha/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (9)Versions (11)Used By (1)

Google reCAPTCHA plugin for Craft CMS
=====================================

[](#google-recaptcha-plugin-for-craft-cms)

[![Stable Version](https://camo.githubusercontent.com/0e817733caf7244ca25d7cd6483956ceb4c0fbb9166265f0ef77cb1d68d1a7cf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a75622f63726166742d676f6f676c652d7265636170746368613f6c6162656c3d737461626c65)](https://camo.githubusercontent.com/0e817733caf7244ca25d7cd6483956ceb4c0fbb9166265f0ef77cb1d68d1a7cf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a75622f63726166742d676f6f676c652d7265636170746368613f6c6162656c3d737461626c65)[![Total Downloads](https://camo.githubusercontent.com/e3e8d0054577cee1fb8b539cfa345173b6948768ab4bd86569a81215c4777f4c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a75622f63726166742d676f6f676c652d726563617074636861)](https://packagist.org/packages/jub/craft-google-recaptcha)[![Tests status](https://github.com/juban/craft-google-recaptcha/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/juban/craft-google-recaptcha/actions/workflows/ci.yml/badge.svg?branch=master)

[![](logo.png)](logo.png)

Google reCAPTCHA for Craft CMS enables to render and validate the reCAPTCHA widget. It is compatible with both API v2 and v3, including checkbox badge and invisible flavors.

Requirements
------------

[](#requirements)

This plugin requires Craft CMS 4 or 5 and PHP 8.0.2 or later.

To use the plugin, you will need to get an API site key and secret key which you can configure [here](https://www.google.com/recaptcha/admin).

Installation
------------

[](#installation)

1. Install with composer via `composer require jub/craft-google-recaptcha` from your project directory or from the Plugin Store section of the Control Panel.
2. Install the plugin in the Craft Control Panel under Settings → Plugins, or from the command line via `./craft plugin/install google-recaptcha`.

Configuration
-------------

[](#configuration)

### Control Panel

[](#control-panel)

You can manage configuration setting through the Control Panel by going to Settings → Google reCAPTCHA

- Provide the Site Key and the Secret Key obtained from [your reCAPTCHA account](https://www.google.com/recaptcha/admin).
- Select the API version accordingly to the reCAPTCHA type you created the keys upon.
- For v2 API, select the following parameters:
    - Size: Select the size of the reCAPTCHA widget.
    - Theme: Select the color theme of the reCAPTCHA widget.
    - Badge: Select the position of the reCAPTCHA badge.
- For v3 API:
    - Default Action: the default action name to be used during reCAPTCHA verification. Defaults to `homepage` if blank.
    - Default Score Threshold : Minimum score between 0 and 1 to obtain in order for the end user to validate the reCAPTHCHA challenge (see [here](https://developers.google.com/recaptcha/docs/v3#interpreting_the_score) for help on interpreting the score) . Leave blank for no score checking.
    - Actions: A score threshold can be defined per action here.

### Configuration file

[](#configuration-file)

You can create a `google-recaptcha.php` file in the `config` folder of your project and provide the settings as follow:

```
return [
    "version"   		=> 2, // Either 2 our 3
    "siteKey"   		=> '', // Site key
    "secretKey" 		=> '', // Secret key
    "size"      		=> 'normal', // (v2) normal, compact or invisible
    "theme"     		=> 'light', // (v2) light or dark
    "badge"     		=> 'bottomright', // (v2) bottomright, bottomleft or inline
    "actionName"        => 'homepage', // (v3) Default action name
    "scoreThreshold"	=> 0.5 // (v3) Value between 0 and 1 to determine the minimum score to validate
    "actions"			=> [ // (v3) List of actions with their associated score threshold value (see the template part below to know how to specify the action parameter in the render method)
    	[
    		'name' 				=> 'some_action_name',
    		'scoreThreshold' 	=> 0.5
    	]
    ]

];
```

> ⚠️ Any value provided in that file will override the settings from the Control Panel.

Using Google reCAPTCHA
----------------------

[](#using-google-recaptcha)

### Display Google reCAPTCHA widget in template

[](#display-google-recaptcha-widget-in-template)

You can integrate the Google reCAPTCHA widget in your Twig templates as follow:

```
{{ craft.googleRecaptcha.render() }}
```

The `render` method accept an optional parameter in which you can provide any HTML attributes to apply to the widget container (div for v2, hidden input for v3).
For example, to provide a container id, you can do:

```
{{ craft.googleRecaptcha.render({id: 'recaptcha-widget'}) }}
```

> 💡 For v2 API, you can provide a second boolean argument to the render method to trigger the instant rendering of the widget (ie. `{{ craft.googleRecaptcha.render({ id: 'recaptcha-widget' }, true) }}`). This is useful if you are working with views loaded through Ajax or [Sprig](https://plugins.craftcms.com/sprig) calls and you need to refresh the widget.

#### v3 special options

[](#v3-special-options)

##### Action

[](#action)

An [`action`](https://developers.google.com/recaptcha/docs/v3?hl=fr#actions) property can be provided as follow:

```
{{ craft.googleRecaptcha.render({id: 'recaptcha-widget', action: 'some_action_name'}) }}
```

In that case, the score threshold to be used for that action can be defined in the "Actions Settings" part of the plugin control panel.

##### Form ID

[](#form-id)

To prevent the widget from expiring after 2 minutes, you should provide a `formId` option to specify the ID of the protected form:

```
{{ craft.googleRecaptcha.render({id: 'recaptcha-widget', formId: 'some-form-id'}) }}
```

In that case, reCAPTCHA will be executed upon submit event of the form.

#### Setting scripts extra attributes

[](#setting-scripts-extra-attributes)

In the first render parameter, `scriptOptions` special property can be used to add extra attributes to the generated scripts tags.

For example, to support Content Security Policy (CSP), assuming you are using the [Sherlock](https://plugins.craftcms.com/sherlock) security plugin, you could do the following:

```
{% set nonce = craft.sherlock.getNonce() %}
{{ craft.googleRecaptcha.render({scriptOptions: {'nonce': nonce}}) }}
```

#### Custom reCAPTCHA Widget

[](#custom-recaptcha-widget)

If the default widget generation using the Twig command `craft.googleRecaptcha.render` does not meet your needs, you can generate your own using the plugin settings:

- Get the API Version (ie `2` or `3`): `{{ craft.googleRecaptcha.version }}`
- Get the Site Key (parsed value): `{{ craft.googleRecaptcha.siteKey }}`

> 💡 If you need even more detailed configuration, you can still access every plugin settings by using `{{ craft.app.plugins.plugin('google-recaptcha').settings }}`

### Verify users submissions

[](#verify-users-submissions)

To validate a user submission on server side, you can use the built-in method:

```
GoogleRecaptcha::$plugin->recaptcha->verify();
```

For example, in a [module](https://craftcms.com/docs/5.x/extend/module-guide.html) controller, you could do something like this:

```
public function actionSubmitForm() {
	if(GoogleRecaptcha::$plugin->recaptcha->verify()) {
		// Do something useful here
	}
	else {
		Craft::$app->session->setError('Looks like you are a robot!');
	}

}
```

### Verify Guest Entries submissions

[](#verify-guest-entries-submissions)

In order to add a reCAPTCHA verification when working with [Craft Guest Entries plugin](https://plugins.craftcms.com/guest-entries), you can do something like the following in a project module:

```
Event::on(SaveController::class, SaveController::EVENT_BEFORE_SAVE_ENTRY, function (SaveEvent $e) {
    /** @var Entry $submission */
    $submission = $e->entry;
    $submission->setScenario(Element::SCENARIO_LIVE);
    $submission->validate();
    // Check reCAPTCHA
    $isValid = GoogleRecaptcha::$plugin->recaptcha->verify();
    if (!$isValid) {
        $submission->addError('recaptcha', 'Please, prove you’re not a robot.');
        $e->isValid = false;
    }
});
```

### Verify Contact Form submissions

[](#verify-contact-form-submissions)

In order to add a reCAPTCHA verification when working with [Contact Form](https://plugins.craftcms.com/contact-form), you can do something like the following in a project module:

```
Event::on(Submission::class, Submission::EVENT_AFTER_VALIDATE, function(Event $e) {
    /** @var Submission $submission */
    $submission = $e->sender;
    // Check reCAPTCHA
    $isValid = GoogleRecaptcha::$plugin->recaptcha->verify();
    if (!$isValid) {
        $submission->addError('recaptcha', 'Please, prove you’re not a robot.');
    }
});
```

### Available events

[](#available-events)

- The `\juban\googlerecaptcha\events\BeforeRecaptchaVerifyEvent` event is triggered just before a reCAPTCHA verification is performed. You can use that event to:
    - **Bypass the verification** by setting the `skipVerification` event property to `true`. In that case, verification will be considered as successful.
    - **Cancel the verification** by setting the `isValid` event property to `false`. In that case, verification will be considered as failed.

---

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance11

Infrequent updates — may be unmaintained

Popularity24

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 94.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~45 days

Recently: every ~1 days

Total

10

Last Release

1457d ago

Major Versions

1.1.0 → 2.0.02022-05-08

1.1.1 → 2.0.22022-05-13

PHP version history (3 changes)1.0.3PHP >=7.0.0

1.1.0PHP >=7.2.5

2.0.0PHP ^8.0.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/e8ee487ad8fd68ef71b606e38019a3cc3d1198c410c9d37443fd7c7ffa6ef22d?d=identicon)[juban](/maintainers/juban)

![](https://www.gravatar.com/avatar/e8e10a88d228a35014afa0e0830321fc369723c62a5c8ad9f7ef3bfb7d624781?d=identicon)[simplonprod](/maintainers/simplonprod)

---

Top Contributors

[![juban](https://avatars.githubusercontent.com/u/1687683?v=4)](https://github.com/juban "juban (89 commits)")[![SimplonReunion](https://avatars.githubusercontent.com/u/18075545?v=4)](https://github.com/SimplonReunion "SimplonReunion (3 commits)")[![liam-spedding](https://avatars.githubusercontent.com/u/111750536?v=4)](https://github.com/liam-spedding "liam-spedding (2 commits)")

---

Tags

cmscraftcraft-plugincraftcmsgoogle-recaptchacmsCraftcraftcmscraft-pluginGoogle ReCaptcha

###  Code Quality

TestsCodeception

### Embed Badge

![Health badge](/badges/simplonprod-craft-google-recaptcha/health.svg)

```
[![Health](https://phpackages.com/badges/simplonprod-craft-google-recaptcha/health.svg)](https://phpackages.com/packages/simplonprod-craft-google-recaptcha)
```

###  Alternatives

[verbb/navigation

Create navigation menus for your site.

90683.7k17](/packages/verbb-navigation)[verbb/formie

The most user-friendly forms plugin for Craft.

101372.9k40](/packages/verbb-formie)[verbb/comments

Add comments to your site.

13753.1k](/packages/verbb-comments)[verbb/tablemaker

Create customizable and user-defined table fields.

40168.8k1](/packages/verbb-tablemaker)[supercool/tablemaker

Create customizable and user-defined table fields.

40141.7k](/packages/supercool-tablemaker)[pennebaker/craft-architect

CraftCMS plugin to generate content models from JSON/YAML data.

72148.5k5](/packages/pennebaker-craft-architect)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)