Installation

Installing H3 PHP is two short steps: enable the FFI extension, then install the package with Composer. The package ships pre-built native binaries, so for most platforms there is nothing to compile.

Requirements

PHP 8.1 or higher
The FFI extension enabled in php.ini

Step 1 — Enable the FFI extension

H3 PHP talks to the H3 C library through PHP's Foreign Function Interface (FFI). FFI ships with PHP but is disabled by default, so you have to turn it on in your php.ini:

php.ini

; Load the FFI extension
extension=ffi
 
; Allow this library to use FFI
ffi.enable=true

ffi.enable accepts two useful values:

Value	Meaning	Use when
`true` (or `1`)	FFI works in every script	Development, CLI, most apps
`preload`	FFI works only in preloaded scripts	Production hardening

ffi.enable cannot be set at runtime

ffi.enable is a PHP_INI_SYSTEM directive — it can only be changed in php.ini itself, not with ini_set() or a .htaccess / .user.ini file. If FFI seems disabled, you are almost always editing the wrong php.ini. Run php --ini to find the file your CLI actually loads, and remember that the web SAPI (php-fpm, Apache) often uses a different php.ini than the CLI.

Verify FFI is enabled

# FFI should appear in the module list
php -m | grep FFI
 
# ffi.enable should report 1 (or "preload")
php -i | grep ffi.enable

If php -m | grep FFI prints nothing, the extension is not loaded — re-check the extension=ffi line and that you are editing the right php.ini.

Step 2 — Install the package

composer require foysal50x/h3-php

That's it. The package autoloads through PSR-4 under the Foysal50x\H3 namespace, and the bundled native library is detected automatically the first time you create an H3 instance.

app/Services/Geo.php

use Foysal50x\H3\H3;
 
$h3 = new H3();
$cell = $h3->latLngToCell(37.7749, -122.4194, 9);
echo $h3->h3ToString($cell);   // 8928308280fffff

Bundled pre-built binaries

H3 PHP includes pre-built copies of the H3 v4.4.1 native library for the most common platforms. The correct binary is auto-detected at runtime based on your OS and CPU architecture:

Platform	Architecture
macOS	Apple Silicon (arm64)
macOS	Intel (x86_64)
Linux	x64
Linux	ARM64
Windows	x64

On these platforms there is nothing else to install — Composer pulls the binary in with the package.

Pinned to H3 v4.4.1

The bundled binaries are built from H3 v4.4.1 (the latest release as of November 2025). The exact version is exposed as the constant H3::H3_VERSION if you need to assert it at runtime.

(Optional) Install a system H3 library

If your platform isn't in the table above — or the bundled binary doesn't load — install the H3 C library system-wide. H3 PHP will fall back to a system library when it can find one.

macOS (Homebrew):

brew install h3

Ubuntu / Debian:

sudo apt install libh3-dev

From source:

git clone https://github.com/uber/h3.git
cd h3
cmake -B build
cmake --build build
sudo cmake --install build

(Optional) Use a custom library path

If your H3 library lives somewhere non-standard, pass its full path to the constructor and H3 PHP will load that file instead of searching:

use Foysal50x\H3\H3;
 
$h3 = new H3('/custom/path/to/libh3.so');

Path and the singleton

The singleton remembers the library path it was created with. If you later call H3::getInstance() with a different path, it throws — call H3::resetInstance() first to switch paths.

Common installation errors

If creating an H3 instance throws an H3Exception, it is almost always one of these — each message tells you exactly what to fix:

Message (abridged)	Cause	Fix
`The FFI extension is not loaded`	`extension=ffi` missing	Add it to `php.ini`, restart php-fpm
`FFI is not enabled`	`ffi.enable` is off	Set `ffi.enable=true` or `preload`
`Could not find H3 library`	No bundled binary for your platform and no system H3	Install system H3 or pass a custom path

See Error Handling & Safety for the full exception surface.

You're ready

FFI is on and the package is installed. Continue to the Quick Start to index your first coordinate, read it back, and find its neighbors.