Brotli Extension for PHP

This extension allows Brotli compression.

Documentation for Brotli can be found at » https://github.com/google/brotli/.

Build

% git clone --recursive --depth=1 https://github.com/kjdev/php-ext-brotli.git
% cd php-ext-brotli
% phpize
% ./configure
% make
$ make install

To use the system library (using pkg-config)

% ./configure --with-libbrotli

Distribution binary packages

Fedora / CentOS / RHEL

RPM packages of this extension are available in » Remi's RPM repository and are named php-brotli.

Configuration

php.ini:

extension=brotli.so

Output handler option

Name	Default	Changeable
brotli.output_compression	0	PHP_INI_ALL
brotli.output_compression_level	11	PHP_INI_ALL
brotli.output_compression_dict	""	PHP_INI_ALL

• brotli.output_compression boolean

  Whether to transparently compress pages. If this option is set to "On" in php.ini or the Apache configuration, pages are compressed if the browser sends an "Accept-Encoding: br" header. "Content-Encoding: br" and "Vary: Accept-Encoding" headers are added to the output. In runtime, it can be set only before sending any output.

• brotli.output_compression_level integer

  Compression level used for transparent output compression. Specify a value between 0 to 11. The default value of BROTLI_COMPRESS_LEVEL_DEFAULT (11).

• brotli.output_compression_dict string

  Specifies the path to the compressed dictionary file to be used by the output handler.

  can be used when BROTLI_DICTIONARY_SUPPORT is enabled

Constant

Name	Description
BROTLI_GENERIC	Generic compress mode value
BROTLI_TEXT	Text compress mode value
BROTLI_FONT	Font compress mode value
BROTLI_COMPRESS_LEVEL_MIN	Minimal compress level value
BROTLI_COMPRESS_LEVEL_MAX	Maximal compress level value
BROTLI_COMPRESS_LEVEL_DEFAULT	Default compress level value
BROTLI_PROCESS	Incremental process mode value
BROTLI_FLUSH	Incremental produce mode value
BROTLI_FINISH	Incremental finalize mode value
BROTLI_DICTIONARY_SUPPORT	Dictionary support value

BROTLI_DICTIONARY_SUPPORT must be enabled with brotli library version 1.1.0 or higher

dictionary only work from compression level 5 or higher note

Function

• brotli_compress — Compress a string
• brotli_uncompress — Uncompress a compressed string
• brotli_compress_init — Initialize an incremental compress context
• brotli_compress_add — Incrementally compress data
• brotli_uncompress_init — Initialize an incremental uncompress context
• brotli_uncompress_add — Incrementally uncompress data

---

brotli_compress — Compress a string

Description

brotli_compress ( string $data, int $level = BROTLI_COMPRESS_LEVEL_DEFAULT, int $mode = BROTLI_GENERIC, string|null $dict = null ): string|false

This function compress a string.

Parameters

• data

  The data to compress.

• level

  The higher the level, the slower the compression. (Defaults to BROTLI_COMPRESS_LEVEL_DEFAULT)

• mode

  The compression mode can be BROTLI_GENERIC (default), BROTLI_TEXT (for UTF-8 format text input) or BROTLI_FONT (for WOFF 2.0).

• dict

  The dictionary data.

  can be used when BROTLI_DICTIONARY_SUPPORT is enabled

Return Values

The compressed string or FALSE if an error occurred.

---

brotli_uncompress — Uncompress a compressed string

Description

brotli_uncompress ( string $data, string|null $dict = null ): string|false

This function uncompress a compressed string.

Parameters

• data

  The data compressed by brotli_compress().

• dict

  The dictionary data.

  can be used when BROTLI_DICTIONARY_SUPPORT is enabled

Return Values

The original uncompressed data or FALSE on error.

---

brotli_compress_init — Initialize an incremental compress context

Description

brotli_compress_init ( int $level = BROTLI_COMPRESS_LEVEL_DEFAULT, int $mode = BROTLI_GENERIC, string|null $dict = null ): Brotli\Compress\Context|false

Initialize an incremental compress context.

Parameters

• level

  The higher the level, the slower the compression. (Defaults to BROTLI_COMPRESS_LEVEL_DEFAULT)

• mode

  The compression mode can be BROTLI_GENERIC (default), BROTLI_TEXT (for UTF-8 format text input) or BROTLI_FONT (for WOFF 2.0).

• dict

  The dictionary data.

  can be used when BROTLI_DICTIONARY_SUPPORT is enabled

Return Values

Returns a Brotli\Compress\Context instance on success, or FALSE on failure.

---

brotli_compress_add — Incrementally compress data

Description

brotli_compress_add ( Brotli\Compress\Context $context, string $data, $mode = BROTLI\_FLUSH ): string|false

Incrementally compress data.

Parameters

• context

  A context created with brotli_compress_init().

• data

  A chunk of data to compress.

