feat(ext): expose GoValue() and PHPValue() functions (#1877)

* feat(ext): expose a GoValue function

* GoValue()

Author: dunglas

docs/cn/CONTRIBUTING.md

@@ -115,22 +115,22 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push
 
 1. 从 GitHub 下载 FrankenPHP 二进制文件的调试版本或创建包含调试符号的自定义静态构建：
 
-    ```console
-    docker buildx bake \
-        --load \
-        --set static-builder.args.DEBUG_SYMBOLS=1 \
-        --set "static-builder.platform=linux/amd64" \
-        static-builder
-    docker cp $(docker create --name static-builder-musl dunglas/frankenphp:static-builder-musl):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp
-    ```
+   ```console
+   docker buildx bake \
+       --load \
+       --set static-builder.args.DEBUG_SYMBOLS=1 \
+       --set "static-builder.platform=linux/amd64" \
+       static-builder
+   docker cp $(docker create --name static-builder-musl dunglas/frankenphp:static-builder-musl):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp
+   ```
 
 2. 将当前版本的 `frankenphp` 替换为 debug FrankenPHP 可执行文件
 3. 照常启动 FrankenPHP（或者，你可以直接使用 GDB 启动 FrankenPHP： `gdb --args frankenphp run`）
 4. 使用 GDB 附加到进程：
 
-    ```console
-    gdb -p `pidof frankenphp`
-    ```
+   ```console
+   gdb -p `pidof frankenphp`
+   ```
 
 5. 如有必要，请在 GDB shell 中输入 `continue`
 6. 使 FrankenPHP 崩溃
@@ -142,13 +142,13 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push
 1. 打开 `.github/workflows/tests.yml`
 2. 启用 PHP 调试符号
 
-    ```patch
-        - uses: shivammathur/setup-php@v2
-          # ...
-          env:
-            phpts: ts
-    +       debug: true
-    ```
+   ```patch
+       - uses: shivammathur/setup-php@v2
+         # ...
+         env:
+           phpts: ts
+   +       debug: true
+   ```
 
 3. 启用 `tmate` 以连接到容器
 
@@ -166,18 +166,18 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push
 5. 打开 `frankenphp.go`
 6. 启用 `cgosymbolizer`
 
-    ```patch
-    -	//_ "github.com/ianlancetaylor/cgosymbolizer"
-    +	_ "github.com/ianlancetaylor/cgosymbolizer"
-    ```
+   ```patch
+   -	//_ "github.com/ianlancetaylor/cgosymbolizer"
+   +	_ "github.com/ianlancetaylor/cgosymbolizer"
+   ```
 
 7. 下载模块： `go get`
 8. 在容器中，可以使用 GDB 和以下：
 
-    ```console
-    go test -tags watcher -c -ldflags=-w
-    gdb --args frankenphp.test -test.run ^MyTest$
-    ```
+   ```console
+   go test -tags watcher -c -ldflags=-w
+   gdb --args frankenphp.test -test.run ^MyTest$
+   ```
 
 9. 当错误修复后，恢复所有这些更改
 

docs/cn/compile.md

@@ -79,10 +79,10 @@ sudo make install
 某些 FrankenPHP 功能依赖于必须安装的可选系统依赖项。
 或者，可以通过向 Go 编译器传递构建标签来禁用这些功能。
 
-| 功能                     | 依赖项                                                                   | 用于禁用的构建标签 |
-|--------------------------|------------------------------------------------------------------------|-------------------|
-| Brotli 压缩              | [Brotli](https://github.com/google/brotli)                            | nobrotli          |
-| 文件更改时重启 worker     | [Watcher C](https://github.com/e-dant/watcher/tree/release/watcher-c) | nowatcher         |
+| 功能                  | 依赖项                                                                | 用于禁用的构建标签 |
+| --------------------- | --------------------------------------------------------------------- | ------------------ |
+| Brotli 压缩           | [Brotli](https://github.com/google/brotli)                            | nobrotli           |
+| 文件更改时重启 worker | [Watcher C](https://github.com/e-dant/watcher/tree/release/watcher-c) | nowatcher          |
 
 ## 编译 Go 应用
 

docs/cn/embed.md

@@ -14,10 +14,10 @@ FrankenPHP 能够将 PHP 应用程序的源代码和资源文件嵌入到静态
 
 例如，你可能希望：
 
-* 给应用安装生产环境的依赖
-* 导出 autoloader
-* 如果可能，为应用启用生产模式
-* 丢弃不需要的文件，例如 `.git` 或测试文件，以减小最终二进制文件的大小
+- 给应用安装生产环境的依赖
+- 导出 autoloader
+- 如果可能，为应用启用生产模式
+- 丢弃不需要的文件，例如 `.git` 或测试文件，以减小最终二进制文件的大小
 
 例如，对于 Symfony 应用程序，你可以使用以下命令：
 
@@ -53,34 +53,34 @@ composer dump-env prod
 
 1. 在准备好的应用的存储库中创建一个名为 `static-build.Dockerfile` 的文件。
 
-    ```dockerfile
-    FROM --platform=linux/amd64 dunglas/frankenphp:static-builder
+   ```dockerfile
+   FROM --platform=linux/amd64 dunglas/frankenphp:static-builder
 
-    # 复制应用代码
-    WORKDIR /go/src/app/dist/app
-    COPY . .
+   # 复制应用代码
+   WORKDIR /go/src/app/dist/app
+   COPY . .
 
-    # 构建静态二进制文件
+   # 构建静态二进制文件
    WORKDIR /go/src/app/
    RUN EMBED=dist/app/ ./build-static.sh
    ```
 
-    > [!CAUTION]
-    >
-    > 某些 `.dockerignore` 文件（例如默认的 [Symfony Docker `.dockerignore`](https://github.com/dunglas/symfony-docker/blob/main/.dockerignore)）
-    > 会忽略 `vendor/` 文件夹和 `.env` 文件。在构建之前，请务必调整或删除 `.dockerignore` 文件。
+   > [!CAUTION]
+   >
+   > 某些 `.dockerignore` 文件（例如默认的 [Symfony Docker `.dockerignore`](https://github.com/dunglas/symfony-docker/blob/main/.dockerignore)）
+   > 会忽略 `vendor/` 文件夹和 `.env` 文件。在构建之前，请务必调整或删除 `.dockerignore` 文件。
 
 2. 构建:
 
-    ```console
-    docker build -t static-app -f static-build.Dockerfile .
-    ```
+   ```console
+   docker build -t static-app -f static-build.Dockerfile .
+   ```
 
 3. 提取二进制文件
 
-    ```console
-    docker cp $(docker create --name static-app-tmp static-app):/go/src/app/dist/frankenphp-linux-x86_64 my-app ; docker rm static-app-tmp
-    ```
+   ```console
+   docker cp $(docker create --name static-app-tmp static-app):/go/src/app/dist/frankenphp-linux-x86_64 my-app ; docker rm static-app-tmp
+   ```
 
 生成的二进制文件是当前目录中名为 `my-app` 的文件。
 

docs/cn/extensions.md

@@ -72,8 +72,8 @@ func repeat_this(s *C.zend_string, count int64, reverse bool) unsafe.Pointer {
 
 这里有两个重要的事情要注意：
 
-* 指令注释 `//export_php:function` 定义了 PHP 中的函数签名。这是生成器知道如何使用正确的参数和返回类型生成 PHP 函数的方式；
-* 函数必须返回 `unsafe.Pointer`。FrankenPHP 提供了一个 API 来帮助你在 C 和 Go 之间进行类型转换。
+- 指令注释 `//export_php:function` 定义了 PHP 中的函数签名。这是生成器知道如何使用正确的参数和返回类型生成 PHP 函数的方式；
+- 函数必须返回 `unsafe.Pointer`。FrankenPHP 提供了一个 API 来帮助你在 C 和 Go 之间进行类型转换。
 
 虽然第一点不言自明，但第二点可能更难理解。让我们在下一节中深入了解类型转换。
 
@@ -82,16 +82,17 @@ func repeat_this(s *C.zend_string, count int64, reverse bool) unsafe.Pointer {
 虽然一些变量类型在 C/PHP 和 Go 之间具有相同的内存表示，但某些类型需要更多逻辑才能直接使用。这可能是编写扩展时最困难的部分，因为它需要了解 Zend 引擎的内部结构以及变量在 PHP 中的内部存储方式。此表总结了你需要知道的内容：
 
 | PHP 类型           | Go 类型             | 直接转换 | C 到 Go 助手          | Go 到 C 助手           | 类方法支持 |
-|--------------------|---------------------|----------|----------------------|----------------------|------------|
-| `int`              | `int64`             | ✅        | -                    | -                    | ✅          |
-| `?int`             | `*int64`            | ✅        | -                    | -                    | ✅          |
-| `float`            | `float64`           | ✅        | -                    | -                    | ✅          |
-| `?float`           | `*float64`          | ✅        | -                    | -                    | ✅          |
-| `bool`             | `bool`              | ✅        | -                    | -                    | ✅          |
-| `?bool`            | `*bool`             | ✅        | -                    | -                    | ✅          |
-| `string`/`?string` | `*C.zend_string`    | ❌        | frankenphp.GoString() | frankenphp.PHPString() | ✅          |
-| `array`            | `*frankenphp.Array` | ❌        | frankenphp.GoArray()  | frankenphp.PHPArray()  | ✅          |
-| `object`           | `struct`            | ❌        | _尚未实现_            | _尚未实现_            | ❌          |
+| ------------------ | ------------------- | -------- | --------------------- | ---------------------- | ---------- |
+| `int`              | `int64`             | ✅       | -                     | -                      | ✅         |
+| `?int`             | `*int64`            | ✅       | -                     | -                      | ✅         |
+| `float`            | `float64`           | ✅       | -                     | -                      | ✅         |
+| `?float`           | `*float64`          | ✅       | -                     | -                      | ✅         |
+| `bool`             | `bool`              | ✅       | -                     | -                      | ✅         |
+| `?bool`            | `*bool`             | ✅       | -                     | -                      | ✅         |
+| `string`/`?string` | `*C.zend_string`    | ❌       | frankenphp.GoString() | frankenphp.PHPString() | ✅         |
+| `array`            | `*frankenphp.Array` | ❌       | frankenphp.GoArray()  | frankenphp.PHPArray()  | ✅         |
+| `mixed`            | `any`               | ❌       | `GoValue()`           | `PHPValue()`           | ❌         |
+| `object`           | `struct`            | ❌       | _尚未实现_            | _尚未实现_             | ❌         |
 
 > [!NOTE]
 > 此表尚不详尽，将随着 FrankenPHP 类型 API 变得更加完整而完善。
@@ -111,16 +112,16 @@ FrankenPHP 通过 `frankenphp.Array` 类型为 PHP 数组提供原生支持。
 func process_data(arr *C.zval) unsafe.Pointer {
     // 将 PHP 数组转换为 Go
     goArray := frankenphp.GoArray(unsafe.Pointer(arr))
-	
+
 	result := &frankenphp.Array{}
-    
+
     result.SetInt(0, "first")
     result.SetInt(1, "second")
     result.Append("third") // 自动分配下一个整数键
-    
+
     result.SetString("name", "John")
     result.SetString("age", int64(30))
-    
+
     for i := uint32(0); i < goArray.Len(); i++ {
         key, value := goArray.At(i)
         if key.Type == frankenphp.PHPStringKey {
@@ -129,28 +130,28 @@ func process_data(arr *C.zval) unsafe.Pointer {
             result.SetInt(key.Int+100, value)
         }
     }
-    
+
     // 转换回 PHP 数组
     return frankenphp.PHPArray(result)
 }
 ```
 
 **`frankenphp.Array` 的关键特性：**
 
-* **有序键值对** - 像 PHP 数组一样维护插入顺序
-* **混合键类型** - 在同一数组中支持整数和字符串键
-* **类型安全** - `PHPKey` 类型确保正确的键处理
-* **自动列表检测** - 转换为 PHP 时，自动检测数组应该是打包列表还是哈希映射
-* **不支持对象** - 目前，只有标量类型和数组可以用作值。提供对象将导致 PHP 数组中的 `null` 值。
+- **有序键值对** - 像 PHP 数组一样维护插入顺序
+- **混合键类型** - 在同一数组中支持整数和字符串键
+- **类型安全** - `PHPKey` 类型确保正确的键处理
+- **自动列表检测** - 转换为 PHP 时，自动检测数组应该是打包列表还是哈希映射
+- **不支持对象** - 目前，只有标量类型和数组可以用作值。提供对象将导致 PHP 数组中的 `null` 值。
 
 **可用方法：**
 
-* `SetInt(key int64, value interface{})` - 使用整数键设置值
-* `SetString(key string, value interface{})` - 使用字符串键设置值  
-* `Append(value interface{})` - 使用下一个可用整数键添加值
-* `Len() uint32` - 获取元素数量
-* `At(index uint32) (PHPKey, interface{})` - 获取索引处的键值对
-* `frankenphp.PHPArray(arr *frankenphp.Array) unsafe.Pointer` - 转换为 PHP 数组
+- `SetInt(key int64, value interface{})` - 使用整数键设置值
+- `SetString(key string, value interface{})` - 使用字符串键设置值
+- `Append(value interface{})` - 使用下一个可用整数键添加值
+- `Len() uint32` - 获取元素数量
+- `At(index uint32) (PHPKey, interface{})` - 获取索引处的键值对
+- `frankenphp.PHPArray(arr *frankenphp.Array) unsafe.Pointer` - 转换为 PHP 数组
 
 ### 声明原生 PHP 类
 
@@ -168,11 +169,11 @@ type UserStruct struct {
 
 **不透明类**是内部结构（属性）对 PHP 代码隐藏的类。这意味着：
 
-* **无直接属性访问**：你不能直接从 PHP 读取或写入属性（`$user->name` 不起作用）
-* **仅方法接口** - 所有交互必须通过你定义的方法进行
-* **更好的封装** - 内部数据结构完全由 Go 代码控制
-* **类型安全** - 没有 PHP 代码使用错误类型破坏内部状态的风险
-* **更清晰的 API** - 强制设计适当的公共接口
+- **无直接属性访问**：你不能直接从 PHP 读取或写入属性（`$user->name` 不起作用）
+- **仅方法接口** - 所有交互必须通过你定义的方法进行
+- **更好的封装** - 内部数据结构完全由 Go 代码控制
+- **类型安全** - 没有 PHP 代码使用错误类型破坏内部状态的风险
+- **更清晰的 API** - 强制设计适当的公共接口
 
 这种方法提供了更好的封装，并防止 PHP 代码意外破坏 Go 对象的内部状态。与对象的所有交互都必须通过你明确定义的方法进行。
 
@@ -219,12 +220,12 @@ func (us *UserStruct) UpdateInfo(name *C.zend_string, age *int64, active *bool)
     if name != nil {
         us.Name = frankenphp.GoString(unsafe.Pointer(name))
     }
-    
+
     // 检查是否提供了 age（不为 null）
     if age != nil {
         us.Age = int(*age)
     }
-    
+
     // 检查是否提供了 active（不为 null）
     if active != nil {
         us.Active = *active
@@ -234,10 +235,10 @@ func (us *UserStruct) UpdateInfo(name *C.zend_string, age *int64, active *bool)
 
 **关于可空参数的要点：**
 
-* **可空原始类型**（`?int`、`?float`、`?bool`）在 Go 中变成指针（`*int64`、`*float64`、`*bool`）
-* **可空字符串**（`?string`）仍然是 `*C.zend_string`，但可以是 `nil`
-* **在解引用指针值之前检查 `nil`**
-* **PHP `null` 变成 Go `nil`** - 当 PHP 传递 `null` 时，你的 Go 函数接收 `nil` 指针
+- **可空原始类型**（`?int`、`?float`、`?bool`）在 Go 中变成指针（`*int64`、`*float64`、`*bool`）
+- **可空字符串**（`?string`）仍然是 `*C.zend_string`，但可以是 `nil`
+- **在解引用指针值之前检查 `nil`**
+- **PHP `null` 变成 Go `nil`** - 当 PHP 传递 `null` 时，你的 Go 函数接收 `nil` 指针
 
 > [!WARNING]
 > 目前，类方法有以下限制。**不支持对象**作为参数类型或返回类型。**完全支持数组**作为参数和返回类型。支持的类型：`string`、`int`、`float`、`bool`、`array` 和 `void`（用于返回类型）。**完全支持可空参数类型**，适用于所有标量类型（`?string`、`?int`、`?float`、`?bool`）。
@@ -356,7 +357,7 @@ func repeat_this(s *C.zend_string, count int64, mode int) unsafe.Pointer {
     str := frankenphp.GoString(unsafe.Pointer(s))
 
     result := strings.Repeat(str, int(count))
-    if mode == STR_REVERSE { 
+    if mode == STR_REVERSE {
         // 反转字符串
     }
 
@@ -375,14 +376,14 @@ type StringProcessorStruct struct {
 //export_php:method StringProcessor::process(string $input, int $mode): string
 func (sp *StringProcessorStruct) Process(input *C.zend_string, mode int64) unsafe.Pointer {
     str := frankenphp.GoString(unsafe.Pointer(input))
-    
+
     switch mode {
     case MODE_LOWERCASE:
         str = strings.ToLower(str)
     case MODE_UPPERCASE:
         str = strings.ToUpper(str)
     }
-    
+
     return frankenphp.PHPString(str, false)
 }
 ```
@@ -437,17 +438,17 @@ echo My\Extension\STATUS_ACTIVE; // 1
 
 #### 重要说明
 
-* 每个文件只允许**一个**命名空间指令。如果找到多个命名空间指令，生成器将返回错误。
-* 命名空间适用于文件中的**所有**导出符号：函数、类、方法和常量。
-* 命名空间名称遵循 PHP 命名空间约定，使用反斜杠（`\`）作为分隔符。
-* 如果没有声明命名空间，符号将照常导出到全局命名空间。
+- 每个文件只允许**一个**命名空间指令。如果找到多个命名空间指令，生成器将返回错误。
+- 命名空间适用于文件中的**所有**导出符号：函数、类、方法和常量。
+- 命名空间名称遵循 PHP 命名空间约定，使用反斜杠（`\`）作为分隔符。
+- 如果没有声明命名空间，符号将照常导出到全局命名空间。
 
 ### 生成扩展
 
 这就是魔法发生的地方，现在可以生成你的扩展。你可以使用以下命令运行生成器：
 
 ```console
-GEN_STUB_SCRIPT=php-src/build/gen_stub.php frankenphp extension-init my_extension.go 
+GEN_STUB_SCRIPT=php-src/build/gen_stub.php frankenphp extension-init my_extension.go
 ```
 
 > [!NOTE]
@@ -567,9 +568,9 @@ extern zend_module_entry ext_module_entry;
 
 接下来，创建一个名为 `extension.c` 的文件，该文件将执行以下步骤：
 
-* 包含 PHP 头文件；
-* 声明我们的新原生 PHP 函数 `go_print()`；
-* 声明扩展元数据。
+- 包含 PHP 头文件；
+- 声明我们的新原生 PHP 函数 `go_print()`；
+- 声明扩展元数据。
 
 让我们首先包含所需的头文件：
 
@@ -701,9 +702,9 @@ import "strings"
 //export go_upper
 func go_upper(s *C.zend_string) *C.zend_string {
     str := frankenphp.GoString(unsafe.Pointer(s))
-    
+
     upper := strings.ToUpper(str)
-    
+
     return (*C.zend_string)(frankenphp.PHPString(upper, false))
 }
 ```