PHP 개발에서 길고 복잡한 SQL 문을 다루는 것은 흔한 일입니다. Doctrine SQL 포매터(Doctrine SqlFormatter)는 가독성을 높이기 위해 SQL 코드를 구조화된 형식으로 변환하는 경량 라이브러리입니다. 디버깅, 로깅, 또는 팀 협업에 유용합니다.
SQL 포매터가 필요한 이유
포맷되지 않은 SQL은 유지보수와 디버깅을 어렵게 만듭니다:
- 중첩 쿼리와 다중 조인(Multi JOIN)에서 오류를 찾기 어려움
- 개발자마다 스타일이 달라 코드 일관성 부족
- 프로젝트 규모가 커질수록 유지보수 비용 증가
핵심 기능
스마트 포매팅 엔진
SQL 구문을 자동으로 인식하고 적절한 들여쓰기를 적용합니다:
$formatter = new SqlFormatter();
$formattedSQL = $formatter->format($complexQuery);자동 처리 요소:
- 키워드 자동 대문자 변환
- 서브쿼리 들여쓰기
- 테이블 조인 구분
- 조건문 계층 정리
다양한 출력 하이라이터
용도에 따라 세 가지 하이라이터를 제공합니다:
HTML 하이라이터 - 웹 페이지 표시용:
$highlighted = (new SqlFormatter())->highlight($sql);CLI 하이라이터 - 터미널 출력용:
$cliHighlighted = (new CliHighlighter())->format($sql);Null 하이라이터 - 순수 텍스트 로그용:
$plainFormatted = (new SqlFormatter(new NullHighlighter()))->format($sql);쿼리 압축
명령줄 실행 시 불필요한 공백과 줄바꿈을 제거합니다:
$compressed = $formatter->compress($sql);실제 사용 사례
복잡한 쿼리 디버깅
ORM이 생성한 복잡한 SQL을 분석할 때:
- 쿼리 논리 구조를 명확히 표시
- 구문 오류 위치를 빠르게 파악
- 서브쿼리 가독성 향상
로그 출력 최적화
오류 로그나 디버그 정보에 SQL을 포함할 때:
- NullHighlighter로 깔끔한 포맷 텍스트 사용
- HTML 태그로 인한 로그 오염 방지
- 쿼리 구조 유지
코드 리뷰 및 협업
통일된 SQL 포맷 표준을 적용하면:
- 코드 리뷰 시간 단축
- 팀 협업 효율 향상
- 코드 스타일 일관성 유지
설치 및 기본 사용법
Composer로 설치:
composer require doctrine/sql-formatter기본 사용:
require_once 'vendor/autoload.php';
use Doctrine\SqlFormatter\SqlFormatter;
$query = "SELECT count(*),Column1,Testing FROM Table1 WHERE...";
echo (new SqlFormatter())->format($query);고급 기능
사용자 정의 하이라이트 테마
색상 구성을 직접 정의할 수 있습니다:
$customHighlighter = new class extends Highlighter {
// 사용자 정의 색상 설정
};일괄 처리
여러 SQL 문을 포함한 스크립트에서:
- 각 쿼리를 자동 분할
- 개별 포매팅
- 전체 구조 일관성 유지
성능 팁
대량 SQL 처리 시 권장 사항:
- 프로덕션 환경에서는 자주 사용하는 쿼리를 미리 포맷
- 반복 SQL에는 캐시 활용
- 디버깅 및 표시 시에만 포매터 사용
다른 도구와 비교
| 기능 | SqlFormatter | 다른 도구 |
|---|---|---|
| 설치 복잡도 | 낮음 | 중~높음 |
| 커스터마이징 유연성 | 높음 | 중간 |
| 성능 부하 | 낮음 | 중~높음 |
| 커뮤니티 지원 | 활발함 | 보통 |
모범 사례
- 개발 단계: IDE에 통합해 실시간 포매팅
- 테스트 단계: 단위 테스트에서 SQL 형식 일관성 검증
- 프로덕션: 불필요한 성능 손실을 피하기 위해 선택적으로 사용
Doctrine SQL 포매터는 PHP 생태계에서 SQL 가독성 문제를 해결하는 성숙한 도구로, 팀 협업과 코드 유지보수에 큰 도움을 줍니다. 적절한 설정과 사용 시나리오 선택으로 복잡한 SQL 디버깅을 단순화할 수 있습니다.
프로젝트 저장소: https://gitcode.com/gh_mirrors/sqlfo/sql-formatter