README

KLua

KLua是一个基于FFI的Lua5库，可以用于PHP和KPHP。

安装

由于这是一个FFI库，它需要在运行时提供动态库。

安装步骤

1. 在你的系统中安装liblua5（如果你还没有安装的话）
2. 找到库文件并将其放置在./ffilibs/liblua5下
3. 安装这个composer包以在代码中使用KLua类

根据你的系统，你需要找到liblua.so、liblua.dylib或liblua.dll文件。然后你可以将其复制到应用程序根目录下的ffilibs文件夹中（注意：没有扩展名后缀）。

如果你在定位库文件时遇到困难，请使用辅助脚本

$ php -f locate_lib.php
note: can't locate liblua5.4, maybe it's not installed
library candidate: /lib/x86_64-linux-gnu/liblua5.3.so.0
library candidate: /lib/x86_64-linux-gnu/liblua5.3.so

run something like this to make it discoverable (unix):
	mkdir -p ffilibs && sudo ln -s /lib/x86_64-linux-gnu/liblua5.3.so ./ffilibs/liblua5.3

然后安装composer库本身

$ composer require quasilyte/klua

注意

• 如果你想要全局放置库文件/链接，将./ffilibs设为符号链接
• 你可能需要将ffilibs/添加到你的gitignore中

示例

• simple.php - API基本功能的简单概述
• phpfunc.php - 如何将PHP函数绑定到Lua
• override_print.php - 覆盖Lua print() stdlib函数
• limited_stdlib.php - 如何限制Lua脚本中stdlib的访问
• plugin_sandbox.php - 如何加载多个插件而不会发生冲突
• phpfunc_table.php - 如何创建类似模块的原生库
• userdata.php - 如何使用Lua light userdata
• memory_limit.php - 如何限制Lua脚本可使用的内存量
• time_limit.php - 如何限制Lua脚本可运行的时长

使用PHP运行示例

$ php -d opcache.enable_cli=1\
      -d opcache.preload=preload.php\
      -f ./examples/1_simple.php

使用KPHP运行示例

# Step 1: compile the example:
$ kphp --mode cli --composer-root $(pwd) ./examples/simple.php
# Step 2: run the binary:
$ ./kphp_out/cli

快速开始

<?php

require_once __DIR__ . '/vendor/autoload.php';

use KLua\KLua;
use KLua\KLuaConfig;

// For PHP, loadFFI() is called from preload script.
// For KPHP, loadFFI() can be called in the beginning of the script.
if (KPHP_COMPILER_VERSION) { KLua::loadFFI(); }

KLua::init(new KLuaConfig());

KLua::eval('
    function example(x)
        return x + 1
    end
');

var_dump(KLua::call('example', 10)); // => 11

使用PHP运行

$ php -d opcache.enable_cli=1 -d opcache.preload=preload.php -f example.php
float(11)

使用KPHP运行

# Compile
$ kphp --mode cli --composer-root $(pwd) example.php
# Execute
$ ./kphp_out/cli
float(11)

值转换

所有转换都是对称的，除了Lua->PHP的序列表情况。

如果KLuaConfig::pack_lua_tables设置为false，Lua表将被“原样”返回。如果该选项设置为true（默认值），则KLua将尝试将Lua序列表作为类似PHP数组的列表返回。

并非所有的PHP值都可以转换为Lua值，反之亦然。两种语言应通过更简单的协议相互通信。

如果某些值无法正确转换，将产生一个特殊错误值。

['_error' => 'error message']

轻量级用户数据是一个特殊情况。它不能自动从PHP值转换，但可以使用KLua::setVarUserData和调用构建器API的pushUserData函数从PHP传递用户数据到Lua。当执行Lua到PHP的转换时，用户数据地址存储为PHP的int值。您可以使用KLua::userDataPtr将那个int地址转换为CData的void*。请参阅userdata.php获取完整示例。

API参考

请参阅api_reference.md以获取完整文档。

所有KLua类方法都是静态的。

KLua初始化方法

• loadFFI()
• init($config)
• close()

KLua主要方法

• eval($code)
• evalScript($filename)
• setVar($var_name, $value)
• setVarUserData($var_name, $ptr)
• getVar($var_name)
• registerFunction($func_name, $php_func)
• userDataPtr($addr)
• call($func_name, ...$args)
• callStaticMethod($table_name, $table_key, ...$args)
• callMethod($table_name, $table_key, ...$args)

KLua调用构建器方法

• callBuilder($func_name)
• staticMethodCallBuilder($table_name, $table_key)
• methodCallBuilder($table_name, $table_key)

KLua实用方法

• getStats()