🚀 Laravel Job Batching with Realtime Progress

Execute Laravel job batches with real-time progress tracking using Pusher WebSocket

🌐 Language / Bahasa

Choose your preferred language for documentation:

🇺🇸 English | View English Documentation |

🇮🇩 Bahasa Indonesia | Lihat Dokumentasi Bahasa Indonesia |

Quick Navigation

• 🚀 Getting Started | 🚀 Memulai
• 📖 API Reference | 📖 Referensi API
• 💡 Examples | 💡 Contoh

---

📖 English Documentation

🎯 Overview

Laravel Job Batching with Realtime Progress is a powerful package that allows you to execute batch jobs with real-time progress tracking. Monitor your job execution progress live using WebSocket technology powered by Pusher.

🎬 Live Demo

📑 Table of Contents

• ✨ Features
• 📋 Requirements
• ⚙️ Installation
• 🔧 Configuration
• 🛠️ Implementation
• 📊 JavaScript Setup
• 📈 API Response
• 🤝 Contributing
• 📝 Changelog
• 👥 Credits
• 📄 License

✨ Features

• 🔄 Real-time Progress Tracking - Monitor job execution progress in real-time
• 📡 WebSocket Integration - Uses Pusher for instant updates
• 🎯 Batch Processing - Handle multiple jobs efficiently
• 🔌 Easy Integration - Simple setup with Laravel projects
• 📊 Progress Metrics - Get detailed progress information
• 🎨 Customizable - Flexible implementation for various use cases

📋 Requirements

• PHP 7.4 or Higher
• Laravel 8 or Higher
• 🔗 Laravel Job Queue
• 📡 Pusher Account

⚙️ Installation

Step 1: Database Setup

Create necessary migration tables:

# Create job table
php artisan queue:table

# Create job batches table  
php artisan queue:batches-table

# Run migrations
php artisan migrate

Step 2: Install Package

composer require yogameleniawan/realtime-job-batching

Step 3: Pusher Setup

Install Pusher PHP SDK:

composer require pusher/pusher-php-server

🔧 Configuration

Pusher Configuration

1. Create Pusher App: Visit Pusher Dashboard to create a new Channels app

2. Environment Variables: Add these variables to your .env file:

PUSHER_APP_ID=your_pusher_app_id
PUSHER_APP_KEY=your_pusher_app_key
PUSHER_APP_SECRET=your_pusher_app_secret
PUSHER_HOST=
PUSHER_PORT=443  
PUSHER_SCHEME=https
PUSHER_APP_CLUSTER=mt1

🛠️ Implementation

Create Service Repository

1. Create Repository Directory: Create folder app/Repositories in your project

2. Create Repository Class: For example, VerificationRepository.php

3. Implement Interface: Your repository must implement RealtimeJobBatchInterface

<?php

namespace App\Repositories;

use Illuminate\Support\Collection;
use YogaMeleniawan\JobBatchingWithRealtimeProgress\Interfaces\RealtimeJobBatchInterface;

class VerificationRepository implements RealtimeJobBatchInterface
{
    /**
     * Get all data to be processed
     * @return Collection
     */
    public function get_all(): Collection
    {
        // Return collection of data to be processed
        return collect([
            // Your data here
        ]);
    }

    /**
     * Process individual data item
     * @param mixed $data
     * @return void
     */
    public function save($data): void
    {
        // Your business logic here
        // Update/delete/process the data
    }
}

Create Controller Method

Create a controller method to handle your job process:

<?php

namespace App\Http\Controllers;

use YogaMeleniawan\JobBatchingWithRealtimeProgress\RealtimeJobBatch;
use App\Repositories\VerificationRepository;

class BatchController extends Controller
{
    public function executeVerification()
    {
        $result = RealtimeJobBatch::setRepository(new VerificationRepository())
                                 ->execute(name: 'User Verification Process');
        
        return response()->json([
            'message' => 'Batch job started successfully',
            'batch_id' => $result->id
        ]);
    }
}

Method Explanation

• setRepository(RealtimeJobBatchInterface $repository): Sets the repository class to use
• execute(string $name): Executes the job batch with a custom name

📊 JavaScript Setup

For Laravel Blade Views

Add this script to your blade template:

