PHP에서 header() 함수로 응답 헤더를 설정하려다가 'headers already sent' 오류를 본 개발자라면, echo나 print 전에 header()를 호출해야 한다는 정도는 알고 있을 것이다. 다만 많은 개발자들은 이미 화면에 무언가 출력된 상황에서도 동적으로 헤더를 제어하고 싶을 때 어떻게 해야 하는지 모른 채 출력 순서를 뒤바꾸거나 구조를 뒤집곤 한다.
이번에는 PHP 출력 버퍼링(Output Buffering) 메커니즘이 정확히 뭔지, ob_start()부터 ob_get_clean()까지 어떻게 동작하는지, 그리고 실무에서 캐싱과 템플릿 엔진 구현까지 어떻게 활용하는지 완벽하게 정리해서 소개하겠다.
보통 PHP 코드에서 echo나 print로 출력하면 바로 클라이언트 브라우저로 전송된다. 그런데 이 동작을 잠시 멈추고 메모리에 모아뒀다가 나중에 한 번에 전송하는 것이 출력 버퍼링이다.
<?php
// 버퍼링 없이: 바로 출력
echo "안녕"; // 즉시 브라우저로 전송됨
header("X-Custom: value"); // 오류: headers already sent
// 버퍼링 사용: 메모리에 먼저 저장
ob_start();
echo "안녕"; // 메모리 버퍼에 저장
header("X-Custom: value"); // 정상 작동(아직 헤더 송신 안 됨)
ob_end_flush(); // 최종적으로 브라우저에 전송
?>
이해하기 쉽게 설명하면, ob_start()를 호출한 순간 PHP는 카메라 녹화를 시작하고, ob_end_flush()를 호출할 때까지의 모든 출력을 메모리에 보관한다. 그 사이에 header() 함수를 몇 번 호출하든 상관없다. 왜냐하면 아직 HTTP 헤더가 클라이언트로 전송되지 않았기 때문이다.
출력 버퍼링 관련 주요 함수들의 역할을 정확히 알아야 실무에서 실수하지 않는다.
| 함수 | 역할 | 반환값 |
|---|---|---|
| ob_start() | 출력 버퍼링 시작 | true |
| ob_get_contents() | 현재 버퍼 내용 조회(제거 안 함) | 문자열 |
| ob_get_clean() | 버퍼 내용 조회 후 폐기 | 문자열 |
| ob_end_clean() | 버퍼 폐기(출력 안 함) | true |
| ob_end_flush() | 버퍼 내용 출력 후 폐기 | true |
| ob_get_level() | 활성 버퍼 단계(중첩된 경우) | 정수 |
실무에서 가장 흔한 경우는 템플릿을 렌더링한 후에야 Content-Type이나 Cache-Control 헤더를 결정해야 하는 상황이다.
<?php
// ✗ 잘못된 코드: 템플릿 경로에 따라 Content-Type이 결정되는데
// header()를 먼저 호출할 수 없음
header("Content-Type: text/html; charset=utf-8");
include($template); // 이 파일이 실제로는 JSON을 반환할 수도
// ✓ 올바른 코드: 출력 버퍼링으로 먼저 템플릿 렌더링
ob_start();
include($template);
$output = ob_get_clean();
// 이제 콘텐츠를 보고 헤더 결정 가능
if (json_decode($output)) {
header("Content-Type: application/json");
} else {
header("Content-Type: text/html; charset=utf-8");
}
echo $output;
?>
이 패턴은 프레임워크나 CMS에서 매우 자주 쓰인다. 템플릿 렌더링이 완료될 때까지 응답 헤더를 미루는 전략이기 때문이다.
정적 컨텐츠가 많은 페이지의 경우, ob_get_clean()으로 렌더링된 HTML을 파일이나 Redis에 저장하면 다음 요청부터 디비 쿼리를 실행할 필요가 없다.
<?php
$cache_key = 'page_' . md5($_SERVER['REQUEST_URI']);
$cached = apcu_fetch($cache_key); // APCu 캐시 확인
if ($cached) {
echo $cached;
exit;
}
ob_start();
?>
<!-- 비용이 큰 쿼리와 템플릿 렌더링 -->
<?php
foreach (get_expensive_data() as $item):
?>
<div><?php echo htmlspecialchars($item['title']); ?></div>
<?php
endforeach;
?>
<?php
$output = ob_get_clean();
// 10분간 캐시 저장
apcu_store($cache_key, $output, 600);
echo $output;
?>
ob_get_clean()은 버퍼를 폐기하면서 동시에 내용을 반환하므로, 캐시에 저장한 후 다시 echo하는 패턴에 최적이다.
많은 소규모 프로젝트에서는 Twig나 Blade 같은 고수준 템플릿 엔진 없이 기본 include()로 템플릿을 로드한다. 이 경우 출력 버퍼링으로 변수 격리와 재사용성을 높일 수 있다.
<?php
class SimpleTemplate {
private $vars = [];
public function assign($key, $value) {
$this->vars[$key] = $value;
}
public function render($template_file) {
// 템플릿 파일의 변수 격리
extract($this->vars, EXTR_PREFIX_ALL, 'tpl');
ob_start();
include $template_file;
return ob_get_clean();
}
}
// 사용 예
$tpl = new SimpleTemplate();
$tpl->assign('title', '안녕하세요');
$tpl->assign('items', ['A', 'B', 'C']);
echo $tpl->render('page.php');
?>
템플릿 파일(page.php):
<h1><?php echo htmlspecialchars($tpl_title); ?></h1>
<ul>
<?php foreach ($tpl_items as $item): ?>
<li><?php echo htmlspecialchars($item); ?></li>
<?php endforeach; ?>
</ul>
이 방식은 전역 변수 오염을 방지하고, 템플릿 로직과 비즈니스 로직을 분리하는 효과가 있다.
✗ 실수 1: ob_end_flush() 호출 잊음
<?php
ob_start();
echo "내용이 많습니다";
// ob_end_flush() 호출 없음
// 결과: 버퍼가 메모리에만 있고, 브라우저에 아무것도 안 나타남
?>
PHP 스크립트가 정상 종료되면 자동으로 플러시되긴 하지만, 명시적으로 호출하는 것이 안전하다.
✓ 올바른 방법
<?php
ob_start();
echo "내용";
ob_end_flush(); // 또는 echo ob_get_clean();
?>
✗ 실수 2: header() 호출 후에 ob_start()
<?php
header("X-Custom: value"); // 이미 헤더 송신됨
ob_start(); // 이제는 너무 늦음
echo "다른 헤더 필요";
?>
ob_start()는 반드시 모든 출력과 header() 호출 전에 맨 처음에 실행해야 한다.
✗ 실수 3: 중첩된 ob_start() 관리 누락
<?php
ob_start(); // 레벨 1
echo "외부";
ob_start(); // 레벨 2
echo "내부";
$inner = ob_get_clean(); // 레벨 2 폐기
echo $inner; // 이것도 레벨 1 버퍼에 저장됨
$output = ob_get_clean(); // 레벨 1 폐기
echo $output;
?>
중첩된 ob_start()를 사용할 때는 ob_get_level()로 현재 단계를 확인하고 각각을 올바르게 정리해야 한다.
✓ 안전한 방법
<?php
while (ob_get_level()) {
ob_end_clean(); // 모든 버퍼 제거
}
ob_start(); // 깨끗한 상태에서 시작
?>
ob_start()는 강력한 도구이지만, 대용량 페이지에서는 메모리 사용을 고려해야 한다. 버퍼에 저장된 내용이 클수록 메모리를 더 많이 차지한다.
<?php
// 메모리 절약: 큰 루프는 버퍼링하지 말고 직접 출력
echo <<<'HTML'
<html><body>
HTML;
foreach (range(1, 1000000) as $i) {
echo "<p>$i</p>";
}
echo <<<'HTML'
</body></html>
HTML;
?>
100MB 이상의 대용량 응답이 필요한 경우, ob_start() 대신 readfile()이나 스트리밍 기법을 써야 한다.
PHP의 출력 버퍼링은 구조적으로 깔끔한 코드를 만드는 데 필수 도구다. 헤더 제어, 캐싱, 템플릿 엔진 구현 등 실무에서 만나는 많은 문제가 ob_start() 한 줄로 간단히 해결된다는 점을 잊지 말자. 이 글의 '실전 예제' 섹션을 참고해 자신의 프로젝트 구조에 맞게 적용하면, 더 유지보수하기 쉽고 확장 가능한 시스템을 만들 수 있을 것이다.