Repository files navigation

A GIS geometry library for PHP.

This library is a PHP implementation of theOpenGIS specification.

It providesGeometry classes (Point,LineString,Polygon, etc.), and can natively read/write many formats: WKB, WKT, EWKB, EWKT, and GeoJSON.

It also provides aGeometryEngine interface for advanced calculations (length,area,union,intersection, etc.),together with implementations that delegate these operations to a third-party GIS engine: theGEOS extension, or a GIS-enabled database such as MySQL or PostgreSQL.

This library requires PHP 8. For PHP 7.4, you can use version0.7.

Install the library withComposer:

composer require brick/geo

If you only need basic operations such as building Geometry objects, importing from / exporting to one of the supported formats (WKB, WKT, EWKB, EWKT, or GeoJSON), then you're all set.

If you need advanced features, such aslength(),union(),intersection, etc., head on to theConfiguration section to choose aGeometryEngine implementation.

This library is still under development.

The current releases are numbered0.x.y. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.),y is incremented.

When a breaking change is introduced, a new0.x version cycle is always started.

It is therefore safe to lock your project to a given release cycle, such as0.9.*.

If you need to upgrade to a newer release cycle, check therelease history for a list of changes introduced by each further0.x.0 version.

useBrick\Geo\LineString;useBrick\Geo\Point;useBrick\Geo\Polygon;// Building geometries from coordinates$lineString = LineString::of(    Point::xy(1,2),    Point::xy(3,4),);echo$lineString->asText();// LINESTRING (1 2, 3 4)// Importing geometries$point = Point::fromText('POINT (1 2)');echo$point->x();// 1echo$point->y();// 2// Using advanced calculations from a GeometryEngine// (see the Configuration section)$polygon = Polygon::fromText('POLYGON ((0 0, 0 3, 3 3, 0 0))');echo$geometryEngine->area($polygon);// 4.5$centroid =$geometryEngine->centroid($polygon);echo$centroid->asText();// POINT (1 2)

Advanced calculations are available through theGeometryEngine interface. The library ships with the following implementations:

• PDOEngine: communicates with a GIS-compatible database over aPDO connection.
  This engine currently supports the following databases:
  • MySQL version 5.6 or greater (2D geometries only)
  • MariaDB version 5.5 or greater
  • PostgreSQL with thePostGIS extension.
• SQLite3Engine: communicates with aSQLite3 database with theSpatiaLite extension.
• GEOSEngine: uses theGEOS PHP extension

Your choice for the right implementation should be guided by two criteria:

• availability: if you already use a GIS-enabled database such as MySQL, this may be an easy choice;
• capabilities: not all databases offer the same GIS capabilities:
  • some functions may be available on PostgreSQL but not on other databases (see theSpatial Function Reference section)
  • some functions may be restricted to certain geometry types and/or SRIDs; for example,buffer() works on MySQL, but would fail with aPolygon on SRID 4326 (GPS coordinates, distance in meters)
  • some databases may return distances in meters on SRID 4326, while others may return distances in degrees

You should probably start with the easiest method that works for you, and test if this setup matches your expectations.

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

All geometry objects reside in theBrick\Geo namespace, and extend a baseGeometry class:

• Geometryabstract
  • Point
  • Curveabstract
    • LineString
    • CompoundCurve
    • CircularString
  • Surfaceabstract
    • Polygon
      • Triangle
    • CurvePolygon
    • PolyhedralSurface
      • TIN
  • GeometryCollection
    • MultiPoint
    • MultiCurveabstract
      • MultiLineString
    • MultiSurfaceabstract
      • MultiPolygon

All geometry exceptions reside in theBrick\Geo\Exception namespace, and extend a baseGeometryException object.

Geometry exceptions are fine-grained: only subclasses of the baseGeometryException class are thrown throughoutthe 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 aLineString with only onePoint
• NoSuchGeometryException is thrown when attempting to get a geometry at a non-existing index in a collection
• UnexpectedGeometryException is thrown when a geometry is not an instance of the expected sub-type, for example whencallingPoint::fromText() with aLineString WKT.

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

This library supports importing from and exporting to the following formats:

• WKT
• WKB
• EWKT
• EWKB
• GeoJSON

Well-Known Text is the standard text format for geometries.

Every Geometry class provides a convenience methodfromText(), that accepts a WKT string and an optional SRID, andreturns a Geometry object:

useBrick\Geo\Point;$point = Point::fromText('POINT (1.5 2.5)',4326);

Geometries can be converted to WKT using the convenience methodasText():

echo$point->asText();// POINT (1.5 2.5)

You can alternatively use theWKTReader andWKTWriter classes directly; the latter allows you topretty-print the output.

Well-Known Binary is the standard binary format for geometries.

Every Geometry class provides a convenience methodfromBinary(), that accepts a WKB binary string and an optionalSRID, and returns a Geometry object:

useBrick\Geo\Point;$point = Point::fromBinary(hex2bin('0101000000000000000000f83f0000000000000440'),4326);echo$point->asText();// POINT (1.5 2.5)echo$point->SRID();// 4326

Geometries can be converted to WKB using the convenience methodasBinary():

echobin2hex($point->asBinary());// 0101000000000000000000f83f0000000000000440

You can alternatively use theWKBReader andWKBWriter classes directly; the latter allows you tochoose the endianness of the output (big endian or little endian).

Extended WKT is a PostGIS-specific text format that includes the SRID of the geometry object, which is missing from thestandard WKT format. You can import from and export to this format using theEWKTReader andEWKTWriter classes:

useBrick\Geo\Point;useBrick\Geo\IO\EWKTReader;useBrick\Geo\IO\EWKTWriter;$reader =newEWKTReader();$point =$reader->read('SRID=4326; POINT (1.5 2.5)');echo$point->asText();// POINT (1.5 2.5)echo$point->SRID();// 4326$writer =newEWKTWriter();echo$writer->write($point);// SRID=4326; POINT (1.5 2.5)

Extended WKB is a PostGIS-specific binary format that includes the SRID of the geometry object, which is missing fromthe standard WKB format. You can import from and export to this format using theEWKBReader andEWKBWriter classes:

useBrick\Geo\Point;useBrick\Geo\IO\EWKBReader;useBrick\Geo\IO\EWKBWriter;$reader =newEWKBReader();$point =$reader->read(hex2bin('0101000020e6100000000000000000f83f0000000000000440'));echo$point->asText();// POINT (1.5 2.5)echo$point->SRID();// 4326$writer =newEWKBWriter();echobin2hex($writer->write($point));// 0101000020e6100000000000000000f83f0000000000000440

GeoJSON is an open standard format designed for representing simple geographical features, based on JSON, andstandardized inRFC 7946.

This library supports importing geometries from, and exporting them to GeoJSON documents using theGeoJSONReader andGeoJSONWriter classes:

useBrick\Geo\Point;useBrick\Geo\IO\GeoJSONReader;useBrick\Geo\IO\GeoJSONWriter;$reader =newGeoJSONReader();$point =$reader->read('{ "type": "Point", "coordinates": [1, 2] }');echo$point->asText();// POINT (1 2)echo$point->SRID();// 4326$writer =newGeoJSONWriter();echo$writer->write($point);// {"type":"Point","coordinates":[1,2]}

The library supports reading and writingFeature andFeatureCollection objects, together with custom properties.

GeoJSON aims to support WGS84 only, and as such all Geometries are imported usingSRID 4326.

You can usebrick/geo types in your Doctrine entities using thebrick/geo-doctrine package.