<script src="https://js.pusher.com/7.2/pusher.min.js"></script>
<script>
    // Initialize Pusher
    var pusher = new Pusher('YOUR_PUSHER_APP_KEY', {
        cluster: 'mt1'
    });

    // Listen for progress updates
    var progressChannel = pusher.subscribe('channel-job-batching');
    progressChannel.bind('broadcast-job-batching', function(data) {
        console.log('Progress Update:', data);
        
        // Update your progress bar
        updateProgressBar(data.progress);
        updateStats(data);
    });

    // Listen for completion
    var finishChannel = pusher.subscribe('channel-finished-job');
    finishChannel.bind('request-finished-job', function(data) {
        if (data.finished === true) {
            console.log('Job completed!');
            resetProgressBar();
        }
    });

    // Helper functions
    function updateProgressBar(progress) {
        document.getElementById('progress-bar').style.width = progress + '%';
        document.getElementById('progress-text').textContent = progress + '%';
    }

    function updateStats(data) {
        document.getElementById('total-jobs').textContent = data.total;
        document.getElementById('pending-jobs').textContent = data.pending;
    }

    function resetProgressBar() {
        updateProgressBar(0);
        // Add your completion logic here
    }
</script>

For Other Frameworks

For React, Vue, or other JavaScript frameworks, check the Pusher documentation.

📈 API Response

The WebSocket will send progress updates in this format:

{
    "finished": false,
    "progress": 10,
    "pending": 90,
    "total": 100,
    "data": {
        "batch_id": "uuid-string",
        "name": "User Verification Process",
        "started_at": "2024-01-01T10:00:00Z"
    }
}

Response Fields

• finished: Boolean indicating if the batch is complete
• progress: Number of completed jobs
• pending: Number of remaining jobs
• total: Total number of jobs in the batch
• data: Additional batch information

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

📝 Changelog

Please see CHANGELOG for more information about recent changes.

👥 Credits

• Yoga Meleniawan Pamungkas - Original Author
• All Contributors - Community Contributors

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📖 Dokumentasi Bahasa Indonesia

🎯 Ringkasan

Laravel Job Batching with Realtime Progress adalah package yang memungkinkan Anda menjalankan batch job dengan pelacakan progres real-time. Pantau eksekusi job Anda secara langsung menggunakan teknologi WebSocket yang didukung oleh Pusher.

🎬 Demo Langsung

📑 Daftar Isi

• ✨ Fitur
• 📋 Persyaratan
• ⚙️ Instalasi
• 🔧 Konfigurasi
• 🛠️ Implementasi
• 📊 Setup JavaScript
• 📈 Response API
• 🤝 Kontribusi
• 📝 Changelog
• 👥 Kredit
• 📄 Lisensi

✨ Fitur

• 🔄 Pelacakan Progres Real-time - Pantau progres eksekusi job secara real-time
• 📡 Integrasi WebSocket - Menggunakan Pusher untuk update instan
• 🎯 Pemrosesan Batch - Menangani multiple job secara efisien
• 🔌 Integrasi Mudah - Setup sederhana dengan proyek Laravel
• 📊 Metrik Progres - Dapatkan informasi progres yang detail
• 🎨 Dapat Dikustomisasi - Implementasi fleksibel untuk berbagai kasus penggunaan

📋 Persyaratan

• PHP 7.4 atau Lebih Tinggi
• Laravel 8 atau Lebih Tinggi
• 🔗 Laravel Job Queue
• 📡 Akun Pusher

⚙️ Instalasi

Langkah 1: Setup Database

Buat tabel migrasi yang diperlukan:

# Buat tabel job
php artisan queue:table

# Buat tabel job batches
php artisan queue:batches-table

# Jalankan migrasi
php artisan migrate

Langkah 2: Install Package

composer require yogameleniawan/realtime-job-batching

Langkah 3: Setup Pusher

Install Pusher PHP SDK:

composer require pusher/pusher-php-server

🔧 Konfigurasi

Konfigurasi Pusher

1. Buat Aplikasi Pusher: Kunjungi Dashboard Pusher untuk membuat aplikasi Channels baru

2. Variabel Environment: Tambahkan variabel ini ke file .env Anda:

PUSHER_APP_ID=your_pusher_app_id
PUSHER_APP_KEY=your_pusher_app_key
PUSHER_APP_SECRET=your_pusher_app_secret
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME=https
PUSHER_APP_CLUSTER=mt1

🛠️ Implementasi

Buat Service Repository

1. Buat Direktori Repository: Buat folder app/Repositories di proyek Anda

