Download the PHP package abuseipdb/laravel without Composer

AbuseIPDB Laravel API Integration

Package to easily integrate the AbuseIPDB API with your Laravel project.

Installation

To install using Composer:

composer require abuseipdb/laravel

Add ABUSEIPDB_API_KEY to your .env file. You can obtain a free key from the AbuseIPDB website once you've registered an account.

ABUSEIPDB_API_KEY=your_key

Remember, the AbuseIPDB API keys are to be treated like private keys -- don't have them publicly accessible!

For your application's safety, your .env file should never be public or committed to source control.

Usage

Using Main Package Functions

The main functions of the package are found in Abuseipdb\AbuseIPDBLaravel.php. The recommended way to access these functions is through the included facade. To use it, use:

Then the functions can be called statically (non-exhaustive list):

This is the recommended method of accessing the functionality of the AbuseIPDB package.

Quick start for SuspiciousOperationException reporting

This package has support for automatically reporting instances of Symfony's SuspiciousOperationException in your Laravel project. To use this functionality, include the following code in your projects app\Exceptions\Handler.php:

At the top of file

Inside of the Handler's register() function

Inside of register function's $this->reportable(function (Throwable $e) {}

If your handler's register() does not contain the aforementioned $this->reportable

Now, your project will automatically report to AbuseIPDB when a SuspiciousOperationException is thrown.

Main Functions

This package implements functions to easily interact with endpoints of the AbuseIPDB API. These functions are found in AbuseIPDBLaravel.php and can be called statically with the AbuseIPDB facade.

Parent response object

All custom response objects extend the custom AbuseResponse class, which extracts certain headers from the response and makes them accessible programmatically. See below:

When handling responses that call an endpoint with custom responses, include the following at the top of file with requesting code:

Then those object types can be referenced as follows:

etc.

Endpoint specific methods

As of current version, this package has methods to access all public APIv2 endpoints. When requests are made to these endpoints, endpoint-specific response objects will be returned, which extend the Illuminate\Http\Client\Response object. If there is an error, a custom exception will be thrown. Check our APIv2 documentation for a list of returned values from each endpoint.

check

The check() method makes a request to the check endpoint of the AbuseIPDB API. Its signature is

string $ipAddress The IP address to check

int $maxAgeInDays The maximum age of reports to return (1-365), defaults to 30

bool $verbose Whether to include verbose information (reports), defaults to false

report

The report() method makes a request to the report endpoint of the AbuseIPDB API. Its signature is

string $ip The IP address to report

array|int $categories Either one or multiple categories to report the IP address for

string|null $comment An optional comment to include with the report, for example a logged indicator of attack

DateTime|null $timestamp An optional timestamp to include with the report indicating the time of attack

reports

The reports() method makes a request to the reports endpoint of the AbuseIPDB API. Its signature is

string $ipAddress The IP address to get reports for

int $maxAgeInDays The maximum age of reports to return (1-365), defaults to 30

int $page The page number to get for the paginated response

int $perPage The number of reports to get per page

blacklist

The blacklist() method makes a request to the blacklist endpoint of the AbuseIPDB API. Its signature is

int $confidenceMinimum The minimum confidence score to include an IP in the blacklist

int $limit The maximum number of blacklisted IPs to return, defaults to 10000

bool $plaintext Whether to return the blacklist in plaintext (a plain array of IPs), defaults to false

array $onlyCountries Only include IPs from these countries (use 2-letter country codes)

array $exceptCountries Exclude IPs from these countries (use 2-letter country codes)

int|null $ipVersion The IP version to return (4 or 6), defaults to both

checkBlock

The checkBlock() method makes a request to the check-block endpoint of the AbuseIPDB API. Its signature is

string $network The network to check in CIDR notation (e.g. 127.0.0.1/28)

int $maxAgeInDays The maximum age of reports to return (1-365), defaults to 30

bulkReport

The bulkReport() method makes a request to the bulk-report endpoint of the AbuseIPDB API. Its signature is

string $csvFileContents The contents of the csv file to upload

clearAddress

The clearAddress() method makes a request to the clear-address endpoint of the AbuseIPDB API. Its signature is

string $ipAddress The IP address to clear reports for

Exceptions

In the event of an error, this package will throw an expection from the Abuseipdb\Exceptions namespace. Those exceptions include the following:

If you'd like to handle these exceptions:

Testing (for package developers)

If using the provided test suite, please note that the test will only run error-free once every 15 minutes. The AbuseIPDB API will throw an error if an IP address is reported more than once in a period of 15 minutes, so any report endpoint tests will throw errors. Any tests that do not use the report endpoint will still work without any waiting period.

To add your API key for tests, copy the .env.testing.example file to .env.testing and fill in the ABUSEIPDB_API_KEY and BAD_IP_TO_TEST vars (you can get one from the AbuseIPDB site, make sure it has plenty of reports against it). The ABUSEIPDB_API_BASE_URL can be left as is.