README

A Laravel package for interactive maps using Leaflet.js. This package provides an easy-to-use Blade component and helper functions to display interactive maps with multiple location markers.

Features

🗺️ Interactive maps powered by Leaflet.js
📍 Multiple location markers with popups
🔍 Click-to-zoom functionality
📏 Auto-fit bounds to show all markers
🔗 Google Maps integration links
🎨 Customizable styling
⚙️ Configurable settings

Installation

Via Composer

composer require imamhsn195/laravel-interactive-map

For Local Development/Testing

If you want to test the package locally before publishing, see TESTING_LOCALLY.md for detailed instructions.

For publishing instructions, see PUBLISHING.md.

Quick setup:

Add path repository to your Laravel project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../laravel-packages/laravel-Interactive-map",
            "options": {
                "symlink": true
            }
        }
    ]
}

Note: symlink: true enables auto-sync - changes in the package are immediately reflected without running composer update. See LOCAL_SETUP.md for details.

Install: composer require imamhsn195/laravel-interactive-map:@dev
Publish assets: php artisan vendor:publish --tag=interactive-map-assets

Step 1: Install Package

composer require imamhsn195/laravel-interactive-map

Step 2: Publish Assets (Optional)

If you want to customize the configuration, views, or assets:

# Publish configuration
php artisan vendor:publish --tag=interactive-map-config

# Publish views
php artisan vendor:publish --tag=interactive-map-views

# Publish assets (CSS/JS)
php artisan vendor:publish --tag=interactive-map-assets

Usage

Important: Layout Requirements

The map component uses Laravel's @push directive to add styles and scripts. Make sure your Blade layout file includes the corresponding @stack directives:

In your layout file (e.g., resources/views/layouts/app.blade.php):

<!DOCTYPE html>
<html>
<head>
    <!-- Other head content -->
    @stack('styles')
</head>
<body>
    <!-- Your content -->
    @yield('content')
    
    <!-- Scripts -->
    @stack('scripts')
</body>
</html>

Without these @stack directives, the map styles and JavaScript won't load, causing the map to not display properly.

Custom Stack Names:

If your layout uses different stack names (e.g., @stack('css') and @stack('js')), you can configure them in config/interactive-map.php:

'stacks' => [
    'styles' => 'css',    // Match your @stack('css')
    'scripts' => 'js',    // Match your @stack('js')
],

Method 1: Using Blade Component (Recommended)

The easiest way to use the map is with the Blade component:

<x-interactive-map 
    :locations="[
        [
            'name' => 'Dubai Office',
            'lat' => 25.17188147144341,
            'lng' => 55.3556179237354,
            'url' => 'https://maps.app.goo.gl/uYiJ6CfwoNm3XGgh9',
            'address' => 'Ras Al Khor Industrial Area, Dubai',
        ],
        [
            'name' => 'Sharjah Office',
            'lat' => 25.333289225273425,
            'lng' => 55.611662864417795,
            'url' => 'https://maps.app.goo.gl/iMcRquz4EvWYQsLx7',
            'address' => 'Sharjah, Sajja',
        ],
    ]"
    container-id="myMap"
    height="500px"
/>

Method 2: Using Helper Function

@php
    $locations = [
        [
            'name' => 'Location 1',
            'lat' => 25.17,
            'lng' => 55.35,
            'url' => 'https://maps.app.goo.gl/...',
            'address' => 'Address here',
        ],
    ];
@endphp

{!! interactive_map($locations, 'contactMap', '400px', '100%') !!}

Method 3: Using in Controller

public function contact()
{
    $locations = [
        [
            'name' => 'Dubai Office',
            'lat' => 25.17188147144341,
            'lng' => 55.3556179237354,
            'url' => 'https://maps.app.goo.gl/uYiJ6CfwoNm3XGgh9',
            'address' => 'Ras Al Khor Industrial Area, Dubai',
        ],
    ];

    return view('contact', compact('locations'));
}

Then in your Blade template:

<x-interactive-map :locations="$locations" />

Method 4: Using with Database Model

