Zstd Extension for PHP

This extension allows Zstandard.

Documentation for Zstandard can be found at » https://github.com/facebook/zstd.

Build from sources

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

To use the system library

% ./configure --with-libzstd

minimum system libzstd library version to 1.4.0

Install from pecl:

% pecl install zstd

Distribution binary packages

Fedora

Fedora users can install the » php-zstd package from official repository.

dnf install php-zstd

CentOS / RHEL

CentOS / RHEL (and other clones) users can install the » php-zstd package from » EPEL repository.

yum install php-zstd

Other RPM packages of this extension, for other PHP versions, are available in » Remi's RPM repository.

Configration

php.ini:

extension=zstd.so

Output handler option

Name	Default	Changeable
zstd.output_compression	0	PHP_INI_ALL
zstd.output_compression_level	3	PHP_INI_ALL
zstd.output_compression_dict	""	PHP_INI_ALL

• zstd.output_compression boolean/integer

  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: zstd" header. "Content-Encoding: zstd" and "Vary: Accept-Encoding" headers are added to the output. In runtime, it can be set only before sending any output.

• zstd.output_compression_level integer

  Compression level used for transparent output compression. Specify a value between 1 to 22. The default value of ZSTD_COMPRESS_LEVEL_DEFAULT (3).

• zstd.output_compression_dict string

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

Constant

Name	Description
ZSTD_COMPRESS_LEVEL_MIN	Minimal compress level value
ZSTD_COMPRESS_LEVEL_MAX	Maximal compress level value
ZSTD_COMPRESS_LEVEL_DEFAULT	Default compress level value
ZSTD_VERSION_NUMBER	libzstd version number
ZSTD_VERSION_TEXT	libzstd version string

Function

• zstd_compress — Zstandard compression
• zstd_uncompress — Zstandard decompression
• zstd_compress_dict — Zstandard compression using a digested dictionary
• zstd_uncompress_dict — Zstandard decompression using a digested dictionary
• zstd_compress_init — Initialize an incremental compress context
• zstd_compress_add — Incrementally compress data
• zstd_uncompress_init — Initialize an incremental uncompress context
• zstd_uncompress_add — Incrementally uncompress data

---

zstd_compress — Zstandard compression

Description

zstd_compress ( string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null ): string|false

Zstandard compression.

Parameters

• data

  The string to compress.

• level

  The level of compression (e.g. 1-22). (Defaults to ZSTD_COMPRESS_LEVEL_DEFAULT)

  A value smaller than 0 means a faster compression level. (Zstandard library 1.3.4 or later)

• dict

  The Dictionary data.

Return Values

Returns the compressed data or FALSE if an error occurred.

---

zstd_uncompress — Zstandard decompression

Description

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

Zstandard decompression.

Alias: zstd_decompress

Parameters

• data

  The compressed string.

• dict

  The Dictionary data.

Return Values

Returns the decompressed data or FALSE if an error occurred.

---

zstd_compress_dict — Zstandard compression using a digested dictionary

deprecated: use zstd_compress() insted

Description

zstd_compress_dict ( string $data , string $dict, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): string|false

Zstandard compression using a digested dictionary.

Alias: zstd_compress_usingcdict

Parameters

• data

  The string to compress.

• dict

  The Dictionary data.

• level

  The level of compression (e.g. 1-22). (Defaults to ZSTD_COMPRESS_LEVEL_DEFAULT)

Return Values

Returns the compressed data or FALSE if an error occurred.

---

zstd_uncompress_dict — Zstandard decompression using a digested dictionary

deprecated: use zstd_uncompress() insted

Description

zstd_uncompress_dict ( string $data , string $dict ): string|false

Zstandard decompression using a digested dictionary.

Alias: zstd_decompress_dict, zstd_uncompress_usingcdict, zstd_decompress_usingcdict

Parameters

• data

  The compressed string.

• dict

  The Dictionary data.

Return Values

Returns the decompressed data or FALSE if an error occurred.

---

zstd_compress_init — Initialize an incremental compress context

Description

zstd_compress_init ( int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null ): Zstd\Compress\Context|false

Initialize an incremental compress context

Parameters

• level

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

• dict

  The Dictionary data.

Return Values

Returns a zstd context instance on success, or FALSE on failure

---

zstd_compress_add — Incrementally compress data

Description

zstd_compress_add ( Zstd\Compress\Context $context, string $data, bool $end = false ): string|false

Incrementally compress data

Parameters

• context

  A context created with zstd_compress_init().

• data

  A chunk of data to compress.

• end

  Set to true to terminate with the last chunk of data.

Return Values

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

---

zstd_uncompress_init — Initialize an incremental uncompress context

Description

zstd_uncompress_init ( ?string $dict = null ): Zstd\UnCompress\Context|false

Initialize an incremental uncompress context

Parameters

• dict

  The Dictionary data.

Return Values

Returns a zstd context instance on success, or FALSE on failure

---

zstd_uncompress_add — Incrementally uncompress data

Description

zstd_uncompress_add ( Zstd\UnCompress\Context $context, string $data ): string|false

Incrementally uncompress data

Parameters

• context

  A context created with zstd_uncompress_init().

• data

  A chunk of compressed data.

Return Values

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

Namespace

Namespace Zstd;

function compress( string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): string|false {}
function uncompress( string $data ): string|false {}
function compress_dict ( string $data, string $dict, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): string|false {}
function uncompress_dict ( string $data, string $dict ): string|false {}
function compress_init ( int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): \Zstd\Compress\Context|false {}
function compress_add ( \Zstd\Compress\Context $context, string $data, bool $end = false ): string|false {}
function uncompress_init (): \Zstd\UnCompress\Context|false {}
function uncompress_add ( \Zstd\UnCompress\Context $context, string $data ): string|false

zstd_compress, zstd_uncompress, zstd_compress_dict, zstd_uncompress_dict, zstd_compress_init, zstd_compress_add, zstd_uncompress_init and zstd_uncompress_add function aliases.

Streams

Zstd compression and decompression are available using the compress.zstd:// stream prefix.

Output handler

ini_set('zstd.output_compression', 'On');
// OR
// ob_start('ob_zstd_handler');

echo ...;

"Accept-Encoding: zstd" must be specified.

Examples

// Using functions
$data = zstd_compress('test');
zstd_uncompress($data);

// Using namespaced functions
$data = \Zstd\compress('test');
\Zstd\uncompress($data);

// Using streams
file_put_contents("compress.zstd:///path/to/data.zstd", $data);
readfile("compress.zstd:///path/to/data.zstd");

// Providing level of compression, when using streams 
$context = stream_context_create([
    'zstd' => [
            'level' => ZSTD_COMPRESS_LEVEL_MIN,
            // 'dict' => $dict,
        ],
    ],
);

file_put_contents("compress.zstd:///path/to/data.zstd", $data, context: $context);
readfile("compress.zstd:///path/to/data.zstd", context: $context);