Overview
The Engine class is the heart of Lyger’s performance optimization layer. It provides a singleton interface to Rust-powered FFI functions for heavy computations, caching, database operations, and the Always-Alive server.
The Engine automatically falls back to PHP implementations when FFI is not available, ensuring compatibility across all environments.
getInstance
Get the singleton instance of the Engine.
public static function getInstance(): self
Returns
The singleton Engine instance
Example
use Lyger\Core\Engine;
$engine = Engine::getInstance();
Server Management
startServer
Start the Always-Alive server with Rust-powered HTTP handling.
public static function startServer(callable $routerHandler, int $port = 8000): void
Callback function that handles routing logic
Port number to run the server on
Example
use Lyger\Core\Engine;
Engine::startServer(function($request) {
// Your routing logic
return Response::json(['status' => 'ok']);
}, 8000);
stopServer
Stop the running server and clean up resources.
public static function stopServer(): void
Example
Basic Functions
helloWorld
Get a hello world message from the Rust layer.
public function helloWorld(): string
Returns
Example
$engine = Engine::getInstance();
echo $engine->helloWorld();
// Output: "Hello from Lyger v0.1"
heavyComputation
Perform CPU-intensive mathematical computations with Rust optimization.
public function heavyComputation(int $iterations = 1000000): float
Number of computational iterations to perform
Returns
Computed result from the heavy computation
Example
$engine = Engine::getInstance();
$result = $engine->heavyComputation(5000000);
echo "Computation result: {$result}";
systemInfo
Get system and framework information as JSON.
public function systemInfo(): string
Returns
JSON string containing framework version, mode, status, and PHP version
Example
$engine = Engine::getInstance();
$info = $engine->systemInfo();
$data = json_decode($info, true);
// Example output:
// {
// "framework": "Lyger v0.1",
// "mode": "Always-Alive",
// "status": "running",
// "php_version": "8.2.0"
// }
Cache Operations
cacheSet
Store a value in the Rust-powered in-memory cache.
public function cacheSet(string $key, string $value): void
Example
$engine = Engine::getInstance();
$engine->cacheSet('user:1', json_encode(['name' => 'John', 'email' => 'john@example.com']));
cacheGet
Retrieve a value from the cache.
public function cacheGet(string $key): string
Returns
Cached value, or empty string if not found
Example
$engine = Engine::getInstance();
$userData = $engine->cacheGet('user:1');
if ($userData) {
$user = json_decode($userData, true);
echo "User: " . $user['name'];
}
cacheDelete
Remove a specific key from the cache.
public function cacheDelete(string $key): void
Example
$engine = Engine::getInstance();
$engine->cacheDelete('user:1');
cacheClear
Clear all entries from the cache.
public function cacheClear(): void
Example
$engine = Engine::getInstance();
$engine->cacheClear();
cacheSize
Get the number of entries currently in the cache.
public function cacheSize(): int
Returns
Example
$engine = Engine::getInstance();
$size = $engine->cacheSize();
echo "Cache contains {$size} entries";
Zero-Copy Database Operations
dbQuery
Execute a database query and return a pointer to the result set.
public function dbQuery(string $dsn, string $query): int
Database connection string (e.g., “postgres://user:pass@localhost/db”)
Returns
Memory pointer to the result set (0 if query fails)
Example
$engine = Engine::getInstance();
$ptr = $engine->dbQuery(
'postgres://admin:password@localhost/mydb',
'SELECT * FROM users WHERE active = true'
);
jsonifyResult
Convert a result set pointer to JSON format.
public function jsonifyResult(int $ptr): string
Result set pointer from dbQuery
Returns
JSON string containing query results
Example
$engine = Engine::getInstance();
$ptr = $engine->dbQuery('postgres://...', 'SELECT * FROM users');
$json = $engine->jsonifyResult($ptr);
$users = json_decode($json, true);
freeResult
Free the memory allocated for a result set.
public function freeResult(int $ptr): void
Result set pointer to free
Always call freeResult() after you’re done with a result set to prevent memory leaks.
Example
$engine = Engine::getInstance();
$ptr = $engine->dbQuery('postgres://...', 'SELECT * FROM users');
$json = $engine->jsonifyResult($ptr);
$engine->freeResult($ptr); // Clean up memory
dbQueryJson
Convenience method that executes a query and returns JSON directly.
public function dbQueryJson(string $dsn, string $query): string
Database connection string
Returns
JSON string containing query results
This method automatically handles memory cleanup, making it the recommended way to perform database queries.
Example
use Lyger\Core\Engine;
$engine = Engine::getInstance();
$json = $engine->dbQueryJson(
'postgres://admin:password@localhost/mydb',
'SELECT id, name, email FROM users WHERE role = $1'
);
$users = json_decode($json, true);
foreach ($users as $user) {
echo "{$user['name']} ({$user['email']})\n";
}
Complete Example
use Lyger\Core\Engine;
// Get engine instance
$engine = Engine::getInstance();
// Cache operations
$engine->cacheSet('config:theme', 'dark');
$theme = $engine->cacheGet('config:theme');
// Heavy computation
$result = $engine->heavyComputation(10000000);
// Database query with zero-copy
$users = $engine->dbQueryJson(
'postgres://admin:pass@localhost/mydb',
'SELECT * FROM users LIMIT 10'
);
// System information
$info = json_decode($engine->systemInfo(), true);
echo "Running: {$info['framework']}";
// Cleanup cache when done
$engine->cacheClear();