From cd8b88d574a1ab851734e9ec90da7234314461b6 Mon Sep 17 00:00:00 2001
From: kjdev <kjclev@gmail.com>
Date: Fri, 1 Aug 2025 10:22:55 +0900
Subject: [PATCH 1/5] feat: add dictionary parameter to compress and uncompress
 functions

---
 zstd.c | 46 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/zstd.c b/zstd.c
index 3f27a4b..d44191a 100644
--- a/zstd.c
+++ b/zstd.c
@@ -318,19 +318,23 @@ static php_zstd_context* php_zstd_output_handler_context_init(void)
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_zstd_compress, 0, 1, MAY_BE_STRING|MAY_BE_FALSE)
     ZEND_ARG_TYPE_INFO(0, data, IS_STRING, 0)
     ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, level, IS_LONG, 0, "ZSTD_COMPRESS_LEVEL_DEFAULT")
+    ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, dict, IS_STRING, 1, "null")
 #else
 ZEND_BEGIN_ARG_INFO_EX(arginfo_zstd_compress, 0, 0, 1)
     ZEND_ARG_INFO(0, data)
     ZEND_ARG_INFO(0, level)
+    ZEND_ARG_INFO(0, dict)
 #endif
 ZEND_END_ARG_INFO()
 
 #if PHP_VERSION_ID >= 80000
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_zstd_uncompress, 0, 1, MAY_BE_STRING|MAY_BE_FALSE)
     ZEND_ARG_TYPE_INFO(0, data, IS_STRING, 0)
+    ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, dict, IS_STRING, 1, "null")
 #else
 ZEND_BEGIN_ARG_INFO_EX(arginfo_zstd_uncompress, 0, 0, 1)
     ZEND_ARG_INFO(0, data)
+    ZEND_ARG_INFO(0, dict)
 #endif
 ZEND_END_ARG_INFO()
 
@@ -362,9 +366,11 @@ ZEND_END_ARG_INFO()
 #if PHP_VERSION_ID >= 80000
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_zstd_compress_init, 0, 0, Zstd\\Compress\\Context, MAY_BE_FALSE)
     ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, level, IS_LONG, 0, "ZSTD_COMPRESS_LEVEL_DEFAULT")
+    ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, dict, IS_STRING, 1, "null")
 #else
 ZEND_BEGIN_ARG_INFO_EX(arginfo_zstd_compress_init, 0, 0, 0)
     ZEND_ARG_INFO(0, level)
+    ZEND_ARG_INFO(0, dict)
 #endif
 ZEND_END_ARG_INFO()
 
@@ -383,8 +389,10 @@ ZEND_END_ARG_INFO()
 
 #if PHP_VERSION_ID >= 80000
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_zstd_uncompress_init, 0, 0, Zstd\\UnCompress\\Context, MAY_BE_FALSE)
+    ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, dict, IS_STRING, 1, "null")
 #else
 ZEND_BEGIN_ARG_INFO_EX(arginfo_zstd_uncompress_init, 0, 0, 0)
+    ZEND_ARG_INFO(0, dict)
 #endif
 ZEND_END_ARG_INFO()
 
@@ -415,6 +423,10 @@ ZEND_END_ARG_INFO()
 ZEND_DECLARE_MODULE_GLOBALS(zstd);
 #endif
 
