PHPackages                             diogo-graciano/laravel-lua-engine - 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. [Utility & Helpers](/categories/utility)
4. /
5. diogo-graciano/laravel-lua-engine

ActiveLibrary[Utility & Helpers](/categories/utility)

diogo-graciano/laravel-lua-engine
=================================

Laravel package for safely executing Lua scripts using PHP-Lua extension

v1.0.3(6mo ago)015MITPHPPHP ^8.1CI passing

Since Oct 27Pushed 6mo agoCompare

[ Source](https://github.com/DiogoGraciano/LuaEngineLaravel)[ Packagist](https://packagist.org/packages/diogo-graciano/laravel-lua-engine)[ RSS](/packages/diogo-graciano-laravel-lua-engine/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (4)Versions (4)Used By (0)

Laravel Lua Engine
==================

[](#laravel-lua-engine)

A secure Lua script execution engine for Laravel applications using the [PHP LuaSandbox extension](https://www.php.net/manual/en/class.luasandbox.php).

This package provides a clean, Laravel-friendly wrapper around LuaSandbox, making it easy to execute Lua scripts safely within your Laravel application with proper error handling, logging, and resource management.

Features
--------

[](#features)

- 🔒 **Safe Sandbox**: Automatic removal of dangerous Lua functions (os, io, require, etc.)
- ⚡ **Easy Integration**: Built specifically for Laravel
- 🎯 **Flexible Configuration**: Control which Lua modules are allowed
- 📊 **Data Binding**: Pass PHP variables to Lua scripts
- 🧪 **Resource Limits**: Timeout and memory limit controls
- 📝 **Error Logging**: Configurable logging levels
- ✅ **Validation**: Check script syntax before execution

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

[](#requirements)

- PHP 8.1 or higher (compatible with PHP 8.4)
- Laravel 10.0 or higher
- LuaSandbox PHP extension (`pecl install luasandbox`)

Installation
------------

[](#installation)

1. Install the LuaSandbox PHP extension:

```
sudo pecl install luasandbox
```

2. Add this package to your Laravel application:

```
composer require diogo-graciano/laravel-lua-engine
```

3. Publish the configuration file:

```
php artisan vendor:publish --provider="DiogoGraciano\LuaEngine\LuaEngineServiceProvider"
```

Configuration
-------------

[](#configuration)

The configuration file is published to `config/lua-engine.php`:

```
return [
    'options' => [
        // CPU limit in seconds (0 = no limit)
        // Sets the maximum CPU time allowed for Lua execution
        // See: https://www.php.net/manual/en/luasandbox.setcpulimit.php
        'cpu_limit' => 30,

        // Maximum memory limit
        // Can be specified as:
        // - Integer bytes: 67108864
        // - String with unit: '64M', '128K', '2G'
        // See: https://www.php.net/manual/en/luasandbox.setmemorylimit.php
        'memory_limit' => '64M', // or 67108864 for 64MB

        // Log errors to Laravel log
        'log_errors' => true,

        // Log level for Lua errors
        // Available: 'error', 'warning', 'info', 'debug'
        'log_level' => 'error',
    ],
];
```

**Note:** LuaSandbox automatically provides a secure sandboxed environment. All dangerous Lua functions are disabled by default. See the [Security & Sandbox](#security--sandbox) section for details.

Basic Usage
-----------

[](#basic-usage)

### Using the Facade

[](#using-the-facade)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Execute a simple Lua script
$result = LuaEngine::execute('return 42');
echo $result; // 42

// Pass data to Lua using registerLibrary
// Note: Functions must return arrays (LuaSandbox requirement)
$data = ['name' => 'John', 'age' => 30];
LuaEngine::registerLibrary([
    'getName' => function() use ($data) {
        return [$data['name']]; // Return as array
    },
    'getAge' => function() use ($data) {
        return [$data['age']];
    },
], 'data');
$result = LuaEngine::execute('return data.getName()');
echo $result; // John
```

### Dependency Injection

[](#dependency-injection)

```
use DiogoGraciano\LuaEngine\LuaEngine;

class MyController
{
    public function __construct(private LuaEngine $luaEngine) {}

    public function example()
    {
        $result = $this->luaEngine->execute('return math.floor(3.7)');
        return $result; // 3
    }
}
```

Examples
--------

[](#examples)

### Example 1: Simple Calculations

[](#example-1-simple-calculations)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Basic math operations
$result = LuaEngine::execute('return 10 + 5 * 2');
// Result: 20

// Using Lua math library
$result = LuaEngine::execute('return math.sqrt(16)');
// Result: 4.0
```

### Example 2: Working with Data

[](#example-2-working-with-data)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

$data = [
    'user' => [
        'name' => 'Alice',
        'age' => 28,
        'scores' => [85, 90, 78]
    ]
];

// Access nested data using registerLibrary
// Note: Functions must return arrays (LuaSandbox requirement)
LuaEngine::registerLibrary([
    'getUserName' => function() use ($data) {
        return [$data['user']['name']]; // Return as array
    },
    'getScore' => function($index) use ($data) {
        return [$data['user']['scores'][$index - 1]]; // Lua is 1-indexed
    },
], 'data');

$name = LuaEngine::execute('return data.getUserName()');
// Result: "Alice"

// Calculate average score
$avg = LuaEngine::execute(
    'return (data.getScore(1) + data.getScore(2) + data.getScore(3)) / 3'
);
// Result: 84.33333333333333
```

### Example 3: Conditional Evaluation

[](#example-3-conditional-evaluation)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Use evaluate() for boolean conditions
$data = ['age' => 25, 'minimumAge' => 18];

// Note: Functions must return arrays (LuaSandbox requirement)
LuaEngine::registerLibrary([
    'getAge' => function() use ($data) {
        return [$data['age']]; // Return as array
    },
    'getMinimumAge' => function() use ($data) {
        return [$data['minimumAge']];
    },
], 'data');

$canVote = LuaEngine::evaluate('data.getAge() >= data.getMinimumAge()');
// Result: true

$isAdult = LuaEngine::evaluate('data.getAge() >= 21');
// Result: true
```

### Example 4: String Operations

[](#example-4-string-operations)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

$data = ['message' => 'hello world'];

// Note: Functions must return arrays (LuaSandbox requirement)
LuaEngine::registerLibrary([
    'getMessage' => function() use ($data) {
        return [$data['message']]; // Return as array
    },
], 'data');

// Transform string
$upper = LuaEngine::execute('return string.upper(data.getMessage())');
// Result: "HELLO WORLD"

// Get string length
$length = LuaEngine::execute('return #data.getMessage()');
// Result: 11
```

### Example 5: Registering Custom PHP Functions

[](#example-5-registering-custom-php-functions)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Register a library of PHP functions
// Note: Functions must return arrays (LuaSandbox requirement)
LuaEngine::registerLibrary([
    'double' => function($x) {
        return [$x * 2]; // Return as array
    },
    'square' => function($x) {
        return [$x * $x];
    },
    'cube' => function($x) {
        return [$x * $x * $x];
    },
], 'custom');

// Use in Lua - functions are accessible as custom.functionName()
$result = LuaEngine::execute('return custom.double(21)');
// Result: 42

$square = LuaEngine::execute('return custom.square(5)'); // 25
$cube = LuaEngine::execute('return custom.cube(3)'); // 27

// Extend the library - add more functions to existing table
LuaEngine::registerLibrary([
    'add' => function($a, $b) {
        return [$a + $b];
    },
], 'custom');
// Now custom library has: double, square, cube, and add
```

### Example 6: Validating Script Syntax

[](#example-6-validating-script-syntax)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Check if script is valid before execution
$isValid = LuaEngine::validate('return true and false');
// Result: true

$isValid = LuaEngine::validate('invalid syntax [[[[');
// Result: false
```

### Example 7: Executing Lua Files

[](#example-7-executing-lua-files)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Execute from a file
// Note: If your Lua script needs data, use registerLibrary first
// Functions must return arrays (LuaSandbox requirement)
LuaEngine::registerLibrary([
    'getValue' => function() {
        return [100]; // Return as array
    },
], 'data');
$result = LuaEngine::executeFile('/path/to/script.lua');
```

### Example 8: Calling Lua Functions

[](#example-8-calling-lua-functions)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Define a function in Lua and store it globally
LuaEngine::execute('
    _G["multiply"] = function(a, b)
        return a * b
    end
');

// Call the function using callFunction
$result = LuaEngine::callFunction('multiply', 6, 7);
// Result: [42] (returns array from LuaSandbox)

// Access first element if single result
$value = is_array($result) ? $result[0] : $result;
// Result: 42
```

### Example 9: Loading and Executing Lua Code Separately

[](#example-9-loading-and-executing-lua-code-separately)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Load Lua code into a function
$func = LuaEngine::loadString('return a + b');

if ($func !== false) {
    // Execute the loaded function (note: you need to set variables first)
    // For simplicity, use execute() method instead
    $result = LuaEngine::execute('return 10 + 5');
    // Result: 15
}
```

### Example 10: Complex Business Logic

[](#example-10-complex-business-logic)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

$order = [
    'items' => [
        ['price' => 10, 'quantity' => 2],
        ['price' => 15, 'quantity' => 1],
    ],
    'discount' => 0.1, // 10%
    'tax' => 0.08 // 8%
];

// Register order data as a library
// Note: Functions must return arrays (LuaSandbox requirement)
LuaEngine::registerLibrary([
    'getItemPrice' => function($index) use ($order) {
        return [$order['items'][$index - 1]['price']]; // Return as array
    },
    'getItemQuantity' => function($index) use ($order) {
        return [$order['items'][$index - 1]['quantity']];
    },
    'getItemsCount' => function() use ($order) {
        return [count($order['items'])];
    },
    'getDiscount' => function() use ($order) {
        return [$order['discount']];
    },
    'getTax' => function() use ($order) {
        return [$order['tax']];
    },
], 'data');

$total = LuaEngine::execute('
    local subtotal = 0
    local itemsCount = data.getItemsCount()
    for i = 1, itemsCount do
        subtotal = subtotal + data.getItemPrice(i) * data.getItemQuantity(i)
    end
    local discount = subtotal * data.getDiscount()
    local afterDiscount = subtotal - discount
    local tax = afterDiscount * data.getTax()
    return afterDiscount + tax
');

echo "Total: $" . number_format($total, 2);
// Total: $35.64
```

### Example 11: Registering a single function with registerFunction

[](#example-11-registering-a-single-function-with-registerfunction)

```
use DiogoGraciano\LuaEngine\Facades\LuaEngine;

// Register only one function inside a library (creates the lib if needed)
LuaEngine::registerFunction('triple', function($x) {
    return [$x * 3];
}, 'mathx');

$value = LuaEngine::execute('return mathx.triple(7)');
// Result: 21

// You can keep adding more functions to the same library
LuaEngine::registerFunction('inc', fn($x) => [$x + 1], 'mathx');
$next = LuaEngine::execute('return mathx.inc(21)');
// Result: 22
```

API Reference
-------------

[](#api-reference)

### Methods

[](#methods)

#### `execute(string $script)`

[](#executestring-script)

Execute a Lua script and return the result.

**Parameters:**

- `$script` - Lua code to execute

**Returns:** The execution result (first element if array, otherwise the result as-is)

**Note:** To pass data to Lua scripts, use `registerLibrary()` to register PHP functions that provide access to your data.

**Example:**

```
$result = LuaEngine::execute('return 42');
```

---

#### `evaluate(string $script): bool`

[](#evaluatestring-script-bool)

Evaluate a Lua expression and return a boolean result. Used for conditional checks.

**Parameters:**

- `$script` - Lua expression (will be wrapped with `return (...)`)

**Returns:** `true` or `false`

**Note:** To pass data to Lua expressions, use `registerLibrary()` to register PHP functions that provide access to your data.

**Example:**

```
// Note: Functions must return arrays (LuaSandbox requirement)
LuaEngine::registerLibrary('data', [
    'getAge' => function() { return [20]; }, // Return as array
]);
$valid = LuaEngine::evaluate('data.getAge() >= 18');
// Result: true
```

---

#### `validate(string $script): bool`

[](#validatestring-script-bool)

Check if a Lua script has valid syntax without executing it.

**Parameters:**

- `$script` - Lua code to validate

**Returns:** `true` if valid, `false` otherwise

**Example:**

```
if (LuaEngine::validate($userScript)) {
    $result = LuaEngine::execute($userScript);
}
```

---

#### `registerLibrary(array $functions, string $libname = 'php'): void`

[](#registerlibraryarray-functions-string-libname--php-void)

Register a set of PHP functions as a Lua library.

This method wraps [LuaSandbox::registerLibrary()](https://www.php.net/manual/en/luasandbox.registerlibrary.php).

**Parameters:**

- `$functions` - An associative array where each key is a function name and each value is a corresponding PHP callable (function name string or callable)
- `$libname` - The name of the library. In the Lua state, the global variable of this name will be set to a table of functions

**Important Notes:**

- If a table with the same `$libname` already exists in Lua, the new functions will be **added** to the existing table (not replaced)
- Functions can be specified as:
    - **Callable closures**: `function($x) { return [$x * 2]; }`
    - **Function name strings**: `'myFunction'` (references a PHP function by name)
- In Lua, functions are accessed as `libname.functionName()`
- Functions that return values **must return arrays** - the first element is used as the Lua return value
- Functions that don't need to return values can return nothing (void)
- Functions can throw `LuaSandboxRuntimeError` or other LuaSandbox exceptions

**Example:**

```
// Define a PHP function
function frobnosticate($v) {
    return [$v + 42]; // Return array for values
}

// Register library with both callables and function name strings
LuaEngine::registerLibrary([
    'frobnosticate' => 'frobnosticate', // Function name as string
    'output' => function($string) {      // Void function - no return needed
        echo "$string\n";
    },
    'add' => function($a, $b) {         // Returns value - must return array
        return [$a + $b];
    },
    'error' => function() {             // Can throw exceptions
        throw new \LuaSandboxRuntimeError("Something is wrong");
    },
    'multiply' => fn($a, $b) => [$a * $b], // Arrow function
], 'php');

// Use in Lua - functions are accessible as php.functionName()
$result = LuaEngine::execute('return php.frobnosticate(100)'); // 142
LuaEngine::execute('php.output("Hello from Lua")'); // Prints: Hello from Lua
$sum = LuaEngine::execute('return php.add(5, 3)'); // 8

// Add more functions to the same library (extends existing)
LuaEngine::registerLibrary('php', [
    'subtract' => function($a, $b) {
        return [$a - $b];
    },
]);
// Now php library has: frobnosticate, output, add, error, multiply, and subtract
```

---

#### `loadString(string $code): LuaSandboxFunction|false`

[](#loadstringstring-code-luasandboxfunctionfalse)

Load Lua code into a function without executing it.

This method wraps [LuaSandbox::loadString()](https://www.php.net/manual/en/luasandbox.loadstring.php).

**Parameters:**

- `$code` - Lua code string

**Returns:** `LuaSandboxFunction` on success, `false` on failure

**Example:**

```
$func = LuaEngine::loadString('return 42');
if ($func !== false) {
    $result = $func->call();
    // Result: [42]
}
```

---

#### `callFunction(string $name, mixed ...$args): array|false`

[](#callfunctionstring-name-mixed-args-arrayfalse)

Call a function in a Lua global variable.

This method wraps [LuaSandbox::callFunction()](https://www.php.net/manual/en/luasandbox.callfunction.php).

**Parameters:**

- `$name` - Lua function name (can contain "." for nested access like "string.match")
- `...$args` - Variable arguments to pass to the function

**Returns:** Array of return values or `false` on failure

**Example:**

```
// Define function in Lua
LuaEngine::execute('_G["add"] = function(a, b) return a + b end');

// Call the function
$result = LuaEngine::callFunction('add', 5, 3);
// Result: [8]
```

---

#### `wrapPhpFunction(callable $function): LuaSandboxFunction|false`

[](#wrapphpfunctioncallable-function-luasandboxfunctionfalse)

Wrap a PHP callable for use in Lua.

This method wraps [LuaSandbox::wrapPhpFunction()](https://www.php.net/manual/en/luasandbox.wrapphpfunction.php).

**Parameters:**

- `$function` - PHP callable to wrap

**Returns:** `LuaSandboxFunction` or `false` on failure

**Example:**

```
$phpFunc = LuaEngine::wrapPhpFunction(function($x) {
    return [$x * 2];
});

if ($phpFunc !== false) {
    // Call directly from PHP
    $ret = $phpFunc->call(21); // returns array [42]
}

// Tip: For exposing PHP functions to Lua, prefer registerFunction/registerLibrary
LuaEngine::registerFunction('double', function($x) { return [$x * 2]; }, 'custom');
$result = LuaEngine::execute('return custom.double(21)'); // 42
```

---

#### `registerFunction(string $functionName, callable $function, string $libName = 'php'): void`

[](#registerfunctionstring-functionname-callable-function-string-libname--php-void)

Register a single PHP function inside a Lua library (creates the library if it doesn't exist yet).

**Parameters:**

- `$functionName` - Function name as exposed to Lua
- `$function` - PHP callable that returns an array when returning a value
- `$libName` - Library name (table in Lua)

**Example:**

```
LuaEngine::registerFunction('triple', fn($x) => [$x * 3], 'mathx');
$res = LuaEngine::execute('return mathx.triple(7)'); // 21
```

---

#### `getRegisteredFunctions(string $libName = 'php'): array`

[](#getregisteredfunctionsstring-libname--php-array)

Get all registered functions for a specific library.

---

#### `getRegisteredLibrary(): array`

[](#getregisteredlibrary-array)

Get all libraries and their registered functions.

---

#### `isRegisteredFunction(string $functionName, string $libName = 'php'): bool`

[](#isregisteredfunctionstring-functionname-string-libname--php-bool)

Check whether a function is registered within a given library.

---

#### `executeFile(string $filePath)`

[](#executefilestring-filepath)

Execute a Lua script from a file.

**Parameters:**

- `$filePath` - Path to Lua file

**Returns:** Execution result

**Note:** To pass data to Lua scripts, use `registerLibrary()` before calling this method to register PHP functions that provide access to your data.

**Throws:** `Exception` if file not found

**Example:**

```
$result = LuaEngine::executeFile('/path/to/script.lua');
```

---

#### `setMemoryLimit(int $bytes): void`

[](#setmemorylimitint-bytes-void)

Set the memory limit for the Lua environment.

This method wraps [LuaSandbox::setMemoryLimit()](https://www.php.net/manual/en/luasandbox.setmemorylimit.php).

**Parameters:**

- `$bytes` - Memory limit in bytes

**Example:**

```
LuaEngine::setMemoryLimit(128 * 1024 * 1024); // 128MB
```

---

#### `setCPULimit(float $seconds): void`

[](#setcpulimitfloat-seconds-void)

Set the CPU time limit for the Lua environment.

This method wraps [LuaSandbox::setCPULimit()](https://www.php.net/manual/en/luasandbox.setcpulimit.php).

**Parameters:**

- `$seconds` - CPU limit in seconds (0 or false = no limit)

**Example:**

```
LuaEngine::setCPULimit(60.0); // 60 seconds
```

---

#### `getSandbox(): ?LuaSandbox`

[](#getsandbox-luasandbox)

Get the underlying LuaSandbox instance for advanced usage.

**Returns:** `LuaSandbox` instance or `null` if not available

**Example:**

```
$sandbox = LuaEngine::getSandbox();
if ($sandbox) {
    // Access advanced LuaSandbox methods directly
    // See: https://www.php.net/manual/en/class.luasandbox.php
    $memoryUsage = $sandbox->getMemoryUsage();
    $cpuUsage = $sandbox->getCPUUsage();
}
```

---

#### `getLastError(): ?string`

[](#getlasterror-string)

Get the last error message that occurred.

**Returns:** Last error message or `null`

**Example:**

```
try {
    LuaEngine::execute('invalid syntax');
} catch (Exception $e) {
    $error = LuaEngine::getLastError();
}
```

---

#### `isAvailable(): bool`

[](#isavailable-bool)

Check if the LuaSandbox extension is available.

**Returns:** `true` if available, `false` otherwise

**Example:**

```
if (LuaEngine::isAvailable()) {
    // Use Lua engine
}
```

Security & Sandbox
----------------------

[](#security--sandbox)

This package uses the [PHP LuaSandbox extension](https://www.php.net/manual/en/class.luasandbox.php), which provides a secure sandboxed Lua environment by default.

### Disabled Functions & Modules

[](#disabled-functions--modules)

LuaSandbox automatically disables dangerous Lua functions and modules:

- ❌ `os` - Most operating system functions are disabled
    - ⚠️ **Exceptions:** `os.clock()`, `os.date()`, `os.difftime()`, `os.time()` are available
- ❌ `io` - All file I/O operations are disabled
- ❌ `require`, `package`, `module` - Module loading and package management disabled
- ❌ `dofile`, `loadfile` - File operations disabled
- ❌ `load`, `loadstring` - Dynamic code loading disabled
- ❌ `debug` - Most debugging functions disabled
    - ⚠️ **Exception:** `debug.traceback()` is available
- ❌ `print` - Standard output disabled

### Available Modules

[](#available-modules)

These standard Lua modules are available and safe to use:

- ✅ `math` - Mathematical functions (`math.sin`, `math.cos`, `math.floor`, etc.)
- ✅ `string` - String manipulation (`string.upper`, `string.lower`, `string.match`, etc.)
- ✅ `table` - Table operations (`table.insert`, `table.remove`, `table.concat`, etc.)

### Resource Limits

[](#resource-limits)

LuaSandbox provides built-in resource limits to prevent resource exhaustion:

- **CPU Time Limits**: Controlled via `setCPULimit()` or configuration option `cpu_limit`
    - See: [LuaSandbox::setCPULimit()](https://www.php.net/manual/en/luasandbox.setcpulimit.php)
- **Memory Limits**: Controlled via `setMemoryLimit()` or configuration option `memory_limit`
    - See: [LuaSandbox::setMemoryLimit()](https://www.php.net/manual/en/luasandbox.setmemorylimit.php)
- **Automatic Error Handling**: LuaSandbox throws specific exceptions:
    - `LuaSandboxTimeoutError` - When CPU limit is exceeded
    - `LuaSandboxMemoryError` - When memory limit is exceeded
    - `LuaSandboxSyntaxError` - For syntax errors
    - `LuaSandboxRuntimeError` - For runtime errors

### Additional Security Features

[](#additional-security-features)

You can access additional LuaSandbox features through `getSandbox()`:

- Monitor resource usage: `getMemoryUsage()`, `getCPUUsage()`, `getPeakMemoryUsage()`
- Enable profiling: `enableProfiler()`, `disableProfiler()`, `getProfilerFunctionReport()`
- Load precompiled binaries: `loadBinary()`
- Pause/unpause CPU timer: `pauseUsageTimer()`, `unpauseUsageTimer()`

For complete documentation, see the [official PHP LuaSandbox documentation](https://www.php.net/manual/en/class.luasandbox.php).

Error Handling
--------------

[](#error-handling)

This package provides comprehensive error handling that wraps LuaSandbox exceptions with user-friendly messages.

### Exception Types

[](#exception-types)

The following exceptions may be thrown:

- `LuaSandboxSyntaxError` - Caught and wrapped in `Exception` with message "Lua syntax error: ..."
- `LuaSandboxRuntimeError` - Caught and wrapped in `Exception` with message "Lua runtime error: ..."
- `LuaSandboxTimeoutError` - Caught and wrapped in `Exception` with message "Lua execution timeout: ..."
- `LuaSandboxMemoryError` - Caught and wrapped in `Exception` with message "Lua memory limit exceeded: ..."
- `LuaSandboxError` - Generic error caught and wrapped in `Exception` with message "Lua script error: ..."

### Error Logging

[](#error-logging)

Errors are automatically logged according to your configuration:

```
try {
    $result = LuaEngine::execute('invalid syntax');
} catch (\Exception $e) {
    // Error message
    echo 'Error: ' . $e->getMessage();

    // Get last error (same as exception message in this case)
    echo 'Last error: ' . LuaEngine::getLastError();

    // Error is also logged to Laravel logs based on log_level config
}
```

### Accessing LuaSandbox Exceptions Directly

[](#accessing-luasandbox-exceptions-directly)

If you need access to the original LuaSandbox exceptions, you can catch them directly:

```
use LuaSandbox\LuaSandboxSyntaxError;
use LuaSandbox\LuaSandboxRuntimeError;
use LuaSandbox\LuaSandboxTimeoutError;
use LuaSandbox\LuaSandboxMemoryError;

try {
    $sandbox = LuaEngine::getSandbox();
    $function = $sandbox->loadString('invalid syntax');
} catch (LuaSandboxSyntaxError $e) {
    // Handle syntax error
    echo 'Syntax error: ' . $e->getMessage();
}
```

Testing
-------

[](#testing)

Run the test suite:

```
php vendor/bin/phpunit
```

Or using composer scripts (if configured):

```
composer test
```

### Test Requirements

[](#test-requirements)

Tests require the LuaSandbox extension to be installed. If the extension is not available, tests will be skipped automatically.

References
----------

[](#references)

- [PHP LuaSandbox Extension Documentation](https://www.php.net/manual/en/class.luasandbox.php)
- [LuaSandbox Methods Reference](https://www.php.net/manual/en/class.luasandbox.php#class.luasandbox-methods)
- [Lua Language Documentation](https://www.lua.org/manual/)

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance67

Regular maintenance activity

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

3

Last Release

194d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d9d0b884c384c0878d4d1af0f8e7aeb4d1b898295407ce5349d0e88222df4a8e?d=identicon)[Diogo691](/maintainers/Diogo691)

---

Top Contributors

[![DiogoGraciano](https://avatars.githubusercontent.com/u/138625607?v=4)](https://github.com/DiogoGraciano "DiogoGraciano (13 commits)")

---

Tags

laravelsandboxscriptinglua

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/diogo-graciano-laravel-lua-engine/health.svg)

```
[![Health](https://phpackages.com/badges/diogo-graciano-laravel-lua-engine/health.svg)](https://phpackages.com/packages/diogo-graciano-laravel-lua-engine)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[wnx/laravel-stats

Get insights about your Laravel Project

1.8k1.8M7](/packages/wnx-laravel-stats)[livewire/flux

The official UI component library for Livewire.

9385.0M86](/packages/livewire-flux)[laragear/preload

Effortlessly make a Preload script for your Laravel application.

119363.5k](/packages/laragear-preload)[glhd/conveyor-belt

14797.0k](/packages/glhd-conveyor-belt)[getsolaris/laravel-make-service

A MVCS pattern create a service command for Laravel 5+

81161.3k](/packages/getsolaris-laravel-make-service)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)