본문 바로가기
← 패키지 목록

Laravel Debugbar

fruitcake/laravel-debugbar

제출자 Laravel Korea Discovery Bot
최신 vv4.4.5라이센스 MIT배포 2026년 10월 31일
DevOps

Laravel용 PHP Debugbar 통합 패키지

GitHub

Laravel용 Debugbar

Unit Tests Packagist License Latest Stable Version Total Downloads Fruitcake

이 패키지는 PHP Debug Bar를 Laravel에 통합해 줍니다. 디버그바를 등록하고 응답 출력에 붙여 주는 서비스 프로바이더가 포함되어 있으며, 에셋 퍼블리시와 Laravel 설정을 통한 구성도 지원합니다. Laravel에서 동작하도록 여러 Collector를 초기화하고, Laravel에 특화된 몇 가지 커스텀 DataCollector도 구현하고 있습니다. 리다이렉트와 Ajax/Livewire 요청도 드롭다운으로 표시하도록 구성되어 있습니다. 더 많은 설정 옵션은 문서를 참고하세요.

Debugbar Dark Mode screenshot

CAUTION

DebugBar는 개발 환경에서만 사용하세요. 저장된 요청의 정보가 노출되므로(설계상 그렇습니다), 외부에 공개된 웹사이트에서는 절대 사용하지 마세요.

WARNING

데이터를 수집하고 렌더링해야 하므로 애플리케이션이 느려질 수도 있습니다. 느려진다고 느껴지면 일부 Collector를 비활성화해 보세요.

이 패키지에는 다음과 같은 커스텀 Collector가 포함되어 있습니다.

  • QueryCollector: 바인딩 값과 실행 시간을 포함한 모든 쿼리를 보여줍니다.
  • RouteCollector: 현재 라우트에 대한 정보를 보여줍니다.
  • ViewCollector: 현재 로드된 뷰를 보여줍니다. (선택적으로 공유 데이터도 표시)
  • EventsCollector: 발생한 모든 이벤트를 보여줍니다.
  • LaravelCollector: Laravel 버전과 환경을 보여줍니다. (기본값: 비활성화)
  • SymfonyRequestCollector: 기존 RequestCollector를 대체하여 요청/응답에 대한 더 자세한 정보를 보여줍니다.
  • LogsCollector: storage 로그의 최근 로그 항목을 보여줍니다. (기본값: 비활성화)
  • FilesCollector: PHP가 include/require한 파일을 보여줍니다. (기본값: 비활성화)
  • ConfigCollector: 설정 파일의 값을 보여줍니다. (기본값: 비활성화)
  • CacheCollector: 모든 캐시 이벤트를 보여줍니다. (기본값: 비활성화)

Laravel용으로 다음 Collector도 초기화합니다.

  • LogCollector: 모든 로그 메시지를 보여줍니다.
  • SymfonyMailCollector: 메일 정보를 보여줍니다.

그리고 기본 Collector는 다음과 같습니다.

  • PhpInfoCollector
  • MessagesCollector
  • TimeDataCollector (부팅 및 애플리케이션 실행 시간 포함)
  • MemoryCollector
  • ExceptionsCollector

또한 메시지, 예외, 시간을 손쉽게 기록할 수 있는 파사드 인터페이스(Debugbar)도 제공합니다.

설치

Composer로 패키지를 설치하세요. 개발 환경에서만 사용하도록 dev 의존성으로 설치하는 것을 권장합니다.

composer require fruitcake/laravel-debugbar --dev

Note: 패키지 이름이 fruitcake/laravel-debugbar로 바뀌었습니다. barryvdh/laravel-debugbar를 사용 중이라면 새 패키지 이름으로 안전하게 교체할 수 있습니다: composer remove barryvdh/laravel-debugbar --dev --no-scripts

Laravel은 패키지 자동 발견(Package Auto-Discovery)을 지원하므로 서비스 프로바이더를 직접 추가할 필요가 없습니다.

Debugbar는 APP_DEBUG가 true이고 환경이 production이나 testing이 아닐 때 활성화됩니다.

설정(debugbar.enabled)에서 비활성화하거나 .env에 DEBUGBAR_ENABLED를 지정할 수 있습니다. 더 많은 옵션은 config/debugbar.php에서 확인하세요. 벤더 파일(FontAwesome, Highlight.js, jQuery)을 포함할지 여부도 설정할 수 있습니다. 이미 사이트에서 사용 중이라면 false로 지정하세요. 'js' 또는 'css'로 지정하면 JS 또는 CSS 벤더 파일만 표시할 수도 있습니다. (Highlight.js는 CSS와 JS가 모두 필요하므로, 구문 강조를 사용하려면 true로 설정하세요.)

퍼블리시 명령으로 패키지 설정을 프로젝트에 복사하기

php artisan vendor:publish --provider='Fruitcake\\LaravelDebugbar\\ServiceProvider'

Octane 사용 시

Laravel Debugbar 4.x는 Octane에서 별도 설정 없이 바로 동작합니다. 설정에 아무것도 추가할 필요가 없습니다.

Laravel Debugbar 3.x에서 업그레이드하는 경우, config/octane.php에 있는 Debugbar용 'flush' 설정을 제거하세요.

사용법

이제 (파사드를 추가했다면) 파사드로 PSR-3 레벨(debug, info, notice, warning, error, critical, alert, emergency)에 맞춰 메시지를 추가할 수 있습니다.

