-
Notifications
You must be signed in to change notification settings - Fork 0
Config Reference
Rumen Damyanov edited this page Jul 31, 2025
·
1 revision
Complete reference for all configuration options available in php-geolocation package.
- Basic Configuration
- Provider Configuration
- Cache Configuration
- Simulation Configuration
- API Configuration
- Logging Configuration
- Security Configuration
- Performance Configuration
- Environment Variables
- Configuration Examples
<?php
// config/geolocation.php
return [
// Default IP to use when none is provided
'default_ip' => '8.8.8.8',
// Default country code for fallback
'default_country' => 'US',
// Default language for fallback
'default_language' => 'en',
// Default currency for fallback
'default_currency' => 'USD',
// Default timezone for fallback
'default_timezone' => 'UTC',
// Enable/disable the package
'enabled' => true,
// Enable debug mode
'debug' => false,
// Enable simulation mode for local development
'simulation_mode' => env('APP_ENV') === 'local',
// Strict mode - throw exceptions on errors
'strict_mode' => false,
// Timeout for external API calls (seconds)
'timeout' => 10,
// Number of retry attempts for failed requests
'retry_attempts' => 3,
// Delay between retry attempts (seconds)
'retry_delay' => 1
];<?php
// Provider-specific configuration
'providers' => [
'cloudflare' => [
'enabled' => true,
'priority' => 1,
'headers' => [
'country' => 'CF-IPCountry',
'region' => 'CF-Region',
'city' => 'CF-IPCity',
'timezone' => 'CF-Timezone',
'latitude' => 'CF-IPLatitude',
'longitude' => 'CF-IPLongitude'
],
'fallback_enabled' => true,
'trust_proxy' => true
],
'maxmind' => [
'enabled' => false,
'priority' => 2,
'license_key' => env('MAXMIND_LICENSE_KEY'),
'user_id' => env('MAXMIND_USER_ID'),
'database_path' => storage_path('geoip/GeoLite2-City.mmdb'),
'auto_update' => true,
'update_interval' => 7 * 24 * 60 * 60, // 7 days
'services' => [
'city' => true,
'country' => true,
'insights' => false
]
],
'ipapi' => [
'enabled' => false,
'priority' => 3,
'api_key' => env('IPAPI_KEY'),
'endpoint' => 'http://api.ipapi.com',
'fields' => [
'country_code',
'country_name',
'region_code',
'region_name',
'city',
'zip',
'latitude',
'longitude',
'timezone',
'currency',
'languages'
],
'security_enabled' => false // Requires paid plan
],
'ipstack' => [
'enabled' => false,
'priority' => 4,
'api_key' => env('IPSTACK_KEY'),
'endpoint' => 'http://api.ipstack.com',
'use_https' => false, // Requires paid plan
'security_module' => false, // Requires paid plan
'hostname_lookup' => false,
'fields' => 'main'
],
'ipgeolocation' => [
'enabled' => false,
'priority' => 5,
'api_key' => env('IPGEOLOCATION_KEY'),
'endpoint' => 'https://api.ipgeolocation.io/ipgeo',
'fields' => [
'country_code2',
'country_name',
'state_prov',
'city',
'latitude',
'longitude',
'time_zone',
'currency'
]
],
'freegeoip' => [
'enabled' => false,
'priority' => 6,
'endpoint' => 'https://freegeoip.app/json',
'rate_limit' => 15000, // per hour
'timeout' => 5
]
];'failover' => [
'enabled' => true,
'strategy' => 'priority', // priority, round_robin, random
'max_failures' => 3,
'failure_timeout' => 300, // 5 minutes
'circuit_breaker' => [
'enabled' => true,
'failure_threshold' => 5,
'recovery_timeout' => 600, // 10 minutes
'test_interval' => 30
]
];'cache' => [
'enabled' => true,
'store' => 'redis', // redis, memcached, file, database, array
'prefix' => 'geolocation:',
'ttl' => 3600, // 1 hour default TTL
// TTL for different data types
'ttl_by_type' => [
'country' => 86400, // 24 hours
'region' => 43200, // 12 hours
'city' => 21600, // 6 hours
'coordinates' => 86400, // 24 hours
'timezone' => 604800, // 7 days
'currency' => 604800, // 7 days
'language' => 604800, // 7 days
'provider_data' => 3600 // 1 hour
],
// Cache key strategies
'key_strategy' => 'ip_hash', // ip_hash, ip_plain, custom
'hash_algorithm' => 'sha256',
// Cache warming
'warming' => [
'enabled' => false,
'ips' => [
'8.8.8.8', // Google DNS
'1.1.1.1', // Cloudflare DNS
'208.67.222.222' // OpenDNS
],
'schedule' => '0 2 * * *' // Daily at 2 AM
],
// Cache tags for selective clearing
'tags' => [
'enabled' => true,
'by_country' => true,
'by_provider' => true,
'by_ip_range' => false
],
// Redis-specific configuration
'redis' => [
'connection' => 'cache',
'serializer' => 'php', // php, igbinary, json
'compression' => false,
'cluster' => false
],
// File cache configuration
'file' => [
'path' => storage_path('cache/geolocation'),
'permissions' => 0644,
'locking' => true
],
// Database cache configuration
'database' => [
'connection' => null,
'table' => 'geolocation_cache',
'cleanup_schedule' => '0 3 * * *' // Daily at 3 AM
]
];// Create migration: php artisan make:migration create_geolocation_cache_table
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class CreateGeolocationCacheTable extends Migration
{
public function up()
{
Schema::create('geolocation_cache', function (Blueprint $table) {
$table->id();
$table->string('key', 255)->unique();
$table->longText('value');
$table->string('tags')->nullable();
$table->timestamp('expires_at');
$table->timestamps();
$table->index(['key', 'expires_at']);
$table->index('tags');
});
}
public function down()
{
Schema::dropIfExists('geolocation_cache');
}
}'simulation' => [
'enabled' => env('APP_ENV') === 'local',
'default_country' => 'US',
'random_mode' => false,
// IP-to-country mappings for testing
'ip_mappings' => [
'192.168.1.100' => 'US',
'192.168.1.101' => 'CA',
'192.168.1.102' => 'GB',
'192.168.1.103' => 'DE',
'192.168.1.104' => 'FR',
'192.168.1.105' => 'JP',
'192.168.1.106' => 'AU',
'192.168.1.107' => 'BR'
],
// Country-specific simulation data
'countries' => [
'US' => [
'country_name' => 'United States',
'region' => 'California',
'city' => 'San Francisco',
'latitude' => 37.7749,
'longitude' => -122.4194,
'timezone' => 'America/Los_Angeles',
'currency' => 'USD',
'language' => 'en'
],
'CA' => [
'country_name' => 'Canada',
'region' => 'Ontario',
'city' => 'Toronto',
'latitude' => 43.6532,
'longitude' => -79.3832,
'timezone' => 'America/Toronto',
'currency' => 'CAD',
'language' => 'en'
],
'GB' => [
'country_name' => 'United Kingdom',
'region' => 'England',
'city' => 'London',
'latitude' => 51.5074,
'longitude' => -0.1278,
'timezone' => 'Europe/London',
'currency' => 'GBP',
'language' => 'en'
],
'DE' => [
'country_name' => 'Germany',
'region' => 'Bavaria',
'city' => 'Munich',
'latitude' => 48.1351,
'longitude' => 11.5820,
'timezone' => 'Europe/Berlin',
'currency' => 'EUR',
'language' => 'de'
],
'FR' => [
'country_name' => 'France',
'region' => 'Île-de-France',
'city' => 'Paris',
'latitude' => 48.8566,
'longitude' => 2.3522,
'timezone' => 'Europe/Paris',
'currency' => 'EUR',
'language' => 'fr'
],
'JP' => [
'country_name' => 'Japan',
'region' => 'Tokyo',
'city' => 'Tokyo',
'latitude' => 35.6762,
'longitude' => 139.6503,
'timezone' => 'Asia/Tokyo',
'currency' => 'JPY',
'language' => 'ja'
],
'AU' => [
'country_name' => 'Australia',
'region' => 'New South Wales',
'city' => 'Sydney',
'latitude' => -33.8688,
'longitude' => 151.2093,
'timezone' => 'Australia/Sydney',
'currency' => 'AUD',
'language' => 'en'
],
'BR' => [
'country_name' => 'Brazil',
'region' => 'São Paulo',
'city' => 'São Paulo',
'latitude' => -23.5505,
'longitude' => -46.6333,
'timezone' => 'America/Sao_Paulo',
'currency' => 'BRL',
'language' => 'pt'
]
],
// Simulation behavior
'behavior' => [
'add_random_delay' => true,
'delay_range' => [50, 200], // milliseconds
'simulate_failures' => false,
'failure_rate' => 0.05, // 5%
'vary_coordinates' => true,
'coordinate_variance' => 0.01 // degrees
]
];'api' => [
'enabled' => true,
'version' => 'v1',
'base_path' => '/api/v1/geolocation',
// Authentication
'authentication' => [
'enabled' => true,
'methods' => ['api_key', 'jwt'], // api_key, jwt, oauth2
'required_for' => ['detailed', 'batch'], // all, detailed, batch, none
'public_endpoints' => [
'/api/v1/geolocation/countries',
'/api/v1/geolocation/currencies',
'/api/v1/geolocation/languages',
'/api/v1/geolocation/timezones'
]
],
// Rate limiting
'rate_limiting' => [
'enabled' => true,
'global' => [
'requests_per_minute' => 1000,
'requests_per_hour' => 10000
],
'per_ip' => [
'requests_per_minute' => 60,
'requests_per_hour' => 1000
],
'per_user' => [
'requests_per_minute' => 100,
'requests_per_hour' => 2000
],
'endpoint_specific' => [
'/api/v1/geolocation/batch' => [
'requests_per_minute' => 10,
'requests_per_hour' => 100
]
]
],
// Response configuration
'response' => [
'format' => 'json', // json, xml
'include_metadata' => true,
'pretty_print' => false,
'charset' => 'UTF-8',
'compression' => true,
'etag_enabled' => true
],
// CORS configuration
'cors' => [
'enabled' => true,
'allowed_origins' => ['*'],
'allowed_methods' => ['GET', 'POST', 'OPTIONS'],
'allowed_headers' => ['Content-Type', 'Authorization', 'X-API-Key'],
'exposed_headers' => ['X-RateLimit-*'],
'max_age' => 86400
],
// API documentation
'documentation' => [
'enabled' => true,
'path' => '/api/docs',
'title' => 'PHP Geolocation API',
'version' => '1.0.0',
'description' => 'Geographic location detection API'
]
];'graphql' => [
'enabled' => false,
'endpoint' => '/api/graphql',
'playground' => [
'enabled' => env('APP_ENV') !== 'production',
'path' => '/api/graphql/playground'
],
'schema_cache' => true,
'introspection' => env('APP_ENV') !== 'production',
'max_query_complexity' => 1000,
'max_query_depth' => 15
];'logging' => [
'enabled' => true,
'level' => 'info', // debug, info, notice, warning, error, critical, alert, emergency
'channel' => 'geolocation',
// What to log
'log_requests' => true,
'log_responses' => false,
'log_cache_hits' => false,
'log_cache_misses' => true,
'log_errors' => true,
'log_performance' => true,
// Log rotation
'rotation' => [
'enabled' => true,
'max_files' => 10,
'max_size' => '10MB'
],
// Sensitive data filtering
'filter_sensitive' => true,
'sensitive_fields' => [
'ip_address',
'exact_coordinates',
'user_agent'
],
// Performance logging
'performance' => [
'slow_request_threshold' => 1000, // milliseconds
'log_sql_queries' => false,
'log_external_api_calls' => true
]
];// config/logging.php
'channels' => [
'geolocation' => [
'driver' => 'daily',
'path' => storage_path('logs/geolocation.log'),
'level' => env('LOG_LEVEL', 'debug'),
'days' => 14,
'replace_placeholders' => true,
],
];'security' => [
// IP validation
'ip_validation' => [
'enabled' => true,
'allow_private' => false,
'allow_reserved' => false,
'whitelist' => [],
'blacklist' => []
],
// Data sanitization
'sanitization' => [
'enabled' => true,
'sanitize_output' => true,
'escape_html' => true,
'max_string_length' => 255
],
// Privacy protection
'privacy' => [
'anonymize_ips' => false,
'anonymization_method' => 'hash', // hash, truncate, encrypt
'data_retention_days' => 30,
'gdpr_compliant' => true
],
// SSL/TLS
'ssl' => [
'verify_peer' => true,
'verify_host' => true,
'allow_self_signed' => false,
'cafile' => null,
'capath' => null
],
// Request signing
'request_signing' => [
'enabled' => false,
'algorithm' => 'sha256',
'header_name' => 'X-Signature'
]
];'performance' => [
// Connection pooling
'connection_pooling' => [
'enabled' => true,
'max_connections' => 10,
'idle_timeout' => 30,
'connection_timeout' => 5
],
// Concurrent requests
'concurrency' => [
'max_concurrent_requests' => 5,
'queue_timeout' => 10
],
// Memory management
'memory' => [
'max_memory_usage' => '128MB',
'garbage_collection' => true,
'cache_cleanup_interval' => 3600
],
// Database optimization
'database' => [
'connection_pooling' => true,
'query_caching' => true,
'index_optimization' => true
],
// Monitoring
'monitoring' => [
'enabled' => true,
'metrics_collection' => true,
'performance_alerts' => [
'slow_response_threshold' => 2000, // milliseconds
'high_error_rate_threshold' => 0.05, // 5%
'memory_usage_threshold' => 0.8 // 80%
]
]
];# .env file
# Application
APP_ENV=local
APP_DEBUG=true
# Geolocation
GEOLOCATION_ENABLED=true
GEOLOCATION_DEBUG=false
GEOLOCATION_SIMULATION_MODE=true
GEOLOCATION_DEFAULT_COUNTRY=US
# Provider API Keys
MAXMIND_LICENSE_KEY=your_maxmind_license_key
MAXMIND_USER_ID=your_maxmind_user_id
IPAPI_KEY=your_ipapi_key
IPSTACK_KEY=your_ipstack_key
IPGEOLOCATION_KEY=your_ipgeolocation_key
# Cache
CACHE_DRIVER=redis
GEOLOCATION_CACHE_TTL=3600
# API
GEOLOCATION_API_ENABLED=true
GEOLOCATION_API_AUTH_ENABLED=true
GEOLOCATION_RATE_LIMIT_ENABLED=true
# Security
GEOLOCATION_SSL_VERIFY=true
GEOLOCATION_ANONYMIZE_IPS=false
# Logging
GEOLOCATION_LOG_LEVEL=info
GEOLOCATION_LOG_REQUESTS=true<?php
// config/geolocation.php for production
return [
'enabled' => true,
'debug' => false,
'simulation_mode' => false,
'strict_mode' => true,
'timeout' => 5,
'retry_attempts' => 2,
'providers' => [
'cloudflare' => [
'enabled' => true,
'priority' => 1
],
'maxmind' => [
'enabled' => true,
'priority' => 2,
'license_key' => env('MAXMIND_LICENSE_KEY'),
'auto_update' => true
]
],
'cache' => [
'enabled' => true,
'store' => 'redis',
'ttl' => 86400, // 24 hours
'warming' => [
'enabled' => true,
'schedule' => '0 2 * * *'
]
],
'api' => [
'enabled' => true,
'authentication' => [
'enabled' => true,
'methods' => ['api_key', 'jwt']
],
'rate_limiting' => [
'enabled' => true,
'per_ip' => [
'requests_per_minute' => 100,
'requests_per_hour' => 2000
]
]
],
'logging' => [
'enabled' => true,
'level' => 'warning',
'log_requests' => false,
'log_errors' => true
],
'security' => [
'ip_validation' => [
'enabled' => true,
'allow_private' => false
],
'privacy' => [
'anonymize_ips' => true,
'data_retention_days' => 30
],
'ssl' => [
'verify_peer' => true,
'verify_host' => true
]
]
];<?php
// config/geolocation.php for development
return [
'enabled' => true,
'debug' => true,
'simulation_mode' => true,
'strict_mode' => false,
'timeout' => 10,
'simulation' => [
'enabled' => true,
'random_mode' => true,
'behavior' => [
'add_random_delay' => true,
'simulate_failures' => true,
'failure_rate' => 0.1
]
],
'cache' => [
'enabled' => true,
'store' => 'array',
'ttl' => 300 // 5 minutes
],
'api' => [
'enabled' => true,
'authentication' => [
'enabled' => false
],
'rate_limiting' => [
'enabled' => false
]
],
'logging' => [
'enabled' => true,
'level' => 'debug',
'log_requests' => true,
'log_cache_hits' => true,
'log_performance' => true
],
'security' => [
'ip_validation' => [
'allow_private' => true
],
'ssl' => [
'verify_peer' => false
]
]
];<?php
// config/geolocation.php for testing
return [
'enabled' => true,
'simulation_mode' => true,
'strict_mode' => true,
'simulation' => [
'enabled' => true,
'random_mode' => false,
'behavior' => [
'add_random_delay' => false,
'simulate_failures' => false
]
],
'cache' => [
'enabled' => false
],
'logging' => [
'enabled' => false
],
'providers' => [
'cloudflare' => [
'enabled' => false
]
]
];Previous: API Development Patterns | Next: Error Handling