Skip to content

Installation

Jump to bottom
Rumen Damyanov edited this page Jul 31, 2025 · 1 revision

Installation & Setup

Complete installation guide with configuration options and requirements for the php-geolocation package.

Requirements

  • PHP: 8.3 or higher
  • Composer: For package management
  • Cloudflare: For production geolocation data (optional in development)

Installation Methods

Via Composer (Recommended)

composer require rumenx/php-geolocation

Manual Installation

  1. Download the latest release from GitHub
  2. Extract to your project directory
  3. Include the autoloader:
require_once 'path/to/php-geolocation/src/Geolocation.php';
require_once 'path/to/php-geolocation/src/GeolocationSimulator.php';

Verification

Verify the installation works:

<?php
require_once 'vendor/autoload.php';

use Rumenx\Geolocation\Geolocation;

$geo = new Geolocation();
echo "Package installed successfully!\n";
echo "Local development: " . ($geo->isLocalDevelopment() ? 'Yes' : 'No') . "\n";

Configuration Options

Basic Configuration

use Rumenx\Geolocation\Geolocation;

// Default configuration
$geo = new Geolocation();

// Custom server data
$geo = new Geolocation($_SERVER);

// With country-to-language mapping
$countryToLanguage = [
    'US' => ['en'],
    'CA' => ['en', 'fr'],
    'DE' => ['de'],
    'FR' => ['fr'],
    'ES' => ['es'],
];

$geo = new Geolocation($_SERVER, $countryToLanguage);

// With custom language cookie name
$geo = new Geolocation($_SERVER, $countryToLanguage, 'my_lang_cookie');

Advanced Configuration

// Custom server array for testing
$customServer = [
    'HTTP_CF_IPCOUNTRY' => 'DE',
    'HTTP_CF_CONNECTING_IP' => '192.168.1.100',
    'HTTP_ACCEPT_LANGUAGE' => 'de-DE,de;q=0.9,en;q=0.8',
    'HTTP_USER_AGENT' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)...'
];

$geo = new Geolocation($customServer, $countryToLanguage, 'lang');

Environment Setup

Development Environment

For local development, no special setup is required. The package automatically detects local environments:

$geo = new Geolocation();

if ($geo->isLocalDevelopment()) {
    echo "Running in development mode\n";
    // Simulation features available
    $geo = Geolocation::simulate('US');
}

Production Environment

For production, you need Cloudflare configured. See the Cloudflare Setup Guide for detailed instructions.

Framework-Specific Setup

Laravel

Add to a service provider or use directly in controllers:

// In a controller
use Rumenx\Geolocation\Geolocation;

class HomeController extends Controller
{
    public function index()
    {
        $geo = new Geolocation();
        $country = $geo->getCountryCode();

        return view('home', compact('country'));
    }
}

Symfony

Register as a service or use directly in controllers:

// In a controller
use Rumenx\Geolocation\Geolocation;
use Symfony\Component\HttpFoundation\Response;

class HomeController extends AbstractController
{
    public function index(): Response
    {
        $geo = new Geolocation();
        $country = $geo->getCountryCode();

        return $this->render('home.html.twig', [
            'country' => $country
        ]);
    }
}

Plain PHP

Include in any PHP application:

require_once 'vendor/autoload.php';

use Rumenx\Geolocation\Geolocation;

$geo = new Geolocation();
$info = $geo->getGeoInfo();

// Use the geolocation data
include 'templates/header.php';
echo "<h1>Welcome visitor from " . $info['country_code'] . "!</h1>";
include 'templates/footer.php';

Testing Installation

Test Script

Create a test file to verify everything works:

<?php
// test-geolocation.php
require_once 'vendor/autoload.php';

use Rumenx\Geolocation\Geolocation;

echo "=== PHP Geolocation Test ===\n\n";

// Test 1: Basic initialization
$geo = new Geolocation();
echo "✓ Package loaded successfully\n";

// Test 2: Local development detection
$isLocal = $geo->isLocalDevelopment();
echo "✓ Local development: " . ($isLocal ? 'Yes' : 'No') . "\n";

// Test 3: Simulation (works in any environment)
$simGeo = Geolocation::simulate('DE');
$country = $simGeo->getCountryCode();
echo "✓ Simulation works: {$country}\n";

// Test 4: Get information
$info = $simGeo->getGeoInfo();
echo "✓ Data extraction works: " . count($info) . " fields\n";

echo "\n=== Test completed successfully! ===\n";

Run the test:

php test-geolocation.php

Common Issues

Composer Issues

# Clear composer cache
composer clear-cache

# Update dependencies
composer update

# Reinstall package
composer remove rumenx/php-geolocation
composer require rumenx/php-geolocation

PHP Version Issues

Check your PHP version:

php --version

The package requires PHP 8.3+. Update if necessary.

Autoloader Issues

Ensure the Composer autoloader is included:

// Make sure this path is correct
require_once __DIR__ . '/vendor/autoload.php';

Next Steps

Getting Help

Next: Quick Start Guide to begin using the package.

Clone this wiki locally