eng-mmustafa/laravel-location-monitor

Laravel real-time gateway for Location Monitor Service using Redis Pub/Sub and Reverb

v1.0.0 2026-01-12 13:51 UTC

Requires

• php: ^8.2
• illuminate/broadcasting: ^10.0|^11.0|^12.0
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/events: ^10.0|^11.0|^12.0
• illuminate/queue: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

MIT

• Mohammed Mustafa

README

A robust Laravel package that acts as a real-time gateway for the Location Monitor Service. It subscribes to Redis Pub/Sub events from the core engine and broadcasts them via Laravel Reverb to your frontend.

Features

• 🔌 Redis Pub/Sub Integration: Listens to real-time location events from the Node.js engine.
• 📡 Laravel Reverb Ready: Broadcasts events securely using Laravel's native broadcasting system.
• 🛡️ Event Driven: Maps infrastructure messages to clean Laravel Events (LocationUpdated, StatusUpdated).
• 🏗️ Architecturally Sound: Decouples the heavy location processing from your Laravel application.

Requirements

• PHP 8.2+
• Laravel 10.0+
• Redis
• Laravel Reverb (or any compatible broadcaster)

Installation

1. Install the package via composer:

composer require eng-mmustafa/laravel-location-monitor

1. Publish the configuration file:

php artisan vendor:publish --tag=location-monitor-config

1. Configure your environment variables in .env:

LOCATION_MONITOR_REDIS_CONNECTION=default
LOCATION_MONITOR_PREFIX=location-monitor:
LOCATION_MONITOR_CHANNEL=location-monitor:events

Usage

1. Start the Listener

The package includes an Artisan command to listen for Redis events. This should be run as a daemon (e.g., using Supervisor).

php artisan location-monitor:listen

2. Subscribe in Frontend (Laravel Echo)

The package broadcasts events to private channels named agent.{agentId}.

// Using Laravel Echo
Echo.private(`agent.${agentId}`)
    .listen('.location.updated', (e) => {
        console.log('Location update:', e.location);
        console.log('Speed:', e.speed);
    })
    .listen('.status.updated', (e) => {
        console.log('Status changed:', e.newStatus);
    });

3. Access Location Data Manually

You can use the Facade to access the current state of any agent from your controllers or services.

use LocationMonitor\Facades\LocationMonitor;

// Get last known location
$location = LocationMonitor::location($agentId);

// Get agent status
$status = LocationMonitor::status($agentId);

Architecture

This package is designed as a Gateway. It does not perform location calculations or geofencing logic; that is handled by the Node.js Location Monitor Service.

1. Node.js Service publishes location-monitor:events to Redis.
2. Laravel Listener (location-monitor:listen) picks up the message.
3. Laravel Event (LocationUpdated) is dispatched.
4. Laravel Reverb broadcasts the event to WebSocket clients.

Security

By default, the package defines a broadcast channel agent.{agentId}. You should ensure your routes/channels.php or BroadcastServiceProvider is configured to handle authentication if you need custom logic. The package registers a default callback that allows any authenticated user to listen.

License

The MIT License (MIT). Please see License File for more information.