2. Buat Class Repository: Misalnya, VerificationRepository.php

3. Implement Interface: Repository Anda harus mengimplementasikan RealtimeJobBatchInterface

<?php

namespace App\Repositories;

use Illuminate\Support\Collection;
use YogaMeleniawan\JobBatchingWithRealtimeProgress\Interfaces\RealtimeJobBatchInterface;

class VerificationRepository implements RealtimeJobBatchInterface
{
    /**
     * Dapatkan semua data yang akan diproses
     * @return Collection
     */
    public function get_all(): Collection
    {
        // Return collection data yang akan diproses
        return collect([
            // Data Anda di sini
        ]);
    }

    /**
     * Proses item data individual
     * @param mixed $data
     * @return void
     */
    public function save($data): void
    {
        // Logic bisnis Anda di sini
        // Update/delete/proses data
    }
}

Buat Method Controller

Buat method controller untuk menangani proses job Anda:

<?php

namespace App\Http\Controllers;

use YogaMeleniawan\JobBatchingWithRealtimeProgress\RealtimeJobBatch;
use App\Repositories\VerificationRepository;

class BatchController extends Controller
{
    public function executeVerification()
    {
        $result = RealtimeJobBatch::setRepository(new VerificationRepository())
                                 ->execute(name: 'Proses Verifikasi User');
        
        return response()->json([
            'message' => 'Batch job berhasil dimulai',
            'batch_id' => $result->id
        ]);
    }
}

Penjelasan Method

• setRepository(RealtimeJobBatchInterface $repository): Mengatur class repository yang akan digunakan
• execute(string $name): Menjalankan job batch dengan nama kustom

📊 Setup JavaScript

Untuk Laravel Blade Views

Tambahkan script ini ke template blade Anda:

<script src="https://js.pusher.com/7.2/pusher.min.js"></script>
<script>
    // Inisialisasi Pusher
    var pusher = new Pusher('YOUR_PUSHER_APP_KEY', {
        cluster: 'mt1'
    });

    // Listen untuk update progres
    var progressChannel = pusher.subscribe('channel-job-batching');
    progressChannel.bind('broadcast-job-batching', function(data) {
        console.log('Update Progres:', data);
        
        // Update progress bar Anda
        updateProgressBar(data.progress);
        updateStats(data);
    });

    // Listen untuk penyelesaian
    var finishChannel = pusher.subscribe('channel-finished-job');
    finishChannel.bind('request-finished-job', function(data) {
        if (data.finished === true) {
            console.log('Job selesai!');
            resetProgressBar();
        }
    });

    // Helper functions
    function updateProgressBar(progress) {
        document.getElementById('progress-bar').style.width = progress + '%';
        document.getElementById('progress-text').textContent = progress + '%';
    }

    function updateStats(data) {
        document.getElementById('total-jobs').textContent = data.total;
        document.getElementById('pending-jobs').textContent = data.pending;
    }

    function resetProgressBar() {
        updateProgressBar(0);
        // Tambahkan logic completion Anda di sini
    }
</script>

Untuk Framework Lain

Untuk React, Vue, atau framework JavaScript lainnya, periksa dokumentasi Pusher.

📈 Response API

WebSocket akan mengirim update progres dalam format ini:

{
    "finished": false,
    "progress": 10,
    "pending": 90,
    "total": 100,
    "data": {
        "batch_id": "uuid-string",
        "name": "Proses Verifikasi User",
        "started_at": "2024-01-01T10:00:00Z"
    }
}

Field Response

• finished: Boolean yang menunjukkan apakah batch sudah selesai
• progress: Jumlah job yang sudah selesai
• pending: Jumlah job yang tersisa
• total: Total jumlah job dalam batch
• data: Informasi tambahan batch

🤝 Kontribusi

Kami menyambut kontribusi! Silakan lihat Panduan Kontribusi kami untuk detail.

📝 Changelog

Silakan lihat CHANGELOG untuk informasi lebih lanjut tentang perubahan terbaru.

👥 Kredit

• Yoga Meleniawan Pamungkas - Penulis Asli
• Semua Kontributor - Kontributor Komunitas

📄 Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT - lihat file LICENSE untuk detail.

---

⬆ Back to top | ⬆ Kembali ke atas | ⬆ トップに戻る

---

🌟 Star this repository if you find it helpful!

Made with ❤️ by Yoga Meleniawan Pamungkas