IP Insight - Intelligent IP Geolocation and Analytics

Powerful IP geolocation and analytics WordPress plugin with efficient caching and enrichment from multiple data sources.

Features

Core Functionality

• REST API for IP lookups with custom namespace (/ipinsight/v1/)
• Bulk processing capabilities for multiple IP addresses
• Efficient caching system with configurable TTL
• Automatic data enrichment from multiple providers
• Admin dashboard with detailed analytics and monitoring
• Shortcode and Block Editor support for frontend integration

Data Sources

• MaxMind GeoLite2 database for initial geolocation data
• ip-api.com for data enrichment and validation
• Local CSV imports for custom data sources
• MMDB file support for MaxMind binary databases

Performance & Scalability

• SQLite database with optimized indexing for fast lookups
• Rate limiting to prevent API abuse
• Background job processing for data imports and enrichment
• Automatic database maintenance and cleanup
• Memory-efficient bulk operations

Security

• Input validation and sanitization
• CSRF protection with WordPress nonces
• Capability-based access control
• Secure file uploads with type validation
• Private IP filtering options
• API key encryption and secure storage

Installation

Requirements

• WordPress 5.9 or higher
• PHP 8.0 or higher
• SQLite support (usually included with PHP)
• Write permissions for uploads directory

Manual Installation

1. Download the plugin files
2. Upload to /wp-content/plugins/ip-insight/
3. Activate through WordPress admin
4. Configure settings in IP Insight menu

Configuration

1. API Keys: Configure provider API keys in settings
2. Rate Limits: Set appropriate rate limits for your needs
3. Data Sources: Upload MaxMind CSV or configure API access
4. Cache Settings: Configure TTL and cache behavior

Usage

REST API

Single IP Lookup

GET /wp-json/ipinsight/v1/ip?q=8.8.8.8

Response:

{
  "status": "success",
  "country": "United States",
  "countryCode": "US",
  "region": "CA",
  "regionName": "California",
  "city": "Mountain View",
  "zip": "94043",
  "lat": 37.4056,
  "lon": -122.0775,
  "timezone": "America/Los_Angeles",
  "isp": "Google LLC",
  "org": "Google Public DNS",
  "as": "AS15169 Google LLC",
  "query": "8.8.8.8",
  "updatedAt": 1640995200
}

Bulk IP Lookup

POST /wp-json/ipinsight/v1/ip/bulk
Content-Type: application/json

{
  "queries": ["8.8.8.8", "1.1.1.1", "208.67.222.222"]
}

Statistics

GET /wp-json/ipinsight/v1/stats

Shortcode

[ipinsight_lookup]

Displays an IP lookup form on the frontend.

Attributes:

• placeholder: Input placeholder text
• button_text: Submit button text
• show_map: Show location map (true/false)

Block Editor

Search for "IP Insight Lookup" in the block editor to add the lookup form to any post or page.

PHP Integration

// Get IP data
$ip_data = ipinsight()->get_service('repository')->find_ip('8.8.8.8');

// Validate IP
$validator = ipinsight()->get_service('validator');
$result = $validator->validate_ip('8.8.8.8');

// Log message
ipinsight_log('Custom message', 'info', ['context' => 'data']);

Configuration

Environment Variables

Create .env.php in plugin directory:

<?php
// Database
define('IPINSIGHT_DB_TYPE', 'sqlite');
define('IPINSIGHT_DB_PATH', WP_CONTENT_DIR . '/ip-insight/ip-insight.db');

// API Keys
define('IPINSIGHT_IPAPI_KEY', 'your-ip-api-key');
define('IPINSIGHT_MAXMIND_KEY', 'your-maxmind-key');

// Rate Limits
define('IPINSIGHT_PUBLIC_RATE_LIMIT', 60);
define('IPINSIGHT_ENRICH_BATCH_SIZE', 5000);

// Cache
define('IPINSIGHT_CACHE_TTL', 2592000); // 30 days
define('IPINSIGHT_NEGATIVE_CACHE_TTL', 3600); // 1 hour

// Security
define('IPINSIGHT_ALLOW_PRIVATE_IPS', false);
define('IPINSIGHT_CORS_ORIGINS', 'https://example.com');

