Download the PHP package webnuvola/geo without Composer
On this page you can find all versions of the php package webnuvola/geo. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download webnuvola/geo
More information about webnuvola/geo
Files in webnuvola/geo
Informations about the package geo
Brick\Geo
A collection of classes to work with GIS geometries.
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 7.1 or later. for PHP 5.6 and PHP 7.0 support, use version 0.1
.
Install the library with Composer:
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.
Project status & release process
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.2.*
.
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.
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 aPDO
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.
- MySQL version 5.6 or greater.
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('mod_spatialite.so'); GeometryEngineRegistry::set(new SQLite3Engine($sqlite3));
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 the PHP bindings for GEOS are installed on your server (GEOS 3.6.0 onwards; previous versions require compiling GEOS with the
--enable-php
flag). -
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
abstract
- Point
- Curve
abstract
- LineString
- CompoundCurve
- CircularString
- Surface
abstract
- Polygon
- CurvePolygon
- PolyhedralSurface
- GeometryCollection
- MultiPoint
- MultiCurve
abstract
- MultiSurface
abstract
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 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 aLineString
with only onePoint
NoSuchGeometryException
is thrown when attempting to get a geometry at an non-existing index in a collectionUnexpectedGeometryException
is thrown when a geometry is not an instance of the expected sub-type, for example when callingPoint::fromText()
with aLineString
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 |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Importing and exporting geometries
This library supports importing from and exporting to the following formats:
- WKT
- WKB
- EWKT
- EWKB
- GeoJSON
WKT
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:
Geometries can be converted to WKT using the convenience method asText()
:
You can alternatively use the WKTReader and WKTWriter classes directly; the latter allows you to pretty-print the output.
WKB
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:
Geometries can be converted to WKB using the convenience method asBinary()
:
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).
EWKT
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:
EWKB
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:
GeoJSON
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:
Note that Feature
s are imported as Geometry
objects, and FeatureCollection
s are imported as GeometryCollection
objects. Non-spatial attributes are ignored.
GeoJSON aims to support WGS84 only, and as such all Geometries are imported using SRID 4326.