Make PHP apps faster, with proof.Tăng tốc ứng dụng PHP, có số liệu chứng minh.

<?php
// Classic PHP (PHP-FPM / php -S): this file runs from the top on every request.
header('Content-Type: application/json');
echo json_encode(['hello' => 'world', 'pid' => getmypid()]);

<?php
// QHturbo Performance: everything above "return" runs once per worker,
// the closure runs per request.
//   php runtime/bin/qhturbo-serve examples/01-hello/app.php --port=8080 --workers=4
use QHTurbo\Runtime\Http\Request;

return static fn (Request $request): array => ['hello' => 'world', 'pid' => getmypid()];

<?php
// QHturbo Performance: the same framework boots ONCE per worker.
//   php runtime/bin/qhturbo-serve examples/02-framework/app.php --port=8080 --workers=4
use QHTurbo\Runtime\Http\Request;

require __DIR__ . '/../common/framework.php';

$t = hrtime(true);
$app = QhtExample\App::boot();
$boot = round((hrtime(true) - $t) / 1e6, 2);

return static fn (Request $r): array => $app->handle($r->method, $r->path()) + ['boot_ms' => 0, 'boot_once_ms' => $boot];

<?php
// Classic PHP: the framework boots on EVERY request (what PHP-FPM does).
require __DIR__ . '/../common/framework.php';

$t = hrtime(true);
$app = QhtExample\App::boot();
$boot = (hrtime(true) - $t) / 1e6;

$path = (string) parse_url($_SERVER['REQUEST_URI'] ?? '/hello', PHP_URL_PATH);
header('Content-Type: application/json');
echo json_encode($app->handle($_SERVER['REQUEST_METHOD'] ?? 'GET', $path) + ['boot_ms' => round($boot, 2)]);

<?php
// A small stand-in for a real framework boot (Laravel/Symfony style):
// 300 service classes autoloaded, 40 config files read, a DI container
// filled and 200 routes compiled. Under PHP-FPM this whole boot runs on
// EVERY request; a QHturbo worker runs it ONCE.
//
// Generated class/config files are cached in sys_get_temp_dir()/qht-example-fw.

declare(strict_types=1);

namespace QhtExample;

const CLASSES = 300;
const CONFIGS = 40;
const ROUTES = 200;

function cacheDir(): string
{
    $dir = sys_get_temp_dir() . '/qht-example-fw';
    if (!is_file("$dir/ready")) {
        @mkdir("$dir/src", 0777, true);
        @mkdir("$dir/config", 0777, true);
        for ($i = 0; $i < CLASSES; $i++) {
            $deps = $i > 0 ? 'private Service' . ($i - 1) . ' $prev' : '';
            file_put_contents("$dir/src/Service$i.php", "<?php\nnamespace QhtExample\\Gen;\n"
                . "final class Service$i {\n"
                . "    public function __construct(" . ($i > 0 ? "public ?Service" . ($i - 1) . " \$prev = null" : '') . ") {}\n"
                . "    public function name(): string { return 'service-$i'; }\n"
                . "    public function work(int \$n): int { \$s = 0; for (\$k = 0; \$k < \$n; \$k++) { \$s += \$k * $i % 7; } return \$s; }\n"
                . "}\n");
        }
        for ($i = 0; $i < CONFIGS; $i++) {
            $cfg = [];
            for ($k = 0; $k < 50; $k++) {
                $cfg["key_$k"] = ['enabled' => $k % 2 === 0, 'value' => str_repeat('x', 20) . $k, 'list' => range(0, 9)];
            }
            file_put_contents("$dir/config/c$i.php", '<?php return ' . var_export($cfg, true) . ';');
        }
        touch("$dir/ready");
    }
    return $dir;
}

final class Container
{
    /** @var array<string, \Closure> */
    private array $factories = [];
    /** @var array<string, object> */
    private array $instances = [];

    public function bind(string $id, \Closure $factory): void { $this->factories[$id] = $factory; }

    public function get(string $id): object
    {
        return $this->instances[$id] ??= ($this->factories[$id])($this);
    }
}

final class App
{
    public Container $container;
    /** @var array<string, array<string, mixed>> */
    public array $config = [];
    /** @var list<array{string, string, string}> regex, method, name */
    public array $routes = [];

    public static function boot(): self
    {
        $dir = cacheDir();
        spl_autoload_register(static function (string $class) use ($dir): void {
            if (str_starts_with($class, 'QhtExample\\Gen\\')) {
                require "$dir/src/" . substr($class, strlen('QhtExample\\Gen\\')) . '.php';
            }
        });

        $app = new self();
        for ($i = 0; $i < CONFIGS; $i++) {
            $app->config["c$i"] = require "$dir/config/c$i.php";
        }

        $app->container = new Container();
        for ($i = 0; $i < CLASSES; $i++) {
            $class = "QhtExample\\Gen\\Service$i";
            $app->container->bind($class, static fn (Container $c) => $i > 0
                ? new $class($c->get('QhtExample\\Gen\\Service' . ($i - 1)))
                : new $class());
        }
        // Eagerly resolve services, as providers do at boot.
        $app->container->get('QhtExample\\Gen\\Service' . (CLASSES - 1));

        for ($i = 0; $i < ROUTES; $i++) {
            $pattern = "/api/r$i/{id}/items/{item}";
            $regex = '#^' . preg_replace('#\{(\w+)\}#', '(?P<$1>[^/]+)', $pattern) . '$#';
            $app->routes[] = [$regex, 'GET', "route$i"];
        }
        $app->routes[] = ['#^/api/users/(?P<id>\d+)$#', 'GET', 'user'];
        $app->routes[] = ['#^/hello$#', 'GET', 'hello'];
        return $app;
    }

    /** @return array<string, mixed> */
    public function handle(string $method, string $path): array
    {
        foreach ($this->routes as [$regex, $m, $name]) {
            if ($m === $method && preg_match($regex, $path, $args)) {
                $svc = $this->container->get('QhtExample\\Gen\\Service42');
                return [
                    'route' => $name,
                    'args' => array_filter($args, 'is_string', ARRAY_FILTER_USE_KEY),
                    'service' => $svc->name(),
                    'debug' => $this->config['c3']['key_7']['enabled'],
                ];
            }
        }
        return ['error' => 'not found'];
    }
}

<?php
// QHturbo Performance: the 3 backend calls run in parallel (~20 ms, not ~60 ms),
// and while they wait the worker serves other requests.
//   php runtime/bin/qhturbo-serve examples/03-async-io/app.php --port=8080 --workers=4 --concurrency=64
use QHTurbo\Runtime\Http\Client;
use QHTurbo\Runtime\Http\Request;
use function QHTurbo\Runtime\Async\{all, async, timeout};

$backend = getenv('QHT_BACKEND') ?: 'http://127.0.0.1:9000';

return static function (Request $r) use ($backend): array {
    $t = hrtime(true);
    $calls = [];
    foreach (['users', 'orders', 'stats'] as $name) {
        $calls[$name] = timeout(async(static fn () => Client::get("$backend/$name")), 2.0);
    }
    $out = array_map(static fn (array $res) => json_decode($res['body'], true), all($calls));
    return ['took_ms' => round((hrtime(true) - $t) / 1e6, 1), 'results' => $out];
};

<?php
// Classic PHP: 3 backend calls one after another, the process is blocked
// while it waits (3 x 20 ms = ~60 ms per request).
$backend = getenv('QHT_BACKEND') ?: 'http://127.0.0.1:9000';
$t = hrtime(true);
$out = [];
foreach (['users', 'orders', 'stats'] as $name) {
    $out[$name] = json_decode((string) file_get_contents("$backend/$name"), true);
}
header('Content-Type: application/json');
echo json_encode(['took_ms' => round((hrtime(true) - $t) / 1e6, 1), 'results' => $out]);

<?php
// A slow internal service: every call takes QHT_BACKEND_MS (default 20 ms),
// or ?ms=N for that call; ?fail=1 answers 500.
// Uses delay(), so one process answers many calls at once:
//   php runtime/bin/qhturbo-serve examples/03-async-io/backend.php --port=9000 --concurrency=1024
use QHTurbo\Runtime\Http\Request;
use QHTurbo\Runtime\Http\Response;
use function QHTurbo\Runtime\Async\delay;

$default = (int) (getenv('QHT_BACKEND_MS') ?: 20);

return static function (Request $r) use ($default): Response|array {
    $ms = isset($r->query['ms']) ? max(0, min(10000, (int) $r->query['ms'])) : $default;
    delay($ms / 1000);
    if (!empty($r->query['fail'])) {
        return Response::json(['error' => 'backend failure'], 500);
    }
    return ['service' => $r->path(), 'ms' => $ms, 'value' => random_int(1, 1000)];
};

<?php
// QHturbo Performance + async MySQL: the shop API.
// Queries that do not depend on each other run in parallel on pooled connections,
// and while MySQL works the worker serves other requests (--concurrency > 1).
//
//   php /opt/qhturbo-src/runtime/bin/qhturbo-serve app.php --port=8080 --workers=4 --concurrency=32
// or as a service: deploy/qhturbo-shop.service

declare(strict_types=1);

