README

A focused PHP library for the AbuseIPDB /check API, built for WordPress with wp_remote_get and transient caching. Community-sourced IP-abuse confidence scores (0-100) and report counts. Free tier supports ~1k checks/day.

Features

• 🎯 One endpoint — wraps /api/v2/check cleanly; no scope creep into reporting / blacklist endpoints
• 🚦 Stable error handling — auth / quota / transport failures come back as WP_Error, not a fake 0 score
• 🪶 Zero deps — only PHP and WordPress's HTTP API
• 🔁 Transient caching — per-IP, default 1-hour TTL
• 📦 Getter-friendly response — pull confidence score, total reports, country, usage type, Tor flag, allowlist flag without poking at raw JSON

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later
• AbuseIPDB account + API key (free tier available)

Installation

composer require arraypress/abuseipdb

Quick start

use ArrayPress\AbuseIPDB\Client;

$client = new Client( 'your-api-key' );

$result = $client->check_ip( '203.0.113.42' );

if ( is_wp_error( $result ) ) {
    error_log( 'AbuseIPDB failed: ' . $result->get_error_message() );
    return;
}

if ( $result->is_abusive() ) {
    // Confidence score >= 75 — block or hold the request
}

$score        = $result->get_confidence_score();   // 0-100
$reports      = $result->get_total_reports();      // lifetime report count
$reporters    = $result->get_distinct_reporters(); // distinct community reporters
$country      = $result->get_country_code();       // ISO-2
$usage_type   = $result->get_usage_type();         // 'Data Center/Web Hosting/Transit', etc.
$is_tor       = $result->is_tor();
$allowlisted  = $result->is_whitelisted();         // Google / Cloudflare / Apple etc.
$last_seen    = $result->get_last_reported_days(); // null when no reports

Configuration

$client = new Client(
    'api-key',
    [
        'max_age_days'  => 90,        // window of reports to consider (1-365)
        'cache_enabled' => true,      // default true
        'cache_ttl'     => 3600,      // seconds; default 1 hour
        'cache_prefix'  => 'abuse_',  // transient key prefix
    ]
);

Threshold guidance

AbuseIPDB documents two tiers:

The is_abusive() convenience boolean defaults to >= 75. Pass a custom threshold to use a different cutoff:

if ( $result->is_abusive( 90 ) ) {
    // Stricter check
}

Error handling

Errors come back as WP_Error:

$result = $client->check_ip( '203.0.113.42' );

if ( is_wp_error( $result ) ) {
    $code = $result->get_error_code();
    // 'abuseipdb_missing_ip', 'abuseipdb_missing_key',
    // 'abuseipdb_api_error', 'abuseipdb_bad_response',
    // or a passed-through WordPress HTTP error
}

Bonus: avoiding false positives

AbuseIPDB's is_whitelisted() flag covers IPs on public allowlists (Google, Cloudflare, Apple, etc.). Use it as an inverse signal so legitimate crawlers / Apple Private Relay traffic don't get blocked:

if ( ! $result->is_whitelisted() && $result->is_abusive() ) {
    // Only block when AbuseIPDB confirms abuse AND the IP isn't a known good actor
}

License

GPL-2.0-or-later