Package to easily integrate AbuseIPDB API with your Laravel project.
To install using Composer:
composer require abuseipdb/laravel
Add ABUSEIPDB_API_KEY to your .env file. Keys are made on the AbuseIPDB website for users with accounts.
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.
The main functions of the package are stored in the namespace Abuseipdb\AbuseIPDBLaravel.php. For your convenience, this package uses a facade to allow access to the main functions.
To use the facade, including the following in the file you wish to use it in:
use AbuseIPDB\Facades\AbuseIPDB;Then the functions can be called statically:
$response = AbuseIPDB::check('127.0.0.1');These functions will be explained in greater detail later in the documentation.
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:
use Symfony\Component\HttpFoundation\Exception\SuspiciousOperationException;
use AbuseIPDB\AbuseIPDBExceptionReporter;Inside of the Handler's register() function:
$this->stopIgnoring(SuspiciousOperationException::class);Inside of register function's $this->reportable(function (Throwable $e) {}
if ($e instanceof SuspiciousOperationException) {
AbuseIPDBExceptionReporter::reportSuspiciousOperationException();
}If your handler's register() does not contain the aforementioned $this->reportable, then include the following:
$this->reportable(function (Throwable $e) {
if ($e instanceof SuspiciousOperationException) {
AbuseIPDBExceptionReporter::reportSuspiciousOperationException();
}
});Now your project will automatically report to AbuseIPDB if a SuspiciousOperationException is thrown.
This package implements functions to easily interact with endpoints of the AbuseIPDB API.
These functions are stored in the AbuseIPDBLaravel.php and can be called statically with the AbuseIPDB facade.
The makeRequest function handles all API requests made through the package. The function's signature is as follows:
public function makeRequest($endpointName, $parameters, $acceptType = 'application/json') : ?ResponsemakeRequest accepts 3 parameters, and returns a response of type Illuminate\Http\Client\Response.
endpointName: Name of the AbuseIPDB API endpoint where the request will be made.
The following endpoints are supported by the API:
check, reports, blacklist, report, check-block, bulk-report, clear-address
Please refer the AbuseIPDB API Documentation for more information about the API.
This function will automatically make the correct HTTP Request type, whether the endpoint needs get, post or delete.
parameters: Any parameters that need to be passed to the API. This should an array, and will send parameters for any HTTP request method used by the API.
acceptType: Sets the Accept header for the request. By default this will be application/json. This may need to be set as text/plain if request is being made to the blacklist endpoint and plaintext response is desired.
This function returns a Illuminate\Http\Client\Response object. The documentation for this object is here.
As of current version, this package also has methods to request the check and report 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 ErrorResponse object will be returned. Objects are made to package the responses received by the API, and contain accessible properties that store the data from the response.
The check() method makes a request to the check endpoint of the AbuseIPDB API. Its signature is as follows:
public function check($ipAddress, $maxAgeInDays = null, $verbose = null): ResponseObjects\CheckResponseipAddress: IP address to be checked by the API.
maxAgeInDays: Optional: Age of reports used to check the IP address. Must be between 1 and 365 if set, default is 30.
verbose: Optional: If set, returns full reports array for the IP address.
Returns a ResponseObjects\CheckResponse object. Please refer to documentation below regarding this object.
The report() method makes a request to the report endpoint of the AbuseIPDB API. Its signature is as follows:
public function report($ip, $categories, $comment = null): ResponseObjects\ReportResponseip: IP address to be reported.
categories: Single category or array of categories, provided as numbers between 1 and 30. Please refer to AbuseIPDB's reference on their category numbers here.
comment: Optional: Include information about the attack, such as an error log message.
Returns a ResponseObjects\ReportResponse object. Please refer to documentation below regarding this object.
The reports() method makes a request to the reports endpoint of the AbuseIPDB API. Its signature is as follows:
public function reports(string $ipAddress, int $maxAgeInDays = 30, int $page = 1, int $perPage = 25): ReportsPaginatedResponseipAddress: The IP address to get reports for
maxAgeInDays: Optional: Age of reports used to check the IP address. Must be between 1 and 365 if set, the default is 30.
page: Optional: Current page of pagination. Must be at least 1, the default is 1.
perPage: Optional: Quantity of results per page. Must be between 1 and 100, the default is 25.
Returns a ResponseObjects\ReportResponse object. Please refer to documentation below regarding this object.
All custom response objects extend a custom AbuseResponse class, which extracts certain headers from the response and makes them accessible.
When handling responses that call an endpoint with custom responses, include the following at the top of file with requesting code:
use AbuseIPDB\ResponseObjects;Then those object types can be referenced as follows:
ResponseObjects\AbuseResponse
ResponseObjects\CheckResponse
ResponseObjects\ReportResponse
ResponseObjects\ReportsPaginatedResponseThe AbuseResponse makes specific headers sent with a response from AbuseIPDB's API more accessible. The following properties are accessible from the object:
use AbuseIPDB\ResposneObjects\AbuseResponse;
$response = new AbuseResponse($httpResponse);
$response -> x_ratelimit_limit
$response -> x_ratelimit_remaining;
$response -> content_type;
$response -> cache_control;
$response -> cf_cache_status;Since the custom endpoint-specific response objects extend the AbuseResponse object, you may access these properties from the child object. You may also access any method from the Illuminate\Http\Client\Response class, such as headers() or status().
The CheckResponse object reflects the response data given from making a check response to the API. The following properties are included:
use AbuseIPDB\ResponseObjects\CheckResponse;
$response = new CheckResponse($httpResponse);
$response -> ipAddress;
$response -> isPublic;
$response -> ipVersion;
$response -> isWhitelisted
$response -> abuseConfidenceScore;
$response -> countryCode;
$response -> usageType;
$response -> isp;
$response -> domain;
$response -> hostnames;
$response -> isTor;
$response -> totalReports
$response -> numDistinctUsers;
$response -> lastReportedAt;
$response -> countryName;
$response -> reports The ReportResponse object reflects the response data given from making a report response to the API. The following properties are included:
use AbuseIPDB\ResponseObjects\ReportResponse;
$response = new ReportResponse($httpResponse);
$response -> $ipAddress;
$response -> $abuseConfidenceScore; use AbuseIPDB\ResponseObjects\ReportsPaginatedResponse;
$response = new ReportsPaginatedResponse($httpResponse);
$response->total;
$response->page;
$response->perPage;
$response->lastPage;
$response->nextPageUrl;
$response->previousPageUrl;In the event of an error, this package will throw an expection from the Abuseipdb\Exceptions namespace. Those exceptions include the following:
InvalidAcceptTypeException //Accept Type was set to type other than application/json or text/plain.
InvalidEndpointException //Endpoint name provided was not a valid endpoint for the API.
InvalidParameterException //Parameter passed in was invalid for the API.
MissingParameterException //A required parameter for an endpoint was missing.
PaymentRequiredException //402 error was thrown by API, indicating feature needs a higher subscription.
TooManyRequestsException //429 error was thrown by API, indicating request limit has been exceeded.
UnprocessableContentException //422 error was thrown by API, indicating request parameters could not be handled, either missing or incorrect.
UnconventionalErrorException //Error code other than 402, 422, or 429 was returned by the API.To handle these exceptions, use like the following:
use AbuseIPDB\Exceptions;
try {
/* some code */
}
catch(Throwable $e){
if($e instanceof Exceptions\TooManyRequestsException){
//429 was thrown, do something to address issue
}
}Additionally, be wary of the ArgumentCountError that will be thrown if any functions are called with the incorrect number of arguments.
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 a bunch of reports against it). The ABUSEIPDB_API_BASE_URL can be left as is.