Engine

Core engine class that manages FFI integration with Rust libraries

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

Engine · Engine

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

routerHandler · callable · required

Callback function that handles routing logic

port · int · default: "8000"

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

Engine::stopServer();

Basic Functions

helloWorld

Get a hello world message from the Rust layer.

public function helloWorld(): string

Returns

message · string

Hello message from Lyger

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

iterations · int · default: "1000000"

Number of computational iterations to perform

Returns

result · float

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

info · string

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

key · string · required

Cache key identifier

value · string · required

Value to store in cache

Example

$engine = Engine::getInstance();
$engine->cacheSet('user:1', json_encode(['name' => 'John', 'email' => '[e-mail]']));

cacheGet

Retrieve a value from the cache.

public function cacheGet(string $key): string

key · string · required

Cache key to retrieve

Returns

value · string

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

key · string · required

Cache key to delete

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

size · int

Number of cache entries

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

dsn · string · required

Database connection string (e.g., “postgres://user:pass@localhost/db”)

query · string · required

SQL query to execute

Returns

pointer · int

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

ptr · int · required

Result set pointer from dbQuery

Returns

json · string

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

ptr · int · required

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

dsn · string · required

Database connection string

query · string · required

SQL query to execute

Returns

json · string

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();