View source for LuaSandbox

<languages />
''<translate><!--T:1--> For the MediaWiki extension that allows use of sandboxed Lua code, see <tvar name=1>{{ll|Extension:Scribunto}}</tvar></translate>''

<translate>
<!--T:2-->
'''LuaSandbox''' is an extension for PHP 7 and PHP 8 to allow safely running untrusted Lua 5.1 code from within PHP, which will generally be faster than shelling out to a Lua binary and using inter-process communication.

== Installation == <!--T:3-->

=== Linux package manager === <!--T:4-->
</translate>
<translate><!--T:5--> LuaSandbox is available on Linux in the [<tvar name=debian>https://packages.debian.org/stable/php-luasandbox</tvar> Debian] and [<tvar name=ubuntu>https://packages.ubuntu.com/search?keywords=php-luasandbox&searchon=names</tvar> Ubuntu] repositories.</translate>
<translate><!--T:6--> Install with the following command:</translate>

<syntaxhighlight lang="bash">
apt install php-luasandbox -y
</syntaxhighlight>

<translate>
<!--T:87-->
LuaSandbox can be installed on RPM-based distributions (Fedora, RedHat, SUSE, etc.) using <code>yum</code> from [<tvar name=1>https://rpms.remirepo.net/</tvar> Remi's repository] ([<tvar name=url>https://rpmfind.net/linux/rpm2html/search.php?query=php-pecl-luasandbox</tvar> package list]).</translate>

=== PIE ===

<translate><!--T:10--> To install LuaSandbox with <tvar name=2>[https://php.github.io/pie/ PIE]</tvar>, first get the correct Lua 5.1 library as described below under "[[<tvar name=1>#Build from source</tvar>|build from source]]".</translate>
<translate><!--T:11--> Then run:</translate>

<code>pie install wikimedia/luasandbox</code>

See [https://packagist.org/packages/wikimedia/luasandbox LuaSandbox in Packagist].

<translate>
=== PECL === <!--T:7-->
</translate>
PECL is deprecated as of 2026.
New releases will not be published to PECL.

To install LuaSandbox with PECL, first get the correct Lua 5.1 library, then run:

<pre>
pecl install luasandbox
</pre>

<translate>
=== Build from source === <!--T:12-->

<!--T:13-->
'''Requirements''':

<!--T:14-->
Install the headers and library files for PHP and [<tvar name=url>https://www.lua.org/</tvar> Lua] 5.1.
</translate>
* <translate><!--T:15--> For Debian-derived Linux distributions, such as Ubuntu:</translate> <syntaxhighlight lang="bash">apt install php-dev liblua5.1-0-dev -y</syntaxhighlight>
* <translate><!--T:16--> For CentOS/Redhat-derived Linux distributions:</translate> <syntaxhighlight lang="bash">yum install php-devel lua5.1 lua5.1-devel</syntaxhighlight>

<translate>
<!--T:19-->
Download the source code into an appropriate directory from git:
</translate>

<syntaxhighlight lang="bash">
git clone https://gerrit.wikimedia.org/r/mediawiki/php/luasandbox.git
</syntaxhighlight>

<translate>
<!--T:20-->
Or {{<tvar name=1>DownloadGitMaster|base=mediawiki-php-|luasandbox</tvar>|download a snapshot}} and unpack.

<!--T:22-->
<tvar name=1><code>luasandbox/</code></tvar> is the directory with the LuaSandbox source code.
</translate>

<syntaxhighlight lang="bash">
cd luasandbox/
phpize && ./configure && make && sudo make install
</syntaxhighlight>

<translate><!--T:23--> Then add <tvar name=1><code>extension = luasandbox</code></tvar> to the PHP configuration in an appropriate place.</translate>
<translate><!--T:24--> For example, in modern Debian-derived distributions you would add a file to <tvar name=1><code>/etc/php/$version/mods-available</code></tvar> (where <tvar name=2><code>$version</code></tvar> is the version of PHP for which you complied LuaSandbox) and use the <tvar name=3><code>phpenmod</code></tvar> command to enable it.</translate>

<translate><!--T:25--> If you are using LuaSandbox with a web application such as MediaWiki, you will need to restart your web server or <tvar name=1><code>php-fpm</code></tvar> for PHP to load the extension.</translate>
<translate><!--T:26--> After such reload, you should see LuaSandbox in the output of <tvar name=1>{{phpi|phpinfo()}}</tvar> and <tvar name=2>{{phpi|get_loaded_extensions()}}</tvar> (and, for MediaWiki with Scribunto installed, <tvar name=3>[[Special:Version]]</tvar>).</translate>

<translate>
== Examples == <!--T:27-->
</translate>
<syntaxhighlight lang="php">
$sandbox = new LuaSandbox;
$sandbox->setMemoryLimit( 50 * 1024 * 1024 );
$sandbox->setCPULimit( 10 );

// <translate nowrap><!--T:28--> Register some functions in the Lua environment</translate>

function frobnosticate( $v ) {
    return [ $v + 42 ];
}

$sandbox->registerLibrary( 'php', [
    'frobnosticate' => 'frobnosticate',
    'output' => function ( $string ) {
        echo "$string\n";
    },
    'error' => function () {
        throw new LuaSandboxRuntimeError( "<translate nowrap><!--T:29--> Something is wrong</translate>" );
    }
] );

// <translate nowrap><!--T:30--> Execute some Lua code, including callbacks into PHP and into Lua</translate>

$luaCode = <<<EOF
php.output( "Hello, world" );

return "Hi", function ( v )
    return php.frobnosticate( v + 200 )
end
EOF;

list( $hi, $frob ) = $sandbox->loadString( $luaCode )->call();
assert( $frob->call( 4000 ) === [ 4242 ] );

// <translate nowrap><!--T:31--> PHP-thrown LuaSandboxRuntimeError exceptions can be caught inside Lua</translate>

list( $ok, $message ) = $sandbox->loadString( 'return pcall( php.error )' )->call();
assert( !$ok );
assert( $message === 'Something is wrong' );
</syntaxhighlight>

<translate>
== Documentation == <!--T:32-->

<!--T:33-->
Our documentation now lives within the upstream PHP manual at <tvar name=url>https://www.php.net/book.luasandbox</tvar>.

<!--T:34-->
If you want to change the manual, you can either submit a pull request against the [<tvar name=url>https://github.com/php/doc-en/tree/master/reference/luasandbox</tvar> PHP manual repository in GitHub], or change our mirror of the LuaSandbox chapter in the extension's Gerrit project.

== Differences from standard Lua == <!--T:35-->

<!--T:36-->
LuaSandbox provides a sandboxed environment which differs in some ways from standard Lua 5.1.

<!--T:37-->
The following functions and packages are not available:
</translate>

* <translate><!--T:38--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-dofile <code>dofile()</code>]</tvar>, <tvar name=2>[https://www.lua.org/manual/5.1/manual.html#pdf-loadfile <code>loadfile()</code>]</tvar>, and the <tvar name=4>[https://www.lua.org/manual/5.1/manual.html#5.7 <code>io</code>]</tvar> package, as they allow direct filesystem access.</translate> <translate><!--T:39--> If needed, filesystem access should be done via PHP callbacks.</translate>
* <translate><!--T:40--> The <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#5.3 <code>package</code>]</tvar> package, including <tvar name=2><code>require()</code></tvar> and <tvar name=3><code>module()</code></tvar>, as it depends heavily on direct filesystem access.</translate> <translate><!--T:41--> A pure-Lua rewrite such as [[<tvar name=1>phab:diffusion/ELUA/browse/master/includes/Engines/LuaCommon/lualib/package.lua</tvar>|that used in Scribunto]] may be used instead.</translate>
* <translate><!--T:42--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-load <code>load()</code>]</tvar> and <tvar name=2>[https://www.lua.org/manual/5.1/manual.html#pdf-loadstring <code>loadstring()</code>]</tvar>, to allow for static analysis of Lua code.</translate>
* <translate><!--T:43--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-print <code>print()</code>]</tvar>, since it outputs to standard output.</translate> <translate><!--T:44--> If needed, output should be done via PHP callbacks.</translate>
* <translate><!--T:45--> Most of the <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#5.8 <code>os</code>]</tvar> package, as it allows manipulation of the process and executing of other processes.</translate>
** <translate><!--T:46--> <tvar name=1><code>os.clock()</code></tvar>, <tvar name=2><code>os.date()</code></tvar>, <tvar name=3><code>os.difftime()</code></tvar>, and <tvar name=4><code>os.time()</code></tvar> remain available.</translate>
* <translate><!--T:47--> Most of the <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#5.9 <code>debug</code>]</tvar> package, as it allows manipulation of Lua state and metadata in ways that can break sandboxing.</translate>
** <translate><!--T:48--> <tvar name=1><code>debug.traceback()</code></tvar> remains available.</translate>
* <translate><!--T:49--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-string.dump <code>string.dump()</code>]</tvar>, as it may expose internal data.</translate>
* <translate><!--T:50--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-collectgarbage <code>collectgarbage()</code>]</tvar>, <tvar name=2>[https://www.lua.org/manual/5.1/manual.html#pdf-gcinfo <code>gcinfo()</code>]</tvar>, and the <tvar name=3>[https://www.lua.org/manual/5.1/manual.html#2.11 <code>coroutine</code>]</tvar> package have not been reviewed for security.</translate>

<translate>
<!--T:51-->
The following features have been modified:
</translate>

* <translate><!--T:52--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-pcall <code>pcall()</code>]</tvar> and <tvar name=2>[https://www.lua.org/manual/5.1/manual.html#pdf-xpcall <code>xpcall()</code>]</tvar> cannot catch certain errors, particularly timeout errors.</translate>
* <translate><!--T:53--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-tostring <code>tostring()</code>]</tvar> does not include pointer addresses.</translate>
* <translate><!--T:54--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-string.match <code>string.match()</code>]</tvar> has been patched to limit the recursion depth and to periodically check for a timeout.</translate>
* <translate><!--T:55--> <tvar name=1>[https://www.lua.org/manual/5.1/manual.html#pdf-math.random <code>math.random()</code>]</tvar> and <tvar name=2>[https://www.lua.org/manual/5.1/manual.html#pdf-math.random <code>math.randomseed()</code>]</tvar> are replaced with versions that don't share state with PHP's <tvar name=3><code>rand()</code></tvar>.</translate>
* <translate><!--T:56--> The Lua 5.2 <tvar name=1>[https://www.lua.org/manual/5.2/manual.html#pdf-pairs <code>__pairs</code>]</tvar> and <tvar name=2>[https://www.lua.org/manual/5.2/manual.html#pdf-ipairs <code>__ipairs</code>]</tvar> metamethods are supported by <tvar name=3><code>pairs()</code></tvar> and <tvar name=4><code>ipairs()</code></tvar>.</translate>

<translate>
== History == <!--T:57-->
</translate>
<translate><!--T:58--> Over the years, MediaWiki's wikitext template language gained more features and grew more complicated.</translate>
<translate><!--T:59--> As early as 2009, MediaWiki developers began discussing the idea of embedding a real scripting language instead of continuing to make wikitext more complex.</translate>

<translate><!--T:60--> Requirements for such a project included a strong sandbox and strict limitations on memory and CPU time usage, since it would be executing untrusted user code on production servers.</translate>
<translate><!--T:61--> It would need to be usable by shelling out to a standalone binary, with the ability to be run in-process via a PHP extension for better performance being a major benefit.</translate>

<translate><!--T:62--> When development started in earnest circa 2011, four candidate languages were identified: Lua, JavaScript, PHP, or a hypothetical "WikiScript" language to be developed.</translate>
<translate><!--T:63--> Lua had several advantages:</translate>

* <translate><!--T:64--> Small (170K standalone) and fast.</translate> <translate><!--T:65--> The existence of LuaJIT was also considered a benefit.</translate>
* <translate><!--T:66--> Designed for embedding, including easy hooks for CPU and memory limiting.</translate>
* <translate><!--T:67--> Easy sandboxing, no internal globals.</translate>
* <translate><!--T:68--> Detailed reference manual, including instructions on embedding.</translate>

<translate>
<!--T:69-->
The main disadvantage was that it wasn't known as widely as JavaScript.

<!--T:70-->
JavaScript, in the form of the V8 engine at the time, had several disadvantages:
</translate>

* <translate><!--T:71--> Minimal documentation on embedding.</translate>
* <translate><!--T:72--> Continued support for embedding unclear.</translate>
* <translate><!--T:73--> No allocation hook.</translate>
* <translate><!--T:74--> Huge standalone binary.</translate>

<translate><!--T:75--> The Rhino engine was worse, as being written in Java it couldn't sanely be embedded in PHP at all.</translate>
<translate><!--T:76--> PHP itself was rejected since proper embedding and sandboxing would have been extremely difficult and pre-parsing would have been slow, and "WikiScript" would have been a much larger project in that it would have required developing an interpreter (or two) from scratch.</translate>

<translate><!--T:77--> Thus, Lua was chosen, specifically version 5.1 that was available at the time, and this PHP extension was developed.</translate>
<translate><!--T:78--> The changes made to function environment handling in 5.2 have prevented a simple upgrade since, see <tvar name=1>[[phab:T178146]]</tvar> for details.</translate>

<translate>
== External links == <!--T:79-->
</translate>
* [[File:Gerrit icon.svg|28px|link=Special:MyLanguage/Gerrit]] [[git:mediawiki/php/luasandbox|Gerrit <translate><!--T:80--> source code</translate>]]
** [[File:Wikimedia Phabricator logo.svg|28px|link=Special:MyLanguage/Phabricator]] [[phab:diffusion/MLUS/repository/master/|Phabricator <translate><!--T:83--> mirror</translate>]]
** [[File:Octicons-mark-github.svg|28px|link=Special:MyLanguage/Gerrit/GitHub|class=skin-invert-image]] [https://github.com/wikimedia/mediawiki-php-luasandbox GitHub <translate><!--T:84--> mirror</translate>]
* [https://packages.debian.org/stable/php-luasandbox <translate><!--T:81--> Debian package</translate>]
* [https://doc.wikimedia.org/mediawiki-php-luasandbox/master/annotated.html <translate><!--T:82--> Code documentation</translate>]

[[Category:PHP extensions{{#translation:}}]]