// In your controller
public function locations()
{
    $locations = Location::all()->map(function ($location) {
        return [
            'name' => $location->name,
            'lat' => $location->latitude,
            'lng' => $location->longitude,
            'url' => $location->google_maps_url,
            'address' => $location->address,
        ];
    })->toArray();

    return view('locations', compact('locations'));
}

Location Data Format

Each location can have the following fields:

Field	Required	Description	Alternative Names
`name`	Yes	Location name	`title`
`lat`	Yes	Latitude	`latitude`
`lng`	Yes	Longitude	`longitude`
`url`	No	Google Maps URL	`map_url`
`address`	No	Physical address	-
`description`	No	Additional description	-

Configuration

After publishing the configuration file, you can customize the map settings in config/interactive-map.php:

return [
    'default' => [
        'tile_layer' => 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
        'attribution' => '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
        'zoom' => 8,
        'padding' => [50, 50],
        'marker_click_zoom' => 11,
    ],
    
    'container' => [
        'id' => 'mapContainer',
        'class' => 'w-100 h-100',
        'height' => '400px',
        'width' => '100%',
    ],

    /*
    | Blade Stack Names
    | Configure the stack names used for pushing styles and scripts.
    | These should match the @stack directives in your layout file.
    */
    'stacks' => [
        'styles' => 'styles',  // Change to match your layout's @stack('styles')
        'scripts' => 'scripts', // Change to match your layout's @stack('scripts')
    ],
];

Configuration Options

Option	Default	Description
`tile_layer`	OpenStreetMap URL	Map tile provider
`attribution`	OSM attribution	Map attribution text
`zoom`	8	Default zoom level
`padding`	[50, 50]	Bounds padding
`marker_click_zoom`	11	Zoom level on marker click
`container.id`	'mapContainer'	Container element ID
`container.height`	'400px'	Default map height
`container.width`	'100%'	Default map width
`stacks.styles`	'styles'	Blade stack name for styles
`stacks.scripts`	'scripts'	Blade stack name for scripts

Component Attributes

When using the Blade component, you can pass the following attributes:

locations (array, required): Array of location data
container-id (string, optional): Custom container ID
height (string, optional): Map height (e.g., '400px', '500px', '50vh'). Default: '400px'
width (string, optional): Map width (e.g., '100%', '800px', '90vw'). Default: '100%'

Requirements

PHP: ^8.1
Laravel: ^9.0|^10.0|^11.0|^12.0
Leaflet.js: 1.9.4 (loaded via CDN)

Browser Support

This package uses Leaflet.js, which supports all modern browsers:

Chrome
Firefox
Safari
Edge
Opera

Customization

Custom Styling

After publishing assets, you can customize the CSS in public/vendor/interactive-map/css/interactive-map.css.

Custom Views

After publishing views, you can customize the Blade template in resources/views/vendor/interactive-map/map.blade.php.

Troubleshooting

Map not displaying

Check your layout file - Ensure you have @stack('styles') in <head> and @stack('scripts') before </body> in your Blade layout file. Without these, the map styles and JavaScript won't load.
Ensure Leaflet.js is loading correctly (check browser console)
Verify the container ID is unique on the page
Check that the container has a defined height

Markers not showing

Verify location coordinates are valid (lat/lng)
Check that locations array is not empty
Ensure coordinates are within valid range (-90 to 90 for lat, -180 to 180 for lng)

Styles not applying

Verify @stack('styles') is in your layout - The component uses @push('styles') which requires @stack('styles') in your layout
Publish assets: php artisan vendor:publish --tag=interactive-map-assets
Clear view cache: php artisan view:clear
Check that CSS file is being loaded in browser DevTools

JavaScript not working

Verify @stack('scripts') is in your layout - The component uses @push('scripts') which requires @stack('scripts') in your layout
Check browser console for JavaScript errors
Ensure Leaflet.js library is loading (check Network tab)

License

MIT License

Support

For issues, questions, or contributions, please visit the GitHub repository.

Changelog

See CHANGELOG.md for version history.

imamhsn195 / interactive-map

Maintainers

Package info

Statistics

Security