README.md

php-geobuf

PHP library for the geobuf compact geospatial format.

This is essentially a PHP port of the great pygeobuf.

Geobuf stores GeoJSON 6-8 times smaller and TopoJSON 2-3 times smaller. Depending on the $precision attribute, lossless compression is possible. More information about Geobuf is available in the JS implementation or the Python implementation.

Quick size comparison: An example 745 kB GeoJSON was converted to a 90 kB Geobuf file – more than 8 times less.

Beware: Experimental state – it works for my purposes but there probably are some bugs.

Installation

composer require mbolli/php-geobuf

Usage

The following methods are exposed:

Encoder

• encode() reads a JSON string. Returns a geobuf-encoded string
  • string $dataJson a JSON string
• encodeToFile() reads a JSON string and writes to a file. Returns the filesize of the resulting file or false
  • string $filePath where to store the resulting geobuf file
  • string $dataJson a JSON string
• encodeFileToBufFile() reads from a JSON file and writes to a file. Returns the filesize of the resulting file or false
  • string $jsonFile path to the JSON file
  • string $geobufFile where to store the resulting geobuf file
• encodeFileToBuf() reads from a JSON file. Returns a geobuf-encoded string
  • string $fileName path to the JSON file

All encoding methods support the following two non-mandatory arguments:

• int $precision max number of digits after the decimal point in coordinates, 6 by default (10 cm).
• int $dim number of dimensions in coordinates, 2 by default.

Decoder

• decodeToArray() returns a PHP array
  • string $encodedInput geobuf input
• decodeFileToArray() returns a PHP array
  • string $fileName path to the geobuf file
• decodeToJson() returns a JSON string
  • string $encodedInput geobuf input
• decodeFileToJson() returns a JSON string
  • string $fileName path to the geobuf file
• decodeFileToJsonFile() writes to a file and returns the filesize of the resulting JSON file or false
  • string $geobufFile path to the geobuf file
  • string $jsonFile where to store the resulting JSON file

Example

<?php

require_once('./vendor/autoload.php');

$jsonFile = './my.geojson';
$geobufFile = basename($jsonFile) . '.geobuf';
try {
    // encodes a json string to geobuf
    $geobufString = \MBolli\PhpGeobuf\Encoder::encode(
        file_get_contents($jsonFile), // (string) a json string 
        6, // (int) precision: max number of digits after the decimal point in coordinates, 6 by default
        2 // (int) dimensions: number of dimensions in coordinates, 2 by default.
    );
    
    // decodes a geobuf file to json
    $jsonString = \MBolli\PhpGeobuf\Decoder::decodeToJson(
        file_get_contents($geobufFile) // (string) expects a geobuf string
    )

} catch (\MBolli\PhpGeobuf\GeobufException $e) {
    var_dump($e);
} catch (\Throwable $e) {
    var_dump($e);
}

Contribute

Pull requests are encouraged. Code style is enforced by PHP-CS-Fixer:

composer run lint # lint source files and show problems (read-only)
composer run lint-diff # lint source files and show diff to the files fixed state (read-only)
composer run fix # lint source files and fix the problems
composer run test # execute all tests
composer run analyse # run phpstan static analyzer

If the PR is about the Encoder or Decoder, please add a test JSON to the tests/geojson folder. The test suite will automatically pick it up and test it when executed.

Background: Proto compilation

Classes were generated by the proto compiler using this command:

bin/protoc --proto_path=src --php_out=build src/geobuf.proto

Used was this proto file, lightly modified from the mapbox/geobuf proto file for proto3 compatibility and automated namespace generation.