PHP API
new Scriptling() creates an isolated VM with its own variables. VMs share
nothing, so each request, user or tenant can have its own. The VM is created
on first use, with the libraries the operator’s
configuration allows.
Running scripts
$vm = new Scriptling();
echo $vm->eval('2 + 3'); // 5
echo $vm->eval('[1, "a"]'); // [1, 'a']
echo $vm->evalWithTimeout(500, 'sum(range(10))'); // 45, or an error after 500 ms
echo $vm->evalFile('/app/scripts/report.py');eval() returns the value of the script’s last expression as a string,
written as Python’s str() writes it, and None when the script ends with a
statement. To get structured data back, read a variable as JSON (below).
Passing data
$vm->setVar('name', 'Alice');
$vm->setVarInt('count', 42);
$vm->setVarFloat('rate', 0.1);
$vm->setVarBool('active', true);
$vm->setVarNull('missing');
$vm->setVarJSON('order', json_encode(['items' => [20.00, 5.50], 'country' => 'AU']));
echo $vm->eval(<<<'PY'
subtotal = sum(order["items"])
tax = subtotal * rate if order["country"] == "AU" else 0
result = {"subtotal": subtotal, "total": round(subtotal + tax, 2)}
f"{name}: {result['total']:.2f}"
PY); // Alice: 28.05
$result = json_decode($vm->getVarJSON('result'), true); // ['subtotal' => 25.5, 'total' => 28.05]
$count = $vm->getVarInt('count');Read lists and dicts with getVarJSON(); getVar() is for scalars.
setVarList() and setVarDict() take JSON like setVarJSON(), and check
that it is an array or an object. hasVar(), listVars() (a JSON array of
names) and unsetVar() manage variables, and reset() clears them all and
closes anything the script left open, such as connections.
Calling PHP functions
eval(), evalWithTimeout(), evalFile() and callFunction() take an
optional last argument: an array of name => PHP callable. Each becomes a
function the script can call during that call:
$php = [
'get_customer' => fn(int $id) => $customers[$id] ?? null, // closure
'upper' => 'strtoupper', // function name
'greet' => [$greeter, 'greet'], // [object, method]
'shout' => 'Greeter::shout', // static method
];
echo $vm->eval(<<<'PY'
c = get_customer(42)
f"{upper(c['name'])} owes {c['balance'] * 1.1:.2f}"
PY, $php);- Values convert both ways.
None/null, bools, ints, floats and strings are themselves; lists and tuples become PHP lists; dicts become associative arrays in the same order, and PHP arrays come back as lists or dicts. Bytes become a string. Anything else is aTypeErrorin the script. - Keyword arguments become PHP named arguments:
add(1, c=5)calls$add(1, c: 5). - PHP exceptions become exceptions the script can catch:
TypeErrorandArgumentCountErrorasTypeError,ValueErrorandInvalidArgumentExceptionasValueError,DivisionByZeroErrorasZeroDivisionError,OutOfRangeExceptionasIndexError, and anything else asRuntimeError, with the PHP message. Uncaught, it ends the script like any other error. exit()or a fatal error in a PHP function ends the request as it would in plain PHP.- Only during the call. The functions are removed when the call returns,
so a later call without the array cannot reach them, and a reference the
script kept raises
RuntimeError. Nothing is kept between calls, so worker mode does not leak. - Not sandboxed. A PHP function runs as ordinary PHP: the Scriptling policy does not apply to what it does. Pass only functions the script should be able to use.
- A timeout cannot interrupt a PHP function; the script stops once it returns.
Script libraries and functions
Register libraries written in Scriptling, then import them:
$vm->registerScriptLibrary('pricing', <<<'PY'
def with_tax(amount, rate=0.1):
return round(amount * (1 + rate), 2)
PY);
$vm->import('pricing'); // or importMultiple('["pricing", "other"]')
echo $vm->eval('pricing.with_tax(100)'); // 110.0
$vm->registerScriptFunc('add', 'lambda a, b: a + b');
echo $vm->callFunction('add', '[10, 20]'); // 30
callFunction() takes the arguments as a JSON array (or "" for none) and
returns the result as a string, like eval().
To load libraries from files, set an autoload path before the first
eval(), import() or callFunction(), since the VM is created then:
$vm = new Scriptling();
$vm->setAutoloadPath('/app/libs'); // import foo loads /app/libs/foo.py or foo/__init__.py
$vm->addAutoloadPath('/app/shared'); // searched in order, first match wins
$vm->import('foo');Output and errors
$vm->enableOutputCapture();
$vm->eval('print("hi")');
echo $vm->getOutput(); // hi
$vm->eval('1/0');
if ($vm->hasError()) {
echo $vm->getLastError(); // division by zero (line 1)
$vm->clearError();
}A script error does not throw in PHP: the call returns an empty string and
hasError() is true until clearError(). Without output capture, print()
goes to PHP’s output.
Limits
$vm->setMemoryLimit(16 * 1024 * 1024); // lower this VM's memory limit
$vm->setMaxValueBytes(1024 * 1024); // lower its largest single value
$usage = json_decode($vm->getResourceUsage(), true); // memory_bytes, peak_memory_bytes, ...
PHP can lower the operator’s limits for one VM but not raise them;
getMemoryLimit() and getMaxValueBytes() return the limit in force, 0
meaning none. Going over the memory limit cancels the call with an error
containing memory limit exceeded, and the VM stays usable.
Reference
| Method | Returns | Description |
|---|---|---|
eval(string $code, array $functions = []) |
string |
Run code, return the last expression |
evalWithTimeout(int $ms, string $code, array $functions = []) |
string |
eval() with a time limit |
evalFile(string $path, array $functions = []) |
string |
Run a script file |
callFunction(string $name, string $argsJSON, array $functions = []) |
string |
Call a script function with JSON arguments |
setVar, setVarInt, setVarFloat, setVarBool, setVarNull |
void |
Set a variable |
setVarJSON, setVarList, setVarDict |
void |
Set a variable from JSON |
getVar, getVarAsString, getVarInt, getVarFloat, getVarBool |
Read a variable | |
getVarJSON(string $name) |
string |
Read a variable as JSON |
hasVar, listVars, unsetVar, reset |
Manage variables | |
registerScriptLibrary(string $name, string $source) |
void |
Register a library written in Scriptling |
registerScriptFunc(string $name, string $source) |
void |
Register a function from a lambda or def |
import(string $name), importMultiple(string $namesJSON) |
void |
Import libraries |
setAutoloadPath, addAutoloadPath, getAutoloadPath |
Load libraries from directories | |
enableOutputCapture(), getOutput() |
Capture print() output |
|
hasError(), getLastError(), clearError() |
Error state of the last call | |
setMemoryLimit, getMemoryLimit, setMaxValueBytes, getMaxValueBytes, getResourceUsage |
Resource limits | |
getScriptlingVersion(), getImageVersion(), getBuildInfo() |
string |
Versions; getBuildInfo() is JSON with the image, Scriptling, FrankenPHP and PHP versions |