README

A modern PostGIS toolbox for Laravel

Introduction

Every sailor needs a nice ship to travel the seven seas ⛵️

This package will have you prepared for accessing PostGIS related functionality within Laravel. It was heavily inspired by mstaack/laravel-postgis, but has evolved into much more since. Other than some slight changes, you should be familiar with Magellan very quickly.

Magellan comes with paddles included and also provides parsers/generators for GeoJson, WKB & WKT out of the box. Easily use all PostGIS datatypes in your migrations and avoid raw SQL to access PostGIS functions by using our Builder functions.

Additionally laravel-magellan provides extensions to the Schema, Query Builder and Postgres Grammar for easy access of PostGIS database functions like ST_EXTENT. It does all this without breaking compatibility to other packages, like tpetry/laravel-postgresql-enhanced, which has to extend the Grammar and Connection.

Requirements

Magellan supports Laravel projects, which meet the following requirements:

Laravel ^9.28 or ^10.0
PHP ^8.1

Installation

You can install the package via composer:

composer require clickbar/laravel-magellan

You can publish and run the migrations with:

php artisan vendor:publish --tag="magellan-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="magellan-config"

You may find the contents of the published config file here: config/magellan.php

What's included

Migration Schema Blueprints
Geometry Data Classes
WKT Generator & Parser
WKB Generator & Parser
GeoJson Generator & Parser
Eloquent Model Trait
Command to automatically add the PostGIS trait to models
Auto transform on insert with different projection
GeoJson Request Validation Rule
Transforms Geometry for Form Requests
Exposes nearly all PostGIS functions as typed functions that can be used in select, where, orderBy, groupBy, having, from
Geometry and BBox Cast classes
Auto Cast when using functions that return geometry or bbox
Empty Geometry Support
Custom update Builder method for conversion safety
Automatic PostGIS Function Doc Generator
BBox support within $postgisColumns & trait (currently with cast only)
Custom Geometry Factories & Models
More tests
...

Before you start

We highly recommend using the laravel-ide-helper from barryvdh to be able to see everything included in the IDEs auto completion.

Creating Tables with PostGIS Columns

Laravel-magellan extends the default Schema Blueprint with all PostGIS functions. Since Laravel has introduced basic geometry support, all methods are prefixed with magellan. e.g.

$table->magellanPoint('location', 4326);

Preparing the Model

In order to properly integrate everything with the model you need to to perform the following 2 steps:

Add the HasPostgisColumns trait to your model
Add the $postgisColumns array to the model

protected array $postgisColumns = [
        'location' => [
            'type' => 'geometry',
            'srid' => 4326,
        ],
    ];

Both steps can be automated by using the following command:

php artisan magellan:update-postgis-columns

The command automatically scans the database and adds the trait and the array as well.

Using the geometry data classes

We've included data classes for the following common geometries:

Point
LineString
Polygon
MultiPoint
MultiLineString
MultiPolygon
GeometryCollection

To create a geometry object manually, use the suited <GeometryClass>::make method. e.g.

$point = Point::make(51.087, 8.76);

You will notice that there are 3 different make methods for the Point class with different parameters:

make(...)
makeGeodetic(...)
makeEmpty(...)

Let's take a closer look to the first two:

This is the default factory method that can be used to fill all possible values. This method is considered the "plain" way. You should consider using this method when you use a non lng/lat projection (e.g.something different than WGS84:srid=4326).

function make(float $x, float $y, ?float $z = null, ?float $m = null, ?int $srid = null): self

Most of the common web use cases use the WGS84 projection. Therefore, most of the time the terms that are used will be latitude, longitute and altitude instead of x, y and z. To provide more comfort we have included a factory method that accepts those terms and automatically sets the srid to the default geodetic srid, which can be set in the config file.

function makeGeodetic(float $latitude, float $longitude, ?float $altitude = null, ?float $m = null): self

When using a Point class that uses a geodetic projection, you can access the latitude, longitude and altitude with properly named getters and setters:

function getLatitude(): float
function setLatitude(float $latitude): void
function getLongitude(): float
function setLongitude(float $longitude): void
function getAltitude(): ?float
function setAltitude(float $altitude): void

An exception will be thrown if you try to use this functions on a Point without a srid listed in the geodetic_srids config. Use the default x, y, z, m getters and setters instead.

