PHPackages timefrontiers/php-location - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. timefrontiers/php-location ActiveLibrary[Utility & Helpers](/categories/utility) timefrontiers/php-location ========================== Get visitor's location information from IP address with multiple provider support v1.0.1(3w ago)027MITPHPPHP >=8.1 Since Apr 14Pushed 3w agoCompare [ Source](https://github.com/timefrontiers/php-location)[ Packagist](https://packagist.org/packages/timefrontiers/php-location)[ Docs](https://github.com/timefrontiers/php-location)[ RSS](/packages/timefrontiers-php-location/feed)WikiDiscussions master Synced 1w ago READMEChangelog (2)Dependencies (1)Versions (3)Used By (0) TimeFrontiers PHP Location ========================== [](#timefrontiers-php-location) A modern, flexible PHP library to retrieve visitor location information from IP address with support for multiple GeoIP providers. [![PHP Version](https://camo.githubusercontent.com/04744bae0a61d2ffe29c26f07a9612eae20445fc6feaeb77b3af1f0e9be6447c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e312d3838393242462e737667)](https://php.net/)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE) Features -------- [](#features) - **Multiple GeoIP provider support** via interface – easily switch between services. - **Built-in free provider** using ip-api.com (no API key required). - **Currency symbol mapping** for over 100 currencies. - **Client IP auto-detection** from common server headers. - **Error collection** with access‑based filtering via `InstanceError`. - **Strict typing and modern PHP** (8.1+). - **PSR‑4 autoloading**. Installation ------------ [](#installation) ``` composer require timefrontiers/php-location ``` Requirements ------------ [](#requirements) - PHP 8.1 or higher - [timefrontiers/php-instance-error](https://github.com/timefrontiers/php-instance-error) ^1.0 (optional, for error display) Basic Usage ----------- [](#basic-usage) ### Quick Start [](#quick-start) ``` use TimeFrontiers\Location; $location = new Location(); echo $location->ip; // 123.45.67.89 echo $location->city; // Lagos echo $location->state; // Lagos echo $location->country; // Nigeria echo $location->country_code; // NG echo $location->currency_code; // NGN echo $location->currency_symbol; // ₦ echo $location->latitude; // 6.4474 echo $location->longitude; // 3.3903 ``` ### Specify an IP Address [](#specify-an-ip-address) ``` $location = new Location('8.8.8.8'); echo $location->city; // Mountain View ``` ### Refresh Location [](#refresh-location) ``` $location = new Location(); // Later... $location->refresh('1.1.1.1'); ``` Error Handling -------------- [](#error-handling) Errors are stored in a protected `$_errors` property and can be retrieved with `getErrors()`. Use the `InstanceError` package to filter errors based on user rank. ``` use TimeFrontiers\Location; use TimeFrontiers\InstanceError; $location = new Location('invalid-ip'); if (!$location->refresh()) { $errors = (new InstanceError($location, false))->get(); foreach ($errors['refresh'] as $error) { echo $error[2]; // Error message } } ``` GeoIP Providers --------------- [](#geoip-providers) ### Default: ip-api.com (free) [](#default-ip-apicom-free) The library uses ip-api.com by default with no API key required. Free tier limit: 45 requests per minute. ``` $location = new Location(); // Uses ip-api.com ``` ### Using a Commercial ip-api.com Key [](#using-a-commercial-ip-apicom-key) ``` use TimeFrontiers\GeoIP\IpApiService; $service = new IpApiService('your-api-key'); $location = new Location(null, $service); ``` ### Creating a Custom Provider [](#creating-a-custom-provider) Implement the `GeoIPInterface` and pass it to the constructor. ``` use TimeFrontiers\GeoIP\GeoIPInterface; use TimeFrontiers\GeoIP\LocationData; use TimeFrontiers\Location; class MyProvider implements GeoIPInterface { public function locate(string $ip): LocationData { // Fetch from your API return new LocationData( ip: $ip, city: '...', region: '...', country: '...', country_code: '...', currency_code: '...', currency_symbol: '...', latitude: 0.0, longitude: 0.0 ); } } $location = new Location(null, new MyProvider()); ``` Currency Symbols ---------------- [](#currency-symbols) The library includes a static map of over 100 currency codes to symbols (`CurrencySymbols::get('USD') // '$'`). If a code is not found, the code itself is returned. Available Properties -------------------- [](#available-properties) PropertyTypeDescription`$ip`stringIP address used`$city`stringCity name`$city_code`?stringReserved for future use (currently null)`$state`stringRegion/state name`$state_code`?stringReserved for future use (currently null)`$country`stringCountry name`$country_code`stringTwo‑letter country code`$currency_code`stringThree‑letter currency code`$currency_symbol`stringCurrency symbol (e.g. $, €, ₦)`$latitude`floatLatitude`$longitude`floatLongitudeSecurity Considerations ----------------------- [](#security-considerations) - IP addresses are never stored locally; they are sent to the configured GeoIP provider. - When using a free service, be aware of rate limits and privacy policies. - Client IP detection respects proxy headers; ensure your application is configured securely. License ------- [](#license) MIT License. See [LICENSE](LICENSE) for details. ``` ``` ### Health Score 40 — FairBetter than 86% of packages Maintenance94 Actively maintained with recent releases Popularity10 Limited adoption so far Community6 Small or concentrated contributor base Maturity43 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~29 days Total 2 Last Release 26d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dfcd9a5645cb2deb0771b9102be193d63b495564b1e06c0b85cb31bf028d0887?d=identicon)[ikechukwuokalia](/maintainers/ikechukwuokalia) --- Top Contributors [![ikechukwuokalia](https://avatars.githubusercontent.com/u/4541227?v=4)](https://github.com/ikechukwuokalia "ikechukwuokalia (4 commits)") --- Tags phpgeoipgeolocationIPlocation ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/timefrontiers-php-location/health.svg) ``` [![Health](https://phpackages.com/badges/timefrontiers-php-location/health.svg)](https://phpackages.com/packages/timefrontiers-php-location) ``` ### Alternatives [stevebauman/location Retrieve a user's location by their IP Address 1.3k8.2M84](/packages/stevebauman-location)[torann/geoip Support for multiple Geographical Location services. 2.3k14.9M92](/packages/torann-geoip)[zoujingli/ip2region ip2region v3.0 for PHP - 企业级 IP 地理位置查询库，支持 IPv4 和 IPv6，多种缓存策略，零依赖，开箱即用 1.4k462.5k65](/packages/zoujingli-ip2region)[interaction-design-foundation/laravel-geoip Support for multiple Geographical Location services. 19253.0k3](/packages/interaction-design-foundation-laravel-geoip)[tabgeo/country geoip (only countries) php library (http://tabgeo.com) 1160.3k](/packages/tabgeo-country) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)