• mode

  One of BROTLI_FLUSH (default) and BROTLI_PROCESS, BROTLI_FINISH.

  BROTLI_FINISH to terminate with the last chunk of data.

Return Values

Returns a chunk of compressed data, or FALSE on failure.

---

brotli_uncompress_init — Initialize an incremental uncompress context

Description

brotli_uncompress_init ( string|null $dict = null ): Brotli\UnCompress\Context|false

Initialize an incremental uncompress context.

Parameters

• dict

  The dictionary data.

  can be used when BROTLI_DICTIONARY_SUPPORT is enabled

Return Values

Returns a Brotli\UnCompress\Context instance on success, or FALSE on failure.

---

brotli_uncompress_add — Incrementally uncompress data

Description

brotli_uncompress_add ( Brotli\UnCompress\Context $context, string $data, $mode = BROTLI\_FLUSH ): string|false

Incrementally uncompress data.

Parameters

• context

  A context created with brotli_uncompress_init().

• data

  A chunk of compressed data.

• mode

  One of BROTLI_FLUSH (default) and BROTLI_PROCESS, BROTLI_FINISH.

  BROTLI_FINISH to terminate with the last chunk of data.

Return Values

Returns a chunk of uncompressed data, or FALSE on failure.

Namespace

Namespace Brotli;

function compress( string $data, int $level = \BROTLI_COMPRESS_LEVEL_DEFAULT, int $mode = \BROTLI_GENERIC, string|null $dict = null ): string|false {}
function uncompress( string $data, string|null $dict = null ): string|false {}
function compress_init( int $level = \BROTLI_COMPRESS_LEVEL_DEFAULT, int $mode = \BROTLI_GENERIC, string|null $dict = null ): \Brotli\Compress\Context|false {}
function compress_add( \Brotli\Compress\Context $context, string $data, $mode = \BROTLI_FLUSH ): string|false {}
function uncompress_init(string|null $dict = null): \Brotli\UnCompress\Context|false {}
function uncompress_add( \Brotli\UnCompress\Context $context, string $data, int $mode = \BROTLI_FLUSH ): string|false {}

alias functions..

Streams

Brotli compression and uncompression are available using the compress.brotli:// stream prefix.

Examples

$compressed = brotli_compress('Compresstest');

$uncompressed = brotli_uncompress($compressed);

echo $uncompressed;

Output handler

ini_set('brotli.output_compression', 'On');
// OR
// ob_start('ob_brotli_handler');

echo ...;

"Accept-Encoding: br" must be specified.

Namespace

$data = \Brotli\compress('test');

\Brotli\uncompress($data);

Streams

file_put_contents("compress.brotli:///path/to/data.br", $data);
readfile("compress.brotli:///path/to/data.br");

Incrementally

// compression
$resource = brotli_compress_init();
$compressed = '';
$compressed .= brotli_compress_add($resource, 'Hello, ', BROTLI_FLUSH);
$compressed .= brotli_compress_add($resource, 'World!', BROTLI_FLUSH);
$compressed .= brotli_compress_add($resource, '', BROTLI_FINISH);

echo brotli_uncompress($compressed), PHP_EOL; // Hello, World!

// uncompression
$resource = brotli_uncompress_init();
$uncompressed = '';
$uncompressed .= brotli_uncompress_add($resource, substr($compressed, 0, 5), BROTLI_FLUSH);
$uncompressed .= brotli_uncompress_add($resource, substr($compressed, 5), BROTLI_FLUSH);
$uncompressed .= brotli_uncompress_add($resource, '', BROTLI_FINISH);

echo $uncompressed, PHP_EOL; // Hello, World!

Dictionary

$data = '..';

// load dictionary data
$dict = file_get_contents('data.dict');

// basic
$compressed = brotli_compress(data: $data, dict: $dict);
$uncompressed = brotli_uncompress(data: $compressed, dict: $dict);

// incrementally
$context = brotli_compress_init(dict: $dict);
$compressed = '';
$compressed .= brotli_compress_add($context, $data);
$compressed .= brotli_compress_add($context, '', BROTLI_FINISH);

$context = brotli_uncompress_init(dict: $dict);
$uncompressed = '';
$uncompressed .= brotli_uncompress_add($context, $compressed, BROTLI_FLUSH);
$uncompressed .= brotli_uncompress_add($context, '', BROTLI_FINISH);

// streams
$ctx = stream_context_create([
    'brotli' => [
        'dict' => $dict,
    ],
]);

file_put_contents('compress.brotli:///path/to/data.br', $data, 0, $ctx);

$uncompressed = file_get_contents('compress.brotli:///path/to/data.br', false, $ctx);

// output handler
ini_set('brotli.output_compression_dict', __DIR__ . '/data.dict');
ini_set('brotli.output_compression', 'On');
// OR: ob_start('ob_brotli_handler');
echo ...;

Experimental: Compression Dictionary Transport support

must be specified headers.

• Accept-Encoding: dcb
• Available-Dictionary: :<base64-hash>: