用 PHP-CPP 开发 PHP 扩展:raylib-phpcpp

在上一篇关于FFI的文章中,我尝试用FFI去调用raylib,但是FFI功能还不完善,涉及嵌套结构体、结构体里有数组的功能都不能使用,所以我又实现了一个PHP扩展:raylib-phpcpp
demo

目标

虽然只是业余项目,我还是想做得尽量完善,所以定了目标:

  1. 完整支持:主要功能不能缺(目前覆盖88%的raylib函数,算上PHP有替代品的,覆盖92%)
  2. 容易维护:raylib新版本发布时可以尽快跟进
  3. 快速开发:时间不能投入太多,毕竟是业余项目

下面会看到,我主要通过代码生成的方式实现上面这些目标。

选型

开发一个PHP扩展,据我所知至少有4种方式:C、Zephir、PHP-X、PHP-CPP。

C的开发难度太高,我也不熟悉Zend API,所以不考虑。

Zephir是类似PHP的语言,可以被编译成C。Zephir可以通过优化器和CBLOCK调用C代码,但是这两种方法还是要用到Zend API,而且没有简单的方法去封装一个C的结构体,所以Zephir被排除掉。

PHP-X和PHP-CPP有点像,都是C++封装了Zend API,可以用C++实现扩展,PHP-CPP功能相对完善,示例也多,所以我最后选择了PHP-CPP。

我只是看了一下文档和StackOverflow,没有深入调研每个方案,所以以上信息很可能不准确。

封装结构体

首先raylib的每一个结构体,我都使用一个类封装,这些类里都有一个data属性,保存对应的结构体,例如Vector3是:

class Vector3 : public Php::Base {
public:
  ::Vector3 data;
  Vector3(::Vector3 x) { data = x; } // 从raylib的Vector3构造Vector3
  // ... getter and setter
};

在调用raylib函数的时候,我可以直接取出data属性传过去就可以了,返回结果也类似,直接构造函数保存到data里。

有了类还不够,每个结构体都有很多字段,例如Vector3xyz,这些字段的会通过__ get__set方法返回,例如x字段的getter、setter:

Php::Value getx() {
  double result = data.x;
  return result;
}
void setz(const Php::Value &v) { data.z = (double)v; }

然后注册到Vector3的里:

rlVector3.property("x", &Vector3::getx, &Vector3::setx);

对于嵌套的结构体,实现也类似的,例如Camera3D里有一个Vector3类型的position字段:

Php::Value getposition() {
  Php::Value result =
      Php::Object("RayLib\\Vector3", new Vector3(data.position));
  return result;
}

void setposition(const Php::Value &v) {
  data.position = ((Vector3 *)(v.implementation()))->data;
}

rlCamera3D.property("position", &Camera3D::getposition, &Camera3D::setposition);

最终效果就是可以在PHP代码里直接构造和访问结构体的字段:

$vec = RL::Vector3(1, 2, 3);
$vec->x = $vec->y + 1;

$camera = RL::Camera2D(RL::Vector2(1, 1), RL::Vector2(0, 0), 1.0, 1.0);
echo  $camera->target->x;

封装函数

对raylib里的每一个函数,我生成一个对应的方法,这个方法接收一个Php::Value数组作为参数,数组里的每一项会被转换或者提取出data,然后传给raylib的函数。

例如DrawPixel:

static void DrawPixel(Php::Parameters &params) {
  int p0 = params[0];  // 标量直接取出
  int p1 = params[1];
  ::Color p2 = ((Color *)(params[2].implementation()))->data; // 结构体提取出data
  ::DrawPixel(p0, p1, p2); // 调用raylib的DrawPixel
}

这些方法都是RL类的静态方法,会被注册到PHP对应的方法里:

rlClass.method<&RL::DrawPixel>("DrawPixel");

有些函数需要使用结构体指针,只需在提取data后取址即可:

static void UpdateCamera(Php::Parameters &params) {
  ::Camera3D *p0 = &((Camera3D *)(params[0].implementation()))->data;
  ::UpdateCamera(p0);
}

代码生成

经过上面两节的分析,可以发现这里面有明显的模式,把全部绑定写出来只是体力活。对于一个业余项目,投入这么多时间去做重复工作实在不值和不爽,所以我直接从raylib的头文件直接生成代码。

生成代码的第一步是解析raylib.h,这部分工作可以直接使用libclang完成,我用了rust的绑定,使用非常方便:

let clang = Clang::new().unwrap();
let index = Index::new(&clang, false, false);
let tu = index.parser("raylib.h").parse().unwrap();

let mut functions: Vec<FunctionDecl> = Vec::new();
let mut structs: Vec<StructDecl> = Vec::new();

// 遍历每个entity,收集函数和结构体声明:
for e in tu.get_entity().get_children().into_iter() {
    if e.get_kind() == EntityKind::FunctionDecl {
        functions.push(FunctionDecl{entity: e});
    }
    if e.get_kind() == EntityKind::StructDecl {
        structs.push(StructDecl{entity: e});
    }
}

接着就是遍历每一个函数和结构体,按照类型信息生成代码,最终结果是生成了4千行的C++代码: raylib.cpp

用代码生成的方式,可以很好地完成定下的目标,大部分功能都直接支持,新版本发布时只需重新生成代码,而且工作量比直接手写少了很多(生成器5百行,生成代码4千行),而且非常容易统一添加功能和修改实现。例如我要添加参数类型检查,可以统一添加,例如改为全局函数,也只需修改方法的注册方式。

目前的不足

  1. 有些函数需要使用void *传数组参数或返回数据,可以暴露成一个PHP的字符串,但是用户使用不太友好,设想需要一个Typed Array类型,目前没实现
  2. raylib的字符串处理函数没有绑定,不过PHP自带的字符串函数更完善,直接用PHP就好

下一步就是继续完善代码生成器和做一个小游戏啦。

php
本作品采用《CC 协议》,转载必须注明作者和本文链接
Oraoto
讨论数量: 6
Shuyi

我在想,用composer生产的拓展,和用这种方法做的,有什么区别呢。。。

4年前 评论
Oraoto

@Shuyi composer不生产扩展,只是代码的搬运工 :joy:

4年前 评论
Shuyi

@Oraoto 嗯,说错了,应该说是按照psr4制作autoload的扩展包,和这种拓展包有什么区别呢

4年前 评论
Oraoto

@Shuyi 通常说的PHP扩展(extension)是个二进制文件(.so.dll),动态或静态链接到PHP。

autoload自动加载的是PHP代码,通常都称为包(package)。

4年前 评论
Shuyi

@Oraoto 这么说吧,Laravel这个框架,我可以做成so,也可以做成包,但是这两种做法有什么分别呢?

4年前 评论
Oraoto
PHP扩展 Composer包
实现语言 C/C++,Zephir(类似PHP) PHP
编译产物 静态库、共享库 不用编译
性能
加载方式 1.静态链接到PHP可执行文件 2.动态链接,php.ini配置或dl() include,require……
管理工具 pecl,系统包管理工具(yum、apt),手工维护 composer
例子 mbstring, swoole psr/log, laravel/framework

@Shuyi Laravel做成包或者PHP扩展,都可以做到接口、功能一致,只是性能、维护成本、安装方式有差别。

4年前 评论
Shuyi 4年前

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!