PHPackages                             matanyadaev/laravel-eloquent-spatial - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. matanyadaev/laravel-eloquent-spatial

ActiveLibrary[Database & ORM](/categories/database)

matanyadaev/laravel-eloquent-spatial
====================================

Spatial library for Laravel

4.7.0(2mo ago)3982.9M—2.4%54[4 issues](https://github.com/MatanYadaev/laravel-eloquent-spatial/issues)11MITPHPPHP ^8.1CI passing

Since Feb 23Pushed 2mo ago4 watchersCompare

[ Source](https://github.com/MatanYadaev/laravel-eloquent-spatial)[ Packagist](https://packagist.org/packages/matanyadaev/laravel-eloquent-spatial)[ Docs](https://github.com/matanyadaev/laravel-eloquent-spatial)[ RSS](/packages/matanyadaev-laravel-eloquent-spatial/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (16)Versions (47)Used By (11)

Laravel Eloquent Spatial
========================

[](#laravel-eloquent-spatial)

[![Latest Version on Packagist](https://camo.githubusercontent.com/fcb4033b6a50bfdbfab2a55f9525fa9a596cef7774bcce9a5b45e42921a0f8b3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6174616e7961646165762f6c61726176656c2d656c6f7175656e742d7370617469616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/matanyadaev/laravel-eloquent-spatial)[![Tests](https://github.com/matanyadaev/laravel-eloquent-spatial/actions/workflows/pest.yml/badge.svg)](https://github.com/matanyadaev/laravel-eloquent-spatial/actions/workflows/pest.yml/badge.svg)[![Static code analysis](https://github.com/matanyadaev/laravel-eloquent-spatial/actions/workflows/phpstan.yml/badge.svg)](https://github.com/matanyadaev/laravel-eloquent-spatial/actions/workflows/phpstan.yml/badge.svg)[![Lint](https://github.com/matanyadaev/laravel-eloquent-spatial/actions/workflows/pint.yml/badge.svg)](https://github.com/matanyadaev/laravel-eloquent-spatial/actions/workflows/pint.yml/badge.svg)[![Total Downloads](https://camo.githubusercontent.com/cf480f9f918a93034e310fb025fdf388ee30464c61cdf5e9a1751cae9ea4f88e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6174616e7961646165762f6c61726176656c2d656c6f7175656e742d7370617469616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/matanyadaev/laravel-eloquent-spatial)

**This Laravel package allows you to easily work with spatial data types and functions.**

Supported databases:

- MySQL 5.7/8
- MariaDB 10
- Postgres 12/13/14/15/16 with PostGIS 3.4

Getting Started
---------------

[](#getting-started)

### Installing the Package

[](#installing-the-package)

You can install the package via composer:

```
composer require matanyadaev/laravel-eloquent-spatial
```

### Setting Up Your First Model

[](#setting-up-your-first-model)

1. First, generate a new model along with a migration file by running:

    ```
    php artisan make:model {modelName} --migration
    ```
2. 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->geometry('location', subtype: 'point')->nullable();
                $table->geometry('area', subtype: 'polygon')->nullable();
                $table->timestamps();
            });
        }

        public function down(): void
        {
            Schema::dropIfExists('places');
        }
    }
    ```
3. Run the migration:

    ```
    php artisan migrate
    ```
4. In your new model, fill the `$fillable` and `$casts` arrays and use the `HasSpatial` trait:

    ```
    namespace App\Models;

    use Illuminate\Database\Eloquent\Model;
    use MatanYadaev\EloquentSpatial\Objects\Point;
    use MatanYadaev\EloquentSpatial\Objects\Polygon;
    use MatanYadaev\EloquentSpatial\Traits\HasSpatial;

    /**
     * @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

[](#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 MatanYadaev\EloquentSpatial\Objects\Polygon;
use MatanYadaev\EloquentSpatial\Objects\LineString;
use MatanYadaev\EloquentSpatial\Objects\Point;
use MatanYadaev\EloquentSpatial\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
---------------

[](#further-reading)

For more comprehensive documentation on the API, please refer to the [API](API.md) page.

Extension
---------

[](#extension)

### Extend Geometry class with macros

[](#extend-geometry-class-with-macros)

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
```

### Extend with custom geometry classes

[](#extend-with-custom-geometry-classes)

You can extend the geometry classes by creating custom geometry classes and add functionality. You can also override existing methods, although it is not recommended, as it may lead to unexpected behavior.

1. Create a custom geometry class that extends the base geometry class.

```
use MatanYadaev\EloquentSpatial\Objects\Point;

class ExtendedPoint extends Point
{
    public function toCustomArray(): array
    {
        return 'coordinates' => [
            'latitude' => $this->latitude,
            'longitude' => $this->longitude
        ]
    }
}
```

2. Update the geometry class mapping in a service provider file.

```
use App\ValueObjects\ExtendedPoint;
use Illuminate\Support\ServiceProvider;
use MatanYadaev\EloquentSpatial\EloquentSpatial;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        EloquentSpatial::usePoint(ExtendedPoint::class);
    }
}
```

3. Update your model to use the custom geometry class in the `$casts` property or `casts()` method.

```
use App\ValueObjects\ExtendedPoint;
use Illuminate\Database\Eloquent\Model;
use MatanYadaev\EloquentSpatial\Traits\HasSpatial;

class Place extends Model
{
    use HasSpatial;

    protected $casts = [
        'coordinates' => ExtendedPoint::class,
    ];

    // Or:

    protected function casts(): array
    {
        return [
            'coordinates' => ExtendedPoint::class,
        ];
    }
}
```

4. Use the custom geometry class in your code.

```
use App\Models\Location;
use App\ValueObjects\ExtendedPoint;

$place = Place::create([
    'name' => 'London Eye',
    'coordinates' => new ExtendedPoint(51.5032973, -0.1217424),
]);

echo $place->coordinates->toCustomArray(); // ['longitude' => -0.1217424, 'latitude' => 51.5032973]
```

Set default SRID
----------------

[](#set-default-srid)

By default, the SRID is set to 0 (EPSG:0). You can set the default SRID for your application by setting the `SRID` constant in a service provider's `boot` method:

```
use MatanYadaev\EloquentSpatial\Enums\Srid;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Set the default SRID to WGS84 (EPSG:4326)
        EloquentSpatial::setDefaultSrid(Srid::WGS84);
    }
}
```

Development
-----------

[](#development)

Here are some useful commands for development:

- Run tests: `composer pest:mysql`, `composer pest:mariadb`, `composer pest:postgres`
- Run tests with coverage: `composer pest-coverage:mysql`
- Perform type checking: `composer phpstan`
- Perform code formatting: `composer pint`

Before running tests, make sure to run `docker-compose up` to start the database container.

Updates and Changes
-------------------

[](#updates-and-changes)

For details on updates and changes, please refer to our [CHANGELOG](CHANGELOG.md).

License
-------

[](#license)

Laravel Eloquent Spatial is released under The MIT License (MIT). For more information, please see our [License File](LICENSE.md).

###  Health Score

68

—

FairBetter than 100% of packages

Maintenance88

Actively maintained with recent releases

Popularity63

Solid adoption and visibility

Community35

Small or concentrated contributor base

Maturity74

Established project with proven stability

 Bus Factor1

Top contributor holds 92.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~45 days

Recently: every ~118 days

Total

42

Last Release

61d ago

Major Versions

1.0.4 → 2.0.02022-07-08

2.10.0 → 3.0.02023-02-03

2.10.1 → 3.2.02023-06-25

3.2.2 → 4.0.02024-01-18

PHP version history (2 changes)1.0.0PHP ^8.0

3.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/0615d9b6f53bf93a07af72cd5d7829f4fd73ccf055d7ddaa522477138f30cd60?d=identicon)[MatanYadaev](/maintainers/MatanYadaev)

---

Top Contributors

[![MatanYadaev](https://avatars.githubusercontent.com/u/13586343?v=4)](https://github.com/MatanYadaev "MatanYadaev (212 commits)")[![Riley19280](https://avatars.githubusercontent.com/u/14127031?v=4)](https://github.com/Riley19280 "Riley19280 (2 commits)")[![Synchro](https://avatars.githubusercontent.com/u/81561?v=4)](https://github.com/Synchro "Synchro (2 commits)")[![yinx](https://avatars.githubusercontent.com/u/1022847?v=4)](https://github.com/yinx "yinx (2 commits)")[![gdebrauwer](https://avatars.githubusercontent.com/u/22586858?v=4)](https://github.com/gdebrauwer "gdebrauwer (1 commits)")[![jobverplanke](https://avatars.githubusercontent.com/u/18289961?v=4)](https://github.com/jobverplanke "jobverplanke (1 commits)")[![ju-gow](https://avatars.githubusercontent.com/u/5887244?v=4)](https://github.com/ju-gow "ju-gow (1 commits)")[![d0m4te](https://avatars.githubusercontent.com/u/15982187?v=4)](https://github.com/d0m4te "d0m4te (1 commits)")[![lukevi](https://avatars.githubusercontent.com/u/5833626?v=4)](https://github.com/lukevi "lukevi (1 commits)")[![nickknissen](https://avatars.githubusercontent.com/u/204970?v=4)](https://github.com/nickknissen "nickknissen (1 commits)")[![trin4ik](https://avatars.githubusercontent.com/u/839633?v=4)](https://github.com/trin4ik "trin4ik (1 commits)")[![LachlanArthur](https://avatars.githubusercontent.com/u/1870204?v=4)](https://github.com/LachlanArthur "LachlanArthur (1 commits)")[![devinfd](https://avatars.githubusercontent.com/u/468399?v=4)](https://github.com/devinfd "devinfd (1 commits)")[![dzhwar-k](https://avatars.githubusercontent.com/u/73309329?v=4)](https://github.com/dzhwar-k "dzhwar-k (1 commits)")[![eschricker](https://avatars.githubusercontent.com/u/56429442?v=4)](https://github.com/eschricker "eschricker (1 commits)")

---

Tags

eloquentlaravelphpspatial

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/matanyadaev-laravel-eloquent-spatial/health.svg)

```
[![Health](https://phpackages.com/badges/matanyadaev-laravel-eloquent-spatial/health.svg)](https://phpackages.com/packages/matanyadaev-laravel-eloquent-spatial)
```

###  Alternatives

[anourvalar/eloquent-serialize

Laravel Query Builder (Eloquent) serialization

11120.2M21](/packages/anourvalar-eloquent-serialize)[overtrue/laravel-versionable

Make Laravel model versionable.

585308.0k5](/packages/overtrue-laravel-versionable)[abbasudo/laravel-purity

elegant way to add filter and sort in laravel

514330.5k1](/packages/abbasudo-laravel-purity)[statamic-rad-pack/runway

Eloquently manage your database models in Statamic.

135192.6k5](/packages/statamic-rad-pack-runway)[dragon-code/laravel-deploy-operations

Performing any actions during the deployment process

240173.5k2](/packages/dragon-code-laravel-deploy-operations)[stayallive/laravel-eloquent-observable

Register Eloquent model event listeners just-in-time directly from the model.

2928.9k7](/packages/stayallive-laravel-eloquent-observable)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)