Download the PHP package rumenx/php-geolocation without Composer
On this page you can find all versions of the php package rumenx/php-geolocation. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download rumenx/php-geolocation
More information about rumenx/php-geolocation
Files in rumenx/php-geolocation
Package php-geolocation
Short Description Simple, framework-agnostic PHP utility for Cloudflare geolocation detection and client information extraction.
License MIT
Homepage https://github.com/RumenDamyanov/php-geolocation
Rated 5.00 based on 1 reviews
Informations about the package php-geolocation
php-geolocation
A simple, framework-agnostic PHP utility for Cloudflare geolocation detection and client information extraction. Provides helpers to access geolocation, language, and client information (OS, browser, device, resolution) from HTTP headers.
Features
- ๐ Detects Cloudflare geolocation headers (country, IP, etc.)
- ๐ Helper methods to access geolocation, language, and client info (OS, browser, device, resolution)
- ๐ Configurable country-to-language mapping (supports multiple official languages per country)
- ๐ค Language negotiation: matches browser and available site languages for multi-language countries
- ๐ช Configurable language cookie name
- โ๏ธ Configurable fields for returned visitor info
- ๐ ๏ธ Local development simulation - Fake Cloudflare headers for testing without production setup
- ๐ญ Auto-detection of local environments (localhost, local IPs, missing Cloudflare headers)
- ๐งช Fully tested with Pest (100% coverage)
- โ PSR-12 compliant, static analysis and style checks
- ๐ Simple utility class - no framework dependencies or complex setup required
๐ Documentation & Wiki
For comprehensive documentation, examples, and advanced usage patterns, visit our Complete Wiki Documentation:
๐ Quick Links
- Quick Start Guide - Get running in minutes
- Framework Integration - Laravel, Symfony, CodeIgniter guides
- CloudFlare Setup - Production configuration
- Local Development - Testing without CloudFlare
- Multi-language Websites - International applications
- Production Deployment - Best practices & monitoring
- API Development - RESTful APIs with geolocation
- Configuration Reference - Complete options guide
๐ Advanced Topics
- Error Handling - Robust error management
- Caching Strategies - Performance optimization
- Analytics Integration - Geographic tracking
- Troubleshooting - Common issues & solutions
Why This Design?
This package is intentionally designed as a simple utility library rather than a complex framework integration. Here's why:
๐ฏ Focused Purpose
- Single responsibility: Extract and process geolocation data from HTTP headers
- Pure functions: No side effects, no global state, predictable behavior
- Framework-agnostic: Works with any PHP application or framework
๐ง Easy Integration
- No service providers needed: Just instantiate the class when you need it
- No configuration files: Pass configuration directly to the constructor
- No middleware complexity: Use it exactly where and when you need it
- Developer control: You decide how and when to use geolocation data
๐ฆ Minimal Dependencies
- Zero runtime dependencies: Only requires PHP 8.3+
- Small footprint: Single class, focused functionality
- Fast installation: No complex dependency trees
- Version compatibility: No framework version constraints
This approach makes the package more reliable, easier to understand, and simpler to maintain - following the Unix philosophy of "do one thing and do it well."
Installation
Local Development Simulation
When developing locally where Cloudflare is not available, you can simulate its functionality:
Quick Simulation
Advanced Simulation
Auto-Detection of Local Environment
Available Countries for Simulation
Framework Integration for Development
For Laravel and Symfony, check the /examples
directory for middleware and event listeners that automatically inject simulated Cloudflare headers in development environments.
Usage
Basic Usage
Language Detection
Client Information
Framework Integration Examples
Laravel
Symfony
Plain PHP
Configuration
The package is simple and requires minimal configuration. All settings are passed directly to the constructor:
Constructor Parameters
$server
(array, optional): HTTP server array, defaults to$_SERVER
$countryToLanguage
(array, optional): Country code to language mapping$languageCookieName
(string, optional): Language cookie name, defaults to'lang'
Country-to-Language Mapping
Map country codes (ISO 3166-1 alpha-2) to language codes or arrays. The first language is the default for the country:
Example Configurations
Minimal Setup
Basic Country Mapping
Custom Cookie Name
Full Configuration
No configuration files, service providers, or complex setup needed!
Examples
The examples/
directory contains practical demonstrations of the package capabilities:
๐ฏ Basic Usage
demo.php
- Interactive demo showing simulation in local development with multiple countries
โก Framework Integration
LaravelDevelopmentMiddleware.php
- Laravel middleware for automatic header injection in developmentSymfonyDevelopmentListener.php
- Symfony event listener for request-level simulation
๐ Real-World Applications
content-localization.php
- Redirect visitors to country-specific domainsapi-endpoint.php
- REST API with geolocation-based responses (currency, features, etc.)multi-language.php
- Automatic language detection with fallbacks for multi-language sites
Running Examples
All examples automatically detect local development and use simulation, so they work perfectly without Cloudflare setup! ๐
Contributing
We welcome contributions! Please see our Contributing Guide for details on how to contribute to this project.
Code of Conduct
This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
Development
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
composer test
- Run static analysis:
composer analyze
- Check code style:
composer style
- Submit a pull request
Related Projects
๐น Go Version
- go-geolocation - Go adaptation of this package with similar functionality for the Go ecosystem
๐ฎ Future Versions (Planned)
- Python version - Python adaptation planned for future release
- WordPress plugin - WordPress integration plugin planned
- Drupal module - Drupal integration module planned
Security
If you discover a security vulnerability, please see our Security Policy for information on how to report it responsibly.
Changelog
All notable changes to this project are documented in the Changelog.
Support
- ๐ Documentation
- ๐ Issue Tracker
- ๐ฌ Discussions
- ๐ Sponsor this project
License
MIT