PHPackages                             developgravity/lua-ext - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. developgravity/lua-ext

ActivePhp-ext

developgravity/lua-ext
======================

A PHP extension embedding a vendored, patched Lua 5.5 interpreter to run untrusted code under enforced CPU, wall-clock, memory and output limits, with a capability-gated standard library.

10CCI failing

Since Aug 25Pushed todayCompare

[ Source](https://github.com/DevelopGravity/LuaExt)[ Packagist](https://packagist.org/packages/developgravity/lua-ext)[ RSS](/packages/developgravity-lua-ext/feed)WikiDiscussions develop Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

LuaExt
======

[](#luaext)

[![CI](https://camo.githubusercontent.com/78375b5fced34c7d434c8a01bd309e836f742c6f881d2a24d69a6ab9fe50c8c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f43492d6e6f745f7965745f636f6e666967757265642d6c6967687467726579)](#) [![Packagist](https://camo.githubusercontent.com/74407234322ff2f3cdfc8f9c9d529b298364324203ec947ff68d66b81e94f4d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7061636b61676973742d6e6f745f7965745f7075626c69736865642d6c6967687467726579)](#) [![License: MIT](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

A PHP extension that embeds a vendored, patched **Lua 5.5.1** interpreter to run **untrusted, user-supplied Lua code** safely: portable CPU/wall-clock/memory limits, capability-based trust configuration, coroutines strictly scoped to a single call, a virtual filesystem the host implements in PHP, and host-controlled `require()`.

Package: `developgravity/lua-ext` · extension name `luaext` · namespace `DevelopGravity\LuaExt` · license MIT · PHP 8.5+.

> **Status: pre-1.0, no working build yet.** This repository does not have a tagged release, and only the build skeleton exists — no sandboxing behavior has been implemented or tested. The API surface below (classes, methods, parameters, defaults) is pinned and machine-validated against `stubs/luaext.stub.php` and `stubs/luaext_exceptions.stub.php`, the same files that generate the extension's C arginfo, so it will not drift further. What isn't yet true is the runtime: treat every code sample as accurate against that API, not as tested against a working binary.

Why this exists
---------------

[](#why-this-exists)

MediaWiki's `luasandbox` extension has three problems that this project exists to fix:

1. **Its CPU limit is a no-op outside Linux.** `setCPULimit()` is built on Linux-only POSIX timers. On macOS and Windows it silently compiles to a stub — the call succeeds, the limit is simply never enforced, and nothing tells you that. LuaExt's `Sandbox::features()` reports the real, per-platform enforcement level (`LimitSupport::Enforced` / `Degraded` / `Unsupported`) so a host can never be silently unprotected.
2. **It targets an old Lua.** `luasandbox` targets Lua 5.1; 5.4 support only just landed on its master branch, unreleased. LuaExt vendors and patches **Lua 5.5.1** directly — never the system `liblua` — so the sandboxing hooks live in the interpreter's hot loops instead of being bolted on from outside.
3. **It has no filesystem concept and no coroutines.** `luasandbox` removed coroutines entirely because its timeout hook couldn't span them. LuaExt exposes coroutines by default, capped and strictly scoped to the call that created them, and adds a host-implemented virtual filesystem (`FileSystem` interface) so scripts can do `io`-style work against storage the host controls.

This is a from-scratch rewrite, not a fork. There is no LuaSandbox compatibility shim — see [Migrating from LuaSandbox](#migrating-from-luasandbox) below for the mechanical rename most call sites need.

Requirements
------------

[](#requirements)

- PHP **8.5** or later (NTS and ZTS both supported, including FrankenPHP workers).
- Linux (x64, arm64) or macOS (x64, arm64): a C compiler toolchain to build from source. No system Lua is used or required.
- Windows x64: no toolchain needed — installs a prebuilt DLL. Windows on Arm runs the x64 build under emulation for v1; native arm64 is a fast-follow pending upstream `php-windows-builder` support.

Install
-------

[](#install)

Via [PIE](https://github.com/php/pie):

```
pie install developgravity/lua-ext
```

- **Linux / macOS**: PIE builds from source (`phpize && configure && make`) against the vendored Lua tree — nothing is downloaded or compiled outside this repository's `third_party/` sources.
- **Windows**: PIE fetches a prebuilt `php_luaext-{tag}-{php}-{ts|nts}-{vs}-x64.zip` from this repository's GitHub Releases instead of compiling. There is no Windows build toolchain requirement.

For IDE autocomplete and static analysis without loading the extension, add the stub package as a dev dependency once published:

```
composer require --dev developgravity/lua-ext-stubs
```

Quick start
-----------

[](#quick-start)

```