laravel-magellan

Magellan provides a static ST class that returns MagellanExpression objects. These can be used seamlessly within Laravel's query builder methods like select(), addSelect(), where(), orderBy(), and groupBy().

Key Usage Patterns

• Aliasing: Use the as(string) method on an expression to name the resulting column.
• Boolean Expressions: When using where() with an expression that returns a boolean, you must explicitly provide the boolean value (e.g., true or false) to avoid null-check queries.
• Aggregates/Collections: Use ST::collect() to pass a collection of geometries to functions like ST::convexHull().
• Casting: Use AsGeometry or AsGeography to explicitly cast parameters within a function call.

use Clickbar//... imports

// Select with distance and filter
Port::select()
    ->addSelect(ST::distanceSphere($currentPos, 'location')->as('distance_to_ship'))
    ->where(ST::distanceSphere($currentPos, 'location'), '<=', 50000)
    ->orderBy(ST::distanceSphere($currentPos, 'location'))
    ->get();

// Complex grouping and hull calculation
Port::query()
    ->select([
        'country',
        ST::convexHull(ST::collect('location'))->as('hull'),
        ST::area(ST::convexHull(ST::collect('location')))->as('area')
    ])
    ->groupBy('country')
    ->get();

// Explicit casting to Geography for meter-based calculations
Port::query()
    ->select(ST::buffer(new AsGeography('location'), 50)->as('buffered_location'))
    ->get();

By default, GeoJSON is parsed with SRID 4326. To use a different Spatial Reference System (SRID):

1. Validation: Pass the srid argument to GeometryGeojsonRule.
2. Transformation: Override the geometrySrids(): array method in your Form Request to map field names to their respective SRIDs.
3. Manual Parsing: Use GeojsonParser::parseWithSrid() for parsing outside of Form Requests.

Fields not explicitly listed in geometrySrids() will default to 4326.

// Validation with custom SRID
'location' => ['required', new GeometryGeojsonRule([Point::class], srid: 25832)],

// Form Request implementation
class StorePortRequest extends FormRequest
{
    use TransformsGeojsonGeometry;

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

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

    public function geometrySrids(): array
    {
        return ['location' => 25832];
    }
}

// Manual parsing
$point = app(GeojsonParser::class)->parseWithSrid($geojson, srid: 25832);

When handling GeoJSON input in Laravel Form Requests, use GeometryGeojsonRule for validation and the TransformsGeojsonGeometry trait to automatically convert GeoJSON into proper geometry objects.

To enable transformation, you must implement the geometries(): array method in your Form Request, returning an array of the field names that should be transformed.

Note: Currently, only simple field transformation is supported; wildcard or array notation is not yet available.

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'];
    }
}

Magellan 2.x removes the st-prefixed query builder methods (like stSelect, stWhere, stOrderBy). You should now use standard Laravel methods (select, addSelect, where, orderBy) and pass ST expressions directly into them.

To handle result casting for ST functions that return geometry or bounding boxes, use the withMagellanCasts() method on the query builder. To rename an expression, use the ->as('alias') utility on the ST expression object.

$currentShipPosition = Point::makeGeodetic(50.107471773560114, 8.679861151457937);

// Magellan 2.x Query Pattern
$portsWithDistance = Port::select(['name', 'country'])
    ->addSelect(ST::distanceSphere($currentShipPosition, 'location')->as('distance_to_ship'))
    ->where(ST::distanceSphere($currentShipPosition, 'location'), '<=', 50000)
    ->orderBy(ST::distanceSphere($currentShipPosition, 'location'))
    ->withMagellanCasts()
    ->get();