+#ifndef Z_PARAM_STR_OR_NULL
+#define Z_PARAM_STR_OR_NULL(dest) Z_PARAM_STR_EX(dest, 1, 0)
+#endif
+
 static size_t zstd_check_compress_level(zend_long level)
 {
     uint16_t maxLevel = (uint16_t) ZSTD_maxCLevel();
@@ -433,13 +445,14 @@ ZEND_FUNCTION(zstd_compress)
     size_t result;
     smart_string out = { 0 };
     zend_long level = ZSTD_CLEVEL_DEFAULT;
-    zend_string *input;
+    zend_string *input, *dict = NULL;
     php_zstd_context ctx;
 
-    ZEND_PARSE_PARAMETERS_START(1, 2)
+    ZEND_PARSE_PARAMETERS_START(1, 3)
         Z_PARAM_STR(input)
         Z_PARAM_OPTIONAL
         Z_PARAM_LONG(level)
+        Z_PARAM_STR_OR_NULL(dict)
     ZEND_PARSE_PARAMETERS_END_EX(RETURN_FALSE);
 
     if (!zstd_check_compress_level(level)) {
@@ -447,7 +460,7 @@ ZEND_FUNCTION(zstd_compress)
     }
 
     php_zstd_context_init(&ctx);
-    if (php_zstd_context_create_compress(&ctx, level, NULL) != SUCCESS) {
+    if (php_zstd_context_create_compress(&ctx, level, dict) != SUCCESS) {
         php_zstd_context_free(&ctx);
         RETURN_FALSE;
     }
@@ -480,11 +493,13 @@ ZEND_FUNCTION(zstd_uncompress)
     size_t chunk, result;
     uint64_t size;
     smart_string out = { 0 };
-    zend_string *input;
+    zend_string *input, *dict = NULL;
     php_zstd_context ctx;
 
-    ZEND_PARSE_PARAMETERS_START(1, 1)
+    ZEND_PARSE_PARAMETERS_START(1, 2)
         Z_PARAM_STR(input)
+        Z_PARAM_OPTIONAL
+        Z_PARAM_STR_OR_NULL(dict)
     ZEND_PARSE_PARAMETERS_END_EX(RETURN_FALSE);
 
     size = ZSTD_getFrameContentSize(ZSTR_VAL(input), ZSTR_LEN(input));
@@ -496,7 +511,7 @@ ZEND_FUNCTION(zstd_uncompress)
     }
 
     php_zstd_context_init(&ctx);
-    if (php_zstd_context_create_decompress(&ctx, NULL) != SUCCESS) {
+    if (php_zstd_context_create_decompress(&ctx, dict) != SUCCESS) {
         php_zstd_context_free(&ctx);
         RETURN_FALSE;
     }
@@ -547,6 +562,8 @@ ZEND_FUNCTION(zstd_compress_dict)
     zend_string *input, *dict;
     php_zstd_context ctx;
 
+    // php_error_docref(NULL, E_DEPRECATED, "Use zstd_compress() instead");
+
     ZEND_PARSE_PARAMETERS_START(2, 3)
         Z_PARAM_STR(input)
         Z_PARAM_STR(dict)
@@ -595,6 +612,8 @@ ZEND_FUNCTION(zstd_uncompress_dict)
     zend_string *input, *dict;
     php_zstd_context ctx;
 
+    // php_error_docref(NULL, E_DEPRECATED, "Use zstd_uncompress() instead");
+
     ZEND_PARSE_PARAMETERS_START(2, 2)
         Z_PARAM_STR(input)
         Z_PARAM_STR(dict)
@@ -657,10 +676,12 @@ ZEND_FUNCTION(zstd_uncompress_dict)
 ZEND_FUNCTION(zstd_compress_init)
 {
     zend_long level = ZSTD_CLEVEL_DEFAULT;
+    zend_string *dict = NULL;
 
-    ZEND_PARSE_PARAMETERS_START(0, 1)
+    ZEND_PARSE_PARAMETERS_START(0, 2)
         Z_PARAM_OPTIONAL
         Z_PARAM_LONG(level)
+        Z_PARAM_STR_OR_NULL(dict)
     ZEND_PARSE_PARAMETERS_END_EX(RETURN_FALSE);
 
     if (!zstd_check_compress_level(level)) {
@@ -669,7 +690,7 @@ ZEND_FUNCTION(zstd_compress_init)
 
     PHP_ZSTD_CONTEXT_OBJ_INIT_OF_CLASS(php_zstd_compress_context_ce);
 
-    if (php_zstd_context_create_compress(ctx, level, NULL) != SUCCESS) {
+    if (php_zstd_context_create_compress(ctx, level, dict) != SUCCESS) {
         zval_ptr_dtor(return_value);
         RETURN_FALSE;
     }
@@ -729,9 +750,16 @@ ZEND_FUNCTION(zstd_compress_add)
 
 ZEND_FUNCTION(zstd_uncompress_init)
 {
+    zend_string *dict = NULL;
+
+    ZEND_PARSE_PARAMETERS_START(0, 1)
+        Z_PARAM_OPTIONAL
+        Z_PARAM_STR_OR_NULL(dict)
+    ZEND_PARSE_PARAMETERS_END_EX(RETURN_FALSE);
+
     PHP_ZSTD_CONTEXT_OBJ_INIT_OF_CLASS(php_zstd_uncompress_context_ce);
 
-    if (php_zstd_context_create_decompress(ctx, NULL) != SUCCESS) {
+    if (php_zstd_context_create_decompress(ctx, dict) != SUCCESS) {
         zval_ptr_dtor(return_value);
         RETURN_FALSE;
     }

From 3dadf05a46024a2bbfd79fc6c11f3aa761a46243 Mon Sep 17 00:00:00 2001
From: kjdev <kjclev@gmail.com>
Date: Fri, 1 Aug 2025 10:26:17 +0900
Subject: [PATCH 2/5] test: update error message for zstd_uncompress to reflect
 correct argument expectation

---
 tests/005.phpt        | 2 +-
 tests/005_b.phpt      | 2 +-
 tests/named_args.phpt | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/005.phpt b/tests/005.phpt
index 81183dd..bd0ed5e 100644
--- a/tests/005.phpt
+++ b/tests/005.phpt
@@ -22,7 +22,7 @@ var_dump(zstd_uncompress($testclass));
 --EXPECTF--
 *** Testing zstd_uncompress() function with Zero arguments ***
 
-Warning: zstd_uncompress() expects exactly 1 parameter, 0 given in %s on line %d
+Warning: zstd_uncompress() expects at least 1 parameter, 0 given in %s on line %d
 bool(false)
 *** Testing with incorrect arguments ***
 
diff --git a/tests/005_b.phpt b/tests/005_b.phpt
index ade9ff8..b0de46e 100644
--- a/tests/005_b.phpt
+++ b/tests/005_b.phpt
@@ -33,7 +33,7 @@ try {
 ===DONE===
 --EXPECTF--
 *** Testing zstd_uncompress() function with Zero arguments ***
-ArgumentCountError: zstd_uncompress() expects exactly 1 argument, 0 given in %s:%d
+ArgumentCountError: zstd_uncompress() expects at least 1 argument, 0 given in %s:%d
 Stack trace:
 #0 %s(%d): zstd_uncompress()
 #1 {main}
diff --git a/tests/named_args.phpt b/tests/named_args.phpt
index 236043f..c4fd2e4 100644
--- a/tests/named_args.phpt
+++ b/tests/named_args.phpt
@@ -70,7 +70,7 @@ zstd_compress(): Argument #1 ($data) not passed
 string(6) "string"
 bool(true)
 ** zstd_uncompress(): false **
-zstd_uncompress() expects exactly 1 argument, 0 given
+zstd_uncompress() expects at least 1 argument, 0 given
 ** zstd_uncompress(data:) **
 string(6) "string"
 bool(true)

From 92ab1cc25c298b4783e2157a8a211e33bc43e915 Mon Sep 17 00:00:00 2001
From: kjdev <kjclev@gmail.com>
Date: Fri, 1 Aug 2025 10:28:21 +0900
Subject: [PATCH 3/5] chore: update test file permissions to non-executable

---
 tests/inc.phpt        | 0
 tests/inc_comp.phpt   | 0
 tests/inc_decomp.phpt | 0
 tests/inc_ns.phpt     | 0
 4 files changed, 0 insertions(+), 0 deletions(-)
 mode change 100755 => 100644 tests/inc.phpt
 mode change 100755 => 100644 tests/inc_comp.phpt
 mode change 100755 => 100644 tests/inc_decomp.phpt
 mode change 100755 => 100644 tests/inc_ns.phpt

diff --git a/tests/inc.phpt b/tests/inc.phpt
old mode 100755
new mode 100644
diff --git a/tests/inc_comp.phpt b/tests/inc_comp.phpt
old mode 100755
new mode 100644
diff --git a/tests/inc_decomp.phpt b/tests/inc_decomp.phpt
old mode 100755
new mode 100644
diff --git a/tests/inc_ns.phpt b/tests/inc_ns.phpt
old mode 100755
new mode 100644

From 34da37ffe1353e95a186835baebaa619307385b1 Mon Sep 17 00:00:00 2001
From: kjdev <kjclev@gmail.com>
Date: Fri, 1 Aug 2025 10:57:20 +0900
Subject: [PATCH 4/5] test: addn and update update dict arguments

---
 tests/dictionary_01_b.phpt | 74 ++++++++++++++++++++++++++++++++++++++
 tests/dictionary_b.phpt    | 28 +++++++++++++++
 tests/inc_dictionary.phpt  | 68 +++++++++++++++++++++++++++++++++++
 tests/inc_named_args.phpt  | 40 +++++++++++++++------
 tests/named_args.phpt      | 63 ++++++++++++++++++++++++++++++++
 5 files changed, 262 insertions(+), 11 deletions(-)
 create mode 100644 tests/dictionary_01_b.phpt
 create mode 100644 tests/dictionary_b.phpt
 create mode 100644 tests/inc_dictionary.phpt

diff --git a/tests/dictionary_01_b.phpt b/tests/dictionary_01_b.phpt
new file mode 100644
index 0000000..68fb395
--- /dev/null
+++ b/tests/dictionary_01_b.phpt
@@ -0,0 +1,74 @@
+--TEST--
+zstd_compress(): use dict compress level
+--FILE--
+<?php
+include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
+
+function check_compress($data, $dictionary, $level)
+{
+  $output = (string)zstd_compress($data, $level, $dictionary);
+  echo $level, ' -- ', strlen($dictionary), ' -- ', strlen($output), ' -- ',
+    var_export(zstd_uncompress($output, $dictionary) === $data, true), PHP_EOL;
+}
+
+echo "*** Data size ***", PHP_EOL;
+echo strlen($data), PHP_EOL;
+
+echo "*** Compression Level ***", PHP_EOL;
+for (
+  $level = ZSTD_COMPRESS_LEVEL_MIN;
+  $level <= ZSTD_COMPRESS_LEVEL_MAX;
+  $level++
+) {
+  check_compress($data, $dictionary, $level);
+}
+
+echo "*** Faster compression Level ***", PHP_EOL;
+for ($level = -1; $level >= -5; $level--) {
+  check_compress($data, $dictionary, $level);
+}
+
+echo "*** Invalid Compression Level ***", PHP_EOL;
+check_compress($data, $dictionary, 100);
+?>
+===Done===
+--EXPECTF--
+*** Data size ***
+3547
+*** Compression Level ***
+1 -- 142 -- 1%d -- true
+2 -- 142 -- 1%d -- true
+3 -- 142 -- 1%d -- true
+4 -- 142 -- 1%d -- true
+5 -- 142 -- 1%d -- true
+6 -- 142 -- 1%d -- true
+7 -- 142 -- 1%d -- true
+8 -- 142 -- 1%d -- true
+9 -- 142 -- 1%d -- true
+10 -- 142 -- 1%d -- true
+11 -- 142 -- 1%d -- true
+12 -- 142 -- 1%d -- true
+13 -- 142 -- 1%d -- true
+14 -- 142 -- 1%d -- true
+15 -- 142 -- 1%d -- true
+16 -- 142 -- 1%d -- true
+17 -- 142 -- 1%d -- true
+18 -- 142 -- 1%d -- true
+19 -- 142 -- 1%d -- true
+20 -- 142 -- 1%d -- true
+21 -- 142 -- 1%d -- true
+22 -- 142 -- 1%d -- true
+*** Faster compression Level ***
+-1 -- 142 -- %d -- true
+-2 -- 142 -- %d -- true
+-3 -- 142 -- %d -- true
+-4 -- 142 -- %d -- true
+-5 -- 142 -- %d -- true
+*** Invalid Compression Level ***
+
+Warning: zstd_compress(): compression level (100) must be within 1..22 or smaller then 0 in %s on line %d
+100 -- 142 -- 0 -- 
+Warning: zstd_uncompress(): it was not compressed by zstd in %s
+false
+===Done===
diff --git a/tests/dictionary_b.phpt b/tests/dictionary_b.phpt
new file mode 100644
index 0000000..2553d13
--- /dev/null
+++ b/tests/dictionary_b.phpt
@@ -0,0 +1,28 @@
+--TEST--
+zstd_compress(): use dict
+--SKIPIF--
+--FILE--
+<?php
+include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
+
+function check_compress_dict($data, $dictionary)
+{
+  $output = (string)zstd_compress($data, ZSTD_COMPRESS_LEVEL_DEFAULT, $dictionary);
+  echo strlen($dictionary), ' -- ', strlen($output), ' -- ',
+    var_export(zstd_uncompress($output, $dictionary) === $data, true), PHP_EOL;
+}
+
+echo "*** Data size ***", PHP_EOL;
+echo strlen($data), PHP_EOL;
+
+echo "*** Dictionary Compression ***", PHP_EOL;
+check_compress_dict($data, $dictionary);
+?>
+===Done===
+--EXPECTF--
+*** Data size ***
+3547
+*** Dictionary Compression ***
+142 -- 1%d -- true
+===Done===
diff --git a/tests/inc_dictionary.phpt b/tests/inc_dictionary.phpt
new file mode 100644
index 0000000..17de274
--- /dev/null
+++ b/tests/inc_dictionary.phpt
@@ -0,0 +1,68 @@
+--TEST--
+Incremental dictionary compression
+--FILE--
+<?php
+include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
+
+foreach ([128, 512, 1024] as $size) {
+  var_dump($size);
+  $handle = zstd_compress_init(ZSTD_COMPRESS_LEVEL_DEFAULT, $dictionary);
+  var_dump($handle);
+
+  $pos= 0;
+  $compressed = '';
+  while ($pos < strlen($data)) {
+    $chunk = substr($data, $pos, $size);
+    $compressed .= zstd_compress_add($handle, $chunk, false);
+    $pos += strlen($chunk);
+  }
+  $compressed .= zstd_compress_add($handle, '', true);
+  var_dump(strlen($compressed), strlen($compressed) < strlen($data));
+
+  var_dump($data === zstd_uncompress($compressed, $dictionary));
+
+  $handle = zstd_uncompress_init($dictionary);
+  var_dump($handle);
+
+  $pos= 0;
+  $uncompressed = '';
+  while ($pos < strlen($compressed)) {
+    $chunk = substr($compressed, $pos, $size);
+    $uncompressed .= zstd_uncompress_add($handle, $chunk);
+    $pos += strlen($chunk);
+  }
+
+  var_dump($data === $uncompressed);
+}
+?>
+===Done===
+--EXPECTF--
+int(128)
+object(Zstd\Compress\Context)#%d (0) {
+}
+int(%d)
+bool(true)
+bool(true)
+object(Zstd\UnCompress\Context)#%d (0) {
+}
+bool(true)
+int(512)
+object(Zstd\Compress\Context)#%d (0) {
+}
+int(%d)
+bool(true)
+bool(true)
+object(Zstd\UnCompress\Context)#%d (0) {
+}
+bool(true)
+int(1024)
+object(Zstd\Compress\Context)#%d (0) {
+}
+int(%d)
+bool(true)
+bool(true)
+object(Zstd\UnCompress\Context)#%d (0) {
+}
+bool(true)
+===Done===
diff --git a/tests/inc_named_args.phpt b/tests/inc_named_args.phpt
index a5ec24e..1b5842d 100644
--- a/tests/inc_named_args.phpt
+++ b/tests/inc_named_args.phpt
@@ -7,13 +7,14 @@ if (PHP_VERSION_ID < 80000) die("skip requires PHP 8.0+");
 --FILE--
 <?php
 include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
 
-function test($data, $level = 0) {
-    echo "level={$level}\n";
+function test($data, $dict, $level = 0) {
+    echo "level={$level},dict=", gettype($dict), "\n";
 
     $compressed = '';
 
-    $context = zstd_compress_init(level: $level);
+    $context = zstd_compress_init(level: $level, dict: $dict);
     if ($context === false) {
         echo "ERROR\n";
         return;
@@ -31,14 +32,14 @@ function test($data, $level = 0) {
         end: true,
     );
 
-    if ($data === zstd_uncompress(data: $compressed)) {
+    if ($data === zstd_uncompress(data: $compressed, dict: $dict)) {
         echo "OK\n";
     } else {
         echo "ERROR: uncompress\n";
     }
 
     $out = '';
-    $context = zstd_uncompress_init();
+    $context = zstd_uncompress_init(dict: $dict);
     foreach (str_split($compressed, 6) as $var) {
         $out .= zstd_uncompress_add(
             context: $context,
@@ -53,25 +54,42 @@ function test($data, $level = 0) {
 }
 
 foreach ([0, 9, 22, 30, -1] as $level) {
-    test($data, $level, 0);
+    test($data, null, $level);
+    test($data, $dictionary, $level);
 }
 ?>
 ===DONE===
 --EXPECTF--
-level=0
+level=0,dict=NULL
 OK
 Ok
-level=9
+level=0,dict=string
 OK
 Ok
-level=22
+level=9,dict=NULL
 OK
 Ok
-level=30
+level=9,dict=string
+OK
+Ok
+level=22,dict=NULL
+OK
+Ok
+level=22,dict=string
+OK
+Ok
+level=30,dict=NULL
 
 Warning: zstd_compress_init(): compression level (30) must be within 1..22 or smaller then 0 in %s on line %d
 ERROR
-level=-1
+level=30,dict=string
+
+Warning: zstd_compress_init(): compression level (30) must be within 1..22 or smaller then 0 in %s on line %d
+ERROR
+level=-1,dict=NULL
+OK
+Ok
+level=-1,dict=string
 OK
 Ok
 ===DONE===
diff --git a/tests/named_args.phpt b/tests/named_args.phpt
index c4fd2e4..a79b7ed 100644
--- a/tests/named_args.phpt
+++ b/tests/named_args.phpt
@@ -9,6 +9,7 @@ if (PHP_VERSION_ID < 80000) die("skip requires PHP 8.0+");
 include(dirname(__FILE__) . '/data.inc');
 
 $level = ZSTD_COMPRESS_LEVEL_MAX;
+$dict = file_get_contents(dirname(__FILE__) . '/data.dic');
 
 echo "** zstd_compress() **\n";
 try {
@@ -32,6 +33,13 @@ try {
     echo $e->getMessage(), PHP_EOL;
 }
 
+echo "** zstd_compress(dict:) **\n";
+try {
+    var_dump(gettype(zstd_compress(dict: $dict)));
+} catch (Error $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
+
 echo "** zstd_compress(data:, level:) **\n";
 try {
     var_dump(gettype(zstd_compress(data: $data, level: $level)));
@@ -40,6 +48,29 @@ try {
     echo $e->getMessage(), PHP_EOL;
 }
 
+echo "** zstd_compress(data:, dict:) **\n";
+try {
+    var_dump(gettype(zstd_compress(data: $data, dict: $dict)));
+    var_dump(zstd_uncompress(zstd_compress(data: $data, dict: $dict), $dict) === $data);
+} catch (Error $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
+
+echo "** zstd_compress(level:, dict:) **\n";
+try {
+    var_dump(gettype(zstd_compress(level: $level, dict: $dict)));
+} catch (Error $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
+
+echo "** zstd_compress(data:, level:, dict:) **\n";
+try {
+    var_dump(gettype(zstd_compress(data: $data, level: $level, dict: $dict)));
+    var_dump(zstd_uncompress(zstd_compress(data: $data, level: $level, dict: $dict), $dict) === $data);
+} catch (Error $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
+
 $compressed = zstd_compress(data: $data);
 
 echo "** zstd_uncompress(): false **\n";
@@ -56,6 +87,23 @@ try {
 } catch (Error $e) {
     echo $e->getMessage(), PHP_EOL;
 }
+
+echo "** zstd_uncompress(dict:) **\n";
+try {
+    var_dump(gettype(zstd_uncompress(dict: $dict)));
+} catch (Error $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
+
+$compressed = zstd_compress(data: $data, dict: $dict);
+
+echo "** zstd_uncompress(data:, dict:) **\n";
+try {
+    var_dump(gettype(zstd_uncompress(data: $compressed, dict: $dict)));
+    var_dump(zstd_uncompress(data: $compressed, dict: $dict) === $data);
+} catch (Error $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
 ?>
 ===DONE===
 --EXPECTF--
@@ -66,12 +114,27 @@ string(6) "string"
 bool(true)
 ** zstd_compress(level:) **
 zstd_compress(): Argument #1 ($data) not passed
+** zstd_compress(dict:) **
+zstd_compress(): Argument #1 ($data) not passed
 ** zstd_compress(data:, level:) **
 string(6) "string"
 bool(true)
+** zstd_compress(data:, dict:) **
+string(6) "string"
+bool(true)
+** zstd_compress(level:, dict:) **
+zstd_compress(): Argument #1 ($data) not passed
+** zstd_compress(data:, level:, dict:) **
+string(6) "string"
+bool(true)
 ** zstd_uncompress(): false **
 zstd_uncompress() expects at least 1 argument, 0 given
 ** zstd_uncompress(data:) **
 string(6) "string"
 bool(true)
+** zstd_uncompress(dict:) **
+zstd_uncompress(): Argument #1 ($data) not passed
+** zstd_uncompress(data:, dict:) **
+string(6) "string"
+bool(true)
 ===DONE===

From b480694c31ba1d1d0502bc2beb53be345768214d Mon Sep 17 00:00:00 2001
From: kjdev <kjclev@gmail.com>
Date: Fri, 1 Aug 2025 11:31:16 +0900
Subject: [PATCH 5/5] docs: update README.md and  zstd.stub.php

---
 README.md     | 31 +++++++++++++++++++++++++++----
 zstd.stub.php | 20 ++++++++++++--------
 2 files changed, 39 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index d102d5b..ce73649 100644
--- a/README.md
+++ b/README.md
@@ -117,7 +117,7 @@ ZSTD\_VERSION\_TEXT            | libzstd version string
 #### Description
 
 ``` php
-zstd_compress ( string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): string|false
+zstd_compress ( string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null ): string|false
 ```
 
 Zstandard compression.
@@ -136,6 +136,10 @@ Zstandard compression.
   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.
@@ -146,7 +150,7 @@ Returns the compressed data or FALSE if an error occurred.
 #### Description
 
 ``` php
-zstd_uncompress ( string $data ): string|false
+zstd_uncompress ( string $data, ?string $dict = null ): string|false
 ```
 
 Zstandard decompression.
@@ -159,6 +163,10 @@ Zstandard decompression.
 
   The compressed string.
 
+* _dict_
+
+  The Dictionary data.
+
 #### Return Values
 
 Returns the decompressed data or FALSE if an error occurred.
@@ -166,6 +174,8 @@ 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
 
 ``` php
@@ -198,6 +208,8 @@ 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
 
 ``` php
@@ -229,7 +241,7 @@ Returns the decompressed data or FALSE if an error occurred.
 #### Description
 
 ``` php
-zstd_compress_init ( int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): Zstd\Compress\Context|false
+zstd_compress_init ( int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null ): Zstd\Compress\Context|false
 ```
 
 Initialize an incremental compress context
@@ -241,6 +253,10 @@ Initialize an incremental compress context
   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
@@ -280,11 +296,17 @@ Returns a chunk of compressed data, or FALSE on failure.
 #### Description
 
 ``` php
-zstd_uncompress_init ( void ): Zstd\UnCompress\Context|false
+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
@@ -370,6 +392,7 @@ readfile("compress.zstd:///path/to/data.zstd");
 $context = stream_context_create([
     'zstd' => [
             'level' => ZSTD_COMPRESS_LEVEL_MIN,
+            // 'dict' => $dict,
         ],
     ],
 );
diff --git a/zstd.stub.php b/zstd.stub.php
index 7c702a5..6bdba3c 100644
--- a/zstd.stub.php
+++ b/zstd.stub.php
@@ -30,19 +30,21 @@
    */
    const ZSTD_VERSION_TEXT = UNKNOWN;
 
-  function zstd_compress(string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT): string|false {}
+  function zstd_compress(string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null): string|false {}
 
-  function zstd_uncompress(string $data): string|false {}
+  function zstd_uncompress(string $data, ?string $dict = null): string|false {}
 
+  /** @deprecated */
   function zstd_compress_dict(string $data, string $dict, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT): string|false {}
 
+  /** @deprecated */
   function zstd_uncompress_dict(string $data, string $dict): string|false {}
 
-  function zstd_compress_init(int $level = ZSTD_COMPRESS_LEVEL_DEFAULT): Zstd\Compress\Context|false {}
+  function zstd_compress_init(int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null): Zstd\Compress\Context|false {}
 
   function zstd_compress_add(Zstd\Compress\Context $context, string $data, bool $end = false): string|false {}
 
-  function zstd_uncompress_init(): Zstd\UnCompress\Context|false {}
+  function zstd_uncompress_init(?string $dict = null): Zstd\UnCompress\Context|false {}
 
   function zstd_uncompress_add(Zstd\UnCompress\Context $context, string $data): string|false {}
 
@@ -50,19 +52,21 @@ function zstd_uncompress_add(Zstd\UnCompress\Context $context, string $data): st
 
 namespace Zstd {
 
-  function compress(string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT): string|false {}
+  function compress(string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null): string|false {}
 
-  function uncompress(string $data): string|false {}
+  function uncompress(string $data, ?string $dict = null): string|false {}
 
+  /** @deprecated */
   function compress_dict(string $data, string $dict, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT): string|false {}
 
+  /** @deprecated */
   function uncompress_dict(string $data, string $dict): string|false {}
 
-  function compress_init(int $level = ZSTD_COMPRESS_LEVEL_DEFAULT): Compress\Context|false {}
+  function compress_init(int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null): Compress\Context|false {}
 
   function compress_add(Compress\Context $context, string $data, bool $end = false): string|false {}
 
-  function uncompress_init(): UnCompress\Context|false {}
+  function uncompress_init(?string $dict = null): UnCompress\Context|false {}
 
   function uncompress_add(UnCompress\Context $context, string $data): string|false {}