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_exclude_types	""	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_exclude_types string

  The extension contains a built-in list of non-compressible MIME types. The list can be found in the phpinfo() output. If something is missing, more MIME types can be added with this ini setting.

  Comma-separated list of MIME types that should not be compressed by the transparent output handler.

  Supports exact MIME type matches and wildcard family matches. A wildcard entry must use the type/* form.

  Example (both of these are already in the built-in list):

  zstd.output_compression_exclude_types="video/*,application/pdf"

  This is useful for already-compressed binary formats where additional Zstd compression usually provides little benefit.

  A token prefixed with ! negates a match: it makes the extension compress that MIME type even if it is in the built-in exclusion list. Negation also supports exact matches and type/* wildcards. Since ! is a special character in php.ini, values that use it must be quoted.

  zstd.output_compression_exclude_types="!image/png"

  Within the same list, if a MIME type matches multiple tokens, the last matching token wins, regardless of whether it is positive or negative (the same precedence rule .gitignore uses). This allows patterns such as:

  zstd.output_compression_exclude_types="image/*,!image/png"

  which excludes all image/* types except image/png, since the negation is listed after the wildcard.

  Negation only applies within this setting: if it doesn't produce a definitive match for the current MIME type, the built-in list is still consulted. The built-in list's contents can be seen in the phpinfo() output.

• 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

NamespaceZstd;
functioncompress( string$data, int$level = ZSTD_COMPRESS_LEVEL_DEFAULT ): string|false {}
functionuncompress( string$data ): string|false {}
functioncompress_dict ( string$data, string$dict, int$level = ZSTD_COMPRESS_LEVEL_DEFAULT ): string|false {}
functionuncompress_dict ( string$data, string$dict ): string|false {}
functioncompress_init ( int$level = ZSTD_COMPRESS_LEVEL_DEFAULT ): \Zstd\Compress\Context|false {}
functioncompress_add ( \Zstd\Compress\Context$context, string$data, bool$end = false ): string|false {}
functionuncompress_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.

Experimental: Compression Dictionary Transport support

must be specified headers.

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

Examples

// Using functions$data = zstd_compress('test');
zstd_uncompress($data);
// Using namespaced functions$data = \Zstd\compress('test');
\Zstd\uncompress($data);
// Using streamsfile_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);