Laravel Location Showcase

Discover real-world examples and use cases of Laravel Location in action. See how applications leverage normalized geography, reusable locations, geo areas, and polymorphic addresses.

Address Book (Billing/Shipping)

Customer Address Book

Attach multiple addresses to any model with collections

Overview

Most applications need multiple addresses per user or entity (billing, shipping, warehouse, office). Laravel Location provides a clean polymorphic pivot layer for attaching addresses with optional collections and built-in support for soft deletes.

Key Features

• Polymorphic attachments (any model)
• Collection support (billing/shipping/...)
• Resource-based output
• Soft delete-aware reads
• Convenient store/update/delete helpers

Use Cases

• User address book
• Company branches
• Supplier/warehouse addresses
• Pickup points
• Multi-tenant profiles

Implementation Example

use Illuminate\Database\Eloquent\Model;
use JobMetric\Location\HasAddress;

class User extends Model
{
    use HasAddress;
}

$user = User::find(1);

// Store and attach an address in the "billing" collection
$user->storeAddress([
    // Required location fields
    'country_id' => 1,
    'province_id' => 10,
    'city_id' => 120,
    'district_id' => 900, // nullable

    // Required address object (allowed keys: blvd, street, alley, number, floor, unit)
    'address' => [
        'street' => 'Valiasr St',
        'number' => '12',
    ],

    // Optional fields
    'postcode' => '1234567890',
    'info' => [
        'name' => 'John Doe',
        'mobile_prefix' => '+98',
        'mobile' => '9120000000',
    ],
], 'billing');

// Read by collection
$billingAddresses = $user->addresses('billing');

// Update an attached address (service update under the hood)
$user->updateAddress($billingAddresses->first()->id, [
    'postcode' => '1111111111',
    'info' => [
        'notes' => 'Updated at checkout',
    ],
]);

Learn more: HasAddress

Shipping Coverage (Geo Areas)

Shipping Zones / Service Areas

Use Geo Areas to group locations and check coverage

Overview

Geo Areas are reusable groupings of multiple locations. They are perfect for shipping zones, delivery coverage, business regions, or any scenario where you need to attach and query location coverage on other domain models.

Implementation Example

use Illuminate\Database\Eloquent\Model;
use JobMetric\Location\Facades\GeoArea;
use JobMetric\Location\HasGeoArea;

class ShippingMethod extends Model
{
    use HasGeoArea;
}

// Create a geo area with multiple locations
$geoArea = GeoArea::store([
    'translation' => [
        'en' => [
            'name' => 'Tehran Zone',
            'description' => 'All supported locations in Tehran.',
        ],
    ],
    'status' => true,
    'locations' => [
        ['country_id' => 1, 'province_id' => 10, 'city_id' => 120],
        ['country_id' => 1, 'province_id' => 10, 'city_id' => 120, 'district_id' => 900],
    ],
])->data;

$method = ShippingMethod::find(10);
$method->attachGeoArea($geoArea->id);

// Check coverage for a location id
$isCovered = $method->isInGeoArea($locationId);

Learn more: HasGeoArea · GeoArea Service

Unique Locations (firstOrCreate)

use JobMetric\Location\Facades\Location;

// Unique by (country_id, province_id, city_id, district_id)
$response = Location::store([
    'country_id' => 1,
    'province_id' => 10,
    'city_id' => 120,
    'district_id' => 900,
]);

// If the location already exists, the service returns the existing one.

Learn more: Location Service

Dataset Import Pipeline

# Generate/refresh countries.json dataset
php artisan location:generate-countries --pretty

# Import all countries
php artisan location:import

# Import hierarchy (provinces/cities/districts) for a specific country key
php artisan location:import ir --force

Learn more: Datasets