h3 Extension for PHP

PHP binding for Uber's H3 spatial coordinate library write by c extension for php7.

For more information on H3 and for the full API documentation, please see the H3 Documentation.

Post bug reports or feature requests to the Github Issues page
Ask questions by posting to the H3 tag on StackOverflow

Build from sources

first install official h3 library, and switch to official release at v3.7.1 (master or newer doesn't work)

% git clone https://github.com/uber/h3.git
% git checkout tags/v3.7.1 --force
% cd h3
% mkdir build
% cd build
% cmake -DBUILD_SHARED_LIBS=ON ..
% make -j4
% make install

then compile and install h3 php binding:

% cd php-h3
% phpize
% ./configure
% make
% make install

Building php_h3 on Windows

building h3 library Building H3 on Windows

mkdir build
cd build
cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release -DH3_ALLOC_PREFIX= ..
msbuild ALL_BUILD.vcxproj
msbuild RUN_TESTS.vcxproj

Copy h3.dll to php root directory

Add the php root directory to the system environment variable path

download php-sdk-binary-tools and php source,PHP version:PHP 7.0+

building php_h3 Build your own PHP on Windows

c:\php-sdk\phpsdk-vc15-x64.bat

If using Microsoft Build Tools 2019 run phpsdk-vc15-x64.bat,modify php-sdk\bin\phpsdk_setshell.bat to support

Copy php_h3 to source directory \ext\

Copy h3api.h to php_h3 directory

Add the following code to h3.c

#pragma comment(lib, "C:\\php-sdk\\h3-master\\build\\bin\\Debug\\h3.lib")
#pragma comment(linker, "/NODEFAULTLIB:msvcrtd.lib")

Enter your PHP source directory

buildconf
configure --disable-all --enable-cli --enable-h3=shared

Copy php_h3.dll to php extension_dir

Configration

enable h3.so extension in your php configration:

extension=h3.so

修复原版geoToH3 得到h3index 之后再h3ToGeo得到的值不一样的问题 zend_register_resource（ &indexed, le_h3_index) 后在 H3Index *indexed = (H3Index ) Z_RES_VAL_P(index_resource_zval); 获得的indexed值不对此处改为了 zend_register_resource（ indexed, le_h3_index) H3Index *indexed = (H3Index *) Z_RES_VAL_P(index_resource_zval); 使用indexed 问题解决了但原理咱不是很懂有懂的大佬再修复修复其他的

只处理了geoToH3 h3ToLong h3GetResolution h3ToGeo kRing h3ToGeoBoundary h3GetBaseCell h3IsValid h3IsResClassIII h3IsPentagon hexRange方法

h3ToGeoBoundary中原版输出的lat lon 没有进行radsToDegs操作此处增加了

php资源类型用于存储文件句柄，mysql链接等指针类型的数据。把 H3index（int64_t）当成资源类型，在geotoh3存地址后会销毁内存，再取地址就是随机数了，把本身当指针存，取出时自然也不能取地址内的内存。

h3返回H3的索引值H3index最多占63个比特，8字节；php7 以后"l" 对应的c类型为 zend_long 也是一个8字节无符号整形，所以将程序返回类型改为zend_long。

其他返回结构体（如经纬度），在 PHP 中可以使用数组（HashTable）和对象类型，为编码简单选用了数组类型。

部分函数返回结果未经测试，欢迎测试后提交bug或者直接修改。

Windows编译器不支持变长数组，都改为了calloc()，Linux使用可以改为变长数组。

☑ TODO

Global Helpers

h3ToLong (removed, pls use h3ToString)
h3FromLong (removed, pls use stringToH3)

Indexing

geoToH3
h3ToGeoBoundary
h3ToGeo

Inspection

Neighbors

Distance

h3Distance

Hierarchy

Regions

polyfill
maxPolyfillSize
h3SetToLinkedGeo
destroyLinkedPolygon

Unidirectional Edges

h3IndexesAreNeighbors
getH3UnidirectionalEdge
h3UnidirectionalEdgeIsValid
getOriginH3IndexFromUnidirectionalEdge
getDestinationH3IndexFromUnidirectionalEdge
getH3IndexesFromUnidirectionalEdge
getH3UnidirectionalEdgesFromHexagon
getH3UnidirectionalEdgeBoundary

Miscellaneous

Examples

$index = geoToH3(40.689167, -74.044444, 10);

var_dump($index);

var_dump(h3ToGeo($index));

var_dump(h3ToGeoBoundary($index));

var_dump(h3GetResolution($index));

var_dump(h3GetBaseCell($index));

var_dump(h3ToString($index, "hello world"));

var_dump(h3IsValid($index));

var_dump(h3IsResClassIII($index));

var_dump(h3IsPentagon($index));

var_dump(kRing($index, 5));

var_dump(maxKringSize(5));

var_dump(kRingDistances($index, 5));

var_dump(hexRange($index, 5));

var_dump(hexRangeDistances($index, 5));

$index1 = geoToH3(341.689167, -173.044444, 10);

var_dump(hexRanges([$index, $index1], 5));

var_dump(hexRing($index, 5));

var_dump(h3Distance($index, $index1));

var_dump(h3ToParent($index, 5));

var_dump(h3ToChildren($index, 2));

var_dump(maxH3ToChildrenSize($index, 2));

var_dump($rads = degsToRads(40.689167));

var_dump(radsToDegs($rads));

var_dump(hexAreaKm2(10));

var_dump(hexAreaM2(10));

var_dump(edgeLengthKm(10));

var_dump(edgeLengthM(10));

var_dump(numHexagons(2));


var_dump(h3IndexesAreNeighbors($index, $index1));
var_dump(getH3UnidirectionalEdge($index, $index1));
var_dump(h3UnidirectionalEdgeIsValid($index));
var_dump(getOriginH3IndexFromUnidirectionalEdge($index));
var_dump(getDestinationH3IndexFromUnidirectionalEdge($index));
var_dump(getH3IndexesFromUnidirectionalEdge($index));
var_dump(getH3UnidirectionalEdgesFromHexagon($index));
var_dump(getH3UnidirectionalEdgeBoundary($index));

var_dump($compacts = h3Compact([$index, $index1]));
var_dump(uncompact($compacts, 2));
var_dump(maxUncompactSize($compacts, 2));

hds-solutions/php-h3