{"id":13792207,"url":"https://github.com/quasilyte/KLua","last_synced_at":"2025-05-12T14:31:42.596Z","repository":{"id":52284442,"uuid":"518447442","full_name":"quasilyte/KLua","owner":"quasilyte","description":"KLua is a FFI-based Lua5 library that can be used in both PHP and KPHP","archived":false,"fork":false,"pushed_at":"2022-08-23T13:20:18.000Z","size":181,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-03T01:51:07.993Z","etag":null,"topics":["composer","composer-package","embedded","ffi","kphp","kphp-ffi","library","lua","php","plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quasilyte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-27T12:22:41.000Z","updated_at":"2024-01-07T03:33:20.000Z","dependencies_parsed_at":"2022-08-13T01:50:25.880Z","dependency_job_id":null,"html_url":"https://github.com/quasilyte/KLua","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quasilyte%2FKLua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quasilyte%2FKLua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quasilyte%2FKLua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quasilyte%2FKLua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quasilyte","download_url":"https://codeload.github.com/quasilyte/KLua/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754967,"owners_count":21958934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer","composer-package","embedded","ffi","kphp","kphp-ffi","library","lua","php","plugin"],"created_at":"2024-08-03T22:01:09.519Z","updated_at":"2025-05-12T14:31:42.225Z","avatar_url":"https://github.com/quasilyte.png","language":"PHP","readme":"![](docs/logo.png)\n\n# KLua\n\nKLua is a [FFI](https://www.php.net/manual/ru/class.ffi.php)-based [Lua5](https://www.lua.org) library that can be used in both PHP and [KPHP](github.com/VKCOM/kphp).\n\n## Installation\n\nSince this is a FFI library, it needs a dynamic library available during the run time.\n\nInstallation steps:\n\n1. Install liblua5 in your system (if you don't have it already)\n2. Locate the library file and place in under `./ffilibs/liblua5`\n3. Install this composer package to use KLua classes inside your code\n\nDepending on your system, you need to find `liblua.so`, `liblua.dylib`\nor `liblua.dll` file. Then you can copy it to the application root `ffilibs` folder\nunder the `liblua5` name (note: no extension suffixes).\n\nIf you're having difficulties locating the library file, use a helper script:\n\n```bash\n$ php -f locate_lib.php\nnote: can't locate liblua5.4, maybe it's not installed\nlibrary candidate: /lib/x86_64-linux-gnu/liblua5.3.so.0\nlibrary candidate: /lib/x86_64-linux-gnu/liblua5.3.so\n\nrun something like this to make it discoverable (unix):\n\tmkdir -p ffilibs \u0026\u0026 sudo ln -s /lib/x86_64-linux-gnu/liblua5.3.so ./ffilibs/liblua5.3\n```\n\nThen install the composer library itself:\n\n```bash\n$ composer require quasilyte/klua\n```\n\nNotes:\n\n* If you want to place library files/links globally, make `./ffilibs` a symlink\n* You'll probably want to add `ffilibs/` to your gitignore\n\n## Examples\n\n* [simple.php](examples/1_simple.php) - a simple overview of the API basics\n* [phpfunc.php](examples/2_phpfunc.php) - how to bind PHP functions to Lua\n* [override_print.php](examples/3_override_print.php) - override Lua `print()` stdlib function\n* [limited_stdlib.php](examples/4_limited_stdlib.php) - how to limit the stdlib access in Lua scripts\n* [plugin_sandbox.php](examples/5_plugin_sandbox.php) - how to load several plugins without conflicts\n* [phpfunc_table.php](examples/6_phpfunc_table.php) - how to create module-like native libraries\n* [userdata.php](examples/7_userdata.php) - how to use Lua [light userdata](https://www.lua.org/pil/28.5.html)\n* [memory_limit.php](examples/8_memory_limit.php) - how to limit the amount of memory Lua scripts can use\n* [time_limit.php](examples/9_time_limit.php) - how to limit the amount of time Lua scripts can run\n\nRunning examples with PHP:\n\n```bash\n$ php -d opcache.enable_cli=1\\\n      -d opcache.preload=preload.php\\\n      -f ./examples/1_simple.php\n```\n\nRunning examples with KPHP:\n\n```bash\n# Step 1: compile the example:\n$ kphp --mode cli --composer-root $(pwd) ./examples/simple.php\n# Step 2: run the binary:\n$ ./kphp_out/cli\n```\n\n## Quick start\n\n```php\n\u003c?php\n\nrequire_once __DIR__ . '/vendor/autoload.php';\n\nuse KLua\\KLua;\nuse KLua\\KLuaConfig;\n\n// For PHP, loadFFI() is called from preload script.\n// For KPHP, loadFFI() can be called in the beginning of the script.\nif (KPHP_COMPILER_VERSION) { KLua::loadFFI(); }\n\nKLua::init(new KLuaConfig());\n\nKLua::eval('\n    function example(x)\n        return x + 1\n    end\n');\n\nvar_dump(KLua::call('example', 10)); // =\u003e 11\n```\n\nRunning with PHP:\n\n```bash\n$ php -d opcache.enable_cli=1 -d opcache.preload=preload.php -f example.php\nfloat(11)\n```\n\nRunning with KPHP:\n\n```bash\n# Compile\n$ kphp --mode cli --composer-root $(pwd) example.php\n# Execute\n$ ./kphp_out/cli\nfloat(11)\n```\n\n## Value conversion\n\n| PHP Type | Lua Type | Operation Cost |\n|---|---|---|\n| bool | boolean | free |\n| int | number | free |\n| float | number | free |\n| string | string | string data is copied |\n| map-like array | table | expensive conversion |\n| list-like array | sequence table | expensive conversion |\n\nAll conversions are symmetrical, except for the Lua-\u003ePHP case of sequence tables.\n\nIf `KLuaConfig::pack_lua_tables` is set to `false`, Lua tables will be returned \"as is\".\nIf that option is set to `true` (the default), then KLua will try to return Lua sequence\ntables as list-like PHP arrays.\n\nNot every PHP value can be converted to a Lua value and vice versa.\nBoth languages should communicate to each other using the simpler protocols.\n\nIf some value can't be converted properly, a special error-like value is produced instead.\n\n```\n['_error' =\u003e 'error message']\n```\n\nThe [light userdata](https://www.lua.org/pil/28.5.html) 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-\u003ePHP 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](examples/7_userdata.php) for the complete example.\n\n## API reference\n\nSee [api_reference.md](docs/api_reference.md) for full documentation.\n\nAll `KLua` class methods are static.\n\n`KLua` initialization methods:\n\n* [`loadFFI()`](docs/api_reference.md#klualoadffi)\n* [`init($config)`](docs/api_reference.md#kluainit)\n* [`close()`](docs/api_reference.md#kluaclose)\n\n`KLua` main methods:\n\n* [`eval($code)`](docs/api_reference.md#kluaeval)\n* [`evalScript($filename)`](docs/api_reference.md#kluaevalscript)\n* [`setVar($var_name, $value)`](docs/api_reference.md#kluasetvar)\n* [`setVarUserData($var_name, $ptr)`](docs/api_reference.md#kluasetvaruserdata)\n* [`getVar($var_name)`](docs/api_reference.md#kluagetvar)\n* [`registerFunction($func_name, $php_func)`](docs/api_reference.md#kluaregisterfunction)\n* [`userDataPtr($addr)`](docs/api_reference.md#kluauserdataptr)\n* [`call($func_name, ...$args)`](docs/api_reference.md#kluacall)\n* [`callStaticMethod($table_name, $table_key, ...$args)`](docs/api_reference.md#kluacallstaticmethod)\n* [`callMethod($table_name, $table_key, ...$args)`](docs/api_reference.md#kluacallmethod)\n\n`KLua` call builder methods:\n\n* [`callBuilder($func_name)`](docs/api_reference.md#kluacallbuilder)\n* [`staticMethodCallBuilder($table_name, $table_key)`](docs/api_reference.md#kluastaticmethodcallbuilder)\n* [`methodCallBuilder($table_name, $table_key)`](docs/api_reference.md#kluamethodcallbuilder)\n\n`KLua` utility methods:\n\n* [`getStats()`](docs/api_reference.md#kluagetstate)\n","funding_links":[],"categories":["Table of Contents"],"sub_categories":["FFI libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquasilyte%2FKLua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquasilyte%2FKLua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquasilyte%2FKLua/lists"}