Introduction

H3 PHP is a set of PHP bindings for Uber's H3 — a hexagonal hierarchical geospatial indexing system. It lets your application turn raw latitude / longitude coordinates into a compact, hierarchical grid of hexagons, then ask fast spatial questions about them: who is nearby, which cells does an area cover, and how far apart are two points.

The package is a thin, faithful binding of the official H3 C library (version 4.4.1) via PHP's FFI extension. You get the full H3 API in idiomatic PHP, with input validation, memory-safety limits, and typed exceptions layered on top.

What is H3?

H3 divides the surface of the Earth into a grid of hexagons. Picture wrapping the globe in chicken wire, where every cell of the mesh is a hexagon. H3 gives each of those hexagons a unique ID — a single 64-bit integer — so any place on Earth maps to exactly one cell.

Three properties make this powerful:

• Hierarchical. The grid exists at 16 resolutions (0–15). Resolution 0 has 122 enormous cells covering whole continents; resolution 15 has cells smaller than a square meter. Each cell neatly nests inside a coarser parent, so you can zoom in and out of the data.
• Roughly uniform. Hexagons tile the plane with only six neighbors each, all about the same distance away. That makes "find everything within k steps" simple and consistent, unlike a square grid where diagonal neighbors are farther than edge neighbors.
• Compact. A cell is just a number. You can store it in a database column, group by it, join on it, and index it like any other integer.

What you can do with it

Once a location is a cell, a lot becomes easy:

• Spatial indexing — store the cell alongside a record and query by cell instead of by bounding box. See Indexing & Inspection.
• Proximity search — expand outward from a cell to find everything nearby with gridDisk. See Traversal & Hierarchy.
• Aggregation & heatmaps — group millions of points by cell to count, bin, and visualize them.
• Coverage & geofencing — represent a region as a set of cells, then test membership with a single lookup.
• Measurement — compute exact cell areas, edge lengths, and great-circle distances. See Measurements & Utilities.

When to use it

H3 shines whenever you need to reason about where things are at scale — ride-sharing driver matching, food-delivery zones, fleet tracking, store locators, demand heatmaps, and any "what's near me" feature. The Examples page walks through several of these end to end.

If you only ever need the straight-line distance between two known points, the greatCircleDistanceKm helper covers that on its own — you don't have to adopt the grid for one calculation.

What this package gives you

• The complete H3 v4.4.1 API — indexing, inspection, traversal, hierarchy, directed edges, vertices, local IJ coordinates, measurements, and utilities.
• Input validation on every method — coordinates are checked for NaN, Inf, and range; H3 strings are checked for null bytes and valid hex; resolution relationships are enforced.
• Memory-safety limits — grid operations are bounded (default k ≤ 500) so a bad input can't exhaust memory.
• A typed H3Exception carrying the underlying H3 error code.
• Pre-built binaries for macOS (Apple Silicon & Intel), Linux (x64 & ARM64), and Windows (x64), auto-detected at runtime — no system library to compile.
• An optional singleton for convenient reuse.

Requirements

• PHP 8.1 or higher
• The FFI extension enabled (extension=ffi and ffi.enable=true or preload in php.ini)

The package bundles the H3 native library for common platforms, so for most installs you do not need to compile or install H3 yourself. Installation covers the optional system-library path for unusual platforms.

Links

Next steps

Head to Installation to enable FFI and add the package, then work through the Quick Start to index your first coordinate and find its neighbors.