Laravel Debugbar pokazuje zapytania, czasy wykonania i twoje własne komunikaty debugowe w pasku na dole przeglądarki. Oto jak go skonfigurować i używać.
Wprowadzenie
Laravel Debugbar, stworzony przez Barry'ego vd. Heuvela, to narzędzie do debugowania w Laravel. W przeciwieństwie do dd() czy dump(), które zatrzymują skrypt, Debugbar pozwala podglądać aplikację, a żądanie dochodzi do końca.
Instalacja i konfiguracja
Zainstaluj Laravel Debugbar jako zależność deweloperską:
composer require fruitcake/laravel-debugbar --dev
Pakiet był dawniej publikowany jako barryvdh/laravel-debugbar; wersja 4 przeniosła się do fruitcake/laravel-debugbar (namespace Fruitcake\LaravelDebugbar). Jest wykrywany automatycznie, więc ręczna rejestracja nie jest potrzebna. Tylko jeśli wyłączyłeś package discovery, dodaj ServiceProvider do config/app.php:
Fruitcake\LaravelDebugbar\ServiceProvider::class,
oraz opcjonalnie alias:
'Debugbar' => Fruitcake\LaravelDebugbar\Facades\Debugbar::class,
Następnie opublikuj plik konfiguracyjny:
php artisan vendor:publish --provider="Fruitcake\LaravelDebugbar\ServiceProvider"
Domyślnie Debugbar jest włączony, gdy APP_DEBUG ma wartość true (opcja enabled w config/debugbar.php to null, nadpisywalna przez DEBUGBAR_ENABLED). To narzędzie deweloperskie: na produkcji trzymaj APP_DEBUG=false.
Nieinwazyjne debugowanie z Debugbar::addMessage()
Debugbar pozwala dodawać komunikaty bez zatrzymywania skryptu:
use Debugbar;
public function show($id)
{
$user = User::find($id);
// Zamiast dd($user) lub dump($user)
Debugbar::info($user);
// Możemy też dodać własne komunikaty
Debugbar::addMessage('Użytkownik został pobrany', 'info');
// Zauważ, że aplikacja nadal działa
return view('users.show', compact('user'));
}
Typy komunikatów są oznaczone kolorami w interfejsie:
Debugbar::info($zmienna); // Informacja
Debugbar::error($zmienna); // Błąd
Debugbar::warning($zmienna); // Ostrzeżenie
Debugbar::addMessage($zmienna, 'debug'); // Debug
Możesz też logować tablice, kolekcje i obiekty:
$users = User::with('posts')->get();
Debugbar::info($users);
Zagnieżdżone struktury można rozwijać w pasku.
Pomiar wydajności z Debugbar::startMeasure()
Debugbar mierzy też czas wykonania wybranych bloków kodu:
Debugbar::startMeasure('render', 'Czas renderowania widoku');
// Jakiś złożony kod, który chcemy zmierzyć
$view = view('complex.view', $data)->render();
Debugbar::stopMeasure('render');
Pomiary można zagnieżdżać, żeby zlokalizować wolne fragmenty:
Debugbar::startMeasure('total', 'Całkowity czas przetwarzania');
Debugbar::startMeasure('database', 'Operacje bazodanowe');
$posts = Post::with('comments', 'author', 'categories')->get();
Debugbar::stopMeasure('database');
Debugbar::startMeasure('transform', 'Transformacja danych');
$transformedData = $this->transformService->transformPosts($posts);
Debugbar::stopMeasure('transform');
Debugbar::startMeasure('render', 'Renderowanie widoku');
$view = view('posts.index', compact('transformedData'))->render();
Debugbar::stopMeasure('render');
Debugbar::stopMeasure('total');
return $view;
Śledzenie zapytań SQL
Laravel Debugbar automatycznie śledzi wszystkie zapytania SQL wykonywane podczas przetwarzania żądania. Własne komunikaty dodasz do zakładki Messages, żeby oznaczyć miejsce zdarzenia:
// Zapytania są zbierane automatycznie; komunikat oznacza miejsce na osi czasu
Debugbar::info('Pobieranie aktywnych użytkowników');
$activeUsers = User::where('status', 'active')->get();
Debugbar pokazuje nie tylko same zapytania, ale także ich czas wykonania, parametry oraz lokalizację w kodzie, z której zostały wywołane.
Debugowanie API i Ajax
Debugbar wstrzykuje się w odpowiedzi HTML; żądania Ajax i JSON są przechwytywane, gdy włączone jest capture_ajax (domyślnie w wersji 4):
// W pliku konfiguracyjnym config/debugbar.php:
'capture_ajax' => env('DEBUGBAR_CAPTURE_AJAX', true),
Dla żądań API działają te same helpery:
public function apiEndpoint()
{
$data = $this->processData();
// Logowanie API
Debugbar::debug('API wywołane z parametrami: ' . json_encode(request()->all()));
// Dodaj dane do osobnej zakładki w Debugbar
Debugbar::addMessage($data, 'api_data');
return response()->json($data);
}
Żądania Ajax wysyłane ze strony wyglądają tak:
// Odpowiedzi Ajax są przechwytywane automatycznie, gdy capture_ajax jest włączone:
// żądanie pojawia się w selektorze żądań w pasku
$.ajax({
url: '/api/data',
success: function (data) {
console.log(data);
}
});
Niestandardowe kolekcje danych
Własną zakładkę w pasku dodasz przez niestandardowy kolektor danych:
use DebugBar\DataCollector\DataCollector;
use DebugBar\DataCollector\Renderable;
class MyCustomCollector extends DataCollector implements Renderable
{
protected $data = [];
public function addData($key, $value)
{
$this->data[$key] = $value;
}
public function collect(): array
{
return $this->data;
}
public function getName(): string
{
return 'custom';
}
public function getWidgets(): array
{
return [
"custom" => [
"icon" => "cubes",
"widget" => "PhpDebugBar.Widgets.VariableListWidget",
"map" => "custom",
"default" => "{}"
]
];
}
}
// Rejestracja kolektora
$customCollector = new MyCustomCollector();
Debugbar::addCollector($customCollector);
// Dodawanie danych
$customCollector->addData('key1', 'value1');
$customCollector->addData('key2', ['nested' => 'array']);
Debugowanie w testach
Debugbar działa też w testach, np. gdy trzeba sprawdzić, czemu któryś jest wolny:
public function testSlowOperation()
{
Debugbar::enable(); // Włącz Debugbar w tym teście
Debugbar::startMeasure('slow_test', 'Wolny test');
// Kod testu
$result = $this->service->performComplexOperation();
Debugbar::stopMeasure('slow_test');
// Zapisz raport debugowania do pliku
$debugbarData = Debugbar::getData();
file_put_contents(
storage_path('logs/test_debug_' . time() . '.json'),
json_encode($debugbarData)
);
$this->assertTrue($result);
}
Praktyczne przykłady
Przykład 1: Debugowanie problemów z zapytaniami N+1
public function index()
{
Debugbar::startMeasure('posts_query', 'Pobieranie postów');
// Problem N+1 zapytań
$posts = Post::all();
Debugbar::info('Liczba postów: ' . count($posts));
Debugbar::stopMeasure('posts_query');
foreach ($posts as $post) {
// Każde z tych wywołań wygeneruje dodatkowe zapytanie - Debugbar pokaże je wszystkie
$post->author->name;
}
// Rozwiązanie
Debugbar::startMeasure('posts_eager', 'Pobieranie postów z eager loadingiem');
$optimizedPosts = Post::with('author')->get();
Debugbar::stopMeasure('posts_eager');
return view('posts.index', compact('optimizedPosts'));
}
Przykład 2: Debugowanie użycia pamięci
public function processLargeDataset()
{
Debugbar::startMeasure('memory_test', 'Test użycia pamięci');
$initialMemory = memory_get_usage();
Debugbar::info('Początkowe użycie pamięci: ' . $this->formatBytes($initialMemory));
// Operacja intensywnie wykorzystująca pamięć
$data = $this->largeDataService->processData();
$afterMemory = memory_get_usage();
Debugbar::info('Końcowe użycie pamięci: ' . $this->formatBytes($afterMemory));
Debugbar::info('Różnica: ' . $this->formatBytes($afterMemory - $initialMemory));
Debugbar::stopMeasure('memory_test');
return response()->json(['status' => 'completed']);
}
private function formatBytes($bytes, $precision = 2)
{
$units = ['B', 'KB', 'MB', 'GB', 'TB'];
$bytes = max($bytes, 0);
$pow = floor(($bytes ? log($bytes) : 0) / log(1024));
$pow = min($pow, count($units) - 1);
$bytes /= (1 << (10 * $pow));
return round($bytes, $precision) . ' ' . $units[$pow];
}
Przykład 3: Debugowanie procesów wielowątkowych
public function runQueue()
{
Debugbar::startMeasure('queue_process', 'Przetwarzanie kolejki');
dispatch(function () {
// To nie będzie widoczne w Debugbar, ponieważ działa w osobnym procesie workera kolejki (kolejki, nie wątki)
logger('Zadanie rozpoczęte');
});
// Rozwiązanie: zapisz ID zadania i monitoruj jego status
$jobId = Str::uuid();
Debugbar::info('Zadanie o ID: ' . $jobId . ' zostało dodane do kolejki');
dispatch(function () use ($jobId) {
cache()->put('job_status_' . $jobId, 'running', now()->addMinutes(5));
// Przetwarzanie
cache()->put('job_status_' . $jobId, 'completed', now()->addMinutes(5));
});
// W prawdziwej aplikacji użylibyśmy AJAX do sprawdzania statusu
Debugbar::info('Status zadania można sprawdzić przez cache()->get("job_status_' . $jobId . '")');
Debugbar::stopMeasure('queue_process');
return response()->json(['job_id' => $jobId]);
}
Podsumowanie
Instaluj z --dev, włączaj tylko w local i zacznij od zakładki zapytań oraz startMeasure().