// Debug
define('IPINSIGHT_DEBUG', false);

WordPress Options

Settings are stored in ipinsight_options:

$options = [
    'public_rate_limit' => 60,
    'cache_ttl' => 2592000,
    'allow_private_ips' => false,
    'cors_origins' => '',
    'enrich_batch_size' => 5000,
    'debug_enabled' => false,
];

Data Import

MaxMind CSV Import

1. Download GeoLite2 CSV files from MaxMind
2. Go to IP Insight > Settings > Import
3. Upload CSV files
4. Monitor import progress in dashboard

MMDB Import

1. Upload MMDB file through admin interface
2. Plugin will convert to CSV format automatically
3. Import process runs in background

API Enrichment

Plugin automatically enriches data using configured providers:

• ip-api.com: Free tier (1000 requests/month)
• MaxMind: Paid API access
• Custom providers: Extensible architecture

Background Jobs

Scheduled Tasks

• Enrichment Job: Runs hourly to update incomplete records
• Cleanup Job: Daily cleanup of old data and logs
• Stats Job: Daily statistics aggregation
• Vacuum Job: Weekly database optimization

Manual Jobs

Trigger jobs manually through admin interface:

• Import CSV/MMDB files
• Enrich specific IP ranges
• Database maintenance
• Cache cleanup

Monitoring & Analytics

Dashboard Metrics

• Total IP records in database
• Cache hit/miss ratios
• API provider health status
• Daily lookup statistics
• Database size and performance
• Recent activity logs

Performance Monitoring

• Response time tracking
• Error rate monitoring
• Provider quota usage
• Database query performance
• Memory usage statistics

Security Considerations

API Security

• Rate limiting per IP address
• Input validation and sanitization
• CORS configuration
• Nonce verification for admin actions

Data Protection

• Database stored outside web root
• .htaccess protection for data directory
• API key encryption
• Secure file upload handling

Privacy Compliance

• No personal data collection
• IP addresses are not logged by default
• Configurable data retention policies
• GDPR-compliant data handling

Troubleshooting

Common Issues

Database Connection Errors

Solution: Check file permissions and SQLite support

Rate Limit Exceeded

Solution: Adjust rate limits in settings or wait for reset

Import Failures

Solution: Check file format and size limits

Debug Mode

Enable debug mode for detailed logging:

define('IPINSIGHT_DEBUG', true);
define('IPINSIGHT_DEBUG_LOG', WP_CONTENT_DIR . '/debug-ip-insight.log');

Log Files

• Debug Log: /wp-content/debug-ip-insight.log
• WordPress Error Log: Standard WordPress error log
• Database Logs: Stored in plugin options

Development

Architecture

• Service Container: Dependency injection pattern
• Repository Pattern: Database abstraction
• Provider Pattern: External API abstraction
• Job Queue: Background processing
• Event System: Extensible hooks

Extending the Plugin

Custom Providers

class CustomProvider extends IPInsight\Providers\BaseProvider {
    public function lookup($ip) {
        // Custom implementation
    }
}

Custom Hooks

// Before IP lookup
add_action('ipinsight_before_lookup', function($ip) {
    // Custom logic
});

// After data enrichment
add_action('ipinsight_after_enrich', function($ip, $data) {
    // Custom processing
});

Testing

# Run unit tests
composer test

# Run integration tests
composer test:integration

# Code quality checks
composer phpcs
composer phpstan

Contributing

1. Fork the repository
2. Create feature branch
3. Follow WordPress coding standards
4. Add tests for new features
5. Update documentation
6. Submit pull request

Coding Standards

• WordPress Coding Standards (WPCS)
• PSR-4 autoloading
• PHPDoc documentation
• Unit test coverage

License

This plugin is licensed under the GPLv2 or later.

Support

• Documentation: See /docs directory
• Issues: GitHub issue tracker
• Community: WordPress.org support forums

Changelog

See CHANGELOG.md for detailed version history.

Credits

• MaxMind: GeoLite2 database
• ip-api.com: IP geolocation API
• WordPress: Plugin framework
• Contributors: See GitHub contributors

---

Note: This plugin respects the terms of service of all data providers and implements appropriate rate limiting and attribution.