README

Nova Debug DevTools 브라우저 확장의 서버측 레퍼런스 구현입니다. 요청 단위로 쿼리·덤프·트레이스·타임라인을 수집해 프레임워크 중립 디버그 페이로드 스키마 v1 JSON을 생산합니다.

브라우저 확장 연동(헤더 협상 + 조회 endpoint) 및 인페이지 폴백 렌더링(debug.js) 지원
쿼리 분석: EXPLAIN(드라이버 주입), SLOW/DUP/LOOP 감지, 테이블별 집계
특정 프레임워크에 의존하지 않음 — 프레임워크 연동 지점은 전부 Debug::configure() 로 주입

페이로드 스키마 스펙은 확장 저장소의 SCHEMA.md를 참고하세요.

설치

Composer

composer require daddyofsky/nova-debug

소스 복사 (composer 미사용)

autoload.php + src/ + assets/ 세 개만 프로젝트 안 원하는 위치에 복사한 뒤 autoload.php 하나만 require 하면 됩니다 (상대 배치 유지 필수).

your-app/lib/nova-debug/
  autoload.php
  src/
  assets/

require_once '/path/to/nova-debug/autoload.php';

빠른 시작

use Nova\Debug\Debug;
use Nova\Debug\Drivers\PDOQueryDriver;

Debug::configure([
    'rootPath'    => __DIR__,                                // 경로 상대화 기준
    'allowedIps'  => ['127.0.0.1'],                          // 필수 — 미설정 시 모든 접근 차단
    'queryDriver' => static fn() => new PDOQueryDriver($pdo), // EXPLAIN 분석용 (선택)
]);
Debug::initExtension(); // 브라우저 확장 헤더 협상 (헤더 전송 전 조기 호출)

// 수집
Debug::output($value, 'label');                       // 덤프
Debug::output($sql, 'QUERY [S]', ['term' => 0.0021]); // 쿼리 (label이 QUERY로 시작 + 소요시간)

// 요청 종료 시 출력 (인페이지 폴백 / 로그 / 확장용 JSON 저장을 모드에 따라 자동 처리)
register_shutdown_function([Debug::class, 'debugOutputHandler']);

타임라인은 Debug::setTimestamps(['START' => $t0, 'ROUTE' => $t1, ..., 'END' => $tn]) 으로 전달합니다.

브라우저 확장 연동

서버는 두 가지를 제공하면 됩니다. 이 라이브러리가 둘 다 구현합니다.

헤더 협상 — 요청 헤더 X-Nova-Debug(값 = 토큰) 검증 후 디버그 JSON을 저장하고 응답 헤더 X-Nova-Debug-Id 로 식별자 반환 (Debug::initExtension() + debugOutputHandler())
조회 endpoint — 식별자로 저장된 JSON(스키마 v1) 반환 (assets/log.php)

조회 endpoint 는 두 방식 중 하나로 노출합니다.

// 방식 A — 앱 endpoint 에서 설정 후 위임 (권장)
Debug::configure([...]);              // 앱 부트스트랩과 동일 설정
require '/path/to/nova-debug/assets/log.php';

방식 B — assets/ 를 웹 접근 가능한 경로에 drop-in 배치하면 log.php 가 관례 경로 (상위 3단계/Debug.php)에서 부트스트랩을 자체 탐색합니다.

프레임워크 연동 지점

전부 선택 사항이며 Debug::configure() 로 주입합니다.

키	용도
`queryDriver`	`AbstractQueryDriver` 인스턴스 또는 lazy Closure — EXPLAIN 실행 (PDO/Mysqli/CI3 제공, 미설정 시 EXPLAIN 없이 동작)
`ajaxDetector`	AJAX 판별 Closure (기본: `X-Requested-With` 헤더)
`controllerNameResolver`	로그 파일명용 컨트롤러명 Closure (기본: URL 경로 기반)
`timestamps`	타임라인 구간 타임스탬프 배열

주요 설정

키	기본값	설명
`enabled`	`true`	전체 on/off
`allowedIps`	`[]`	허용 IP 배열 또는 정규식 문자열. 비어 있으면 전부 차단
`query.slowTime`	`0.01`	SLOW 쿼리 임계값(초)
`dump.maxLength`	`8192`	덤프 길이 제한
`log.dir`	`tmp`	로그/확장 JSON 저장 디렉터리 (rootPath 기준)
`ext.tokens`	`[]`	확장 토큰 목록 `[['token' => '...', 'ip' => '...']]` — 설정 시 검증 필수화
`ext.only`	`false`	`true` 면 인페이지 폴백 렌더링 완전 비활성
`ide.protocol` 등	`phpstorm`	트레이스 IDE 딥링크

전체 키 목록과 기본값은 src/Debug.php의 $config 를 참고하세요.

테스트

phpunit --configuration phpunit.xml

License

MIT

daddyofsky / nova-debug

Maintainers

Package info

Statistics

Security