Debugbar::info($object); Debugbar::error('Error!'); Debugbar::warning('Watch out…'); Debugbar::addMessage('Another message', 'mylabel');

시간 측정을 시작하고 종료할 수도 있습니다.

Debugbar::startMeasure('render','Time for rendering'); Debugbar::stopMeasure('render'); Debugbar::addMeasure('now', LARAVEL_START, microtime(true)); Debugbar::measure('My long operation', function() { // Do something… });

예외를 기록할 수도 있습니다.

try { throw new Exception('foobar'); } catch (Exception $e) { Debugbar::addThrowable($e); }

자주 쓰는 호출에는 헬퍼 함수도 준비되어 있습니다.

// 모든 인자가 디버그 메시지로 덤프됩니다 debug($var1, $someString, $intValue, $object); // `$collection->debug()`는 컬렉션을 반환하면서 디버그 메시지로 덤프합니다. `$collection->dump()`와 비슷합니다 collect([$var1, $someString])->debug(); debugbar()->startMeasure('render','Time for rendering'); debugbar()->stopMeasure('render'); debugbar()->addMeasure('now', LARAVEL_START, microtime(true)); debugbar()->measure('My long operation', function() { // Do something… });

원한다면 컨테이너나 파사드를 통해 직접 만든 DataCollector를 추가할 수 있습니다.

Debugbar::addCollector(new DebugBar\DataCollector\MessagesCollector('my_messages')); // 또는 App 컨테이너를 통해: $debugbar = App::make('debugbar'); $debugbar->addCollector(new DebugBar\DataCollector\MessagesCollector('my_messages'));

기본적으로 Debugbar는 </body> 바로 앞에 삽입됩니다. 직접 삽입하고 싶다면 설정의 'inject' 옵션을 false로 지정한 뒤, https://php-debugbar.com/docs/rendering 를 참고해 렌더러를 직접 사용하세요.

$renderer = Debugbar::getJavascriptRenderer();

참고: 자동 삽입을 사용하지 않으면, 요청 정보가 응답 이후에 추가되기 때문에 Request 정보가 표시되지 않습니다. 대안으로 설정에 default_request 데이터 컬렉터를 추가할 수 있습니다.

실행 중 활성화/비활성화

실행 중에 Debugbar를 켜거나 끌 수 있습니다.

\Debugbar::enable(); \Debugbar::disable();

참고로 한 번 활성화되면 Collector가 추가되어 추가 오버헤드가 발생할 수 있습니다. 프로덕션에서 Debugbar를 사용해야 한다면 설정에서는 비활성화해 두고 필요할 때만 활성화하세요.

Note: 기본적으로 Debugbar는 디버그 모드이면서 프로덕션이 아닌 환경에서만 활성화할 수 있습니다. 프로덕션에는 아예 설치하지 않는 것을 강력히 권장합니다. 정말 프로덕션에서 활성화해야 한다면 debugbar.force_allow_enable을 true로 지정하거나 .env에 DEBUGBAR_FORCE_ALLOW_ENABLE=true를 설정하세요. 이 설정은 Debugbar를 활성화하는 것은 아니며, 서비스 프로바이더의 부트스트랩만 실행해 두어 부팅 이후에 직접 활성화할 수 있게 해 줍니다.

스토리지

Debugbar는 이전 요청을 기억하며, 오른쪽의 Browse 버튼으로 확인할 수 있습니다. 기본적으로는 localhost 또는 사설 네트워크(예: Docker/Sail, 사내 LAN)에서 온 요청에 대해서만 동작합니다. 이를 바꾸려면 debugbar.storage.open(또는 DEBUGBAR_OPEN_STORAGE)을 true/false로 지정하거나 콜백을 사용하세요. 로컬 개발 환경에서만 변경하세요. 그렇지 않으면 다른 사람이 이전 요청을 볼 수 있습니다. 일반적으로 Debugbar는 로컬에서만 사용하거나, 최소한 IP로 접근을 제한해야 합니다. 요청(Request) 객체를 받는 콜백을 전달하여 OpenHandler 스토리지에 대한 접근 여부를 직접 판단할 수도 있습니다.

Twig 연동

Laravel Debugbar에는 두 가지 Twig 확장이 포함되어 있습니다. 이 확장들은 rcrowe/TwigBridge 0.6.x에서 테스트되었습니다.

TwigBridge의 config/extensions.php에 다음 확장을 추가하세요. (또는 확장을 직접 등록해도 됩니다.)

'Fruitcake\LaravelDebugbar\Twig\Extension\Debug', 'Fruitcake\LaravelDebugbar\Twig\Extension\Dump', 'Fruitcake\LaravelDebugbar\Twig\Extension\Stopwatch',

Dump 확장은 dump 함수를 대체하여 DataFormatter로 변수를 출력합니다. Debug 확장은 debug() 함수를 추가하는데, 이 함수는 변수를 템플릿에 직접 출력하는 대신 Message Collector로 전달합니다. 인자를 덤프하며, 인자가 없으면 모든 컨텍스트 변수를 덤프합니다.

{{ debug() }} {{ debug(user, categories) }}

Stopwatch 확장은 Symfony/Silex Twigbridge에 있는 것과 비슷한 stopwatch 태그를 추가합니다.

{% stopwatch "foo" %} …시간을 측정할 코드 {% endstopwatch %}