'Automatic (recommended): detects Cloudflare', self::MODE_DIRECT => 'Not behind a proxy or CDN (most sites)', self::MODE_CLOUDFLARE => 'Cloudflare (CF-Connecting-IP)', self::MODE_REAL_IP => 'X-Real-IP header', self::MODE_FORWARDED => 'X-Forwarded-For header (one proxy in front)', ); /** @param array $server $_SERVER-style values (already unslashed). */ public static function resolve( array $server, string $mode = self::MODE_DIRECT, ?array $extraCloudflareRanges = null ): string { $remote = self::valid( $server['REMOTE_ADDR'] ?? null ); $fromHeader = null; switch ( $mode ) { case self::MODE_AUTO: // Trust CF-Connecting-IP only when the connection itself comes from a Cloudflare address. if ( null !== $remote && CloudflareRanges::isCloudflare( $remote, $extraCloudflareRanges ) ) { $fromHeader = self::valid( $server['HTTP_CF_CONNECTING_IP'] ?? null ); } break; case self::MODE_CLOUDFLARE: $fromHeader = self::valid( $server['HTTP_CF_CONNECTING_IP'] ?? null ); break; case self::MODE_REAL_IP: $fromHeader = self::valid( $server['HTTP_X_REAL_IP'] ?? null ); break; case self::MODE_FORWARDED: $raw = $server['HTTP_X_FORWARDED_FOR'] ?? null; if ( is_string( $raw ) && '' !== trim( $raw ) ) { $parts = array_map( 'trim', explode( ',', $raw ) ); $fromHeader = self::valid( end( $parts ) ); // the entry our proxy appended; earlier ones are client-supplied } break; } return $fromHeader ?? $remote ?? 'unknown'; } /** * Rate-limit BUCKET KEY for a resolved address (never use it as the "real" IP): IPv4 unchanged, IPv4-mapped IPv6 * becomes its IPv4, any other IPv6 collapses to its /64 (one subscriber/host can rotate freely inside a /64), * 'unknown' stays, anything unparsable becomes 'unknown'. */ public static function bucketKey( string $ip ): string { $ip = trim( $ip ); if ( 'unknown' === $ip || false === filter_var( $ip, FILTER_VALIDATE_IP ) ) { return 'unknown'; } if ( false === filter_var( $ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6 ) ) { return $ip; } $bin = inet_pton( $ip ); if ( false === $bin || 16 !== strlen( $bin ) ) { return 'unknown'; } if ( str_repeat( "\0", 10 ) . "\xff\xff" === substr( $bin, 0, 12 ) ) { return (string) inet_ntop( substr( $bin, 12 ) ); } return bin2hex( substr( $bin, 0, 8 ) ) . '/64'; } private static function valid( mixed $v ): ?string { if ( ! is_string( $v ) ) { return null; } $v = trim( $v ); return false !== filter_var( $v, FILTER_VALIDATE_IP ) ? $v : null; } }