Quick Start

This guide takes you from a fresh install to working with the grid: turn a coordinate into a cell, read it back, and find what's nearby. It assumes you've already enabled FFI and installed the package — if not, start with Installation.

Every step builds on the last, so the snippets concatenate into one runnable script.

Step 1 — Create an H3 instance

Everything goes through an H3 object. Construct one directly:

use Foysal50x\H3\H3;
 
$h3 = new H3();

The first time you create an instance, H3 PHP locates and loads the native library. If that fails it throws an H3Exception explaining what to fix — usually an FFI setting.

Step 2 — Index a coordinate into a cell

latLngToCell is the workhorse: give it a latitude, a longitude, and a resolution (0–15), and it returns the H3 cell that contains that point.

// San Francisco, at resolution 9 (cells ~174 m across)
$cell = $h3->latLngToCell(37.7749, -122.4194, 9);

The returned value is a 64-bit integer — the cell's index. That's the number you store in a database, group by, or join on.

Step 3 — Read the cell as a string

The integer index has a canonical hexadecimal string form — the representation you'll see in APIs, logs, and the H3 documentation. Convert with h3ToString:

echo $h3->h3ToString($cell);   // 8928308280fffff

To go the other way — string back to integer — use stringToH3:

$cell = $h3->stringToH3('8928308280fffff');

Step 4 — Read the cell's center back

Given a cell, cellToLatLng returns the latitude and longitude of its center as an associative array:

$center = $h3->cellToLatLng($cell);
 
echo $center['lat'];   // 37.77670234943567
echo $center['lng'];   // -122.41845030397129

The shape is array{lat: float, lng: float}. Indexing and reading back are not exact inverses — the center of the cell won't equal your original point, but it will be the same cell.

Step 5 — Find the neighbors

gridDisk returns every cell within k grid steps of an origin — a filled hexagonal disk. At k = 1 that's the cell itself plus its six immediate neighbors:

$neighbors = $h3->gridDisk($cell, 1);
 
echo count($neighbors);   // 7  (the origin + 6 neighbors)

Increase k to widen the search. k = 2 returns 19 cells, k = 3 returns 37, and so on — each ring adds 6 * k cells. This is the foundation of every "what's near me" query; see Traversal & Hierarchy for the full toolkit.

// A wider search area — every cell within 3 steps
$searchArea = $h3->gridDisk($cell, 3);
 
foreach ($searchArea as $nearbyCell) {
    // look up records stored against $nearbyCell
}

The singleton pattern

Loading the native library has a small one-time cost. If you use H3 throughout a request, reuse a single instance with the built-in singleton instead of constructing new H3() repeatedly:

use Foysal50x\H3\H3;
 
$h3 = H3::getInstance();   // creates on first call, reuses thereafter
 
$cell = $h3->latLngToCell(37.7749, -122.4194, 9);

If you need to load a different library path, reset the singleton first:

H3::resetInstance();
$h3 = H3::getInstance();

Putting it together

<?php
 
require __DIR__ . '/vendor/autoload.php';
 
use Foysal50x\H3\H3;
 
$h3 = H3::getInstance();
 
// 1. Index a coordinate
$cell = $h3->latLngToCell(37.7749, -122.4194, 9);
 
// 2. Inspect it
echo 'Cell:   ' . $h3->h3ToString($cell) . PHP_EOL;
echo 'Res:    ' . $h3->getResolution($cell) . PHP_EOL;
 
// 3. Read the center back
$center = $h3->cellToLatLng($cell);
printf("Center: %.5f, %.5f\n", $center['lat'], $center['lng']);
 
// 4. Find neighbors
$neighbors = $h3->gridDisk($cell, 1);
echo 'Neighbors (incl. self): ' . count($neighbors) . PHP_EOL;

Next steps

• Learn the grid vocabulary in Core Concepts — resolutions, base cells, pentagons, and the string-vs-integer split.
• Explore the full indexing surface in Indexing & Inspection.
• Build real proximity queries in Traversal & Hierarchy.
• See it all applied in the Examples.