Download the PHP package lukeraymonddowning/honey without Composer
On this page you can find all versions of the php package lukeraymonddowning/honey. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download lukeraymonddowning/honey
More information about lukeraymonddowning/honey
Files in lukeraymonddowning/honey
Package honey
Short Description Reduce spam on your Laravel site.
License MIT
Informations about the package honey
🍯 Honey
A spam prevention package for Laravel, providing honeypot techniques, ip blocking and beautifully simple Recaptcha integration. Stop spam. Use Honey.
TOC
- Installation
- Usage
- Recaptcha
- Via Middleware
- Manually
- Customising what happens on failure
- Hooks
- Manually running Honey checks
- Integrating with Livewire
- Configuring Honey
- Recaptcha
- Testing
- Accreditations
Installation
You can install Honey via Composer.
You should publish Honey's config file using the following Artisan Command:
Finally, you should run your database migrations, which adds a spammers table:
Honey is now successfully installed!
Upgrading
We document any changes in the UPGRADE.md file.
Usage
Using Honey couldn't be easier. Go to a <form>
in your blade files and add <x-honey/>
as a child element.
Now, in the routes file, add the honey
middleware to the route that your form points to.
That's it! Your route is now protected from spam. If you want to take it to the next level, read on...
Recaptcha
Honey makes it a breeze to integrate Google's Recaptcha on your Laravel site. We integrate with Recaptcha v3 for completely seamless and invisible bot prevention. Here's how to get started.
First, you need to go grab a key pair from Google. You can get yours here:
https://g.co/recaptcha/v3. Head into your .env
file, and add your key pair.
We're almost there. Head to your blade file and, inside of a <form>
element, add the <x-honey-recaptcha/>
component.
We'll use the example from earlier:
As a note, you can use <x-honey-recaptcha/>
alongside <x-honey/>
, or separately. You do you. However, if
you're using both components, you can simplify to this:
To allow you to track different action types in your Google console, you can pass an action attribute to the recaptcha blade component.
You now have 2 options. You can allow Honey to make the Recaptcha request for you and fail automatically if it detects a bot, or you can do it manually (although it's basically magic, so don't worry).
Via Middleware
To use Honey's built in Middleware, add honey-recaptcha
to your route's middleware stack:
Again, you can use this independently of the honey
middleware if you're only interested in Recaptcha. The middleware
will abort the request by default if things look fishy.
Manually
Honey provides you all the power you could ever wish for via the Honey
Facade. To check the token manually, you may
do the following:
The response will return a RecaptchaResponse
object with properties as defined in the Recaptcha docs: https://developers.google.com/recaptcha/docs/v3.
This class implements ArrayAccess
, so you can use array syntax as if you were working with a JSON response.
If you want to quickly ascertain if the request is spam based on your configured minimum score, you can use the
isSpam
method after calling the check
method.
Customising what happens on failure
By default, Honey will abort with a 422
status code when it detects spam through its middleware stack.
Of course, you may wish to do something completely different. No problem! Just tell Honey what it should do instead
in the boot method of your Service Provider:
Hooks
Honey allows you to perform callbacks prior to it failing due to a spam attack. You can register as many callbacks
as you want. To register a callback, call the beforeFailing
method.
Honey also allows you to hook in after a recaptcha token has been checked on the server. This is used in the Livewire traits to force a request for a new token on the next render.
Manually running Honey checks
You can manually run any checks defined in your checks
array in the honey.php
config file using the Facade helper.
Note that this won't fail for you, but will return a boolean instead. You can force a failure if desired:
Integrating with Livewire
Honey offers out of the box Livewire support. To get started, add the
WithHoney
trait to your Livewire component. You don't need to change your form at all, everything will
just work. Note that the honey inputs are deferred,
so they'll only sync back to the server after calling an action. Here's an example form:
When the form is submitted and the signup
action is called, the Honey inputs will sync back to your component.
In your component, you can check if Honey passed by calling $this->honeyPasses()
. Note that your standard fail
method will not be called in Livewire components, because the use case is so different.
Honey also supports reCaptcha for Livewire. Again, your form just needs to include the recaptcha component or
include the recaptcha
attribute on the <x-honey/>
component:
You also need to add the WithRecaptcha
trait to your Livewire component (even if you're using Honey too). You can
check for reCaptcha success by calling $this->recaptchaPasses()
. If you're using WithHoney
, the $this->honeyPasses()
method will also check reCaptcha for you, so there is no need to call both methods.
The WithRecaptcha
trait is smart enough to request a new token from the browser if, for example, your token check passes
but your validation fails.
Configuring Honey
Honey is built with a great set of defaults, but we understand that one size rarely fits all. That's why we provide
plenty of config options for you. You can access them from the honey.php
config file. Let's look at the
different options available to you.
Features
You can disable or enable global features provided by Honey simply by adding or removing them from the features
array.
Here are the features on offer:
Spammer IP Tracking
When enabled, Honey will add a spammers
migration to your database. Any time somebody fails the spam check, their
IP address is added to the spammers
table. If you don't want Honey to track this, simply disable the feature.
Block Spammers Globally
If spammer IP tracking is enabled, Honey can go one step further. By default, it registers global middleware that
will block any IP address in the spammers
table that has hit the maximum_attempts
defined further down in the
config file. If you would like more granular control or wish to remove this functionality entirely, simply disable the feature.
Environments
You likely don't want to run Honey in every environment. Honey will only run in the environments specified in this array.
You can also manually disable Honey by calling the disable
method.
Checks
Each time the honey
middleware is run or Honey::check()
is called, Honey runs through an array of checks to determine
if the request is spam. You can tailor which checks are to be run by adding or removing items in the checks
array.
User is blocked spammer check
This requires the spammerIpTracking
feature to be enabled to take effect. If an IP address is recorded as hitting the
maximum_attempts
of spamming defined further down in the config file, it will fail.
Present but empty check
When you include the <x-honey/>
blade directive, Honey adds a hidden input to your form. If a bot fills this input
out, or removes the input from the request, this check will fail.
Minimum time passed check
When you include the <x-honey/>
blade directive, Honey adds a hidden input to your form with the current time in it as an encrypted value.
If the form is submitted faster than defined in the minimum_time_passed
config entry, or removes the input from the request,
this check will fail.
Javascript input filled check
When you include the <x-honey/>
blade directive, Honey adds a hidden input to your form. It starts empty, but after
the time specified in the minimum_time_passed
config entry, Javascript fills the input with an encrypted value.
If the input has been filled out with a different value, or has no value, the check will fail.
Minimum time passed
If you have the minimum time passed check or the Javascript input filled check enabled, both checks will use this value to determine, in seconds, the minimum amount of time that should pass from the page loading until the form can be submitted. Forms that are submitted more quickly than this will fail the spam check.
Spammer blocking
If you have the spammerIpTracking
feature enabled, you can configure the options for it here. The table_name
entry allows you to change the name of the database table if it conflicts with something else in your application.
The maximum_attempts
entry defines the maximum number of times an IP address can be recorded as spam before they
are blocked from the site. We recommend setting a value higher than 1 to account for occasional mistakes.
Input name selectors
By default, Honey uses the static
driver to decide on input names. If you would like to change the name of each
input, you may do so here. We recommend altering these from the default values to prevent learned bot behaviour across
sites.
Recaptcha
Here you can define your key pair if you don't want to do it in the env file. You may also alter the minimum score (between 0 and 1), that a user must get back from Recaptcha to avoid being classed as spam.
Testing
Honey has a full test suite. Go ahead and run it for yourself!
Accreditations
My main impetus for creating this package came after watching Jefferey Way's brilliant course on Spam prevention on Laracasts. If you don't have a Laracasts subscription, you should get one.
All versions of honey with dependencies
illuminate/support Version ^9.49|^10.0|^11.0
guzzlehttp/guzzle Version ^7.2