Signatur
Beschreibung
LuaSandboxFunction kapselt eine einzelne Lua-Funktion, die aus einem in einer LuaSandbox-Instanz ausgeführten Lua-Skript stammt. Objekte dieser Klasse werden typischerweise nicht direkt instantiiert, sondern entstehen als Rückgabewert von Methoden wie LuaSandbox::loadString() oder LuaSandbox::loadFile(), oder wenn eine Lua-Funktion per LuaSandbox::callFunction() zurückgegeben wird.
Mit einer LuaSandboxFunction-Instanz kann die zugehörige Lua-Funktion beliebig oft aus PHP heraus aufgerufen werden, indem die Methode call() verwendet wird. PHP-Werte (Strings, Zahlen, Booleans, Arrays) werden dabei automatisch in Lua-Werte konvertiert und umgekehrt.
Die Klasse ist besonders nützlich, wenn Lua als Scripting-Sprache in PHP-Anwendungen eingebettet wird — etwa für konfigurierbare Spiellogik, Template-Systeme oder MediaWiki-Scablonen — und dabei einzelne, benannte Funktionen aus dem Lua-Kontext wiederverwendet werden sollen, ohne das gesamte Skript neu zu laden.
Da LuaSandboxFunction-Objekte an ihre Sandbox gebunden sind, ist es nicht möglich, sie zwischen verschiedenen LuaSandbox-Instanzen auszutauschen. Das Sandbox-Konzept schützt den PHP-Host vor unkontrolliertem Ressourcenverbrauch oder gefährlichem Lua-Code.
Beispiele
Lua-Funktion laden und aus PHP aufrufen
<?php
// Neue Sandbox erstellen
$sandbox = new LuaSandbox();
// Speicherlimit und CPU-Zeitlimit setzen
$sandbox->setMemoryLimit(32 * 1024 * 1024); // 32 MB
$sandbox->setCPULimit(10); // 10 Sekunden
// Lua-Code laden – gibt ein LuaSandboxFunction-Objekt zurück
$func = $sandbox->loadString('
local function greet(name)
return "Hallo, " .. name .. "!"
end
return greet
');
// Den geladenen Chunk zunächst ausführen, um die Funktion zu erhalten
$result = $func->call();
// $result[0] ist nun ein weiteres LuaSandboxFunction-Objekt
$greetFunction = $result[0];
// Die eigentliche Lua-Funktion mit einem Argument aufrufen
$output = $greetFunction->call('Welt');
echo $output[0]; // Hallo, Welt!Lua-Funktion wiederholt mit verschiedenen Argumenten nutzen
<?php
$sandbox = new LuaSandbox();
$sandbox->setMemoryLimit(16 * 1024 * 1024);
// Lua-Skript definiert eine Funktion und gibt sie zurück
$chunk = $sandbox->loadString('
local function multiply(a, b)
return a * b
end
return multiply
');
// Chunk ausführen, um die Funktion zu erhalten
[$multiplyFn] = $chunk->call();
// Funktion mehrfach aufrufen
foreach ([[3, 4], [7, 8], [2, 11]] as [$a, $b]) {
[$product] = $multiplyFn->call($a, $b);
echo "{$a} × {$b} = {$product}\n";
}// Wichtig · Fallstricke
Ressourcenlimits: Auch beim wiederholten Aufruf über LuaSandboxFunction::call() werden die in der LuaSandbox-Instanz gesetzten CPU- und Speicherlimits kumulativ gezählt. Ein langläufiges oder speicherhungriges Lua-Skript kann daher das Limit auch über mehrere Aufrufe hinweg überschreiten.
Fehlerbehandlung: Bei Lua-Laufzeitfehlern wirft call() eine LuaSandboxError-Ausnahme. Diese sollte stets mit einem try/catch-Block abgefangen werden, um den PHP-Prozess nicht abstürzen zu lassen.
Typkonvertierung: PHP-Arrays werden als Lua-Tables übergeben. Lua-Tables, die keine reinen Sequenz-Arrays sind (assoziativ), werden als PHP-Arrays zurückgegeben. Lua-Funktionen, die als Rückgabewert übergeben werden, erscheinen in PHP als weitere LuaSandboxFunction-Objekte.
Erweiterungsverfügbarkeit: Die LuaSandbox-Erweiterung ist nicht standardmäßig in PHP enthalten und muss separat installiert werden (z. B. via PECL oder als Debian-Paket php-luasandbox).