Skip to content

Latest commit

 

History

History
487 lines (357 loc) · 16.9 KB

API.md

File metadata and controls

487 lines (357 loc) · 16.9 KB
Raw

API

Available geometry classes

  • Point(float $latitude, float $longitude, int|Srid|null $srid = null) - MySQL Point
  • MultiPoint(Point[] | Collection<Point> $geometries, int|Srid|null $srid = null) - MySQL MultiPoint
  • LineString(Point[] | Collection<Point> $geometries, int|Srid|null $srid = null) - MySQL LineString
  • MultiLineString(LineString[] | Collection<LineString> $geometries, int|Srid|null $srid = null) - MySQL MultiLineString
  • Polygon(LineString[] | Collection<LineString> $geometries, int|Srid|null $srid = null) - MySQL Polygon
  • MultiPolygon(Polygon[] | Collection<Polygon> $geometries, int|Srid|null $srid = null) - MySQL MultiPolygon
  • GeometryCollection(Geometry[] | Collection<Geometry> $geometries, int|Srid|null $srid = null) - MySQL GeometryCollection

Geometry classes can be also created by these static methods:

  • fromArray(array $geometry, int|Srid|null $srid = null) - Creates a geometry object from a GeoJSON array.
  • fromJson(string $geoJson, int|Srid|null $srid = null) - Creates a geometry object from a GeoJSON string.
  • fromWkt(string $wkt, int|Srid|null $srid = null) - Creates a geometry object from a WKT.
  • fromWkb(string $wkb) - Creates a geometry object from a WKB.

Available geometry class methods

  • toArray() - Serializes the geometry object into a GeoJSON associative array.

  • toJson() - Serializes the geometry object into an GeoJSON string.

  • toFeatureCollectionJson() - Serializes the geometry object into an GeoJSON's FeatureCollection string.

  • toWkt() - Serializes the geometry object into a WKT.

  • toWkb() - Serializes the geometry object into a WKB.

  • getCoordinates() - Returns the coordinates of the geometry object.

  • toSqlExpression(ConnectionInterface $connection) - Serializes the geometry object into an SQL query. In addition, GeometryCollection also has these functions:

  • getGeometries() - Returns a geometry array. Can be used with ArrayAccess as well.

$geometryCollection = new GeometryCollection([
        new Polygon([
            new LineString([
                new Point(0, 180),
                new Point(1, 179),
                new Point(2, 178),
                new Point(3, 177),
                new Point(0, 180),
            ]),
        ]),
        new Point(0, 180),
    ]),
]);

echo $geometryCollection->getGeometries()[1]->latitude; // 0
// or access as an array:
echo $geometryCollection[1]->latitude; // 0

Available Enums

Spatial reference identifiers (SRID) identify the type of coordinate system to use.

An enum is provided with the following values:

Identifier Value Description
Srid::WGS84 4326 Geographic coordinate system
Srid::WEB_MERCATOR 3857 Mercator coordinate system

Available spatial scopes

withDistance

Retrieves the distance between 2 geometry objects. Uses ST_Distance.

parameter name type default
$column Geometry \ string
$geometryOrColumn Geometry \ string
$alias string 'distance'
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

$placeWithDistance = Place::query()
    ->withDistance('location', new Point(1, 1, 4326))
    ->first();

echo $placeWithDistance->distance; // 156897.79947260793

// when using alias:
$placeWithDistance = Place::query()
    ->withDistance('location', new Point(1, 1, 4326), 'distance_in_meters')
    ->first();

echo $placeWithDistance->distance_in_meters; // 156897.79947260793

whereDistance

Filters records by distance. Uses ST_Distance.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
$operator string
$value int \ float
Example 
Place::create(['location' => new Point(0, 0, 4326)]);
Place::create(['location' => new Point(50, 50, 4326)]);

$placesCountWithinDistance = Place::query()
    ->whereDistance('location', new Point(1, 1, 4326), '<', 160000)
    ->count();

echo $placesCountWithinDistance; // 1

orderByDistance

Orders records by distance. Uses ST_Distance.

parameter name type default
$column Geometry \ string
$geometryOrColumn Geometry \ string
$direction string 'asc'
Example 
Place::create([
    'name' => 'first',
    'location' => new Point(0, 0, 4326),
]);
Place::create([
    'name' => 'second',
    'location' => new Point(50, 50, 4326),
]);

$places = Place::query()
    ->orderByDistance('location', new Point(1, 1, 4326), 'desc')
    ->get();

echo $places[0]->name; // second
echo $places[1]->name; // first

withDistanceSphere

