包简介

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

README 文档

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 适用场景与选型建议

imamhsn195/interactive-map 是一款基于 Blade 开发的 Composer 扩展包，目前已累计 1 次下载、GitHub Stars 达 0，最近一次更新时间为 2026 年 01 月 24 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「geolocation」「map」「maps」「laravel」「leaflet」「markers」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 imamhsn195/interactive-map 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 imamhsn195/interactive-map 我们能提供哪些服务？

定制开发 / 二次开发

基于 imamhsn195/interactive-map 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 imamhsn195/interactive-map 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

doublesecretagency/craft-googlemaps 12

Maps in minutes. Powered by the Google Maps API.

mauricewijnia/nova-maps-address 6

A Laravel Nova Google Maps Field.

kolyunya/yii2-map-input-widget 28

Yii2 map input widget. Allows you to select geographcal coordinates via a human-friendly inteface.

apiip/apiip.net 0

The official PHP library for apiip.net that allowing customers to automate IP address validation and geolocation lookup in websites, applications and back-office system. Visit our API docs at https://apiip.net/documentation

adbros/google-maps-php-sdk 0

Google Maps PHP SDK.

vitalybaev/sypexgeo 0

Supports GeoIP services (sypexgeo.net).

imamhsn195/interactive-map

包简介

关键字：