use QHTurbo\Runtime\Http\Request;
use QHTurbo\Runtime\Http\Response;
use QHTurbo\Runtime\Mysql\Client as Mysql;
use QHTurbo\Runtime\Mysql\Connection;
use QHTurbo\Runtime\Mysql\QueryException;
use QhtShop as Shop;

use function QHTurbo\Runtime\Async\{all, async};

require_once __DIR__ . '/shop.php';
$config = require __DIR__ . '/config.php';

// Booted once per worker: the pool, and the id ranges used by /orders/random.
$db = new Mysql($config['mysql_uri']);
$slow = $config['slow_ms'] / 1000;
$maxUser = (int) $db->query('SELECT COALESCE(MAX(id), 1) FROM users')->value();
$maxProduct = (int) $db->query('SELECT COALESCE(MAX(id), 1) FROM products')->value();
$q = static fn (string $sql, array $params = []) => async(static fn () => $db->query(Shop\SQL[$sql], $params));

$handlers = [
    'products' => static function (Request $r) use ($q): array {
        [$limit, $offset] = Shop\paging($r->query);
        [$rows, $count] = all([$q('products', [$limit, $offset]), $q('productCount')]);
        return ['total' => (int) $count->value(), 'limit' => $limit, 'offset' => $offset, 'items' => $rows->rows];
    },

    'product' => static function (Request $r, array $args) use ($q): Response|array {
        $id = (int) $args[0];
        [$product, $related, $stats] = all([$q('product', [$id]), $q('related', [$id, $id]), $q('reviewStats', [$id])]);
        if ($product->first() === null) {
            return Response::json(['error' => 'not found'], 404);
        }
        return ['product' => $product->first(), 'reviews' => $stats->first(), 'related' => $related->rows];
    },

    'dashboard' => static function () use ($q): array {
        $r = all([
            'users' => $q('users'), 'sales24h' => $q('sales24h'), 'topProducts' => $q('topProducts'),
            'latestOrders' => $q('latestOrders'), 'lowStock' => $q('lowStock'),
        ]);
        return [
            'users' => (int) $r['users']->value(),
            'sales_24h' => $r['sales24h']->first(),
            'top_products' => $r['topProducts']->rows,
            'latest_orders' => $r['latestOrders']->rows,
            'low_stock' => $r['lowStock']->rows,
        ];
    },

    'createOrder' => static function (Request $r) use ($db, $maxUser, $maxProduct): Response|array {
        try {
            $in = Shop\orderInput($r->path(), $r->parsedBody(), $maxUser, $maxProduct);
            // One connection, BEGIN ... COMMIT; any exception rolls back.
            return $db->transaction(static function (Connection $c) use ($in): array {
                $rows = $c->query(Shop\SQL['lockProducts'], [array_keys($in['items'])])->rows;
                $total = Shop\priceOrder($rows, $in['items']);
                $orderId = (int) $c->query(Shop\SQL['insertOrder'], [$in['user_id'], $total])->insertId;
                $prices = array_column($rows, 'price', 'id');
                foreach ($in['items'] as $pid => $qty) {
                    $c->query(Shop\SQL['insertItem'], [$orderId, $pid, $qty, $prices[$pid]]);
                    $c->query(Shop\SQL['takeStock'], [$qty, $pid]);
                }
                return ['order_id' => $orderId, 'total' => $total, 'items' => $in['items']];
            });
        } catch (\InvalidArgumentException $e) {
            return Response::json(['error' => $e->getMessage()], 422);
        } catch (\DomainException $e) {
            return Response::json(['error' => $e->getMessage()], 409);
        }
    },

    'slow' => static function () use ($q, $slow): array {
        $rows = all([$q('slow', [1, $slow]), $q('slow', [2, $slow]), $q('slow', [3, $slow])]);
        return ['queries' => 3, 'each_s' => $slow, 'rows' => array_map(static fn ($res) => $res->first(), $rows)];
    },

    'health' => static fn () => ['ok' => true, 'mode' => 'qhturbo-worker', 'pid' => getmypid(), 'pool' => $db->poolStats()],
];

return static function (Request $r) use ($handlers): Response|array {
    $match = Shop\route($r->method, $r->path());
    if ($match === null) {
        return Response::json(['error' => 'not found', 'routes' => array_map(static fn ($x) => "$x[0] " . trim($x[1], '#^$'), Shop\ROUTES)], 404);
    }
    $t = hrtime(true);
    try {
        $result = $handlers[$match[0]]($r, $match[1]);
    } catch (QueryException $e) {
        error_log('[shop] ' . $e->getMessage());
        return Response::json(['error' => 'database error', 'code' => $e->getCode()], 500);
    }
    if ($result instanceof Response) {
        return $result;
    }
    return ['took_ms' => round((hrtime(true) - $t) / 1e6, 2)] + $result;
};

<?php
// Routes and SQL shared by app.php (async worker) and fpm.php (PDO), so both
// sides run exactly the same queries.

declare(strict_types=1);

namespace QhtShop;

const ROUTES = [
    ['GET', '#^/products$#', 'products'],                 // ?page=1&per=20
    ['GET', '#^/products/(\d+)$#', 'product'],             // product + related + review stats
    ['GET', '#^/dashboard$#', 'dashboard'],                // 5 aggregate queries
    ['POST', '#^/orders$#', 'createOrder'],                // JSON {"user_id":1,"items":[{"product_id":2,"qty":1}]}
    ['GET', '#^/orders/random$#', 'createOrder'],          // benchmark helper: random order (writes to the DB!)
    ['GET', '#^/slow$#', 'slow'],                          // 3 x SLEEP(SLOW_MS): pure I/O wait
    ['GET', '#^/health$#', 'health'],
];

const SQL = [
    'products' => 'SELECT p.id, p.name, p.price, p.stock,
                          (SELECT c.name FROM categories c WHERE c.id = p.category_id) AS category
                   FROM products p ORDER BY p.id LIMIT ? OFFSET ?',
    'productCount' => 'SELECT COUNT(*) FROM products',
    'product' => 'SELECT p.*, c.name AS category FROM products p JOIN categories c ON c.id = p.category_id WHERE p.id = ?',
    'related' => 'SELECT id, name, price FROM products
                  WHERE category_id = (SELECT category_id FROM products WHERE id = ?) AND id <> ?
                  ORDER BY id DESC LIMIT 5',
    'reviewStats' => 'SELECT COUNT(*) AS reviews, ROUND(AVG(rating), 2) AS rating FROM reviews WHERE product_id = ?',
    'users' => 'SELECT COUNT(*) FROM users',
    'sales24h' => 'SELECT COUNT(*) AS orders, COALESCE(SUM(total), 0) AS revenue
                  FROM orders WHERE created_at >= NOW() - INTERVAL 1 DAY',
    'topProducts' => 'SELECT p.id, p.name, SUM(oi.qty) AS sold
                      FROM orders o JOIN order_items oi ON oi.order_id = o.id JOIN products p ON p.id = oi.product_id
                      WHERE o.created_at >= NOW() - INTERVAL 1 DAY
                      GROUP BY p.id, p.name ORDER BY sold DESC LIMIT 5',
    'latestOrders' => 'SELECT o.id, (SELECT u.name FROM users u WHERE u.id = o.user_id) AS customer, o.total, o.created_at
                       FROM orders o ORDER BY o.id DESC LIMIT 10',
    'lowStock' => 'SELECT id, name, stock FROM products WHERE stock < 5 ORDER BY stock, id LIMIT 10',
    'slow' => 'SELECT ? AS n, SLEEP(?) AS slept',
    // createOrder, inside one transaction:
    'lockProducts' => 'SELECT id, price, stock FROM products WHERE id IN (?) FOR UPDATE',
    'insertOrder' => "INSERT INTO orders (user_id, total, status) VALUES (?, ?, 'paid')",
    'insertItem' => 'INSERT INTO order_items (order_id, product_id, qty, price) VALUES (?, ?, ?, ?)',
    'takeStock' => 'UPDATE products SET stock = stock - ? WHERE id = ?',
];

/** @return array{0: string, 1: list<string>}|null handler name and captured args */
function route(string $method, string $path): ?array
{
    foreach (ROUTES as [$m, $regex, $name]) {
        if ($m === $method && preg_match($regex, $path, $args)) {
            return [$name, array_slice($args, 1)];
        }
    }
    return null;
}

/** @return array{0: int, 1: int} [limit, offset] */
function paging(array $query): array
{
    $per = max(1, min(100, (int) ($query['per'] ?? 20)));
    $page = max(1, (int) ($query['page'] ?? 1));
    return [$per, ($page - 1) * $per];
}

/**
 * The order to create: from the JSON body, or random for /orders/random.
 *
 * @return array{user_id: int, items: array<int, int>} product_id => qty
 */
function orderInput(string $path, array $body, int $maxUser, int $maxProduct): array
{
    if ($path === '/orders/random') {
        $items = [];
        for ($i = random_int(1, 3); $i > 0; $i--) {
            $items[random_int(1, $maxProduct)] = 1;
        }
        return ['user_id' => random_int(1, $maxUser), 'items' => $items];
    }
    $items = [];
    foreach ((array) ($body['items'] ?? []) as $it) {
        $pid = (int) ($it['product_id'] ?? 0);
        $qty = (int) ($it['qty'] ?? 0);
        if ($pid > 0 && $qty > 0 && $qty <= 100) {
            $items[$pid] = ($items[$pid] ?? 0) + $qty;
        }
    }
    if ($items === [] || (int) ($body['user_id'] ?? 0) < 1) {
        throw new \InvalidArgumentException('expected {"user_id": N, "items": [{"product_id": N, "qty": N}]}');
    }
    ksort($items);   // lock rows in a fixed order: avoids deadlocks between concurrent orders
    return ['user_id' => (int) $body['user_id'], 'items' => $items];
}