Retrieves the spherical distance between 2 geometry objects. Uses ST_Distance_Sphere.

parameter name type default
$column Geometry \ string
$geometryOrColumn Geometry \ string
$alias string 'distance'
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

$placeWithDistance = Place::query()
    ->withDistanceSphere('location', new Point(1, 1, 4326))
    ->first();

echo $placeWithDistance->distance; // 157249.59776850493

// when using alias:
$placeWithDistance = Place::query()
    ->withDistanceSphere('location', new Point(1, 1, 4326), 'distance_in_meters')
    ->first();

echo $placeWithDistance->distance_in_meters; // 157249.59776850493

whereDistanceSphere

Filters records by spherical distance. Uses ST_Distance_Sphere.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
$operator string
$value int \ float
Example 
Place::create(['location' => new Point(0, 0, 4326)]);
Place::create(['location' => new Point(50, 50, 4326)]);

$placesCountWithinDistance = Place::query()
    ->whereDistanceSphere('location', new Point(1, 1, 4326), '<', 160000)
    ->count();

echo $placesCountWithinDistance; // 1

orderByDistanceSphere

Orders records by spherical distance. Uses ST_Distance_Sphere.

parameter name type default
$column Geometry \ string
$geometryOrColumn Geometry \ string
$direction string 'asc'
Example 
Place::create([
    'name' => 'first',
    'location' => new Point(0, 0, 4326),
]);
Place::create([
    'name' => 'second',
    'location' => new Point(100, 100, 4326),
]);

$places = Place::query()
    ->orderByDistanceSphere('location', new Point(1, 1, 4326), 'desc')
    ->get();

echo $places[0]->name; // second
echo $places[1]->name; // first

whereWithin

Filters records by the ST_Within function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

Place::query()
    ->whereWithin('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
    ->exists(); // true

whereNotWithin

Filters records by the ST_Within function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

Place::query()
    ->whereNotWithin('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
    ->exists(); // false

whereContains

Filters records by the ST_Contains function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['area' => Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'),]);

Place::query()
    ->whereContains('area', new Point(0, 0, 4326))
    ->exists(); // true

whereNotContains

Filters records by the ST_Contains function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['area' => Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'),]);

Place::query()
    ->whereNotContains('area', new Point(0, 0, 4326))
    ->exists(); // false

whereTouches

Filters records by the ST_Touches function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

Place::query()
    ->whereTouches('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[0,-1],[0,0],[-1,0],[-1,-1]]]}'))
    ->exists(); // true

whereIntersects

Filters records by the ST_Intersects function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

Place::query()
    ->whereIntersects('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
    ->exists(); // true

whereCrosses

Filters records by the ST_Crosses function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['line_string' => LineString::fromJson('{"type":"LineString","coordinates":[[0,0],[2,0]]}')]);

Place::query()
    ->whereCrosses('line_string', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}'))
    ->exists(); // true

whereDisjoint

Filters records by the ST_Disjoint function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

Place::query()
    ->whereDisjoint('location', Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[-0.5,-1],[-0.5,-0.5],[-1,-0.5],[-1,-1]]]}'))
    ->exists(); // true

whereEquals

Filters records by the ST_Equal function.

parameter name type
$column Geometry \ string
$geometryOrColumn Geometry \ string
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

Place::query()
    ->whereEquals('location', new Point(0, 0, 4326))
    ->exists(); // true

whereSrid

Filters records by the ST_Srid function.

parameter name type
$column Geometry \ string
$operator string
$value int
Example 
Place::create(['location' => new Point(0, 0, 4326)]);

Place::query()
    ->whereSrid('location', '=', 4326)
    ->exists(); // true

withCentroid

Retrieves the centroid of the geometry object. Uses ST_Centroid.

parameter name type default
$column Geometry \ string
$alias string 'centroid'
Example 
$polygon = Polygon::fromJson('{"type":"Polygon","coordinates":[[[-1,-1],[1,-1],[1,1],[-1,1],[-1,-1]]]}');
Place::create(['polygon' => $polygon]);

$placeWithCentroid = Place::query()
    ->withCentroid('polygon')
    ->withCasts(['centroid' => Point::class]) // This is important, otherwise the centroid will be returned as a binary string.
    ->first();

echo $placeWithDistance->centroid; // POINT(0 0)

// when using alias:
$placeWithCentroid = Place::query()
    ->withCentroid('polygon', 'centroid_alias')
    ->withCasts(['centroid_alias' => Point::class])
    ->first();

echo $placeWithDistance->centroid_alias; // POINT(0 0)