Indexing & Inspection

These are the functions you reach for first: turning coordinates into cells, turning cells back into geometry, and examining the properties of a cell you already hold.

All examples assume you have an instance:

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

Indexing functions

latLngToCell

Convert a latitude/longitude to the H3 cell that contains it.

public function latLngToCell(float $lat, float $lng, int $resolution): int

Parameter	Type	Description
`$lat`	`float`	Latitude in degrees, −90 to 90
`$lng`	`float`	Longitude in degrees, −180 to 180
`$resolution`	`int`	Target resolution, 0–15

Returns the cell index as an int. Throws an H3Exception if a coordinate is NaN/Inf/out of range, or the resolution is outside 0–15.

$cell = $h3->latLngToCell(37.7749, -122.4194, 9);
echo $h3->h3ToString($cell);   // 8928308280fffff

cellToLatLng

Get the center coordinate of a cell.

public function cellToLatLng(int $cell): array

Returns array{lat: float, lng: float}.

$center = $h3->cellToLatLng($cell);
printf("%.5f, %.5f\n", $center['lat'], $center['lng']);
// 37.77670, -122.41845

cellToBoundary

Get the vertices of a cell's boundary — the corners of the hexagon (or pentagon), in order.

public function cellToBoundary(int $cell): array

Returns a list of array{lat: float, lng: float} vertices (6 for a hexagon, 5 for a pentagon, with occasional extra vertices on Class III cells). This is what you feed into a map polygon.

$boundary = $h3->cellToBoundary($cell);
 
foreach ($boundary as $vertex) {
    printf("  %.5f, %.5f\n", $vertex['lat'], $vertex['lng']);
}
echo 'Vertices: ' . count($boundary) . PHP_EOL;

Drawing a cell on a map

cellToBoundary returns the corners in [lat, lng] order. Most mapping libraries (Leaflet, GeoJSON) expect [lng, lat] — flip each pair when building the polygon, and close the ring by repeating the first vertex at the end.

Inspection functions

These read properties of a cell without converting it back to geometry.

getResolution

Return the resolution (0–15) a cell was created at.

public function getResolution(int $cell): int

$res = $h3->getResolution($cell);   // 9

Handy when you import cells from elsewhere and don't know their resolution up front.

getBaseCellNumber

Return the resolution-0 base cell (0–121) a cell descends from.

public function getBaseCellNumber(int $cell): int

$base = $h3->getBaseCellNumber($cell);   // e.g. 20

Useful for coarse partitioning — every cell on Earth rolls up into one of 122 base cells.

h3ToString

Convert an integer index to its canonical hexadecimal string.

public function h3ToString(int $cell): string

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

stringToH3

Convert a hexadecimal string back to an integer index.

public function stringToH3(string $str): int

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

Throws an H3Exception if the string contains a null byte, is not valid hexadecimal, or is too long. This is your sanitization boundary for cell IDs arriving from outside.

isValidCell

Check whether an index is a well-formed H3 cell.

public function isValidCell(int $cell): bool

if ($h3->isValidCell($cell)) {
    // safe to use
}

Validate external input

Always run isValidCell() (or stringToH3() inside a try) on cell indices that arrive from API requests, imported files, or a database you don't fully trust. Passing a malformed index to other functions raises errors.

isResClassIII

Check whether a cell belongs to a Class III (odd) resolution.

public function isResClassIII(int $cell): bool

$isClassIII = $h3->isResClassIII($cell);   // true for odd resolutions

See Res Class III for why this matters.

isPentagon

Check whether a cell is one of the 12 pentagons at its resolution.

public function isPentagon(int $cell): bool

if ($h3->isPentagon($cell)) {
    // handle the 5-neighbor edge case
}

getIcosahedronFaces

Return the icosahedron face numbers (0–19) a cell touches. Most cells touch a single face; cells near a base-cell boundary or a pentagon can touch several.

public function getIcosahedronFaces(int $cell): array

$faces = $h3->getIcosahedronFaces($cell);   // e.g. [7]

Worked example — validate and inspect imported cells

A small routine that ingests cell IDs from an external source and reports on each:

inspect.php

use Foysal50x\H3\H3;
use Foysal50x\H3\H3Exception;
 
$h3 = H3::getInstance();
 
$incoming = ['8928308280fffff', '872830829ffffff', 'not-a-cell'];
 
foreach ($incoming as $str) {
    try {
        $cell = $h3->stringToH3($str);
 
        if (!$h3->isValidCell($cell)) {
            echo "$str: invalid cell\n";
            continue;
        }
 
        printf(
            "%s: res %d, base cell %d%s\n",
            $str,
            $h3->getResolution($cell),
            $h3->getBaseCellNumber($cell),
            $h3->isPentagon($cell) ? ' (pentagon)' : ''
        );
    } catch (H3Exception $e) {
        echo "$str: rejected — {$e->getMessage()}\n";
    }
}

Next steps

Move across the grid with Traversal & Hierarchy.
Work with cell edges and corners in Edges & Vertices.