Download the PHP package reddingwebdev/abuseipdb without Composer

AbuseIPDB PHP Client

A framework-agnostic PHP client for the AbuseIPDB APIv2, built on PSR-18/PSR-17, with an optional Symfony bundle. You can even use this with vanilla PHP projects with no formal framework!

• Covers all 7 endpoints: check, reports, blacklist, report, check-block, bulk-report, clear-address
• Typed parameter and result objects, typed exceptions, rate-limit metadata
• PHP 7.4+

Installation

If you already have a PHP Framework (Laravel, Symfony, etc) you're all done.

Otherwise, if you don't already have a PSR-18 HTTP client, you'll also need:

Standalone usage - simple setup

(Symfony Instructions and Advanced Standalone examples are later on)

check

Look up a single IP address and retrieve its abuse confidence score and, optionally, recent reports.

reports

Retrieve the reports associated with an IP address, with pagination and an optional report-age window.

blacklist

Download the current AbuseIPDB blacklist as structured entries or as a plaintext IP list.

report

Submit an abuse report for an IP address using one or more documented report categories.

check-block

Check an IP network in CIDR notation and retrieve reported-address counts within that block.

bulk-report

Submit multiple abuse reports at once by uploading a CSV file or passing CSV contents.

clear-address

Remove your reports for an IP address and retrieve the number of reports deleted.

Error handling

Every exception thrown by the library implements AbuseIpDb\Exception\AbuseIpDbException.

Invalid input (bad IP, empty categories, out-of-range values) is rejected before any HTTP call.

Rate limits

All fields are nullable when the headers are absent. API exceptions also expose getRateLimit().

Responses are not cached; caching check results is left to your application.

Standalone usage - more options

Symfony

The bundle is optional and inert unless you register it (requires symfony/framework-bundle or symfony/http-kernel + symfony/dependency-injection).

There is a Symfony Flex Recepie which has been created and submitted to Symfony for automatic prompting when you perform a composer require or composer install - this is currently pending, but once approved, the bundle will be automatically registered and configured for you. The only step required will be inserting your API Key either via the .env file or via Symfony Secrets.

Storing the API key

ABUSEIPDB_API_KEY is just an environment variable, so you can set it however your deployment normally handles secrets.

Flex writes a placeholder ABUSEIPDB_API_KEY= line into .env on install. For local development, put the real value in .env.local (git-ignored), or in an environment-specific .env.<env>.local:

For staging/production, prefer Symfony's encrypted secrets vault instead of plaintext env values:

No configuration change is needed for this — Symfony exposes vault secrets as environment variables at runtime, so the existing %env(ABUSEIPDB_API_KEY)% in abuse_ip_db.yaml picks it up automatically. Use .env.local for local development convenience, and secrets:set for anything deployed, since it keeps plaintext keys out of your environment/CI configuration.

Then autowire the client:

The service is also available as abuse_ip_db.client.

Troubleshooting: "Cannot autowire ... is type-hinted \"string\""

If one of your own services or commands type-hints the raw API key directly, e.g.:

you will get an error like:

This is a general Symfony limitation, not specific to this bundle: autowiring only works for object arguments, so a bare scalar type-hint (string, int, array, etc.) can never be autowired, no matter how the value is exposed.

• Recommended: type-hint AbuseIpDbClient $abuseIpDb instead (shown above) — this already autowires correctly and covers most use cases.

• If you truly need the raw key value (the string API key is primarily meant for standalone, non-Symfony usage), the bundle exposes it as the abuse_ip_db.api_key container parameter, and you must wire it explicitly in your own service, either with the #[Autowire] attribute:

  or with bind: in your config/services.yaml:

Development

Versioning & publishing

This package is published on Packagist as reddingwebdev/abuseipdb from the canonical GitHub repository. This package follows Semantic Versioning.

License

MIT — see LICENSE.