/**
 * Check stock for the locked rows and compute the total.
 *
 * @param list<array{id: int|string, price: string, stock: int|string}> $rows
 * @param array<int, int> $items
 */
function priceOrder(array $rows, array $items): float
{
    $byId = array_column($rows, null, 'id');
    $total = 0.0;
    foreach ($items as $pid => $qty) {
        if (!isset($byId[$pid])) {
            throw new \DomainException("product $pid does not exist");
        }
        if ((int) $byId[$pid]['stock'] < $qty) {
            throw new \DomainException("product $pid is out of stock");
        }
        $total += (float) $byId[$pid]['price'] * $qty;
    }
    return round($total, 2);
}

<?php
// The same shop API the classic way: PHP-FPM + PDO, every query waits for the
// previous one, and the process is blocked while MySQL works.
// nginx: SCRIPT_FILENAME = this file (see deploy/nginx-shop.conf). Requests
// may come with a "/fpm" prefix, which is stripped.

declare(strict_types=1);

use QhtShop as Shop;

require_once __DIR__ . '/shop.php';
$config = require __DIR__ . '/config.php';

$t = hrtime(true);
$path = (string) parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH);
$path = preg_replace('#^/fpm(?=/|$)#', '', $path) ?: '/';
$method = $_SERVER['REQUEST_METHOD'] ?? 'GET';

function respond(int $status, array $data): never
{
    http_response_code($status);
    header('Content-Type: application/json');
    echo json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
    exit;
}

$match = Shop\route($method, $path);
if ($match === null) {
    respond(404, ['error' => 'not found', 'routes' => array_map(static fn ($x) => "$x[0] " . trim($x[1], '#^$'), Shop\ROUTES)]);
}

