asanikovich / laravel-spatial
Laravel Eloquent spatial package
Fund package maintenance!
Ko Fi
Installs: 5 760
Dependents: 0
Suggesters: 0
Security: 0
Stars: 24
Watchers: 3
Forks: 6
Open Issues: 4
Requires
- php: ^8.1
- ext-json: *
- ext-pdo: *
- laravel/framework: ^10.0
- phayes/geophp: ^1.2
Requires (Dev)
- doctrine/dbal: ^3.0
- laravel/pint: ^1.5
- nunomaduro/larastan: ^1.0|^2.4
- orchestra/testbench: ^8.0
- pestphp/pest: ^1.0|^2.6
- pestphp/pest-plugin-laravel: ^1.0|^2.0
This package is auto-updated.
Last update: 2024-11-18 13:47:17 UTC
README
This Laravel package allows you to easily work with spatial data types and functions.
- v2 supports Laravel 10+ and PHP 8.1+
- v1 supports Laravel 8,9 and PHP 8.1+
This package supports MySQL v8 or v5.7, and MariaDB v10.
Getting Started
Installing the Package
You can install the package via composer:
composer require asanikovich/laravel-spatial
Configuration
Default Configuration file includes geometry types mapping:
<?php use ASanikovich\LaravelSpatial\Enums\GeometryType; use ASanikovich\LaravelSpatial\Geometry; return [ GeometryType::POINT->value => Geometry\Point::class, GeometryType::POLYGON->value => Geometry\Polygon::class, /// ... ];
You can publish the config file with:
php artisan vendor:publish --tag="laravel-spatial-config"
If you want you can override custom geometry types mapping:
- globally by config file
- by custom
$casts
in your model (top priority)
Setting Up Your First Model
-
First, generate a new model along with a migration file by running:
php artisan make:model {modelName} --migration
-
Next, add some spatial columns to the migration file. For instance, to create a "places" table:
use Illuminate\Database\Migrations\Migration; use Illuminate\Database\Schema\Blueprint; class CreatePlacesTable extends Migration { public function up(): void { Schema::create('places', static function (Blueprint $table) { $table->id(); $table->string('name')->unique(); $table->point('location')->nullable(); $table->polygon('area')->nullable(); $table->timestamps(); }); } public function down(): void { Schema::dropIfExists('places'); } }
-
Run the migration:
php artisan migrate
-
In your new model, fill
$casts
arrays and use theHasSpatial
trait (fill the$fillable
- optional):namespace App\Models; use Illuminate\Database\Eloquent\Model; use ASanikovich\LaravelSpatial\Eloquent\HasSpatial; use ASanikovich\LaravelSpatial\Geometry\Point; use ASanikovich\LaravelSpatial\Geometry\Polygon; /** * @property Point $location * @property Polygon $area */ class Place extends Model { use HasSpatial; protected $fillable = [ 'name', 'location', 'area', ]; protected $casts = [ 'location' => Point::class, 'area' => Polygon::class, ]; }
Interacting with Spatial Data
After setting up your model, you can now create and access spatial data. Here's an example:
use App\Models\Place; use ASanikovich\LaravelSpatial\Geometry\Polygon; use ASanikovich\LaravelSpatial\Geometry\LineString; use ASanikovich\LaravelSpatial\Geometry\Point; use ASanikovich\LaravelSpatial\Enums\Srid; // Create new records $londonEye = Place::create([ 'name' => 'London Eye', 'location' => new Point(51.5032973, -0.1217424), ]); $whiteHouse = Place::create([ 'name' => 'White House', 'location' => new Point(38.8976763, -77.0365298, Srid::WGS84->value), // with SRID ]); $vaticanCity = Place::create([ 'name' => 'Vatican City', 'area' => new Polygon([ new LineString([ new Point(12.455363273620605, 41.90746728266806), new Point(12.450309991836548, 41.906636872349075), new Point(12.445632219314575, 41.90197359839437), new Point(12.447413206100464, 41.90027269624499), new Point(12.457906007766724, 41.90000118654431), new Point(12.458517551422117, 41.90281205461268), new Point(12.457584142684937, 41.903107507989986), new Point(12.457734346389769, 41.905918239316286), new Point(12.45572805404663, 41.90637337450963), new Point(12.455363273620605, 41.90746728266806), ]), ]), ]) // Access the data echo $londonEye->location->latitude; // 51.5032973 echo $londonEye->location->longitude; // -0.1217424 echo $whiteHouse->location->srid; // 4326 echo $vacationCity->area->toJson(); // {"type":"Polygon","coordinates":[[[41.90746728266806,12.455363273620605],[41.906636872349075,12.450309991836548],[41.90197359839437,12.445632219314575],[41.90027269624499,12.447413206100464],[41.90000118654431,12.457906007766724],[41.90281205461268,12.458517551422117],[41.903107507989986,12.457584142684937],[41.905918239316286,12.457734346389769],[41.90637337450963,12.45572805404663],[41.90746728266806,12.455363273620605]]]}
Further Reading
For more comprehensive documentation on the API, please refer to the API page.
Create queries only with scopes methods:
Place::whereDistance(...); // This is IDE-friendly
Extension
You can add new methods to the Geometry
class through macros.
Here's an example of how to register a macro in your service provider's boot
method:
class AppServiceProvider extends ServiceProvider { public function boot(): void { Geometry::macro('getName', function (): string { /** @var Geometry $this */ return class_basename($this); }); } }
Use the method in your code:
$londonEyePoint = new Point(51.5032973, -0.1217424); echo $londonEyePoint->getName(); // Point
Development
Here are some useful commands for development
Before running tests run db by docker-compose:
docker-compose up -d
Run tests:
composer run test
Run tests with coverage:
composer run test-coverage
Perform type checking:
composer run phpstan
Format your code:
composer run format
Updates and Changes
For details on updates and changes, please refer to our CHANGELOG.
License
Laravel Spatial is released under The MIT License (MIT). For more information, please see our License File.
Credits
Originally inspired from MatanYadaev's laravel-eloquent-spatial package.