Laravel Debugbar
barryvdh/laravel-debugbar
Laravel용 PHP Debugbar 통합 패키지
Laravel용 Debugbar
이 패키지는 PHP Debug Bar를 Laravel과 연동해 줍니다. 디버그바를 등록하고 응답 출력에 붙여 주는 서비스 프로바이더가 포함되어 있으며, 에셋 publish와 설정도 Laravel 방식으로 처리할 수 있습니다. Laravel에서 동작하도록 여러 Collector를 초기화하고, Laravel에 특화된 DataCollector도 몇 가지 직접 구현해 두었습니다. 리다이렉트와 Ajax/Livewire 요청도 표시하도록 설정되어 있으며, 이런 요청은 드롭다운으로 확인할 수 있습니다. 더 많은 설정 옵션은 공식 문서를 참고하세요.
CAUTION
Debugbar는 개발 환경에서만 사용하세요. 저장된 요청 정보가 노출되므로(설계상 그렇게 동작합니다) 외부에 공개된 웹사이트에서는 절대 사용하면 안 됩니다.
WARNING
데이터를 수집하고 렌더링해야 하므로 애플리케이션이 느려질 수도 있습니다. 느려졌다고 느껴지면 일부 Collector를 꺼 보세요.
이 패키지가 제공하는 커스텀 Collector는 다음과 같습니다.
- QueryCollector: 바인딩 값과 실행 시간을 포함한 모든 쿼리를 표시합니다.
- RouteCollector: 현재 라우트에 대한 정보를 표시합니다.
- ViewCollector: 현재 로드된 뷰를 표시합니다. (선택적으로 공유 데이터도 표시)
- EventsCollector: 발생한 모든 이벤트를 표시합니다.
- LaravelCollector: Laravel 버전과 환경(environment)을 표시합니다. (기본값은 비활성화)
- SymfonyRequestCollector: 기존 RequestCollector를 대체하여 요청/응답에 대한 더 많은 정보를 보여 줍니다.
- LogsCollector: storage 로그의 최근 항목을 표시합니다. (기본값은 비활성화)
- FilesCollector: PHP가 include/require 한 파일을 표시합니다. (기본값은 비활성화)
- ConfigCollector: 설정 파일의 값을 표시합니다. (기본값은 비활성화)
- CacheCollector: 모든 캐시 이벤트를 표시합니다. (기본값은 비활성화)
Laravel용으로 초기화되는 Collector는 다음과 같습니다.
- LogCollector: 모든 Log 메시지를 표시합니다.
- SymfonyMailCollector: 메일(Mail) 정보를 표시합니다.
그리고 기본 Collector는 다음과 같습니다.
- PhpInfoCollector
- MessagesCollector
- TimeDataCollector (부팅 시간과 애플리케이션 처리 시간 포함)
- MemoryCollector
- ExceptionsCollector
또한 메시지, 예외, 시간 측정을 간편하게 기록할 수 있는 파사드(Debugbar)도 제공합니다.
설치
Composer로 패키지를 설치합니다. 개발 환경에서만 필요하므로 --dev 옵션으로 설치하는 것을 권장합니다.
composer require fruitcake/laravel-debugbar --devNote: 패키지 이름이
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에서 확인하세요.
vendor 파일(FontAwesome, Highlight.js, jQuery)을 포함할지 여부도 설정할 수 있습니다. 이미 사이트에서 사용 중이라면 false로 지정하세요.
'js' 또는 'css'로 지정하면 JS나 CSS 중 한쪽만 표시할 수도 있습니다. (Highlight.js는 CSS와 JS가 모두 필요하므로 구문 강조를 쓰려면 true로 설정하세요.)
publish 명령으로 패키지 설정을 프로젝트로 복사하기:
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);
}자주 쓰는 호출은 헬퍼 함수로도 제공됩니다.
// All arguments will be dumped as a debug message
debug($var1, $someString, $intValue, $object);
// `$collection->debug()` will return the collection and dump it as a debug message. Like `$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'));
// Or via the App container:
$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::enable();
\Debugbar::disable();주의: 한 번 활성화되면 Collector가 추가되어(추가 오버헤드가 생길 수 있음) 동작합니다. 따라서 프로덕션에서 사용해야 한다면 설정에서는 비활성화해 두고 꼭 필요할 때만 켜세요.
Note: 기본적으로 Debugbar는 디버그 모드이면서 프로덕션이 아닌 환경에서만 활성화할 수 있습니다. 프로덕션에는 아예 설치하지 않는 것을 강력히 권장합니다. 정말로 프로덕션에서 켜야 한다면
debugbar.force_allow_enable을 true로 설정하거나.env에DEBUGBAR_FORCE_ALLOW_ENABLE=true를 지정하세요. 이 설정은 Debugbar를 활성화하는 것이 아니라 서비스 프로바이더의 부트스트랩을 실행해 주는 것이므로, 부팅 이후에 직접 enable 할 수 있게 됩니다.
저장소(Storage)
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" %}
…some things that gets timed
{% endstopwatch %}