Generators & Parsers

We currently provide parsers & generators for the following formats:

EWKB
EWKT
GeoJson

These are also used to format our data classes to strings, convert the return value from the database (which comes in EWKB format) and output our data to the frontend as GeoJson for example.

Note In the following we will use EWKB & WBK or EWKT & WKT interchangeably, even though we always use the extended version of each.

The config file allows you to customize which representation you would like to be used eg. when JSON serialization is done for our data classes, where GeoJson is otherwise the default.

$point = Point::makeGeodetic(51.087, 8.76);

json_encode($point); // returns GeoJson
// "{"type":"Point","coordinates":[8.76,51.087]}"

You can always use instances of each parser / generator and parse / generate on your own behalf.
While Generators have to be created on demand, Parsers are already instanciated in the app container as singletons and you can use them as follows:

$parser = app(WKTParser::class);

$point = $parser->parse('SRID=4326;POINT (2, 2)');

$generator = new WKBGenerator();

$generator->generate($point);
// "0101000020E610000000000000000000400000000000000040"

In this example we obtain an instance of the WKTParser and convert the string to one of our data classes. $point is then a valid Point instance and we can use any other generator eg. the WKBGenerator to output the $point in hexadecimal WKB format.

Request Validation and Transformation

When a form request contains a geometry in Geojson format, you can use the GeometryGeojsonRule for validation. You can even limit the types of allowed geometries by passing an array with the classes.

In order to properly continue working with the received geometry you can use the TransformsGeojsonGeometry trait to use automatic transformation of the geojson to the proper geometry object. Therefore, return the keys in the geometries(): array function.

Note Currently we only support simple field transformation. Arrays & wildcard notation support will follow.

class StorePortRequest extends FormRequest
{
    use TransformsGeojsonGeometry;

    public function rules(): array
    {
        return [
            'name' => ['required', 'string'],
            'country' => ['required', 'string'],
            'location' => ['required', new GeometryGeojsonRule([Point::class])],
        ];
    }

    public function geometries(): array
    {
        return ['location'];
    }
}

Interaction with the database

Example Setup

For demo purpose we consider the following fictional scenario:

We are a sails person with a lovely boat and a database of several ports all over the world.
For each port we store the name, the country and the location.

Here is the migration we use to create the ports table:

Schema::create('ports', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('country');
    $table->magellanPoint('location');
    $table->timestamps();
});

and the model implementation:

class Port extends Model
{
    use HasFactory;
    use HasPostgisColumns;

    protected $guarded = [];

    protected array $postgisColumns = [
        'location' => [
            'type' => 'geometry',
            'srid' => 4326,
        ],
    ];
}

Insert/Update

Magellan geometry objects can be inserted directly as long as they are specified in the $postgisColumns of the affected model. In our case, we can insert a new Port like this:

Port::create([
    'name' => 'Magellan Home Port',
    'country' => 'Germany',
    'location' => Point::makeGeodetic(49.87108851299202, 8.625026485851762),
]);

When you want to update a geometry you can either assign the new location to the model and call save() or use the update() method on the query builder:

$port->location = Point::makeGeodetic(55, 11);
$port->save();

// -- or --

Port::where('name', 'Magellan Home Port')
    ->update(['location' => Point::makeGeodetic(55, 11)]);

Insert/Update with different SRID

When getting Geometries from external systems you might receive them in another projection than the one in the database. Consider we want to insert or update a geometry with a different SRID:

Port::create([
    'name' => 'Magellan Home Port',
    'country' => 'Germany',
    'location' => Point::make(473054.9891044726, 5524365.310057224, srid: 25832),
]);

// -- or --

$port = Port::find(1);
$port->location = Point::make(473054.9891044726, 5524365.310057224, srid: 25832);
$port->save();

Since our port table uses a point with SRID=4326, Magellan will raise an error:

SRID mismatch: database has SRID 4326, geometry has SRID 25832. Consider enabling magellan.eloquent.transform_to_database_projection in order to apply automatic transformation

We included an auto transform option that directly applies ST_Transform(geometry, databaseSRID) for you.

Note
This option will only be applied when inserting/updating directly on an eloquent model.
This option will not be applied on geography columns.

Select

When selecting data from a model that uses the HasPostgisColumns trait, all attributes will directly be parsed to the internal data classes:

$port = Port::first();
dd($port->location);

Clickbar\Magellan\Data\Geometries\Point {#1732
  #srid: 4326
  #dimension: Clickbar\Magellan\Data\Geometries\Dimension {#740
    +name: "DIMENSION_2D"
    +value: "2D"
  }
  #x: 8.6250264858452
  #y: 49.87108851299
  #z: null
  #m: null
}

There might be cases where you also want to use box2d or box3d as column types. Currently, we don't support boxes within the $postgisColumns. Please use the BBoxCast instead.

Using PostGIS functions in queries

A big part of laravel-magallan is its extensive query building feature. To provide a seamless and easy use of PostGIS functions, we have included a wide scope of the typically ST-prefixed functions that can directly be used with Laravel's query builder.

Whenever you want to use a PostGIS function on a query builder, you have to use one of our builder methods. All of them are prefixed with st.
We currently provide the following:

stSelect
stWhere
stOrWhere
stOrderBy
stGroupBy
stHaving
stFrom

Note
Using the stWhere with a MagellanExpression that returns a boolean always requires a following true or false.

That's Laravel default behaviour when using the ->where(), but since php supports stuff like if($boolean) without the explicit $boolean == true condition, the true/false will easily be forgotten resulting in a null check query instead a boolean query.

->stWhere(ST::contains('location', 'polygon'), true)

Each of those builder methods expect to receive a MagellanExpression.
A MagellanExpression is a wrapper around a ST-prefixed function from PostGIS. When sailing with Magellan, you should never have to write ST_xxx in raw SQL for yourself. Therefore, we have included some paddles.

Most of the ST-prefixed functions can be accessed using the static functions on the ST class. But enough talk, let's start sailing (with some examples):

Note: The necessary classes can be imported as follows:

use Clickbar\Magellan\Data\Geometries\Point;
use Clickbar\Magellan\Database\PostgisFunctions\ST;

Assuming we have our ships current position and want to query all ports with their distance:

$currentShipPosition = Point::makeGeodetic(50.107471773560114, 8.679861151457937);
$portsWithDistance = Port::select()
    ->stSelect(ST::distanceSphere($currentShipPosition, 'location'), 'distance_to_ship')
    ->get();

Since we cannot sail over the whole world, let's limit the distance to max. 50.000 meters:

$currentShipPosition = Point::makeGeodetic(50.107471773560114, 8.679861151457937);
$portsWithDistance = Port::select()
    ->stSelect(ST::distanceSphere($currentShipPosition, 'location'), 'distance_to_ship')
    ->stWhere(ST::distanceSphere($currentShipPosition, 'location'), '<=', 50000)
    ->get();

Now let us order them based on the distance:

$currentShipPosition = Point::makeGeodetic(50.107471773560114, 8.679861151457937);
$portsWithDistance = Port::select()
    ->stSelect(ST::distanceSphere($currentShipPosition, 'location'), as: 'distance_to_ship')
    ->stWhere(ST::distanceSphere($currentShipPosition, 'location'), '<=', 50000)
    ->stOrderBy(ST::distanceSphere($currentShipPosition, 'location'))
    ->get();

As you can see, using the st-Builder functions is as easy as using the default Laravel ones. But what about more complex queries? What about the convex hull of all ports grouped by the country including the area of the hull? No problem:

$hullsWithArea = Port::select('country')
    ->stSelect(ST::convexHull(ST::collect('location')), 'hull')
    ->stSelect(ST::area(ST::convexHull(ST::collect('location'))))
    ->groupBy('country')
    ->get();

Autocast for bbox or geometries

In the previous section we used some PostGIS functions. In the first examples, the return types only consist out of scalar values. But in the more complex example we received a geometry as return value.

Since "hull" is not present in our $postgisColumns array, we might intentionally add a cast to the query:

$hullWithArea = Port::select('country')
    ->stSelect(ST::convexHull(ST::collect('location')), 'hull')
    ->stSelect(ST::area(ST::convexHull(ST::collect('location'))))
    ->groupBy('country')
    ->withCasts(['hull' => GeometryWKBCast::class]) /* <======= */
    ->first();

But that's not necessary!
Magellan will automatically add the cast for all functions that return geometry, box2d or box3d.

Testing

composer test

clickbar / laravel-magellan

Maintainers

Details