This in-depth article will guide you on how to install PHP GeoIP, which can be necessary for handling visitors with country-based tasks using PHP.
- 1 Install PHP GeoIP: Step by step
- 1.1 1. Download GeoIP / GeoIP2 databases
- 1.2 2. Method 1: Install PHP GeoIP PECL extension
- 1.3 3. Method 2: Install PHP GeoIP2 / GeoLite2 library
- 1.4 Summary
- 1.5 References
- 1.6 You might also like
What is PHP GeoIP extension?
GeoIP is a PHP extension to get location from an IP address. The primary location information including City, Sate, Country, Longitude, Latitude, ISP and other various information.
How does GeoIP work?
The PHP GeoIP extension works by using the geolocation data created by MaxMind Inc., a US-based leading company in providing IP intelligence and online fraud detection tools.
The extension reads the IP address, then checks with the geolocation data inside the bundled database file (provided by MaxMind), and returns the geolocation information.
Currently, there are two main methods for using GeoIP in PHP:
- PHP GeoIP PECL extension (Deprecated): The original PHP GeoIP extension works as a PHP PECL extension (
php_geoip.dllin Windows), using GeoIP Legacy databases. MaxMind has planned to retire the GeoIP Legacy databases at the end of May 2022. While the legacy databases are still usable, they won’t be updated or supported after that date.
*There is also a client API for GeoIP Legacy Database, but it is not widely used as PECL extension.
- PHP GeoIP2 client library (recommended): Using the newer GeoIP2 databases, doesn’t require installing PHP extensions and only needs the GeoIP2 database + GeoIP2 PHP API to work. This is the recommended method.
*The deprecated PHP PECL GeoIP extension will not work with GeoIP2 databases.
For GeoIP2 method in this tutorial, we will use the free database from MaxMind, which is called GeoLite2.
Which GeoIP to choose for PHP?
As the above recommended option, using GeoIP2 is preferred, as it includes future updates, that means more data accuracy compared to the legacy PECL extension method.
However, in this in-depth tutorial, we will introduce both legacy GeoIP and newer GeoIP2 installation methods for you to pick, since there are still servers using old PHP versions, and in general, unless you want absolute precise location, the Legacy database, or the newer GeoIP2 free version – GeoLite2, are more than enough to provide fairly accurate geolocation information of the IP addresses.
We will also provide downloadable database files/URLs, saving your time looking for them.
Install PHP GeoIP: Step by step
1. Download GeoIP / GeoIP2 databases
You need the GeoIP (legacy) / GeoIP2 databases downloaded and stored to a accessible location first for PHP to read and make use of the database. It could be either at the same project’s root directory, or in system public access directories, such as
/usr/local/share/ directory in Linux.
For GeoIP legacy databases, navigate to this URL and scroll to the Download section:
For GeoIP2 free version – GeoLite2 databases, you can register for a MaxMind account to download the free databases.
Fortunately, we’re going to save you some time. Just navigate to this URL and scroll to the Download section:
You can pick the type of database you want there to download.
After downloaded, extract the package and copy the file to the above mentioned, recommended location. For example:
// GeoIP Legacy database .dat file /usr/local/share/GeoIP.dat // GeoLite2 Country database /usr/local/share/GeoLite2-Country.mmdb
Afteer copying the database file to the preferred location, we can start the extension installation.
2. Method 1: Install PHP GeoIP PECL extension
To install PHP GeoIP extension, depends on the operation system, the method will be different.
2.1. Install PHP GeoIP extension on Windows
Getting PHP GeoIP extension installed on Windows is pretty easy, you just have to download it, and copy the DLL extension file to the
ext folder inside PHP directory, and configure
php.ini to load that extension.
To download latest GeoIP version for Windows, navigate to this URL and scroll down to the DLL List table to pick the correct version to download:
To pick the right version to download, here are our quick tips:
- PHP version: Unfortunately, the GeoIP PECL extension only support maximum of PHP version 7.4 on Windows.
- Thread safety: If you’re using native Apache Handler (LoadModule or default XAMPP Apache configuration) or native IIS, pick Thread Safe version. If you use FastCGI for Apache, use the Non Thread Safe version.
- x86 and x64: If your Windows version is 32-bit, use x86 version. Else, x64 is for 64-bit.
*For example, with PHP 7.3, default Apache Handler, Windows 64-bit, the right version to pick is
7.3 Thread Safe (TS) x64 file.
After downloaded the file, extract it, we will have a number of files but the only one we need is the
Copy the file to the
ext directory of your PHP installation. For example, with XAMPP, the path will be
Finally, enable the extension by modifying
php.ini, the file is usually inside PHP installation directory.
Insert this line into the end of
php.ini file if it doesn’t exist:
If the line existed for some reason, it would have the semicolon comment at the start:
Then, just remove the
Save the file. Skip to the 2.3. Verify that installation works below.
2.2. Install PHP GeoIP extension on Linux
For CentOS or RedHat-based OS, install PHP GeoIP PECL extension by this command:
yum install -y php-pecl-geoip
For Ubuntu or Debian-based OS, install the extension by this command:
sudo apt-get install -y php-geoip
After successful installation, move on the to next section for verifying that installation works.
*We will constantly update this article with more operating systems, along with troubleshooting installation issues.
2.3. Verify that installation works
On either operating system, create a new PHP file, insert these lines:
Save the file and open it on your browser. Look for the
geoip text, if you see this section, the installation is successfully done and GeoIP should work:
2.4. PHP GeoIP PECL extension usage
Below is an example on how to use PHP GeoIP PECL extension for general geolocation information. The database path for the
GeoIP.dat is where we saved as mentioned above.
<?php // Required - Set GeoIP database path geoip_setup_custom_directory('/usr/local/share/GeoIP.dat'); // Get country code geoip_country_code_by_name('184.108.40.206'); // US // Get country name geoip_country_name_by_name('220.127.116.11'); // United States
To see the full list of GeoIP functions, check the official PHP.net GeoIP extension page.
3. Method 2: Install PHP GeoIP2 / GeoLite2 library
This is the recommended method, making GeoIP up to date, easier to use, and less chance of having incompatibility issues on different operating system.
To install PHP GeoIP2 using GeoIP2 PHP API, it is recommended to have Composer installed first.
We assumes that you already have Composer installed, if not, here is the quick way to get it installed.
On your project’s root directory:
3.1. For Linux
To quickly install Composer, run this command:
curl -sS https://getcomposer.org/installer | php
This will download the
composer.phar file and save it to the current directory.
Then, run this command to install the latest GeoIP2 PHP API version:
php composer.phar require geoip2/geoip2:~2.0
This will add a
vendor directory to your current one if it doesn’t exist, along with the
3.2. For Windows
Navigate to Composer download page:
Download and run the
Composer-Setup.exe file to install the latest composer version.
Then, use this command at your project root directory:
composer require geoip2/geoip2:~2.0
Similar with Linux, this will have
composer.lock file and
vendor directory created.
3.3. GeoIP2 PHP API Usage
This is a quick example on how to get basic Country geolocation information based on an IP address by using GeoIP2 PHP API. The GeoLite2 database path is where the downloaded database file in the previous section get saved as recommended.
<?php require_once 'vendor/autoload.php'; use GeoIp2\Database\Reader; $reader = new Reader('/usr/local/share/GeoLite2-Country.mmdb'); $record = $reader->country('18.104.22.168'); print($record->country->isoCode . "\n"); // 'US' print($record->country->name . "\n"); // 'United States' print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota' print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN' print($record->city->name . "\n"); // 'Minneapolis' print($record->postal->code . "\n"); // '55455' print($record->location->latitude . "\n"); // 44.9733 print($record->location->longitude . "\n"); // -93.2323 print($record->traits->network . "\n"); // '22.214.171.124/32'
GeoIP has many usages in PHP, mainly for handling visitors based on the country, or more detailed, city, ISP, etc. By default, the free database can already provide pretty accurate information, but you can always subscribe for the paid GeoIP2 database which will be more accurate (check the pricing here), which could be utilized for fraud prevention in ecommerce websites.
We hope that the tutorial is helpful for you, as we will constantly update and add more useful PHP guides.