From 178636a5777b19b015aee3dbdaa35ca4c12e0a0d Mon Sep 17 00:00:00 2001
From: tianfenghan <rango@swoole.com>
Date: Tue, 25 Aug 2026 10:38:03 +0800
Subject: [PATCH] feat(config): add ext-deps alias for extension-dependencies
 configuration

- Added support for `ext-deps` as equivalent shorthand name for `extension-dependencies`
- Implemented validation to prevent using both config names simultaneously
- Updated documentation to reflect the new alias and usage restrictions
- Added test cases to verify ext-deps alias parsing works correctly
- Added test cases to ensure configuration error occurs when both names are used
- Refactored Translator.php to handle both configuration key variants
- Maintained backward compatibility with existing extension-dependencies usage
---
 docs/COMPILER_CLI.md                |  2 ++
 phpunit/src/CompilerBaseApiTest.php | 36 ++++++++++++++++++++++++++++-
 src/Translator.php                  | 14 +++++++----
 3 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/docs/COMPILER_CLI.md b/docs/COMPILER_CLI.md
index a8fb6574..04fa874b 100644
--- a/docs/COMPILER_CLI.md
+++ b/docs/COMPILER_CLI.md
@@ -127,6 +127,8 @@ extension-dependencies:
   - curl
 ```
 
+`ext-deps` 是等价的简写名称。一个项目中只能使用其中一个配置名；同时出现 `extension-dependencies` 和 `ext-deps` 会产生配置错误。
+
 编译器会为每一项生成 `ZEND_MOD_REQUIRED`。Zend 在加载 TypePHP 模块时检查这些扩展是否已加载。该配置不表示原生链接库；C/C++ 链接依赖仍使用 `link-libs`。
 
 ## 查看权威帮助
diff --git a/phpunit/src/CompilerBaseApiTest.php b/phpunit/src/CompilerBaseApiTest.php
index 58115e74..4a1a4392 100644
--- a/phpunit/src/CompilerBaseApiTest.php
+++ b/phpunit/src/CompilerBaseApiTest.php
@@ -471,6 +471,40 @@ YAML);
         $this->invokeMethod('parseProjectYaml', $projectFile);
     }
 
+    public function testParseProjectYamlSupportsExtDepsAlias(): void
+    {
+        $projectFile = $this->createProjectFile(<<<'YAML'
+sources:
+  - main.php
+ext-deps:
+  - pdo_mysql
+  - curl
+  - curl
+YAML);
+
+        $this->invokeMethod('parseProjectYaml', $projectFile);
+
+        $this->assertSame(['pdo_mysql', 'curl'], $this->compiler->getExtensionDependencies());
+    }
+
+    public function testParseProjectYamlRejectsBothExtensionDependencyNames(): void
+    {
+        $projectFile = $this->createProjectFile(<<<'YAML'
+sources:
+  - main.php
+extension-dependencies:
+  - pdo_mysql
+ext-deps:
+  - curl
+YAML);
+
+        $this->expectException(TestError::class);
+        $this->expectExceptionMessage(
+            '`extension-dependencies` and `ext-deps` cannot be used together',
+        );
+        $this->invokeMethod('parseProjectYaml', $projectFile);
+    }
+
     public function testExtensionDependenciesAreWrittenToZendModuleEntry(): void
     {
         global $translator;
@@ -479,7 +513,7 @@ YAML);
         $projectFile = $this->createProjectFile(<<<'YAML'
 sources:
   - main.php
-extension-dependencies:
+ext-deps:
   - pdo_mysql
   - curl
 YAML);
diff --git a/src/Translator.php b/src/Translator.php
index c5f37c2b..4e0ee4ca 100644
--- a/src/Translator.php
+++ b/src/Translator.php
@@ -2580,14 +2580,20 @@ CODE;
 
         // Required PHP modules. These are emitted as zend_module_dep entries;
         // they are unrelated to native libraries configured through link-libs.
-        if (array_key_exists('extension-dependencies', $cfg)) {
-            $dependencies = $cfg['extension-dependencies'];
+        $hasExtensionDependencies = array_key_exists('extension-dependencies', $cfg);
+        $hasExtensionDependenciesAlias = array_key_exists('ext-deps', $cfg);
+        if ($hasExtensionDependencies && $hasExtensionDependenciesAlias) {
+            $this->error('`extension-dependencies` and `ext-deps` cannot be used together');
+        }
+        if ($hasExtensionDependencies || $hasExtensionDependenciesAlias) {
+            $configKey = $hasExtensionDependencies ? 'extension-dependencies' : 'ext-deps';
+            $dependencies = $cfg[$configKey];
             if (!is_array($dependencies)) {
-                $this->error('`extension-dependencies` must be array');
+                $this->error("`{$configKey}` must be array");
             }
             foreach ($dependencies as $dependency) {
                 if (!is_string($dependency) || trim($dependency) === '') {
-                    $this->error('Each `extension-dependencies` entry must be a non-empty string');
+                    $this->error("Each `{$configKey}` entry must be a non-empty string");
                 }
                 $dependency = trim($dependency);
                 if (str_contains($dependency, "\0")) {