quasilyte/klua

FFI-based Lua5 library that can be used in both PHP and KPHP

v1.0.0 2022-08-12 08:37 UTC

Requires

• php: >=7.4
• quasilyte/kfinalize: ^1.0
• vkcom/kphp-polyfills: ^1.0
• vkcom/ktest-script: ^0.7.4

Requires (Dev)

• phpunit/phpunit: 9.5.16
• vkcom/kphpunit: v1.0.0

MIT

• Iskander Sharipov

README

KLua

KLua is a FFI-based Lua5 library that can be used in both PHP and KPHP.

Installation

Since this is a FFI library, it needs a dynamic library available during the run time.

Installation steps:

1. Install liblua5 in your system (if you don't have it already)
2. Locate the library file and place in under ./ffilibs/liblua5
3. Install this composer package to use KLua classes inside your code

Depending on your system, you need to find liblua.so, liblua.dylib or liblua.dll file. Then you can copy it to the application root ffilibs folder under the liblua5 name (note: no extension suffixes).

If you're having difficulties locating the library file, use a helper script:

$ 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

Then install the composer library itself:

$ composer require quasilyte/klua

Notes:

• If you want to place library files/links globally, make ./ffilibs a symlink
• You'll probably want to add ffilibs/ to your gitignore

Examples

• simple.php - a simple overview of the API basics
• phpfunc.php - how to bind PHP functions to Lua
• override_print.php - override Lua print() stdlib function
• limited_stdlib.php - how to limit the stdlib access in Lua scripts
• plugin_sandbox.php - how to load several plugins without conflicts
• phpfunc_table.php - how to create module-like native libraries
• userdata.php - how to use Lua light userdata
• memory_limit.php - how to limit the amount of memory Lua scripts can use
• time_limit.php - how to limit the amount of time Lua scripts can run

Running examples with PHP:

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

Running examples with KPHP:

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

Quick start

<?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

Running with PHP:

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

Running with KPHP:

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

Value conversion

PHP Type	Lua Type	Operation Cost
bool	boolean	free
int	number	free
float	number	free
string	string	string data is copied
map-like array	table	expensive conversion
list-like array	sequence table	expensive conversion

All conversions are symmetrical, except for the Lua->PHP case of sequence tables.

If KLuaConfig::pack_lua_tables is set to false, Lua tables will be returned "as is". If that option is set to true (the default), then KLua will try to return Lua sequence tables as list-like PHP arrays.

Not every PHP value can be converted to a Lua value and vice versa. Both languages should communicate to each other using the simpler protocols.

If some value can't be converted properly, a special error-like value is produced instead.

['_error' => 'error message']

The light userdata is a special case. It can't be auto-converted from a PHP value, but there are KLua::setVarUserData and call builder API pushUserData functions to pass user data from PHP to Lua. When Lua->PHP conversion is performed, the user data address is stored as PHP int value. You can convert that int addr to the CData void* by using KLua::userDataPtr. See userdata.php for the complete example.

API reference

See api_reference.md for full documentation.

All KLua class methods are static.

KLua initialization methods:

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

KLua main methods:

• 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 call builder methods:

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

KLua utility methods:

• getStats()