$pdo = new PDO($config['pdo_dsn'], $config['db_user'], $config['db_pass'], [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
$run = static function (string $sql, array $params = []) use ($pdo): PDOStatement {
    $st = $pdo->prepare(Shop\SQL[$sql]);
    foreach (array_values($params) as $i => $v) {
        $st->bindValue($i + 1, $v, is_int($v) ? PDO::PARAM_INT : PDO::PARAM_STR);
    }
    $st->execute();
    return $st;
};
$args = $match[1];

try {
    $result = match ($match[0]) {
        'products' => (static function () use ($run) {
            [$limit, $offset] = Shop\paging($_GET);
            $items = $run('products', [$limit, $offset])->fetchAll();
            return ['total' => (int) $run('productCount')->fetchColumn(), 'limit' => $limit, 'offset' => $offset, 'items' => $items];
        })(),

        'product' => (static function () use ($run, $args) {
            $id = (int) $args[0];
            $product = $run('product', [$id])->fetch();
            if ($product === false) {
                respond(404, ['error' => 'not found']);
            }
            return ['product' => $product, 'reviews' => $run('reviewStats', [$id])->fetch(), 'related' => $run('related', [$id, $id])->fetchAll()];
        })(),

        'dashboard' => [
            'users' => (int) $run('users')->fetchColumn(),
            'sales_24h' => $run('sales24h')->fetch(),
            'top_products' => $run('topProducts')->fetchAll(),
            'latest_orders' => $run('latestOrders')->fetchAll(),
            'low_stock' => $run('lowStock')->fetchAll(),
        ],

        'createOrder' => (static function () use ($pdo, $run, $path) {
            $body = json_decode((string) file_get_contents('php://input'), true) ?: [];
            try {
                $maxUser = (int) $pdo->query('SELECT COALESCE(MAX(id), 1) FROM users')->fetchColumn();
                $maxProduct = (int) $pdo->query('SELECT COALESCE(MAX(id), 1) FROM products')->fetchColumn();
                $in = Shop\orderInput($path, $body, $maxUser, $maxProduct);
            } catch (InvalidArgumentException $e) {
                respond(422, ['error' => $e->getMessage()]);
            }
            $ids = array_keys($in['items']);
            // PDO cannot bind an array to IN (?): expand the placeholder.
            $lock = $pdo->prepare(str_replace('IN (?)', 'IN (' . implode(',', array_fill(0, count($ids), '?')) . ')', Shop\SQL['lockProducts']));
            $pdo->beginTransaction();
            try {
                $lock->execute($ids);
                $rows = $lock->fetchAll();
                $total = Shop\priceOrder($rows, $in['items']);
                $run('insertOrder', [$in['user_id'], (string) $total]);
                $orderId = (int) $pdo->lastInsertId();
                $prices = array_column($rows, 'price', 'id');
                foreach ($in['items'] as $pid => $qty) {
                    $run('insertItem', [$orderId, $pid, $qty, (string) $prices[$pid]]);
                    $run('takeStock', [$qty, $pid]);
                }
                $pdo->commit();
            } catch (Throwable $e) {
                $pdo->rollBack();
                if ($e instanceof DomainException) {
                    respond(409, ['error' => $e->getMessage()]);
                }
                throw $e;
            }
            return ['order_id' => $orderId, 'total' => $total, 'items' => $in['items']];
        })(),

        'slow' => (static function () use ($run, $config) {
            $s = $config['slow_ms'] / 1000;
            $rows = [];
            for ($i = 1; $i <= 3; $i++) {
                $rows[] = $run('slow', [$i, (string) $s])->fetch();
            }
            return ['queries' => 3, 'each_s' => $s, 'rows' => $rows];
        })(),

        'health' => ['ok' => true, 'mode' => 'php-fpm', 'pid' => getmypid()],
    };
} catch (PDOException $e) {
    error_log('[shop] ' . $e->getMessage());
    respond(500, ['error' => 'database error', 'code' => $e->getCode()]);
}

respond(200, ['took_ms' => round((hrtime(true) - $t) / 1e6, 2)] + $result);

<?php
// Shared configuration for app.php (QHturbo worker) and fpm.php (PHP-FPM).
// Values come from .env next to this file, then from real environment variables.

declare(strict_types=1);

return (static function (): array {
    $env = [];
    $file = __DIR__ . '/.env';
    if (is_file($file)) {
        foreach (file($file, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) as $line) {
            if ($line[0] === '#' || !str_contains($line, '=')) {
                continue;
            }
            [$k, $v] = explode('=', $line, 2);
            $env[trim($k)] = trim(trim($v), "\"'");
        }
    }
    $get = static fn (string $k, string $default = '') => getenv($k) !== false ? (string) getenv($k) : ($env[$k] ?? $default);

    $host = $get('DB_HOST', '127.0.0.1');
    $port = (int) $get('DB_PORT', '3306');
    $name = $get('DB_NAME', 'qht_shop');
    $user = $get('DB_USER', 'qht');
    $pass = $get('DB_PASS');
    $socket = $get('DB_SOCKET');
    $pool = max(1, (int) $get('DB_POOL', '16'));

    return [
        // QHturbo async client: mysql://user:pass@host:port/db?pool=N[&socket=...]
        'mysql_uri' => sprintf('mysql://%s:%s@%s:%d/%s?charset=utf8mb4&pool=%d%s',
            rawurlencode($user), rawurlencode($pass), $host, $port, rawurlencode($name), $pool,
            $socket !== '' ? '&socket=' . rawurlencode($socket) : ''),
        // PDO for fpm.php and seed.php
        'pdo_dsn' => $socket !== ''
            ? "mysql:unix_socket=$socket;dbname=$name;charset=utf8mb4"
            : "mysql:host=$host;port=$port;dbname=$name;charset=utf8mb4",
        'db_user' => $user,
        'db_pass' => $pass,
        'slow_ms' => max(0, (int) $get('SLOW_MS', '20')),
    ];
})();

# Copy to .env and edit. Read by config.php (both apps) and by the systemd unit.
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=qht_shop
DB_USER=qht
DB_PASS=change-me
# Unix socket instead of TCP, e.g. /run/mysqld/mysqld.sock or /tmp/mysql.sock (aaPanel). Empty = TCP.
DB_SOCKET=
# Async client: connections per worker (total = WORKERS x DB_POOL, keep under MySQL max_connections)
DB_POOL=16
# /slow route: each of its 3 queries runs SLEEP(SLOW_MS / 1000)
SLOW_MS=20
# qhturbo-serve (used by deploy/qhturbo-shop.service)
APP_PORT=8080
WORKERS=4
CONCURRENCY=32

-- QHturbo shop example schema (MySQL 5.7+/8.x, MariaDB 10.3+).
--   mysql -u root -p < schema.sql
-- Then create the user the apps connect with (edit the password):
--   CREATE USER 'qht'@'localhost' IDENTIFIED BY 'change-me';
--   GRANT ALL ON qht_shop.* TO 'qht'@'localhost';

CREATE DATABASE IF NOT EXISTS qht_shop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE qht_shop;

DROP TABLE IF EXISTS reviews, order_items, orders, products, categories, users;

CREATE TABLE users (
  id         INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name       VARCHAR(100) NOT NULL,
  email      VARCHAR(190) NOT NULL UNIQUE,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB;

CREATE TABLE categories (
  id   SMALLINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(100) NOT NULL
) ENGINE=InnoDB;

CREATE TABLE products (
  id          INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  category_id SMALLINT UNSIGNED NOT NULL,
  name        VARCHAR(190) NOT NULL,
  price       DECIMAL(10,2) NOT NULL,
  stock       INT NOT NULL DEFAULT 0,
  created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_category (category_id),
  KEY idx_stock (stock),
  CONSTRAINT fk_products_category FOREIGN KEY (category_id) REFERENCES categories (id)
) ENGINE=InnoDB;

CREATE TABLE orders (
  id         INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  user_id    INT UNSIGNED NOT NULL,
  total      DECIMAL(12,2) NOT NULL,
  status     ENUM('pending','paid','shipped','cancelled') NOT NULL DEFAULT 'paid',
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_created (created_at),
  KEY idx_user (user_id),
  CONSTRAINT fk_orders_user FOREIGN KEY (user_id) REFERENCES users (id)
) ENGINE=InnoDB;

CREATE TABLE order_items (
  order_id   INT UNSIGNED NOT NULL,
  product_id INT UNSIGNED NOT NULL,
  qty        SMALLINT UNSIGNED NOT NULL,
  price      DECIMAL(10,2) NOT NULL,
  PRIMARY KEY (order_id, product_id),
  KEY idx_product (product_id),
  CONSTRAINT fk_items_order FOREIGN KEY (order_id) REFERENCES orders (id) ON DELETE CASCADE,
  CONSTRAINT fk_items_product FOREIGN KEY (product_id) REFERENCES products (id)
) ENGINE=InnoDB;

CREATE TABLE reviews (
  id         INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  product_id INT UNSIGNED NOT NULL,
  user_id    INT UNSIGNED NOT NULL,
  rating     TINYINT UNSIGNED NOT NULL,
  body       VARCHAR(500) NOT NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_product (product_id),
  CONSTRAINT fk_reviews_product FOREIGN KEY (product_id) REFERENCES products (id),
  CONSTRAINT fk_reviews_user FOREIGN KEY (user_id) REFERENCES users (id)
) ENGINE=InnoDB;

<?php
// Fill the qht_shop database with test data (run once, after schema.sql).
//   php seed.php                       10k users, 5k products, 50k orders, 20k reviews
//   php seed.php --scale=0.2           a fifth of that (quick try)
//   php seed.php --scale=5             5x (closer to a real shop)
// Uses .env / config.php. Orders are spread over the last 30 days.

declare(strict_types=1);

$opts = getopt('', ['scale:']);
$scale = max(0.01, (float) ($opts['scale'] ?? 1));
$n = static fn (int $base) => max(10, (int) round($base * $scale));
[$users, $products, $orders, $reviews] = [$n(10000), $n(5000), $n(50000), $n(20000)];

$config = require __DIR__ . '/config.php';
$pdo = new PDO($config['pdo_dsn'], $config['db_user'], $config['db_pass'], [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$pdo->exec('SET FOREIGN_KEY_CHECKS = 0');
foreach (['reviews', 'order_items', 'orders', 'products', 'categories', 'users'] as $t) {
    $pdo->exec("TRUNCATE TABLE $t");
}
$pdo->exec('SET FOREIGN_KEY_CHECKS = 1');

/** Multi-row INSERT in batches of 1000 rows. */
function insert(PDO $pdo, string $table, array $cols, int $count, callable $row): void
{
    $t = microtime(true);
    $one = '(' . implode(',', array_fill(0, count($cols), '?')) . ')';
    for ($done = 0; $done < $count; $done += 1000) {
        $batch = min(1000, $count - $done);
        $values = [];
        for ($i = 1; $i <= $batch; $i++) {
            array_push($values, ...$row($done + $i));
        }
        $pdo->prepare("INSERT INTO $table (" . implode(',', $cols) . ') VALUES ' . implode(',', array_fill(0, $batch, $one)))
            ->execute($values);
    }
    printf("  %-12s %8s rows  %5.1f s\n", $table, number_format($count), microtime(true) - $t);
}

$ago = static fn (int $maxDays) => date('Y-m-d H:i:s', time() - random_int(0, $maxDays * 86400));
$cats = ['Laptop', 'Phone', 'Tablet', 'Audio', 'Camera', 'Gaming', 'Network', 'Storage', 'Monitor', 'Accessory'];

echo "Seeding (scale $scale)\n";
$pdo->beginTransaction();
insert($pdo, 'categories', ['name'], count($cats), static fn (int $i) => [$cats[$i - 1]]);
insert($pdo, 'users', ['name', 'email', 'created_at'], $users,
    static fn (int $i) => ["User $i", "[email protected]", $ago(365)]);
insert($pdo, 'products', ['category_id', 'name', 'price', 'stock', 'created_at'], $products,
    static fn (int $i) => [random_int(1, count($cats)), $cats[$i % count($cats)] . " model $i",
        number_format(random_int(500, 300000) / 100, 2, '.', ''), random_int(0, 50) < 2 ? random_int(0, 4) : random_int(50, 1000), $ago(365)]);
$pdo->commit();

// Orders and their items: prices are computed in PHP so the totals add up.
$pdo->beginTransaction();
$price = [];
foreach ($pdo->query('SELECT id, price FROM products') as $p) {
    $price[(int) $p['id']] = (float) $p['price'];
}
$items = [];
insert($pdo, 'orders', ['user_id', 'total', 'status', 'created_at'], $orders, static function (int $i) use (&$items, $price, $products, $users, $ago) {
    $total = 0.0;
    $picked = [];
    for ($k = random_int(1, 4); $k > 0; $k--) {
        $picked[random_int(1, $products)] = random_int(1, 3);
    }
    foreach ($picked as $pid => $qty) {
        $items[] = [$i, $pid, $qty, number_format($price[$pid], 2, '.', '')];
        $total += $price[$pid] * $qty;
    }
    return [random_int(1, $users), number_format($total, 2, '.', ''), ['paid', 'paid', 'shipped', 'cancelled'][random_int(0, 3)], $ago(30)];
});
insert($pdo, 'order_items', ['order_id', 'product_id', 'qty', 'price'], count($items), static fn (int $i) => $items[$i - 1]);
insert($pdo, 'reviews', ['product_id', 'user_id', 'rating', 'body', 'created_at'], $reviews,
    static fn (int $i) => [random_int(1, $products), random_int(1, $users), random_int(1, 5), "Review $i: " . str_repeat('good ', random_int(2, 20)), $ago(180)]);
$pdo->commit();
echo "Done.\n";

#!/usr/bin/env bash
# One-shot setup of the shop example on a test server (run as root from 04-mysql/).
#   sudo bash deploy/setup.sh                 uses .env (created from .env.example if missing)
#   SCALE=0.2 sudo -E bash deploy/setup.sh    smaller test data
# Steps: create database + user, load schema, seed data, install + start the
# systemd worker. nginx is left to you (deploy/nginx-shop.conf).
set -euo pipefail
cd "$(dirname "$0")/.."
[ -f .env ] || { cp .env.example .env; sed -i "s/^DB_PASS=.*/DB_PASS=$(head -c 12 /dev/urandom | base64 | tr -dc A-Za-z0-9)/" .env; echo "created .env with a random DB_PASS"; }
set -a; . ./.env; set +a
PHP="${PHP:-/opt/qhturbo/8.5/bin/php}"; [ -x "$PHP" ] || PHP=php
MYSQL="${MYSQL:-mysql}"   # aaPanel: /www/server/mysql/bin/mysql ; add -p if root needs a password

echo "== database $DB_NAME, user $DB_USER"
$MYSQL < schema.sql
$MYSQL -e "CREATE USER IF NOT EXISTS '$DB_USER'@'localhost' IDENTIFIED BY '$DB_PASS';
           CREATE USER IF NOT EXISTS '$DB_USER'@'127.0.0.1' IDENTIFIED BY '$DB_PASS';
           GRANT ALL ON \`$DB_NAME\`.* TO '$DB_USER'@'localhost';
           GRANT ALL ON \`$DB_NAME\`.* TO '$DB_USER'@'127.0.0.1'; FLUSH PRIVILEGES;"

echo "== test data"
"$PHP" seed.php --scale="${SCALE:-1}"

echo "== worker service"
sed "s#/opt/qhturbo/8.5/bin/php#$("$PHP" -r 'echo PHP_BINARY;')#" deploy/qhturbo-shop.service > /etc/systemd/system/qhturbo-shop.service
id www-data >/dev/null 2>&1 || sed -i 's/^User=www-data/User=www/; s/^Group=www-data/Group=www/' /etc/systemd/system/qhturbo-shop.service
chmod 640 .env; chgrp "$(sed -n 's/^Group=//p' /etc/systemd/system/qhturbo-shop.service)" .env
systemctl daemon-reload && systemctl enable --now qhturbo-shop && sleep 2
curl -fsS "http://127.0.0.1:$APP_PORT/health" && echo && echo "worker OK on 127.0.0.1:$APP_PORT"
echo "Next: add deploy/nginx-shop.conf to nginx, then: bash bench-server.sh http://<host>/fpm http://<host>/worker"

# nginx: one site serving the same shop API two ways, for side-by-side tests.
#   /fpm/...     -> PHP-FPM running fpm.php (classic, PDO)
#   /worker/...  -> qhturbo-serve running app.php (async MySQL)
# Copy to /etc/nginx/conf.d/qht-shop.conf (aaPanel: add the two location blocks
# to the site's config), edit server_name, the paths and the FPM socket,
# then: nginx -t && nginx -s reload

upstream qht_shop_worker {
    server 127.0.0.1:8080;      # APP_PORT in .env
    keepalive 64;
}

server {
    listen 80;
    server_name shop-test.example.com;   # or an IP; restrict access while testing

    # Optional: only allow your own IP while benchmarking
    # allow 203.0.113.10; deny all;

    location /fpm/ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME /opt/qhturbo-src/examples/04-mysql/fpm.php;
        # QHturbo PHP-FPM: /run/qhturbo/php85-fpm.sock
        # aaPanel PHP 8.3:  /tmp/php-cgi-83.sock      Ubuntu php8.3-fpm: /run/php/php8.3-fpm.sock
        fastcgi_pass unix:/run/qhturbo/php85-fpm.sock;
    }

    location /worker/ {
        proxy_pass http://qht_shop_worker/;   # trailing slash strips the /worker prefix
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 30s;
    }
}

# systemd unit for the async shop worker.
#   sudo cp deploy/qhturbo-shop.service /etc/systemd/system/
#   sudo systemctl daemon-reload && sudo systemctl enable --now qhturbo-shop
#   journalctl -u qhturbo-shop -f          # logs
#   sudo systemctl reload qhturbo-shop     # zero-downtime reload after editing app.php
# Edit the paths if your PHP or checkout live elsewhere. Settings come from .env.
[Unit]
Description=QHturbo shop example (async MySQL worker)
After=network.target mysql.service mariadb.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/opt/qhturbo-src/examples/04-mysql
EnvironmentFile=/opt/qhturbo-src/examples/04-mysql/.env
ExecStart=/opt/qhturbo/8.5/bin/php /opt/qhturbo-src/runtime/bin/qhturbo-serve /opt/qhturbo-src/examples/04-mysql/app.php \
    --host=127.0.0.1 --port=${APP_PORT} --workers=${WORKERS} --concurrency=${CONCURRENCY} \
    --max-requests=100000 --memory-limit=256M
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGTERM
TimeoutStopSec=70
Restart=on-failure
RestartSec=2
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

#!/usr/bin/env bash
# Benchmark the shop API on a real server: PHP-FPM + PDO vs QHturbo workers + async MySQL.
#
#   bash bench-server.sh http://127.0.0.1/fpm http://127.0.0.1/worker
#   C=128 D=20 P=2 WRITE=1 bash bench-server.sh <FPM_URL> <WORKER_URL>
#
# C = connections (64), D = seconds per test (15), P = client processes (1),
# WRITE=1 also benchmarks /orders/random (creates real orders in the database).
# Run it from another machine on the same network if you can; otherwise keep
# in mind that the client uses CPU on the server too.
set -euo pipefail
cd "$(dirname "$0")"
FPM_URL="${1:?usage: bench-server.sh FPM_URL WORKER_URL}"; WORKER_URL="${2:?usage: bench-server.sh FPM_URL WORKER_URL}"
PHP="${PHP:-php}"; C="${C:-64}"; D="${D:-15}"; P="${P:-1}"
BENCH="${BENCH:-../bench.php}"
MAXP=$("$PHP" -r '$c = require "config.php"; $p = new PDO($c["pdo_dsn"], $c["db_user"], $c["db_pass"]); echo $p->query("SELECT MAX(id) FROM products")->fetchColumn();' 2>/dev/null || echo 5000)

ROUTES=("/health" "/products?page={rand:50}" "/products/{rand:$MAXP}" "/dashboard" "/slow")
[ "${WRITE:-0}" = 1 ] && ROUTES+=("/orders/random")

for base in "$FPM_URL" "$WORKER_URL"; do
  curl -fsS "$base/health" >/dev/null || { echo "cannot reach $base/health"; exit 1; }
done

printf "\n%-26s | %-36s | %-36s | %s\n" "route ($C conn, ${D}s)" "PHP-FPM + PDO" "QHturbo + async MySQL" "speed-up"
printf -- "-%.0s" {1..118}; echo
for r in "${ROUTES[@]}"; do
  a=$("$PHP" "$BENCH" "$FPM_URL$r" -c "$C" -d "$D" -p "$P" --json)
  b=$("$PHP" "$BENCH" "$WORKER_URL$r" -c "$C" -d "$D" -p "$P" --json)
  "$PHP" -r '
    [$r, $a, $b] = [$argv[1], json_decode($argv[2], true), json_decode($argv[3], true)];
    $f = fn ($j) => sprintf("%9s req/s  p99 %7.1f ms  e%d", number_format($j["rps"], 1), $j["latency_ms"]["p99"] ?? 0,
        $j["errors"] + array_sum(array_filter($j["status"], fn ($k) => $k >= 500, ARRAY_FILTER_USE_KEY)));
    printf("%-26s | %-36s | %-36s | %5.1fx\n", $r, $f($a), $f($b), $b["rps"] / max(0.1, $a["rps"]));
  ' "$r" "$a" "$b"
done
echo
echo "e = transport errors + 5xx answers. Run each test 2-3 times; numbers on shared VMs move by ~10%."

<?php
// CPU micro-benchmarks: measure the PHP interpreter itself, with or without JIT,
// or compare two PHP binaries (e.g. the system PHP vs /opt/qhturbo/8.5/bin/php).
//
//   php cpu.php                         run once with the current settings
//   php cpu.php --compare               interpreter vs OPcache vs JIT (tracing), same binary
//   php cpu.php --compare --php=/usr/bin/php8.3,/opt/qhturbo/8.5/bin/php
//   php cpu.php --runs=5 --quick --json

declare(strict_types=1);

$opts = getopt('', ['compare', 'php:', 'runs:', 'quick', 'json', 'only:']);
$runs = max(1, (int) ($opts['runs'] ?? 3));
$scale = isset($opts['quick']) ? 0.25 : 1.0;

/** @return array<string, \Closure(): mixed> */
function workloads(float $scale): array
{
    return [
        'fib (recursion)' => static function () use ($scale) {
            $fib = static function (int $n) use (&$fib): int { return $n < 2 ? $n : $fib($n - 1) + $fib($n - 2); };
            return $fib($scale < 1 ? 25 : 28);
        },
        'nbody (float math)' => static function () use ($scale) {
            $b = [[0, 0, 0, 0, 0, 0, 39.47], [4.84, -1.16, -0.10, 0.60, 2.81, -0.02, 0.037],
                  [8.34, 4.12, -0.40, -1.01, 1.82, 0.008, 0.011], [12.89, -15.11, -0.22, 1.08, 0.86, -0.01, 0.0017],
                  [15.37, -25.91, 0.17, 0.97, 0.59, -0.03, 0.002]];
            $n = count($b);
            for ($s = 0, $steps = (int) (200000 * $scale); $s < $steps; $s++) {
                for ($i = 0; $i < $n; $i++) {
                    for ($j = $i + 1; $j < $n; $j++) {
                        $dx = $b[$i][0] - $b[$j][0]; $dy = $b[$i][1] - $b[$j][1]; $dz = $b[$i][2] - $b[$j][2];
                        $d2 = $dx * $dx + $dy * $dy + $dz * $dz; $mag = 0.01 / ($d2 * sqrt($d2));
                        $b[$i][3] -= $dx * $b[$j][6] * $mag; $b[$i][4] -= $dy * $b[$j][6] * $mag; $b[$i][5] -= $dz * $b[$j][6] * $mag;
                        $b[$j][3] += $dx * $b[$i][6] * $mag; $b[$j][4] += $dy * $b[$i][6] * $mag; $b[$j][5] += $dz * $b[$i][6] * $mag;
                    }
                }
                foreach ($b as &$p) { $p[0] += 0.01 * $p[3]; $p[1] += 0.01 * $p[4]; $p[2] += 0.01 * $p[5]; }
                unset($p);
            }
            return round($b[0][0], 6);
        },
        'mandelbrot (loops)' => static function () use ($scale) {
            $size = (int) (400 * sqrt($scale)); $inside = 0;
            for ($y = 0; $y < $size; $y++) {
                for ($x = 0; $x < $size; $x++) {
                    $cr = 2.0 * $x / $size - 1.5; $ci = 2.0 * $y / $size - 1.0; $zr = $zi = 0.0; $i = 0;
                    while ($i < 50 && $zr * $zr + $zi * $zi < 4.0) { $t = $zr * $zr - $zi * $zi + $cr; $zi = 2.0 * $zr * $zi + $ci; $zr = $t; $i++; }
                    if ($i === 50) { $inside++; }
                }
            }
            return $inside;
        },
        'hash map (arrays)' => static function () use ($scale) {
            $m = [];
            for ($i = 0, $n = (int) (1000000 * $scale); $i < $n; $i++) { $k = 'k' . ($i % 50000); $m[$k] = ($m[$k] ?? 0) + $i; }
            ksort($m);
            return count($m);
        },
        'strings' => static function () use ($scale) {
            $s = '';
            for ($i = 0, $n = (int) (300000 * $scale); $i < $n; $i++) { $s .= strtoupper(substr(md5((string) $i), 0, 8)) . ','; }
            return strlen(str_replace('A', 'b', $s)) + count(explode(',', $s));
        },
        'json encode/decode' => static function () use ($scale) {
            $data = [];
            for ($i = 0; $i < 2000; $i++) { $data[] = ['id' => $i, 'name' => "user$i", 'tags' => ['a', 'b', 'c'], 'score' => $i / 3]; }
            $len = 0;
            for ($r = 0, $n = (int) (60 * $scale); $r < $n; $r++) { $len += count(json_decode(json_encode($data), true)); }
            return $len;
        },
        'objects (OOP)' => static function () use ($scale) {
            $sum = 0;
            for ($i = 0, $n = (int) (1000000 * $scale); $i < $n; $i++) { $p = new ArrayObject([$i, $i + 1]); $sum += $p[1] - $p[0]; }
            return $sum;
        },
    ];
}

function runAll(int $runs, float $scale, ?string $only): array
{
    $out = [];
    foreach (workloads($scale) as $name => $fn) {
        if ($only !== null && stripos($name, $only) === false) { continue; }
        $fn(); // warm-up (also lets the JIT compile)
        $best = INF;
        for ($r = 0; $r < $runs; $r++) {
            $t = hrtime(true); $fn(); $best = min($best, (hrtime(true) - $t) / 1e6);
        }
        $out[$name] = round($best, 2);
    }
    return $out;
}

function mode(): string
{
    $oc = function_exists('opcache_get_status') ? @opcache_get_status(false) : false;
    $jit = is_array($oc) && !empty($oc['jit']['on']);
    return PHP_VERSION . ($jit ? ' JIT ' . ini_get('opcache.jit') : (is_array($oc) && $oc['opcache_enabled'] ? ' OPcache' : ' interpreter'));
}

if (!isset($opts['compare'])) {
    $res = runAll($runs, $scale, $opts['only'] ?? null);
    if (isset($opts['json'])) { echo json_encode(['mode' => mode(), 'ms' => $res]), "\n"; exit; }
    printf("PHP %s, best of %d runs (ms, lower is better)\n", mode(), $runs);
    foreach ($res as $n => $ms) { printf("  %-22s %10.2f\n", $n, $ms); }
    exit;
}

// --compare: re-run this script in child processes with different settings.
$bins = isset($opts['php']) ? explode(',', $opts['php']) : [PHP_BINARY];
$configs = [];
foreach ($bins as $bin) {
    $configs[] = [$bin, ['-d', 'opcache.enable_cli=0']];
    $configs[] = [$bin, ['-d', 'opcache.enable_cli=1', '-d', 'opcache.jit=disable']];
    $configs[] = [$bin, ['-d', 'opcache.enable_cli=1', '-d', 'opcache.jit_buffer_size=64M', '-d', 'opcache.jit=tracing']];
}
$pass = ['--json', "--runs=$runs"];
if (isset($opts['quick'])) { $pass[] = '--quick'; }
if (isset($opts['only'])) { $pass[] = '--only=' . $opts['only']; }

$cols = [];
foreach ($configs as [$bin, $ini]) {
    $cmd = array_merge([$bin], $ini, [__FILE__], $pass);
    fwrite(STDERR, '> ' . implode(' ', $cmd) . "\n");
    $p = proc_open($cmd, [1 => ['pipe', 'w'], 2 => STDERR], $pipes);
    $json = stream_get_contents($pipes[1]); proc_close($p);
    $row = json_decode((string) $json, true);
    if (!is_array($row)) { fwrite(STDERR, "  failed: $json\n"); continue; }
    $label = $row['mode'] . (count($bins) > 1 ? ' (' . basename(dirname($bin, 2)) . '/' . basename($bin) . ')' : '');
    $cols[$label] = $row['ms'];
}
if (!$cols) { exit(1); }
$labels = array_keys($cols);
$base = $cols[$labels[0]];
printf("\n%-22s", 'ms (speed-up)');
foreach ($labels as $l) { printf(" | %-24s", substr($l, 0, 24)); }
echo "\n", str_repeat('-', 22 + 27 * count($labels)), "\n";
$geo = array_fill_keys($labels, 0.0);
foreach ($base as $name => $ms0) {
    printf('%-22s', $name);
    foreach ($labels as $l) {
        $ms = $cols[$l][$name]; $geo[$l] += log($ms0 / $ms);
        printf(' | %9.1f  (%5.2fx)      ', $ms, $ms0 / $ms);
    }
    echo "\n";
}
printf('%-22s', 'geometric mean');
foreach ($labels as $l) { printf(' |            %5.2fx      ', exp($geo[$l] / count($base))); }
echo "\n";

<?php
// Small helpers built on QHturbo's Future, for patterns the runtime does not
// ship as functions: settle, race, mapLimit, retry.

declare(strict_types=1);

namespace QhtExample\Async;

use QHTurbo\Runtime\Async\Future;
use function QHTurbo\Runtime\Async\{async, await, delay};

if (!\function_exists(__NAMESPACE__ . '\\settle')) {
    /**
     * Like all(), but never throws: waits for every future and reports each one
     * as ['ok' => true, 'value' => ...] or ['ok' => false, 'error' => '...'].
     *
     * @param array<array-key, Future> $futures
     * @return array<array-key, array{ok: bool, value?: mixed, error?: string}>
     */
    function settle(array $futures): array
    {
        $out = [];
        foreach ($futures as $key => $future) {
            try {
                $out[$key] = ['ok' => true, 'value' => await($future)];
            } catch (\Throwable $e) {
                $out[$key] = ['ok' => false, 'error' => $e::class . ': ' . $e->getMessage()];
            }
        }
        return $out;
    }

    /**
     * The first future to finish wins (value or error). Returns [key, value].
     * The others keep running in the background; their results are ignored.
     *
     * @param array<array-key, Future> $futures
     * @return array{0: array-key, 1: mixed}
     */
    function race(array $futures): array
    {
        $winner = new Future();
        foreach ($futures as $key => $future) {
            $future->onDone(static function (?\Throwable $error, mixed $value) use ($winner, $key): void {
                if ($winner->isDone()) {
                    return;
                }
                $error === null ? $winner->resolve([$key, $value]) : $winner->fail($error);
            });
        }
        return await($winner);
    }

    /**
     * Run $fn over $items with at most $limit calls in flight at once
     * (protects a backend or a connection pool). Keys are preserved.
     *
     * @template T
     * @param array<array-key, mixed> $items
     * @param callable(mixed, array-key): T $fn
     * @return array<array-key, T>
     */
    function mapLimit(array $items, int $limit, callable $fn): array
    {
        $keys = array_keys($items);
        $next = 0;
        $results = [];
        $lanes = [];
        for ($lane = 0; $lane < max(1, $limit); $lane++) {
            $lanes[] = async(static function () use (&$next, $keys, $items, $fn, &$results): void {
                while ($next < count($keys)) {
                    $key = $keys[$next++];
                    $results[$key] = $fn($items[$key], $key);
                }
            });
        }
        foreach ($lanes as $l) {
            await($l);
        }
        $ordered = [];
        foreach ($keys as $key) {
            $ordered[$key] = $results[$key];
        }
        return $ordered;
    }

    /**
     * Call $fn up to $attempts times, waiting $backoff, 2*$backoff, ... seconds
     * between failures (non-blocking). Rethrows the last error.
     */
    function retry(callable $fn, int $attempts = 3, float $backoff = 0.05): mixed
    {
        for ($i = 1; ; $i++) {
            try {
                return $fn($i);
            } catch (\Throwable $e) {
                if ($i >= $attempts) {
                    throw $e;
                }
                delay($backoff * 2 ** ($i - 1));
            }
        }
    }
}

<?php
// Async basics from the command line, no web server needed.
//   php examples/06-async/demo.php            (from the QHTurbo repository root)
//   QHT_RUNTIME=/path/to/QHTurbo/runtime php demo.php
//
// Outside a fiber, await() drives the event loop itself, so plain CLI scripts
// can use async() too.

declare(strict_types=1);

$runtime = getenv('QHT_RUNTIME') ?: __DIR__ . '/../../runtime';
require $runtime . '/src/autoload.php';
require __DIR__ . '/lib.php';

use QHTurbo\Runtime\Async\TimeoutException;
use QHTurbo\Runtime\EventLoop\Loop;
use function QHTurbo\Runtime\Async\{all, async, await, delay, timeout};
use function QhtExample\Async\{mapLimit, race, retry, settle};

/** A fake service call that takes $ms milliseconds (non-blocking). */
function fakeCall(string $name, int $ms, bool $fail = false): string
{
    delay($ms / 1000);
    if ($fail) {
        throw new RuntimeException("$name failed");
    }
    return "$name ($ms ms)";
}

function step(string $title, callable $fn): void
{
    // Timed inside the fiber: that is when a request handler would get the result.
    await(async(static function () use ($title, $fn): void {
        $t = hrtime(true);
        $result = $fn();
        printf("%-46s %7.1f ms  %s\n", $title, (hrtime(true) - $t) / 1e6, json_encode($result, JSON_UNESCAPED_UNICODE));
    }));
}

echo "QHturbo async demo (PHP " . PHP_VERSION . ")\n\n";

step('1. sequential: 3 calls x 100 ms', fn () => [
    fakeCall('a', 100), fakeCall('b', 100), fakeCall('c', 100),
]);

step('2. all(): the same 3 calls in parallel', fn () => all([
    'a' => async(fn () => fakeCall('a', 100)),
    'b' => async(fn () => fakeCall('b', 100)),
    'c' => async(fn () => fakeCall('c', 100)),
]));

// Note: timeout() stops waiting, it does not cancel the slow call, which
// finishes in the background (the script waits for it before step 4).
step('3. timeout(): give up after 150 ms', function () {
    try {
        return await(timeout(async(fn () => fakeCall('slow', 1000)), 0.15));
    } catch (TimeoutException $e) {
        return 'timed out: ' . $e->getMessage();
    }
});

step('4. all() rethrows the error of a failed call', function () {
    try {
        return all([async(fn () => fakeCall('ok', 50)), async(fn () => fakeCall('bad', 80, true))]);
    } catch (RuntimeException $e) {
        return 'caught: ' . $e->getMessage();
    }
});

step('5. settle(): keep every result, errors too', fn () => settle([
    'users' => async(fn () => fakeCall('users', 60)),
    'ads' => async(fn () => fakeCall('ads', 40, true)),
    'stats' => async(fn () => fakeCall('stats', 80)),
]));

step('6. race(): fastest replica wins', fn () => race([
    'replica-1' => async(fn () => fakeCall('replica-1', 120)),
    'replica-2' => async(fn () => fakeCall('replica-2', 30)),
    'replica-3' => async(fn () => fakeCall('replica-3', 90)),
]));

step('7. mapLimit(): 20 jobs x 50 ms, 5 at a time', fn () => count(
    mapLimit(range(1, 20), 5, fn (int $n) => fakeCall("job$n", 50))
) . ' jobs done (~200 ms = 20 / 5 x 50)');

step('8. retry(): fails twice, then succeeds', function () {
    return retry(function (int $attempt) {
        return fakeCall("attempt $attempt", 20, $attempt < 3);
    }, attempts: 3, backoff: 0.05);
});

step('9. Loop timers: repeat() every 25 ms, 4 ticks', function () {
    $ticks = [];
    $done = new QHTurbo\Runtime\Async\Future();
    $id = Loop::get()->repeat(0.025, function () use (&$ticks, &$id, $done) {
        $ticks[] = count($ticks) + 1;
        if (count($ticks) === 4) {
            Loop::get()->cancel($id);
            $done->resolve();
        }
    });
    await($done);
    return $ticks;
});

echo "\nIn a web worker, every await() above lets the same process serve other requests meanwhile.\n";

<?php
// Async patterns inside a web worker. Needs the backend from 03-async-io:
//   php runtime/bin/qhturbo-serve examples/03-async-io/backend.php --port=9000 --concurrency=1024 &
//   php runtime/bin/qhturbo-serve examples/06-async/app.php --port=8080 --workers=2 --concurrency=64
// Optional Redis cache for /cache:  QHT_REDIS=redis://127.0.0.1:6379/0
//
//   curl localhost:8080/fanout        3 calls in parallel with all()
//   curl localhost:8080/settle        partial results when one call fails
//   curl localhost:8080/race          fastest of 3 replicas
//   curl localhost:8080/timeout       a slow call cut at 100 ms, with a fallback
//   curl "localhost:8080/limit?n=20&limit=5"   20 calls, at most 5 at a time
//   curl localhost:8080/retry         retries a flaky call with back-off
//   curl localhost:8080/cache         Redis cache-aside (needs QHT_REDIS)

use QHTurbo\Runtime\Async\TimeoutException;
use QHTurbo\Runtime\Http\Client;
use QHTurbo\Runtime\Http\Request;
use QHTurbo\Runtime\Http\Response;
use QHTurbo\Runtime\Redis\Client as Redis;
use function QHTurbo\Runtime\Async\{all, async, await, timeout};
use function QhtExample\Async\{mapLimit, race, retry, settle};

require __DIR__ . '/lib.php';

$backend = rtrim(getenv('QHT_BACKEND') ?: 'http://127.0.0.1:9000', '/');
$redis = getenv('QHT_REDIS') ? new Redis(getenv('QHT_REDIS'), poolSize: 16) : null;

/** GET the backend and decode JSON; throws on transport errors and non-2xx answers. */
$call = static function (string $path) use ($backend): array {
    $res = Client::get($backend . $path, 2.0);
    if ($res['status'] >= 300) {
        throw new RuntimeException("$path answered {$res['status']}");
    }
    return json_decode($res['body'], true);
};

$routes = [
    '/fanout' => static fn () => all([
        'users' => async($call, '/users'),
        'orders' => async($call, '/orders'),
        'stats' => async($call, '/stats'),
    ]),

    '/settle' => static fn () => settle([
        'users' => async($call, '/users'),
        'ads' => async($call, '/ads?fail=1'),     // this one fails, the page still renders
        'stats' => async($call, '/stats'),
    ]),

    '/race' => static function () use ($call) {
        [$winner, $value] = race([
            'replica-a' => async($call, '/item?ms=' . random_int(5, 60)),
            'replica-b' => async($call, '/item?ms=' . random_int(5, 60)),
            'replica-c' => async($call, '/item?ms=' . random_int(5, 60)),
        ]);
        return ['winner' => $winner, 'answer' => $value];
    },

    '/timeout' => static function () use ($call) {
        try {
            return ['recommendations' => await(timeout(async($call, '/recommendations?ms=500'), 0.1))];
        } catch (TimeoutException) {
            return ['recommendations' => [], 'note' => 'slow service skipped after 100 ms'];
        }
    },

    '/limit' => static function (Request $r) use ($call) {
        $n = max(1, min(200, (int) ($r->query['n'] ?? 20)));
        $limit = max(1, min(50, (int) ($r->query['limit'] ?? 5)));
        $items = mapLimit(range(1, $n), $limit, static fn (int $i) => $call("/item/$i")['value']);
        return ['items' => count($items), 'limit' => $limit, 'sum' => array_sum($items)];
    },

    '/retry' => static function () use ($call) {
        $log = [];
        $value = retry(static function (int $attempt) use ($call, &$log) {
            $log[] = "attempt $attempt";
            return $call('/flaky' . ($attempt < 3 ? '?fail=1' : ''));   // fails twice
        }, attempts: 3, backoff: 0.02);
        return ['value' => $value, 'log' => $log];
    },

    '/cache' => static function () use ($call, $redis) {
        if ($redis === null) {
            return Response::json(['error' => 'set QHT_REDIS=redis://127.0.0.1:6379/0'], 501);
        }
        if (($hit = $redis->get('qht:example:dashboard')) !== null) {
            return ['cache' => 'hit', 'data' => json_decode($hit, true)];
        }
        $data = all(['users' => async($call, '/users'), 'stats' => async($call, '/stats')]);
        $redis->set('qht:example:dashboard', json_encode($data), 'EX', 5);
        return ['cache' => 'miss', 'data' => $data];
    },
];

return static function (Request $r) use ($routes): Response|array {
    $route = $routes[$r->path()] ?? null;
    if ($route === null) {
        return ['routes' => array_keys($routes)];
    }
    $t = hrtime(true);
    $result = $route($r);
    if ($result instanceof Response) {
        return $result;
    }
    return ['took_ms' => round((hrtime(true) - $t) / 1e6, 1)] + $result;
};

<?php
// A small HTTP load generator in PHP (needs the curl extension; pcntl for -p > 1).
// Keeps C requests in flight for D seconds and reports requests/s and latency.
//
//   php bench.php http://127.0.0.1:8080/hello -c 64 -d 10
//   php bench.php http://127.0.0.1:8080/ -c 128 -d 15 -p 4      # 4 client processes
//   php bench.php URL --json                                      # machine-readable
//   php bench.php "http://127.0.0.1:8080/products/{rand:5000}"    # random id 1..5000 per request
//
// For more than ~10-20k req/s the client itself becomes the limit: use more
// processes (-p) or a native tool such as wrk. Run it on another machine, or
// keep the server's worker count below the CPU count, so client and server do
// not fight for the same CPUs.

declare(strict_types=1);

if (!extension_loaded('curl')) { fwrite(STDERR, "bench.php needs the curl extension\n"); exit(1); }

$args = $argv; array_shift($args);
$url = null; $c = 32; $d = 10.0; $procs = 1; $json = false; $warm = 1.0;
while ($args) {
    $a = array_shift($args);
    match (true) {
        $a === '-c' => $c = max(1, (int) array_shift($args)),
        $a === '-d' => $d = max(0.5, (float) array_shift($args)),
        $a === '-p' => $procs = max(1, (int) array_shift($args)),
        $a === '-w' => $warm = max(0.0, (float) array_shift($args)),
        $a === '--json' => $json = true,
        default => $url = $a,
    };
}
if ($url === null) {
    fwrite(STDERR, "usage: php bench.php URL [-c concurrency=32] [-d seconds=10] [-p processes=1] [-w warmup=1] [--json]\n");
    exit(1);
}

/** Runs the load from one process; returns [latencies ms, status counts, errors, bytes]. */
function load(string $url, int $conc, float $seconds, float $warm): array
{
    $mh = curl_multi_init();
    curl_multi_setopt($mh, CURLMOPT_MAX_HOST_CONNECTIONS, $conc);
    $lat = []; $codes = []; $errors = 0; $bytes = 0;
    $start = microtime(true); $measureFrom = $start + $warm; $end = $measureFrom + $seconds;
    $handles = [];
    $add = static function () use ($mh, $url, &$handles): void {
        $h = curl_init(preg_replace_callback('/\{rand:(\d+)\}/', static fn ($m) => (string) random_int(1, max(1, (int) $m[1])), $url));
        curl_setopt_array($h, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_TCP_NODELAY => true,
            CURLOPT_HTTPHEADER => ['Connection: keep-alive'], CURLOPT_FORBID_REUSE => false]);
        $handles[(int) $h] = [$h, hrtime(true)];
        curl_multi_add_handle($mh, $h);
    };
    for ($i = 0; $i < $conc; $i++) { $add(); }
    do {
        curl_multi_exec($mh, $running);
        curl_multi_select($mh, 0.05);
        while ($info = curl_multi_info_read($mh)) {
            $h = $info['handle']; [, $t0] = $handles[(int) $h]; unset($handles[(int) $h]);
            $now = microtime(true);
            if ($now >= $measureFrom && $now < $end) {
                if ($info['result'] === CURLE_OK) {
                    $code = curl_getinfo($h, CURLINFO_RESPONSE_CODE);
                    $codes[$code] = ($codes[$code] ?? 0) + 1;
                    $lat[] = (hrtime(true) - $t0) / 1e6;
                    $bytes += strlen((string) curl_multi_getcontent($h));
                } else {
                    $errors++;
                }
            }
            curl_multi_remove_handle($mh, $h); curl_close($h);
            if ($now < $end) { $add(); }
        }
    } while ($handles);
    curl_multi_close($mh);
    return [$lat, $codes, $errors, $bytes];
}

$per = intdiv($c, $procs) ?: 1;
if ($procs === 1) {
    $results = [load($url, $c, $d, $warm)];
} else {
    if (!function_exists('pcntl_fork')) { fwrite(STDERR, "-p needs the pcntl extension\n"); exit(1); }
    $files = [];
    for ($i = 0; $i < $procs; $i++) {
        $files[$i] = tempnam(sys_get_temp_dir(), 'qhtb');
        if (pcntl_fork() === 0) {
            file_put_contents($files[$i], serialize(load($url, $per, $d, $warm)));
            exit(0);
        }
    }
    while (pcntl_wait($status) > 0);
    $results = array_map(static fn ($f) => unserialize((string) file_get_contents($f)) ?: [[], [], 1, 0], $files);
    array_map('unlink', $files);
}

$lat = []; $codes = []; $errors = 0; $bytes = 0;
foreach ($results as [$l, $cs, $e, $b]) {
    array_push($lat, ...$l); $errors += $e; $bytes += $b;
    foreach ($cs as $k => $v) { $codes[$k] = ($codes[$k] ?? 0) + $v; }
}
sort($lat);
$n = count($lat);
$pct = static fn (float $p) => $n ? round($lat[min($n - 1, (int) floor($p / 100 * $n))], 2) : null;
$out = [
    'url' => $url, 'concurrency' => $procs > 1 ? $per * $procs : $c, 'processes' => $procs, 'seconds' => $d,
    'requests' => $n, 'rps' => round($n / $d, 1), 'errors' => $errors, 'status' => $codes,
    'latency_ms' => ['avg' => $n ? round(array_sum($lat) / $n, 2) : null, 'p50' => $pct(50), 'p90' => $pct(90), 'p99' => $pct(99), 'max' => $n ? round(end($lat), 2) : null],
    'kb_per_s' => round($bytes / 1024 / $d, 1),
];
if ($json) { echo json_encode($out), "\n"; exit; }
ksort($codes);
printf("%s  (%d connections, %d process%s, %.0f s)\n", $url, $out['concurrency'], $procs, $procs > 1 ? 'es' : '', $d);
printf("  Requests/s : %s\n", number_format($out['rps'], 1));
printf("  Latency ms : avg %.2f  p50 %.2f  p90 %.2f  p99 %.2f  max %.2f\n", ...array_values($out['latency_ms']));
printf("  Status     : %s   errors: %d\n", implode('  ', array_map(static fn ($k, $v) => "$k x$v", array_keys($codes), $codes)) ?: '-', $errors);

#!/usr/bin/env bash
# Compare "classic" PHP (the script runs from the top on every request, like
# PHP-FPM) with QHturbo Performance (long-lived workers) on the same example.
#
#   ./compare.sh hello | framework | async-io | mysql | all
#
# Environment:
#   PHP=php                     PHP binary (8.1+), e.g. /opt/qhturbo/8.5/bin/php
#   QHT_SERVE=...               path to runtime/bin/qhturbo-serve
#                               (default: ../runtime/bin/qhturbo-serve, i.e. examples/ inside the repo)
#   WORKERS=2                   PHP processes on each side (keep below the CPU count)
#   C=64 D=10 P=1               bench.php concurrency, seconds, client processes
#   CLASSIC_URL=http://...      benchmark your real nginx + PHP-FPM instead of "php -S"
#                               (point it at the example's fpm.php)
set -euo pipefail
cd "$(dirname "$0")"
EX="${1:-all}"
PHP="${PHP:-php}"
QHT_SERVE="${QHT_SERVE:-../runtime/bin/qhturbo-serve}"
WORKERS="${WORKERS:-2}"; C="${C:-64}"; D="${D:-10}"; P="${P:-1}"
OPC=(-d opcache.enable_cli=1 -d opcache.validate_timestamps=0 -d memory_limit=512M)
PIDS=()
cleanup() { for p in "${PIDS[@]}"; do kill "$p" 2>/dev/null || true; done; wait 2>/dev/null || true; }
trap cleanup EXIT

[ -f "$QHT_SERVE" ] || { echo "qhturbo-serve not found at $QHT_SERVE (set QHT_SERVE)"; exit 1; }

wait_port() { for _ in $(seq 1 100); do (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null && return 0; sleep 0.1; done; echo "port $1 did not open"; exit 1; }

bench() { "$PHP" bench.php "$1" -c "$C" -d "$D" -p "$P" --json; }

row() { # name json
  "$PHP" -r '$j=json_decode($argv[2],true); printf("  %-34s %10s req/s   p50 %7.2f ms   p99 %8.2f ms   errors %d\n",
     $argv[1], number_format($j["rps"],1), $j["latency_ms"]["p50"], $j["latency_ms"]["p99"], $j["errors"]);' "$1" "$2"
}

speedup() { "$PHP" -r '$a=json_decode($argv[1],true); $b=json_decode($argv[2],true); printf("  => QHturbo is %.1fx the requests/s of classic PHP\n\n", $b["rps"]/max(0.1,$a["rps"]));' "$1" "$2"; }

run_one() { # dir path concurrency extra-serve-args
  local dir=$1 path=$2 conc=$3; shift 3
  echo "== $dir  ($WORKERS processes each, $C connections, ${D}s)"
  local classic_url="${CLASSIC_URL:-}"
  if [ -z "$classic_url" ]; then
    PHP_CLI_SERVER_WORKERS=$WORKERS "$PHP" "${OPC[@]}" -S 127.0.0.1:8081 "$dir/fpm.php" >/dev/null 2>&1 & PIDS+=($!)
    wait_port 8081; classic_url="http://127.0.0.1:8081$path"
  fi
  "$PHP" "${OPC[@]}" "$QHT_SERVE" "$dir/app.php" --port=8082 --workers="$WORKERS" --concurrency="$conc" "$@" >/dev/null 2>&1 & PIDS+=($!)
  wait_port 8082
  local a b
  a=$(bench "$classic_url"); row "classic (php -S / FPM)" "$a"
  b=$(bench "http://127.0.0.1:8082$path"); row "QHturbo workers (concurrency $conc)" "$b"
  speedup "$a" "$b"
  cleanup; PIDS=()
}

start_backend() {
  "$PHP" "${OPC[@]}" "$QHT_SERVE" 03-async-io/backend.php --port=9000 --concurrency=1024 --max-connections=1000 >/dev/null 2>&1 & PIDS+=($!)
  wait_port 9000
}

case "$EX" in
  hello)     run_one 01-hello /hello 1 ;;
  framework) run_one 02-framework /api/users/42 1 ;;
  async-io)  start_backend; run_one 03-async-io / 64 ;;
  mysql)     run_one 04-mysql /slow 32 ;;      # needs 04-mysql/.env + schema.sql + seed.php first
  all)       run_one 01-hello /hello 1; run_one 02-framework /api/users/42 1; start_backend; run_one 03-async-io / 64 ;;
  *) echo "usage: $0 hello|framework|async-io|mysql|all"; exit 1 ;;
esac