PHP ob_gzhandler() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Output Control

Definition

In PHP, ob_gzhandler() is a built-in callback for ob_start() that can gzip (or deflate) buffered output for clients that accept compressed pages.

You almost never call it yourself. Pass its name to ob_start('ob_gzhandler'). It needs the zlib extension. On many setups, zlib.output_compression is preferred over wiring this callback by hand.

Syntax

Call ob_gzhandler() with the values you need. Start with this line.

PHP
ob_start('ob_gzhandler');
CallWhat it does
ob_start('ob_gzhandler')Starts a buffer whose handler may compress output.
ob_list_handlers()Shows "ob_gzhandler" while that buffer is active.
ob_end_clean()Ends the gzhandler buffer without sending compressed output.

Do not mix ob_gzhandler() with zlib.output_compression. Compression depends on what the client says it accepts (for example via Accept-Encoding). On CLI there is usually no browser encoding header, so demos focus on registering the handler, not on binary gzip bytes.

Library declarations
PHP
ob_gzhandler(string $data, int $flags): string|false

Parameters

ParameterDescription
dataRequired. Buffer chunk passed by the output buffering engine when the handler runs.
flagsRequired. Bitmask from PHP (for example PHP_OUTPUT_HANDLER_START) describing why the handler was called.

Return Value

Return ValueDescription
string|falseCompressed (or encoded) output when appropriate, or false when compression cannot be used for that client.

PHP Examples

Example 1 — Register ob_gzhandler With ob_start

Start a buffer using ob_gzhandler as the callback, list the handler name, then end-clean.

PHP
<?php
$ok = ob_start('ob_gzhandler');
$handlers = ob_list_handlers();
ob_end_clean();
echo $ok ? "started" : "failed", PHP_EOL;
echo $handlers[0], PHP_EOL;

How It Works

  1. ob_start('ob_gzhandler') turns buffering on with that callback.
  2. ob_list_handlers() reports the active handler name.
  3. ob_end_clean() discards and ends the buffer for a quiet demo.
  4. The printed lines confirm the handler was registered.

Example 2 — Nest a Plain Buffer Outside Compression

Start a default buffer, then an ob_gzhandler buffer, and list both handlers.

PHP
<?php
ob_start();
ob_start('ob_gzhandler');
$handlers = ob_list_handlers();
ob_end_clean();
ob_end_clean();
echo implode(", ", $handlers), PHP_EOL;

How It Works

  1. The outer buffer uses the default output handler.
  2. The inner buffer uses ob_gzhandler.
  3. ob_list_handlers() lists handlers from outer to inner.
  4. Two end-clean calls remove both buffers.

Example 3 — Level While the Handler Is Active

Show that using ob_gzhandler still raises ob_get_level() like any other ob_start().

PHP
<?php
$before = ob_get_level();
ob_start('ob_gzhandler');
$during = ob_get_level();
ob_end_clean();
$after = ob_get_level();
echo $before, " -> ", $during, " -> ", $after, PHP_EOL;

How It Works

  1. The level starts at 0.
  2. Starting the gzhandler buffer makes the level 1.
  3. ob_end_clean() ends that buffer.
  4. The level returns to 0.

Frequently Asked Questions

It is an ob_start() callback that can compress buffered page output for browsers that accept gzip or deflate encoding.
Usually no. Pass 'ob_gzhandler' to ob_start(). PHP calls the handler when the buffer is flushed or ended.
The zlib extension. Without zlib, compression handlers are not available.
No. Do not combine them. Many hosts prefer zlib.output_compression instead of a manual ob_gzhandler buffer.
When the client does not accept compressed content, or compression cannot be applied, the handler can return false so PHP falls back to uncompressed output.

Next: ob_implicit_flush()

ob_implicit_flush() turns automatic flush() behavior on or off after output is produced.

ob_implicit_flush() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful