From 0f728a17f9df01d8208c5a7e156201ff097356ef Mon Sep 17 00:00:00 2001 From: Benjamin Morel Date: Mon, 10 Oct 2022 23:02:31 +0200 Subject: [PATCH] Update README, prepare for release --- CHANGELOG.md | 2 +- README.md | 84 +++++++++++++++++++++++++++++++++++----------------- 2 files changed, 58 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e3c4bd7..3f685e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## UNRELEASED (0.8.0) +## [0.8.0](https://github.com/brick/geo/releases/tag/0.8.0) - 2022-10-11 💥 **Breaking changes** diff --git a/README.md b/README.md index 97e8afd..381ed2c 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,10 @@ Introduction This library is a PHP implementation of the [OpenGIS specification](http://www.opengeospatial.org/standards/sfa). -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. +It provides [Geometry classes](#geometry-hierarchy) (`Point`, `LineString`, `Polygon`, etc.), and can natively read/write many formats: WKB, WKT, EWKB, EWKT, and GeoJSON. -Already using a MySQL 5.6+ or MariaDB 5.5+ database? Just provide the library with a `PDO` instance and unlock the full power of GIS calculations! - -Not using MySQL/MariaDB? You still have a few options to choose from! +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](https://git.osgeo.org/gitea/geos/php-geos) extension, or a GIS-enabled database such as MySQL or PostgreSQL. Requirements and installation ----------------------------- @@ -34,7 +32,9 @@ Install the library with [Composer](https://getcomposer.org/): composer require brick/geo ``` -Then head on to the [Configuration](#configuration) section to configure a GIS geometry engine. +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](#configuration) section to choose a `GeometryEngine` implementation. Project status & release process -------------------------------- @@ -45,23 +45,66 @@ The current releases are numbered `0.x.y`. When a non-breaking change is introdu **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.7.*`. +It is therefore safe to lock your project to a given release cycle, such as `0.8.*`. If you need to upgrade to a newer release cycle, check the [release history](https://github.com/brick/geo/releases) for a list of changes introduced by each further `0.x.0` version. +Quick start +----------- + +```php +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) +``` + Configuration ------------- -Configuring the library consists in choosing the most convenient `GeometryEngine` implementation for your installation. The following implementations are available: +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. This engine currently supports the following databases: - - [MySQL](http://php.net/manual/en/ref.pdo-mysql.php) version 5.6 or greater. - *Note: MySQL currently only supports 2D geometries.* - - MariaDB version 5.5 or greater. + - [MySQL](http://php.net/manual/en/ref.pdo-mysql.php) version 5.6 or greater (*2D geometries only*) + - MariaDB version 5.5 or greater - [PostgreSQL](http://php.net/manual/en/ref.pdo-pgsql.php) with the [PostGIS](http://postgis.net/install) extension. - `SQLite3Engine`: communicates with a [SQLite3](http://php.net/manual/en/book.sqlite3.php) database with the [SpatiaLite](https://www.gaia-gis.it/fossil/libspatialite/index) extension. -- `GEOSEngine`: uses the [GEOS](https://github.com/libgeos/libgeos) PHP bindings. +- `GEOSEngine`: uses the [GEOS](https://git.osgeo.org/gitea/geos/php-geos) 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 the [Spatial Function Reference](#spatial-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 a `Polygon` 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: @@ -168,7 +211,7 @@ In this example we have created an in-memory database for our GIS calculations,
Click to expand -- Ensure that [the PHP bindings for GEOS](https://git.osgeo.org/gogs/geos/php-geos) are installed on your server (GEOS 3.6.0 onwards; previous versions require compiling GEOS with the `--enable-php` flag). +- Ensure that [the PHP bindings for GEOS](https://git.osgeo.org/gitea/geos/php-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 @@ -221,23 +264,10 @@ Here is a list of all exceptions: - `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 +- `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 when calling `Point::fromText()` with a `LineString` WKT. -Example -------- - -```php -use Brick\Geo\Polygon; - -$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) -``` - Spatial Function Reference --------------------------