A GIS geometry library for PHP.
This library is a PHP implementation of the OpenGIS specification.
It provides Geometry classes (Point
, LineString
, Polygon
, etc.), and can natively read/write many formats: WKB, WKT, EWKB, EWKT, and GeoJSON.
It also provides a GeometryEngine
interface for advanced calculations (length
, area
, union
, intersection
, etc.),
together with implementations that delegate these operations to a third-party GIS engine: the GEOS extension, or a GIS-enabled database such as MySQL or PostgreSQL.
This library requires PHP 8.1.
For PHP 8.0, you can use version 0.9
.
For PHP 7.4, you can use version 0.7
.
Install the library with Composer:
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 as length()
, union()
, intersection
, etc., head on to the Configuration section to choose a GeometryEngine
implementation.
This library is still under development.
The current releases are numbered 0.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 new 0.x
version cycle is always started.
It is therefore safe to lock your project to a given release cycle, such as 0.11.*
.
If you need to upgrade to a newer release cycle, check the release history for a list of changes introduced by each further 0.x.0
version.
use Brick\Geo\LineString;
use Brick\Geo\Point;
use Brick\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(); // 1
echo $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 the GeometryEngine
interface. The library ships with the following implementations:
PDOEngine
: communicates with a GIS-compatible database over a PDO
connection.SQLite3Engine
: communicates with a SQLite3 database with the SpatiaLite extension.GEOSEngine
: uses the GEOS PHP extensionYour choice for the right implementation should be guided by two criteria:
buffer()
works on MySQL, but would fail with a Polygon
on SRID 4326 (GPS coordinates, distance in meters)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 the Brick\Geo
namespace, and extend a base Geometry
class:
abstract
abstract
abstract
abstract
abstract
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 geometryGeometryEngineException
is thrown when a functionality is not supported by the current geometry engineGeometryIOException
is thrown when an error occurs while reading or writing (E)WKB/T dataInvalidGeometryException
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 a non-existing index in a collectionUnexpectedGeometryException
is thrown when a geometry is not an instance of the expected sub-type, for example when
calling Point::fromText()
with a LineString
WKT.This is a list of all methods available in the GeometryEngine
interface. Some methods are only available
if you use a specific geometry engine, sometimes with a minimum version.
Function Name | GEOS | PostGIS | MySQL | MariaDB | SpatiaLite |
---|---|---|---|---|---|
area |
✓ | ✓ | ✓ | ✓ | ✓ |
azimuth |
✓ | ✓ | |||
boundary |
✓ | ✓ | ✓ | ||
buffer |
✓ | ✓ | ✓ | ✓ | ✓ |
centroid |
✓ | ✓ | ✓ | ✓ | ✓ |
contains |
✓ | ✓ | ✓ | ✓ | ✓ |
convexHull |
✓ | ✓ | 5.7.6 | ✓ | |
crosses |
✓ | ✓ | ✓ | ✓ | ✓ |
difference |
✓ | ✓ | ✓ | ✓ | ✓ |
disjoint |
✓ | ✓ | ✓ | ✓ | ✓ |
distance |
✓ | ✓ | ✓ | ✓ | ✓ |
envelope |
✓ | ✓ | ✓ | ✓ | ✓ |
equals |
✓ | ✓ | ✓ | ✓ | ✓ |
intersection |
✓ | ✓ | ✓ | ✓ | ✓ |
intersects |
✓ | ✓ | ✓ | ✓ | ✓ |
isClosed |
✓ | ✓ | ✓ | ✓ | ✓ |
isRing |
✓ | ✓ | ✓ | ✓ | ✓ |
isSimple |
✓ | ✓ | ✓ | ✓ | ✓ |
isValid |
✓ | ✓ | 5.7.6 | ✓ | |
length |
✓ | ✓ | ✓ | ✓ | ✓ |
locateAlong |
✓ | ✓ | |||
locateBetween |
✓ | ✓ | |||
makeValid |
✓ | ✓ | |||
maxDistance |
✓ | ✓ | |||
overlaps |
✓ | ✓ | ✓ | ✓ | ✓ |
pointOnSurface |
✓ | ✓ | ✓ | ||
relate |
✓ | ✓ | ✓ | ||
simplify |
✓ | ✓ | 5.7.6 | 4.1.0 | |
snapToGrid |
✓ | ✓ | |||
split |
✓ | ✓ | |||
symDifference |
✓ | ✓ | ✓ | ✓ | ✓ |
touches |
✓ | ✓ | ✓ | ✓ | ✓ |
transform |
✓ | ✓ | 8.0.13 | ✓ | ✓ |
union |
✓ | ✓ | ✓ | ✓ | ✓ |
within |
✓ | ✓ | ✓ | ✓ | ✓ |
This library supports importing from and exporting to the following formats:
Well-Known Text is the standard text format for geometries.
Every Geometry class provides a convenience method fromText()
, that accepts a WKT string and an optional SRID, and
returns a Geometry object:
use Brick\Geo\Point;
$point = Point::fromText('POINT (1.5 2.5)', 4326);
Geometries can be converted to WKT using the convenience method asText()
:
echo $point->asText(); // POINT (1.5 2.5)
You can alternatively use the WKTReader and WKTWriter classes directly; the latter allows you to pretty-print the output.
Well-Known Binary is the standard binary format for geometries.
Every Geometry class provides a convenience method fromBinary()
, that accepts a WKB binary string and an optional
SRID, and returns a Geometry object:
use Brick\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 method asBinary()
:
echo bin2hex($point->asBinary()); // 0101000000000000000000f83f0000000000000440
You can alternatively use the WKBReader and WKBWriter classes directly; the latter allows you to choose 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 the standard WKT format. You can import from and export to this format using the EWKTReader and EWKTWriter classes:
use Brick\Geo\Point;
use Brick\Geo\IO\EWKTReader;
use Brick\Geo\IO\EWKTWriter;
$reader = new EWKTReader();
$point = $reader->read('SRID=4326; POINT (1.5 2.5)');
echo $point->asText(); // POINT (1.5 2.5)
echo $point->SRID(); // 4326
$writer = new EWKTWriter();
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 from the standard WKB format. You can import from and export to this format using the EWKBReader and EWKBWriter classes:
use Brick\Geo\Point;
use Brick\Geo\IO\EWKBReader;
use Brick\Geo\IO\EWKBWriter;
$reader = new EWKBReader();
$point = $reader->read(hex2bin('0101000020e6100000000000000000f83f0000000000000440'));
echo $point->asText(); // POINT (1.5 2.5)
echo $point->SRID(); // 4326
$writer = new EWKBWriter();
echo bin2hex($writer->write($point)); // 0101000020e6100000000000000000f83f0000000000000440
GeoJSON is an open standard format designed for representing simple geographical features, based on JSON, and standardized in RFC 7946.
This library supports importing geometries from, and exporting them to GeoJSON documents using the GeoJSONReader and GeoJSONWriter classes:
use Brick\Geo\Point;
use Brick\Geo\IO\GeoJSONReader;
use Brick\Geo\IO\GeoJSONWriter;
$reader = new GeoJSONReader();
$point = $reader->read('{ "type": "Point", "coordinates": [1, 2] }');
echo $point->asText(); // POINT (1 2)
echo $point->SRID(); // 4326
$writer = new GeoJSONWriter();
echo $writer->write($point); // {"type":"Point","coordinates":[1,2]}
The library supports reading and writing Feature
and FeatureCollection
objects, together with custom properties.
GeoJSON aims to support WGS84 only, and as such all Geometries are imported using SRID 4326.
Before exporting geometries in a text format, you may need to reduce the precision of the coordinates to keep the output small, while retaining a sufficient precision.
You can use the RoundCoordinatesProjector
for this:
use Brick\Geo\Point;
use Brick\Geo\Projector\RoundCoordinatesProjector;
$roundProjector = new RoundCoordinatesProjector(2);
$point = Point::xy(1.2345678, 2.3456789);
echo $point->asText(); // POINT (1.2345678 2.3456789)
$roundedPoint = $point->project($roundProjector);
echo $roundedPoint->asText(); // POINT (1.23 2.35)
You can use brick/geo
types in your Doctrine entities using the brick/geo-doctrine package.