Skip to content

Latest commit

 

History

History
224 lines (162 loc) · 11.8 KB

README.md

File metadata and controls

224 lines (162 loc) · 11.8 KB
Raw

Brick\Geo

A collection of classes to work with GIS geometries.

Build Status Coverage Status

Introduction

This library is a PHP implementation of the OpenGIS specification.

It is essentially a wrapper around a third-party GIS engine, to which it delegates most of the complexity of the geometry calculations. Several engines are supported, from native PHP extensions such as GEOS to GIS-compatible databases such as MySQL or PostgreSQL.

Requirements and installation

This library requires PHP 5.6 or PHP 7. HHVM will be supported as soon as issue #4858 is fixed.

We recommend installing it with Composer. Just define the following requirement in your composer.json file:

{
    "require": {
        "brick/geo": "dev-master"
    }
}

Then head on to the Configuration section to configure a GIS geometry engine.

Failure to configure a geometry engine would result in a GeometryEngineException being thrown when trying to use a method that requires one.

Configuration

Configuring the library consists in choosing the most convenient GeometryEngine implementation for your installation. The following implementations are available:

  • PDOEngine: communicates with a GIS-compatible database over a PDO connection.
    This engine currently supports the following databases:
    • MySQL version 5.6 or greater.
      Note: MySQL currently only supports 2D geometries.
    • MariaDB version 5.5 or greater.
    • PostgreSQL with the PostGIS extension.
  • SQLite3Engine: communicates with a SQLite3 database with the SpatiaLite extension.
  • GEOSEngine: uses the GEOS PHP bindings.

Following is a step-by-step guide for all the possible configurations:

Using PDO and MySQL 5.6 or greater

  • Ensure that your MySQL version is at least 5.6.
    Earlier versions only have partial GIS support based on bounding boxes and are not supported.

  • Use this bootstrap code in your project:

      use Brick\Geo\Engine\GeometryEngineRegistry;
  use Brick\Geo\Engine\PDOEngine;

  $pdo = new PDO('mysql:host=localhost', 'root', '');
  GeometryEngineRegistry::set(new PDOEngine($pdo));

Update the code with your own connection parameters, or use an existing PDO connection if you have one (recommended).

Using PDO and MariaDB 5.5 or greater

MariaDB is a fork of MySQL, so you can follow the same procedure as for MySQL. Just ensure that your MariaDB version is 5.5 or greater.

Using PDO and PostgreSQL with PostGIS

  • Ensure that PostGIS is installed on your server

  • Enable PostGIS on the database server if needed:

      CREATE EXTENSION postgis;

  • Use this bootstrap code in your project:

      use Brick\Geo\Engine\GeometryEngineRegistry;
  use Brick\Geo\Engine\PDOEngine;

  $pdo = new PDO('pgsql:host=localhost', 'postgres', '');
  GeometryEngineRegistry::set(new PDOEngine($pdo));

Update the code with your own connection parameters, or use an existing PDO connection if you have one (recommended).

Using PDO and SQLite with SpatiaLite

Due to limitations in the PDO_SQLITE driver, it is currently not possible to load the SpatiaLite extension with a SELECT LOAD_EXTENSION() query, hence you cannot use SpatiaLite with the PDO driver.

You need to use the SQLite3 driver instead. Note that you can keep using your existing PDO_SQLITE code, all you need to do is create an additional in-memory SQLite3 database just to power the geometry engine.

Using SQLite3 with SpatiaLite

  • Ensure that SpatiaLite is installed on your system.

  • Ensure that the SQLite3 extension is enabled in your php.ini:

      extension=sqlite3.so

  • Ensure that the SQLite3 extension dir where SpatiaLite is installed is configured in your php.ini:

      [sqlite3]
  sqlite3.extension_dir = /usr/lib

  • Use this bootstrap code in your project:

      use Brick\Geo\Engine\GeometryEngineRegistry;
  use Brick\Geo\Engine\SQLite3Engine;

  $sqlite3 = new SQLite3(':memory:');
  $sqlite3->loadExtension('libspatialite.so.3');
  GeometryEngineRegistry::set(new SQLite3Engine($sqlite3));

