README

🌍 GeoIP PHP SDK

Developer-friendly & type-safe PHP SDK for enterprise IP geolocation services

📖 Table of Contents

🌍 GeoIP PHP SDK

🚀 Overview

The GeoIP PHP SDK is a high-performance, enterprise-grade library that provides real-time IP geolocation data for web applications. Built with modern PHP practices, this SDK offers type-safe interfaces and comprehensive error handling for seamless integration into your projects.

Perfect for applications requiring IP-based personalization, analytics, security monitoring, and geographic content delivery. The SDK supports multiple output formats including JSON, JSONP, XML, and YAML.

✨ Key Features

🔒 Type-safe - Full TypeScript-style type safety for PHP
⚡ High Performance - Optimized for enterprise-scale applications
🌐 Multiple Formats - JSON, JSONP, XML, and YAML support
🛡️ Error Handling - Comprehensive exception management
📦 Composer Ready - Easy installation via Composer
🔧 Configurable - Flexible server and endpoint configuration
📊 Real-time Data - Live IP geolocation information
🏢 Enterprise Grade - Built for production environments

📦 Installation

Prerequisites

PHP 8.0 or higher
Composer 2.0+
cURL extension enabled

Install via Composer

Add the following to your composer.json file:

{
    "repositories": [
        {
            "type": "github",
            "url": "https://github.com/geoip/geo-ip-php.git"
        }
    ],
    "require": {
        "geoipapi/sdk": "*"
    }
}

Then run:

composer install

Alternatively, install directly:

composer require geoipapi/sdk

🔧 Quick Start

Get up and running in under 2 minutes:

<?php
declare(strict_types=1);

require 'vendor/autoload.php';

use geoipapi\geoipapi\GeoIp;

// Initialize the SDK
$sdk = GeoIp::builder()->build();

// Get current IP information
$response = $sdk->geoIPEndpoints->getIp();

if ($response->res !== null) {
    echo "Your IP: " . $response->res->ip . "\n";
    echo "Country: " . $response->res->country . "\n";
    echo "City: " . $response->res->city . "\n";
}

📚 Usage Examples

Get Current IP Address

$response = $sdk->geoIPEndpoints->getIp();

if ($response->res !== null) {
    $ipData = $response->res;
    echo "IP: {$ipData->ip}\n";
    echo "Country: {$ipData->country}\n";
    echo "Region: {$ipData->region}\n";
    echo "City: {$ipData->city}\n";
    echo "Timezone: {$ipData->timezone}\n";
}

Get Specific IP Information

try {
    $response = $sdk->geoIPEndpoints->getIpData([
        'ip' => '8.8.8.8',
        'format' => 'json'
    ]);
    
    if ($response->responseGetJsonDataJsonGet !== null) {
        $data = $response->responseGetJsonDataJsonGet;
        // Process geolocation data
    }
} catch (Errors\HTTPValidationErrorThrowable $e) {
    echo "Validation error: " . $e->getMessage();
} catch (Errors\APIException $e) {
    echo "API error: " . $e->getMessage();
}

Custom Server Configuration

$sdk = GeoIp::builder()
    ->setServerURL('https://api.geoipapi.com')
    ->build();

🏗️ Project Structure

geo-ip-php/
├── src/                    # Source code
│   ├── Models/            # Data models and DTOs
│   ├── Endpoints/         # API endpoint classes
│   ├── Errors/           # Exception classes
│   └── GeoIp.php         # Main SDK class
├── docs/                  # Documentation
│   └── sdks/             # SDK-specific docs
├── tests/                # Test suite
├── composer.json         # Composer configuration
├── LICENSE              # MIT License
└── README.md           # This file

Key Components

src/GeoIp.php - Main SDK entry point and builder
src/Endpoints/ - Contains all API endpoint implementations
src/Models/ - Data transfer objects and response models
src/Errors/ - Custom exception classes for error handling
docs/ - Comprehensive API documentation

⚙️ Configuration

Environment Variables

# Optional: Custom API endpoint
GEOIP_API_URL=https://api.geoipapi.com

# Optional: Request timeout (seconds)
GEOIP_TIMEOUT=30

# Optional: Enable debug mode
GEOIP_DEBUG=false

SDK Configuration Options

$sdk = GeoIp::builder()
    ->setServerURL('https://custom-api.example.com')
    ->setTimeout(60)
    ->setDebugMode(true)
    ->build();

🧪 Testing

Run the test suite to ensure everything works correctly:

# Run all tests
composer test

# Run tests with coverage
composer test:coverage

# Run specific test file
vendor/bin/phpunit tests/Unit/GeoIpTest.php

# Run integration tests
composer test:integration

Test Categories

Unit Tests - Test individual components in isolation
Integration Tests - Test API interactions and data flow
End-to-End Tests - Test complete user workflows

🔄 Available Resources and Operations

GeoIP Endpoints

Method	Description	Parameters
`getIp()`	Get current IP address information	None
`getIpData(array $params)`	Get geolocation data for specific IP	`ip`, `format`

Response Formats

JSON (default) - Structured data format
JSONP - JSON with padding for cross-domain requests
XML - Extensible markup language format
YAML - Human-readable data serialization

For detailed API documentation, see docs/sdks/geoipendpoints/README.md.

❌ Error Handling

The SDK provides comprehensive error handling with specific exception types:

Exception Types

Exception	Status Code	Description
`APIException`	4XX, 5XX	General API errors
`HTTPValidationError`	422	Request validation failures
`NetworkException`	N/A	Network connectivity issues

Error Handling Example

use geoipapi\geoipapi\Models\Errors;

try {
    $response = $sdk->geoIPEndpoints->getIpData(['ip' => 'invalid-ip']);
} catch (Errors\HTTPValidationErrorThrowable $e) {
    // Handle validation errors
    error_log("Validation failed: " . $e->getMessage());
} catch (Errors\APIException $e) {
    // Handle API errors
    error_log("API error: " . $e->getMessage());
    error_log("Status code: " . $e->statusCode);
} catch (Exception $e) {
    // Handle unexpected errors
    error_log("Unexpected error: " . $e->getMessage());
}

🌐 Server Configuration

Default Server

The SDK uses https://api.geoipapi.com as the default server endpoint.

Custom Server

Override the default server globally:

$sdk = GeoIp::builder()
    ->setServerURL('https://your-custom-api.com')
    ->build();

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

Fork and clone the repository
Install dependencies: composer install
Run tests: composer test
Create a feature branch: git checkout -b feature/amazing-feature

Code Standards

Follow PSR-12 coding standards
Write comprehensive tests for new features
Update documentation for API changes
Use type declarations throughout

Pull Request Process

Ensure all tests pass
Update documentation if needed
Add entries to CHANGELOG.md
Submit PR with clear description

Development Commands

# Install dependencies
composer install

# Run code style checks
composer lint

# Fix code style issues
composer lint:fix

# Run static analysis
composer analyze

# Generate documentation
composer docs:generate

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

Built With

PHP 8.0+ - Modern PHP features and performance
Composer - Dependency management
PSR Standards - PHP Standards Recommendations
PHPUnit - Testing framework

Acknowledgements

Thanks to all contributors who help improve this SDK
GeoIP data providers for accurate location information
The PHP community for excellent tooling and standards

Ready to get started? ⭐ Star this repo and try the SDK today!

Report Bug • Request Feature • Discussions

geoipapi / sdk

Maintainers

Details