README

Laravel package untuk menangkap error dari Telescope atau Laravel exception handler dan mengirimkannya ke Errly Dashboard.

Requirements

• PHP 8.1 atau lebih baru
• Laravel 10.x, 11.x, 12.x, atau 13.x
• PHP mengikuti versi Laravel yang dipakai; package ini minimum PHP 8.1, sedangkan Laravel 13 membutuhkan PHP 8.3 atau lebih baru
• laravel/telescope opsional, hanya diperlukan jika ingin memakai capture mode telescope

Installation

composer require keloola/errly
php artisan vendor:publish --tag=keloola-errly-config

Tambahkan konfigurasi minimal ke .env:

KELOOLA_ERRLY_ENABLED=true
KELOOLA_ERRLY_DASHBOARD_URL=https://your-dashboard.com
KELOOLA_ERRLY_API_KEY=proj_xxxxxxxxxxxx

Configuration

KELOOLA_ERRLY_ENABLED=true
KELOOLA_ERRLY_DASHBOARD_URL=https://your-dashboard.com
KELOOLA_ERRLY_API_KEY=proj_xxxxxxxxxxxx
KELOOLA_ERRLY_CAPTURE=auto
KELOOLA_ERRLY_USER_CONTEXT=true
KELOOLA_ERRLY_ENVIRONMENTS=production,staging
KELOOLA_ERRLY_QUEUE=false
KELOOLA_ERRLY_QUEUE_NAME=default
KELOOLA_ERRLY_TIMEOUT=5

KELOOLA_ERRLY_ENABLED mengaktifkan package. KELOOLA_ERRLY_DASHBOARD_URL adalah URL dashboard tanpa path API. KELOOLA_ERRLY_API_KEY adalah API key project. KELOOLA_ERRLY_CAPTURE menentukan sumber error: auto, telescope, exception_handler, atau manual. KELOOLA_ERRLY_USER_CONTEXT menambahkan info user login ke payload error. KELOOLA_ERRLY_ENVIRONMENTS membatasi environment yang dikirim; kosongkan untuk semua environment. KELOOLA_ERRLY_QUEUE mengirim payload via queue. KELOOLA_ERRLY_QUEUE_NAME menentukan queue saat mode queue aktif. KELOOLA_ERRLY_TIMEOUT menentukan timeout HTTP dalam detik.

Entry yang dipantau dan exception yang diabaikan bisa diubah di config/keloola-errly.php. Payload akan disanitasi sebelum dikirim; Closure, object, resource, dan struktur terlalu dalam diubah menjadi nilai string aman agar queue/JSON serialization tidak gagal.

Saat user sedang login, payload error akan menyertakan:

{
  "user": {
    "id": 123,
    "email": "user@example.com",
    "name": "User Name"
  }
}

Field user yang dikirim bisa diubah lewat user_context.fields di config. Jangan masukkan field sensitif seperti password, token, atau remember token.

Capture Mode

auto memakai Telescope jika package laravel/telescope tersedia. Jika tidak tersedia, Errly otomatis memakai Laravel exception handler.

Untuk aplikasi yang tidak menggunakan Telescope, set:

KELOOLA_ERRLY_CAPTURE=exception_handler

Dengan mode ini, exception yang masuk ke Laravel exception handler akan dikirim langsung ke dashboard tanpa dependency Telescope.

Untuk memasang manual di bootstrap/app.php, set:

KELOOLA_ERRLY_CAPTURE=manual

Lalu tambahkan report callback:

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Keloola\Errly\ErrlyManager;
use Throwable;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__ . '/../routes/web.php',
        commands: __DIR__ . '/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        //
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->report(function (Throwable $e): void {
            app(ErrlyManager::class)->handleThrowable($e);
        });
    })
    ->create();

Verification

Untuk test manual tanpa Telescope, trigger langsung lewat manager:

php artisan tinker

use Keloola\Errly\ErrlyManager;

app(ErrlyManager::class)->handleThrowable(
    new RuntimeException('Test error dari Errly package!')
);

Cek dashboard Errly untuk memastikan record baru masuk.

Troubleshooting

Jika notifikasi tidak masuk, cek storage/logs/laravel.log:

tail -f storage/logs/laravel.log | grep Errly

Pastikan KELOOLA_ERRLY_ENABLED=true, KELOOLA_ERRLY_DASHBOARD_URL dan KELOOLA_ERRLY_API_KEY terisi, environment aplikasi masuk ke KELOOLA_ERRLY_ENVIRONMENTS, capture mode sesuai, dan dashboard dapat diakses dari aplikasi.