Update the libspatialite extension name as required. In this example we have created an in-memory database for our GIS calculations, but you can also use an existing SQLite3 connection.

Using GEOS PHP bindings

  • Ensure that GEOS is installed on your server. GEOS must have been compiled with the --enable-php flag to provide the PHP extension.

  • Ensure that the GEOS extension is enabled in your php.ini:

      extension=geos.so

  • Use this bootstrap code in your project:

      use Brick\Geo\Engine\GeometryEngineRegistry;
  use Brick\Geo\Engine\GEOSEngine;

  GeometryEngineRegistry::set(new GEOSEngine());

Geometry hierarchy

All geometry objects reside in the Brick\Geo namespace, and extend a base Geometry class:

Geometry exceptions

All geometry exceptions reside in the Brick\Geo\Exception namespace, and extend a base GeometryException object.

Geometry exceptions are fine-grained: only subclasses of the base GeometryException class are thrown throughout the project. This leaves to the user the choice to catch only specific exceptions, or all geometry-related exceptions.

Here is a list of all exceptions:

  • CoordinateSystemException is thrown when mixing objects with different SRID or dimensionality (e.g. XY with XYZ)
  • EmptyGeometryException is thrown when trying to access a non-existent property on an empty geometry
  • GeometryEngineException is thrown when a functionality is not supported by the current geometry engine
  • GeometryIOException is thrown when an error occurs while reading or writing (E)WKB/T data
  • InvalidGeometryException is thrown when creating an invalid geometry, such as a LineString with only one Point
  • NoSuchGeometryException is thrown when attempting to get a geometry at an non-existing index in a collection
  • UnexpectedGeometryException is thrown when a geometry is not an instance of the expected sub-type, for example when calling Point::fromText() with a LineString WKT.

Example

use Brick\Geo\Polygon;

$polygon = Polygon::fromText('POLYGON ((0 0, 0 3, 3 3, 0 0))');
echo $polygon->area(); // 4.5

$centroid = $polygon->centroid();
echo $centroid->asText(); // POINT (1 2)

Spatial Function Reference

This is a list of all functions which are currently implemented in the geo project. Some functions are only available if you use a specific geometry engine, sometimes with a minimum version. This table also shows which functions are part of the OpenGIS standard.

Function Name GEOS PostGIS MySQL MariaDB SpatiaLite OpenGIS standard
area ✓ ✓ ✓ ✓ ✓ ✓
boundary ✓ ✓ ✓ ✓
buffer ✓ ✓ ✓ ✓ ✓ ✓
centroid ✓ ✓ ✓ ✓ ✓ ✓
contains ✓ ✓ ✓ ✓ ✓ ✓
convexHull ✓ ✓ 5.7.6 ✓ ✓
crosses ✓ ✓ ✓ ✓ ✓ ✓
difference ✓ ✓ ✓ ✓ ✓ ✓
disjoint ✓ ✓ ✓ ✓ ✓ ✓
distance ✓ ✓ ✓ ✓ ✓ ✓
envelope ✓ ✓ ✓ ✓ ✓ ✓
equals ✓ ✓ ✓ ✓ ✓ ✓
intersects ✓ ✓ ✓ ✓ ✓ ✓
intersection ✓ ✓ ✓ ✓ ✓ ✓
isSimple ✓ ✓ ✓ ✓ ✓ ✓
isValid ✓ ✓ 5.7.6 ✓
length ✓ ✓ ✓ ✓ ✓ ✓
locateAlong ✓ ✓
locateBetween ✓ ✓
maxDistance ✓ ✓
overlaps ✓ ✓ ✓ ✓ ✓ ✓
pointOnSurface ✓ ✓ ✓ ✓
relate ✓ ✓ ✓ ✓
simplify ✓ ✓ 5.7.6 4.1.0
snapToGrid ✓ ✓
symDifference ✓ ✓ ✓ ✓ ✓ ✓
touches ✓ ✓ ✓ ✓ ✓ ✓
union ✓ ✓ ✓ ✓ ✓ ✓
within ✓ ✓ ✓ ✓ ✓ ✓