parent
67496f6bf6
commit
7ee5f8e018
7 changed files with 0 additions and 2511 deletions
@ -1,290 +0,0 @@ |
|||||||
# PHPX 编译器 - C++ 函数导出规范 |
|
||||||
|
|
||||||
## 概述 |
|
||||||
|
|
||||||
在 PHPX 编译器中，C++ 函数可以被导出为 PHP 函数，供 PHP 代码调用。这需要遵循特定的规范和约定。 |
|
||||||
|
|
||||||
## 三大必要条件 |
|
||||||
|
|
||||||
### 1. 函数名必须以 `php_` 为前缀 |
|
||||||
|
|
||||||
```cpp |
|
||||||
// ✅ 正确：以 php_ 为前缀 |
|
||||||
Int php_messagebox(Int hWnd, String text, String caption, Int uType) { |
|
||||||
// 实现代码 |
|
||||||
} |
|
||||||
|
|
||||||
// ❌ 错误：缺少 php_ 前缀 |
|
||||||
Int messagebox(Int hWnd, String text, String caption, Int uType) { |
|
||||||
// 这不会被导出到 PHP |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
**命名规则：** |
|
||||||
- C++ 函数名：`php_messagebox()` |
|
||||||
- PHP 调用名：`messagebox()`（自动去掉 `php_` 前缀） |
|
||||||
|
|
||||||
### 2. 只能使用 PHPX 类型作为参数和返回值 |
|
||||||
|
|
||||||
**支持的 PHPX 类型：** |
|
||||||
|
|
||||||
| PHPX 类型 | PHP 对应类型 | 说明 | |
|
||||||
|-----------|-------------|------| |
|
||||||
| `Int` | `int` | 整数 | |
|
||||||
| `Bool` | `bool` | 布尔值 | |
|
||||||
| `Double` | `float` | 浮点数 | |
|
||||||
| `String` | `string` | 字符串 | |
|
||||||
| `Array` | `array` | 数组 | |
|
||||||
| `Object` | `object` | 对象 | |
|
||||||
| `Variant` | `mixed` | 混合类型 | |
|
||||||
| `void` | 无返回值 | 仅用于返回值 | |
|
||||||
|
|
||||||
```cpp |
|
||||||
// ✅ 正确：使用 PHPX 类型 |
|
||||||
Int php_add(Int a, Int b) { |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
|
|
||||||
String php_greet(String name) { |
|
||||||
return "Hello, " + name + "!"; |
|
||||||
} |
|
||||||
|
|
||||||
// ❌ 错误：使用原生 C/C++ 类型 |
|
||||||
int php_add(int a, int b) { // 错误！ |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
|
|
||||||
char* php_greet(char* name) { // 错误！ |
|
||||||
return name; |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
### 3. 必须在 `.stub.php` 文件中声明 |
|
||||||
|
|
||||||
**Stub 文件的作用：** |
|
||||||
- 只包含函数签名（参数和返回值类型） |
|
||||||
- 不包含具体实现代码 |
|
||||||
- 让编译器知道有哪些 C++ 函数可供 PHP 调用 |
|
||||||
|
|
||||||
**Stub 文件示例** (`winapi.stub.php`)： |
|
||||||
|
|
||||||
```php |
|
||||||
<?php |
|
||||||
|
|
||||||
/** |
|
||||||
* Windows API 封装函数的声明文件（stub） |
|
||||||
* 这些函数在 C++ 中实现，PHP 层只负责声明 |
|
||||||
*/ |
|
||||||
|
|
||||||
// 显示消息框 |
|
||||||
function messagebox(int $hWnd, string $text, string $caption, int $uType): int {} |
|
||||||
|
|
||||||
// 获取模块句柄 |
|
||||||
function get_module_handle(string $moduleName): int {} |
|
||||||
|
|
||||||
// 创建窗口 |
|
||||||
function create_window( |
|
||||||
string $className, |
|
||||||
string $windowName, |
|
||||||
int $style, |
|
||||||
int $x, |
|
||||||
int $y, |
|
||||||
int $width, |
|
||||||
int $height |
|
||||||
): int {} |
|
||||||
|
|
||||||
// 显示窗口 |
|
||||||
function show_window(int $hWnd, int $cmdShow): bool {} |
|
||||||
|
|
||||||
// 退出消息循环 |
|
||||||
function post_quit_message(int $exitCode): void {} |
|
||||||
``` |
|
||||||
|
|
||||||
**注意事项：** |
|
||||||
- Stub 文件必须是 `.stub.php` 扩展名 |
|
||||||
- 函数体为空（`{}`），不包含任何代码 |
|
||||||
- 参数类型和返回值类型必须与 C++ 实现一致 |
|
||||||
- 函数名不需要 `php_` 前缀（编译器会自动添加） |
|
||||||
|
|
||||||
## 完整示例 |
|
||||||
|
|
||||||
### 项目结构 |
|
||||||
|
|
||||||
``` |
|
||||||
my-extension/ |
|
||||||
├── main.php # PHP 主程序 |
|
||||||
├── cpp-src/ |
|
||||||
│ ├── mylib.stub.php # Stub 声明文件 |
|
||||||
│ └── mylib.cc # C++ 实现文件 |
|
||||||
└── project.yml # 项目配置 |
|
||||||
``` |
|
||||||
|
|
||||||
### 1. Stub 声明文件 (`cpp-src/mylib.stub.php`) |
|
||||||
|
|
||||||
```php |
|
||||||
<?php |
|
||||||
|
|
||||||
// 计算两个整数的和 |
|
||||||
function add(int $a, int $b): int {} |
|
||||||
|
|
||||||
// 拼接字符串 |
|
||||||
function concat(string $str1, string $str2): string {} |
|
||||||
|
|
||||||
// 判断是否为偶数 |
|
||||||
function is_even(int $number): bool {} |
|
||||||
``` |
|
||||||
|
|
||||||
### 2. C++ 实现文件 (`cpp-src/mylib.cc`) |
|
||||||
|
|
||||||
```cpp |
|
||||||
#include <phpx.h> |
|
||||||
|
|
||||||
using namespace php; |
|
||||||
|
|
||||||
// 注意：函数名必须以 php_ 为前缀 |
|
||||||
Int php_add(Int a, Int b) { |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
|
|
||||||
String php_concat(String str1, String str2) { |
|
||||||
return str1 + str2; |
|
||||||
} |
|
||||||
|
|
||||||
Bool php_is_even(Int number) { |
|
||||||
return (number % 2 == 0); |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
### 3. PHP 调用文件 (`main.php`) |
|
||||||
|
|
||||||
```php |
|
||||||
<?php |
|
||||||
|
|
||||||
function main() { |
|
||||||
// 直接调用 C++ 函数，无需额外声明 |
|
||||||
$sum = add(10, 20); |
|
||||||
echo "10 + 20 = $sum\n"; // 输出: 10 + 20 = 30 |
|
||||||
|
|
||||||
$greeting = concat("Hello, ", "World!"); |
|
||||||
echo "$greeting\n"; // 输出: Hello, World! |
|
||||||
|
|
||||||
if (is_even(42)) { |
|
||||||
echo "42 是偶数\n"; |
|
||||||
} |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
### 4. 项目配置 (`project.yml`) |
|
||||||
|
|
||||||
```yaml |
|
||||||
name: my-extension |
|
||||||
version: 0.0.1 |
|
||||||
sources: |
|
||||||
- main.php |
|
||||||
- ./cpp-src |
|
||||||
``` |
|
||||||
|
|
||||||
## 编译流程 |
|
||||||
|
|
||||||
``` |
|
||||||
1. 编译器读取 .stub.php 文件 |
|
||||||
↓ |
|
||||||
2. 生成对应的函数声明头文件 |
|
||||||
↓ |
|
||||||
3. 编译 C++ 实现文件（.cc/.cpp） |
|
||||||
↓ |
|
||||||
4. 链接所有目标文件 |
|
||||||
↓ |
|
||||||
5. 生成可执行文件或扩展 |
|
||||||
``` |
|
||||||
|
|
||||||
## 常见错误 |
|
||||||
|
|
||||||
### 错误 1：函数名没有 `php_` 前缀 |
|
||||||
|
|
||||||
```cpp |
|
||||||
// ❌ 错误 |
|
||||||
Int add(Int a, Int b) { |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
|
|
||||||
// ✅ 正确 |
|
||||||
Int php_add(Int a, Int b) { |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
**症状：** PHP 调用时提示函数未定义 |
|
||||||
|
|
||||||
### 错误 2：使用了原生 C/C++ 类型 |
|
||||||
|
|
||||||
```cpp |
|
||||||
// ❌ 错误 |
|
||||||
int php_add(int a, int b) { |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
|
|
||||||
// ✅ 正确 |
|
||||||
Int php_add(Int a, Int b) { |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
**症状：** 编译错误或类型不匹配 |
|
||||||
|
|
||||||
### 错误 3：没有在 stub 文件中声明 |
|
||||||
|
|
||||||
```cpp |
|
||||||
// C++ 中有实现 |
|
||||||
Int php_my_function(Int x) { |
|
||||||
return x * 2; |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
但没有在 `.stub.php` 中声明。 |
|
||||||
|
|
||||||
**症状：** PHP 调用时提示函数未定义 |
|
||||||
|
|
||||||
### 错误 4：Stub 和 C++ 实现类型不一致 |
|
||||||
|
|
||||||
```php |
|
||||||
// stub.php |
|
||||||
function add(int $a, int $b): string {} // 返回 string |
|
||||||
``` |
|
||||||
|
|
||||||
```cpp |
|
||||||
// mylib.cc |
|
||||||
Int php_add(Int a, Int b) { // 返回 Int，不一致！ |
|
||||||
return a + b; |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
**症状：** 编译错误或运行时类型错误 |
|
||||||
|
|
||||||
## 最佳实践 |
|
||||||
|
|
||||||
1. **组织文件结构** |
|
||||||
- 将相关的 stub 和 C++ 文件放在同一目录 |
|
||||||
- 使用有意义的文件名（如 `winapi.stub.php` 和 `winapi.cc`） |
|
||||||
|
|
||||||
2. **类型安全** |
|
||||||
- 始终使用正确的 PHPX 类型 |
|
||||||
- 避免类型转换，除非必要 |
|
||||||
|
|
||||||
3. **注释清晰** |
|
||||||
- 在 stub 文件中添加函数说明 |
|
||||||
- 在 C++ 实现中添加详细注释 |
|
||||||
|
|
||||||
4. **错误处理** |
|
||||||
- 在 C++ 函数中进行参数验证 |
|
||||||
- 使用 `zend_throw_error()` 抛出异常 |
|
||||||
|
|
||||||
5. **命名规范** |
|
||||||
- 使用小写字母和下划线分隔单词 |
|
||||||
- 保持函数名简洁明了 |
|
||||||
|
|
||||||
## 参考资源 |
|
||||||
|
|
||||||
- [PHPX 官方文档](https://github.com/swoole/phpx) |
|
||||||
- [examples/prime](../prime) - 完整的 C++ 混合编程示例 |
|
||||||
- [examples/win32-hello](../win32-hello) - Windows API 封装示例 |
|
||||||
@ -1,112 +0,0 @@ |
|||||||
# Encoding Guide for PHPX Compiler |
|
||||||
|
|
||||||
## Problem |
|
||||||
|
|
||||||
When using Chinese characters in source code, you may encounter garbled text (乱码) like: |
|
||||||
``` |
|
||||||
Win32 Hello World 绋嬪簭 |
|
||||||
鏄剧ず娑堟伅妗?.. |
|
||||||
``` |
|
||||||
|
|
||||||
This happens because: |
|
||||||
1. Windows console uses code page 936 (GBK) by default |
|
||||||
2. Source files are saved as UTF-8 |
|
||||||
3. The mismatch causes encoding issues |
|
||||||
|
|
||||||
## Solution |
|
||||||
|
|
||||||
### Option 1: Use English (Recommended) ✅ |
|
||||||
|
|
||||||
All example files now use English to avoid encoding issues: |
|
||||||
|
|
||||||
**Before:** |
|
||||||
```php |
|
||||||
echo "显示消息框...\n"; |
|
||||||
``` |
|
||||||
|
|
||||||
**After:** |
|
||||||
```php |
|
||||||
echo "Showing message box...\n"; |
|
||||||
``` |
|
||||||
|
|
||||||
### Option 2: Set Console to UTF-8 |
|
||||||
|
|
||||||
If you must use Chinese, set the console code page to UTF-8 before running: |
|
||||||
|
|
||||||
```powershell |
|
||||||
chcp 65001 |
|
||||||
.\win32_hello.exe |
|
||||||
``` |
|
||||||
|
|
||||||
Or in your PHP code, set it programmatically: |
|
||||||
|
|
||||||
```php |
|
||||||
function main() { |
|
||||||
// Set console to UTF-8 |
|
||||||
exec('chcp 65001 > nul'); |
|
||||||
|
|
||||||
echo "显示消息框...\n"; |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
### Option 3: Use Windows API for Unicode |
|
||||||
|
|
||||||
For message boxes and Windows GUI, use wide character functions: |
|
||||||
|
|
||||||
```cpp |
|
||||||
// In C++ file |
|
||||||
Int php_messagebox(Int hWnd, String text, String caption, Int uType) { |
|
||||||
// Convert UTF-8 to UTF-16 for Windows API |
|
||||||
int wtext_len = MultiByteToWideChar(CP_UTF8, 0, text.data(), -1, NULL, 0); |
|
||||||
wchar_t* wtext = new wchar_t[wtext_len]; |
|
||||||
MultiByteToWideChar(CP_UTF8, 0, text.data(), -1, wtext, wtext_len); |
|
||||||
|
|
||||||
int wcaption_len = MultiByteToWideChar(CP_UTF8, 0, caption.data(), -1, NULL, 0); |
|
||||||
wchar_t* wcaption = new wchar_t[wcaption_len]; |
|
||||||
MultiByteToWideChar(CP_UTF8, 0, caption.data(), -1, wcaption, wcaption_len); |
|
||||||
|
|
||||||
int result = MessageBoxW((HWND)hWnd, wtext, wcaption, (UINT)uType); |
|
||||||
|
|
||||||
delete[] wtext; |
|
||||||
delete[] wcaption; |
|
||||||
return result; |
|
||||||
} |
|
||||||
``` |
|
||||||
|
|
||||||
## Best Practices |
|
||||||
|
|
||||||
1. **Use English for code comments and strings** - Most portable solution |
|
||||||
2. **Save all files as UTF-8 without BOM** - Standard for modern development |
|
||||||
3. **Avoid mixing encodings** - Keep consistency across all files |
|
||||||
4. **Test on target systems** - Different Windows versions may have different defaults |
|
||||||
|
|
||||||
## Current Status |
|
||||||
|
|
||||||
All files in `examples/win32-hello/` now use English: |
|
||||||
- ✅ hello-win.php |
|
||||||
- ✅ main.php |
|
||||||
- ✅ window.php |
|
||||||
- ✅ cpp-src/winapi.cc |
|
||||||
- ✅ cpp-src/winapi.stub.php |
|
||||||
|
|
||||||
Rebuild to see the changes: |
|
||||||
|
|
||||||
```powershell |
|
||||||
php bin\compiler.php examples\win32-hello\project.yml |
|
||||||
.\build\win32_hello.exe |
|
||||||
``` |
|
||||||
|
|
||||||
Expected output: |
|
||||||
``` |
|
||||||
======================================== |
|
||||||
Win32 Hello World Program |
|
||||||
======================================== |
|
||||||
|
|
||||||
Showing message box... |
|
||||||
Message box return value: 1 |
|
||||||
|
|
||||||
Note: To create a full window, you need to implement window procedure and message loop. |
|
||||||
This requires WNDCLASS registration and message pump in C++ layer. |
|
||||||
|
|
||||||
Program ended. Press any key to exit... |
|
||||||
``` |
|
||||||
Loading…
Reference in new issue