Fonctions PHP

OxPHP enregistre ses fonctions via l'extension oxphp_sapi, qui se charge automatiquement pour chaque script PHP exécuté par le serveur. Aucune directive extension= ni aucun chargement manuel n'est requis. Chaque fonction listée ici est disponible dès la première ligne de votre code PHP.

Table des matières

oxphp_http_request()

php
oxphp_http_request(): \OxPHP\Http\Request

Renvoie l'objet requête de la requête HTTP courante. L'objet fournit un accès typé à la méthode HTTP, à l'URI, aux paramètres de requête, au corps analysé, aux en-têtes, aux cookies, aux fichiers téléversés, à l'IP du client et au timing de la requête.

Renvoie : une instance \OxPHP\Http\Request adossée aux données de requête du thread worker PHP courant.

Lève : une exception de l'espace de noms OxPHP\Http\Exception lorsqu'elle est appelée en dehors d'une requête active :

Exception Situation
\OxPHP\Http\Exception\WorkerIdleException Mode worker, entre deux requêtes
\OxPHP\Http\Exception\AsyncContextException À l'intérieur d'un callback oxphp_async()
\OxPHP\Http\Exception\NoActiveRequestException Tout autre contexte sans requête active

Dans le code normal de traitement des requêtes, aucune gestion d'exception n'est requise.

Exemple :

php
<?php $request = oxphp_http_request(); $method = $request->method(); // "POST" $path = $request->path(); // "/api/users" $email = $request->payload('email'); // from JSON or form body $token = $request->header('Authorization'); $theme = $request->cookie('theme', 'light');

Pour la référence complète de l'interface, consultez la documentation HTTP Request API.

oxphp_superglobals_enabled()

php
oxphp_superglobals_enabled(): bool

Indique si le remplissage des superglobales est activé pour cette instance de serveur. La valeur reflète la variable d'environnement SUPERGLOBALS_ENABLED et ne change pas pendant la durée de vie du serveur.

Lorsqu'elle vaut false, $_GET, $_POST, $_COOKIE, $_FILES et $_SERVER sont des tableaux vides. L'API objet HTTP (oxphp_http_request()), php://input et les fonctions de session PHP ne sont pas affectés.

Renvoie : true lorsque SUPERGLOBALS_ENABLED vaut true (la valeur par défaut), false sinon.

Exemple :

php
<?php if (oxphp_superglobals_enabled()) { $query = $_GET['page'] ?? 1; } else { $query = oxphp_http_request()->query('page', 1); }

oxphp_request_id()

php
oxphp_request_id(): string

Renvoie l'identifiant unique de la requête courante. Il s'agit de la même valeur envoyée dans l'en-tête de réponse X-Request-ID. Si le client envoie un en-tête X-Request-ID, OxPHP le transmet tel quel au lieu d'en générer un nouveau.

Renvoie : une chaîne hexadécimale de 20 caractères lorsque OxPHP génère l'ID (par exemple "67890abc12341a2b0042"). Lorsque le client envoie un en-tête X-Request-ID, cette valeur est renvoyée telle quelle (1 à 64 caractères, alphanumériques plus -, _, .).

Exemple :

php
<?php $id = oxphp_request_id(); error_log("[$id] Processing order #1234"); // Propagate the ID to downstream services header("X-Correlation-ID: $id");

oxphp_worker_id()

php
oxphp_worker_id(): int

Renvoie l'indice à base zéro du thread worker PHP qui traite la requête courante. Les indices de worker vont de 0 à PHP_WORKERS - 1.

Renvoie : un entier identifiant le thread worker courant.

Exemple :

php
<?php $workerId = oxphp_worker_id(); // Use per-worker temp files to avoid collisions $tmp = "/tmp/worker_{$workerId}_buffer.dat"; error_log("Worker $workerId handling request");

oxphp_server_info()

php
oxphp_server_info(): array

Renvoie un tableau associatif contenant les métadonnées du serveur et de la requête.

Renvoie : un tableau avec les clés suivantes :

Clé Type Description
version string Version du serveur (par exemple "0.10.0")
worker_id int Même valeur que oxphp_worker_id()
request_time float Horodatage Unix avec précision à la microseconde au moment où la requête a démarré
worker_mode bool Indique si le processus courant s'exécute en mode worker

Exemple :

php
<?php $info = oxphp_server_info(); // [ // "version" => "0.10.0", // "worker_id" => 3, // "request_time" => 1738800000.123456, // "worker_mode" => true, // ] $elapsed = microtime(true) - $info['request_time']; echo "Processing took {$elapsed}s so far";

oxphp_finish_request()

php
oxphp_finish_request(): bool

Vide la réponse vers le client et poursuit l'exécution PHP en arrière-plan. Le client reçoit immédiatement la réponse HTTP complète ; le script continue de s'exécuter jusqu'à ce qu'il se termine naturellement. C'est l'équivalent OxPHP de fastcgi_finish_request() dans PHP-FPM.

Renvoie : true en cas de succès, false si déjà appelée pour cette requête.

Note

Le thread worker PHP reste occupé jusqu'à la fin du script. Gardez le travail d'arrière-plan court ou déchargez les traitements lourds vers une file d'attente.

Exemple :

php
<?php http_response_code(202); echo json_encode(['status' => 'accepted']); oxphp_finish_request(); // The client already has its 202 response; continue working send_notification_email($user); update_analytics($event);

oxphp_is_worker()

php
oxphp_is_worker(): bool

Indique si le serveur s'exécute en mode worker. Le mode worker s'active lorsque WORKER_MODE_ENABLED=true.

Renvoie : true en mode worker, false en mode traditionnel.

Exemple :

php
<?php if (oxphp_is_worker()) { // Reuse persistent connections across requests $db = $GLOBALS['db'] ??= new PDO($dsn); } else { // Traditional mode: create a new connection per request $db = new PDO($dsn); }

oxphp_worker()

php
oxphp_worker(callable $handler): bool

Entre dans la boucle persistante du mode worker. OxPHP appelle $handler une fois pour chaque requête HTTP entrante. Entre deux requêtes, une réinitialisation légère efface l'état propre à la requête — tampons de sortie, en-têtes et superglobales — sans détruire le tas PHP, de sorte que toute variable déclarée en dehors du handler persiste d'une requête à l'autre.

Paramètres :

  • $handler — Appelé une fois par requête. Le handler ne reçoit aucun argument. Utilisez les superglobales ($_SERVER, $_GET, $_POST, etc.) ou oxphp_http_request() à l'intérieur du handler pour accéder aux données de la requête.

Renvoie : true lors d'un arrêt gracieux, false si vous n'êtes pas en mode worker.

La boucle worker se termine dès que l'une des conditions suivantes est remplie :

  • Le serveur s'arrête gracieusement
  • Le handler lève 3 exceptions non interceptées ou erreurs fatales consécutives
  • Le worker dépasse WORKER_MAX_MEMORY_MIB
  • L'application appelle Worker::scheduleExit()
Note

oxphp_worker() ne fonctionne qu'en mode worker (WORKER_MODE_ENABLED=true). En mode traditionnel, elle consigne un avertissement et renvoie false.

Exemple :

worker.php
<?php // worker.php — runs once per worker process lifetime // Bootstrap: executed once on startup require __DIR__ . '/vendor/autoload.php'; $app = new App(); // Handle requests in a loop oxphp_worker(function () use ($app) { $app->handle(); }); // Code after oxphp_worker() runs during shutdown $app->terminate();

oxphp_is_streaming()

php
oxphp_is_streaming(): bool

Indique si la requête courante est en mode streaming. Le mode streaming s'active au premier appel à oxphp_stream_flush() ou automatiquement lorsque PHP définit Content-Type: text/event-stream.

Renvoie : true si le mode streaming est actif, false sinon.

Exemple :

php
<?php if (oxphp_is_streaming()) { echo "data: " . json_encode($event) . "\n\n"; oxphp_stream_flush(); } else { echo json_encode($allData); }

oxphp_stream_flush()

php
oxphp_stream_flush(): bool

Active le mode streaming et vide toute sortie mise en tampon vers le client sous forme de chunk HTTP. Au premier appel, les en-têtes HTTP sont envoyés immédiatement et le streaming commence. Chaque appel suivant vide la sortie écrite depuis le dernier vidage.

Renvoie : true en cas de succès, false si oxphp_finish_request() a déjà été appelée.

Note

Le mode streaming s'active aussi automatiquement lorsque PHP définit Content-Type: text/event-stream. Dans ce cas, vous pouvez utiliser la fonction native flush() de PHP, mais appelez d'abord ob_end_flush() pour contourner la couche de mise en tampon de sortie de PHP.

Exemple :

php
<?php header('Content-Type: text/event-stream'); header('Cache-Control: no-cache'); for ($i = 0; $i < 10; $i++) { echo "id: $i\n"; echo "data: " . json_encode(['counter' => $i]) . "\n\n"; oxphp_stream_flush(); oxphp_sleep(1.0); // use oxphp_sleep instead of sleep — does not block the worker in fiber mode }

oxphp_sleep()

php
oxphp_sleep(float $seconds): void

Met en pause pendant la durée spécifiée. À l'intérieur d'un handler du mode worker s'exécutant dans une Fiber, cet appel est coopératif — il suspend la Fiber courante afin que d'autres requêtes puissent être traitées pendant l'attente. En dehors d'une Fiber, il retombe sur un usleep() bloquant standard.

Paramètres :

  • $seconds — Durée de la pause en secondes. Les valeurs fractionnaires sont acceptées (par exemple 0.5 pour 500 millisecondes). Les valeurs de 0 ou moins retournent immédiatement.

Renvoie : void

Exemple :

php
<?php oxphp_worker(function () { // In worker mode with fiber multiplexing: // this suspends the fiber rather than blocking the thread oxphp_sleep(1.0); echo json_encode(['done' => true]); });

oxphp_usleep()

php
oxphp_usleep(int $microseconds): void

Met en pause pendant le nombre de microsecondes spécifié. Comme oxphp_sleep(), cet appel est coopératif à l'intérieur d'une Fiber et retombe sinon sur un usleep() bloquant.

Paramètres :

  • $microseconds — Durée de la pause en microsecondes. Les valeurs de 0 ou moins retournent immédiatement.

Renvoie : void

Exemple :

php
<?php oxphp_worker(function () { // Poll for a condition every 100ms without blocking other requests while (!$condition_met()) { oxphp_usleep(100_000); } echo "ready"; });

oxphp_async()

php
oxphp_async(Closure $closure, mixed ...$args): int

Distribue une closure pour exécution sur un thread worker asynchrone dédié et renvoie immédiatement un ID de promesse. L'appelant poursuit son exécution sans attendre la fin de la closure. Utilisez oxphp_async_await() pour récupérer le résultat.

Paramètres :

  • $closure — Une Closure définie par l'utilisateur à exécuter sur un thread worker asynchrone
  • ...$args — Arguments à passer à la closure. Les valeurs scalaires (null, bool, int, float, string), les tableaux de celles-ci et les instances OxPHP\Shared\* (les seuls objets autorisés à franchir la frontière entre threads) sont acceptés. Les ressources et tout objet non-Shared sont rejetés.

Renvoie : un ID de promesse entier. Passez-le à oxphp_async_await(), oxphp_async_await_all(), oxphp_async_await_race() ou oxphp_async_await_any().

Lève : OxPHP\Async\AsyncException dans les cas suivants :

  • Le pool asynchrone est désactivé (ASYNC_WORKERS=0) — message : "Async pool is disabled. Set ASYNC_WORKERS > 0 to enable."
  • La closure n'est pas définie par l'utilisateur
  • Le pool asynchrone est plein (tous les emplacements de la file sont occupés)
  • Les arguments ou les variables use contiennent des objets ou des ressources
Note

Les variables capturées via use dans la closure suivent les mêmes restrictions — les objets et les ressources sont rejetés.

Exemple :

php
<?php // Dispatch two independent tasks concurrently $p1 = oxphp_async(function () { return fetch_from_api('/users'); }); $p2 = oxphp_async(function () { return fetch_from_api('/posts'); }); // Retrieve both results $users = oxphp_async_await($p1); $posts = oxphp_async_await($p2);

oxphp_async_await()

php
oxphp_async_await(int $promise_id, float $timeout = 0.0): mixed

Bloque jusqu'à ce que la promesse asynchrone spécifiée s'achève et renvoie son résultat. À l'intérieur d'une Fiber du mode worker, cet appel suspend la Fiber courante de manière coopérative plutôt que de bloquer le thread.

Paramètres :

  • $promise_id — Un ID de promesse renvoyé par oxphp_async()
  • $timeout — Nombre maximal de secondes à attendre. 0.0 signifie attendre indéfiniment. Par défaut : 0.0

Renvoie : la valeur de retour de la closure asynchrone.

Lève :

  • OxPHP\Async\AsyncException si le pool asynchrone est désactivé (ASYNC_WORKERS=0), ou si la tâche asynchrone a levé une exception
  • OxPHP\Async\TimeoutException si $timeout est dépassé

Exemple :

php
<?php $promise = oxphp_async(function (int $n) { return array_sum(range(1, $n)); }, 1_000_000); $result = oxphp_async_await($promise); echo $result; // 500000500000 // With timeout try { $result = oxphp_async_await($promise, 5.0); } catch (\OxPHP\Async\TimeoutException $e) { echo "Task took too long"; }

oxphp_async_await_all()

php
oxphp_async_await_all(array $promise_ids, float $timeout = 0.0): array

Attend toutes les promesses du tableau et renvoie un tableau associatif faisant correspondre chaque ID de promesse à son résultat. Les promesses sont attendues dans l'ordre du tableau.

Paramètres :

  • $promise_ids — Un tableau d'ID de promesse entiers renvoyés par oxphp_async()
  • $timeout — Nombre maximal de secondes à attendre par promesse. 0.0 signifie attendre indéfiniment. Par défaut : 0.0

Renvoie : un tableau associatif où chaque clé est un ID de promesse (entier) et chaque valeur est le résultat de cette promesse.

Lève :

  • OxPHP\Async\AsyncException si le pool asynchrone est désactivé (ASYNC_WORKERS=0), ou si une promesse échoue
  • OxPHP\Async\TimeoutException si une promesse dépasse $timeout

Exemple :

php
<?php $promises = [ oxphp_async(fn() => slow_query('users')), oxphp_async(fn() => slow_query('orders')), oxphp_async(fn() => slow_query('products')), ]; $results = oxphp_async_await_all($promises); foreach ($results as $promiseId => $result) { // process $result }

oxphp_async_await_race()

php
oxphp_async_await_race(array $promise_ids, float $timeout = 0.0): array

Met plusieurs promesses en concurrence et renvoie la première à se résoudre, qu'elle soit tenue ou rejetée. Les autres promesses ne sont pas annulées — elles continuent de s'exécuter et restent attendables avec oxphp_async_await(). C'est l'équivalent de Promise.race en JavaScript.

Paramètres :

  • $promise_ids — Un tableau d'au moins un ID de promesse entier renvoyé par oxphp_async(). Ne doit pas être vide.
  • $timeout — Nombre maximal de secondes à attendre qu'une promesse se résolve. 0.0 signifie attendre indéfiniment. Par défaut : 0.0

Renvoie : un tableau associatif à deux clés :

  • id (int) — L'ID de promesse du gagnant
  • value (mixed) — La valeur de retour de la promesse gagnante

Lève :

  • OxPHP\Async\AsyncException si le pool asynchrone est désactivé (ASYNC_WORKERS=0), ou si la promesse gagnante a été rejetée
  • OxPHP\Async\TimeoutException si aucune promesse ne se résout dans le délai $timeout

Exemple :

php
<?php // Try two mirror endpoints; use whichever responds first $p1 = oxphp_async(fn() => fetch('https://mirror-1.example.com/data')); $p2 = oxphp_async(fn() => fetch('https://mirror-2.example.com/data')); $winner = oxphp_async_await_race([$p1, $p2], timeout: 10.0); echo "Mirror {$winner['id']} won: " . json_encode($winner['value']);

oxphp_async_await_any()

php
oxphp_async_await_any(array $promise_ids, float $timeout = 0.0): array

Retourne dès qu'une promesse est TENUE. Les rejets sont accumulés et ne deviennent observables que si toutes les promesses sont rejetées. C'est l'équivalent de Promise.any en JavaScript — utile pour les schémas de repli / redondance où l'on veut n'importe quelle source qui fonctionne.

Paramètres :

  • $promise_ids — Un tableau d'au moins un ID de promesse entier renvoyé par oxphp_async(). Ne doit pas être vide.
  • $timeout — Nombre maximal de secondes à attendre le premier accomplissement. 0.0 signifie attendre indéfiniment. Par défaut : 0.0

Renvoie : un tableau associatif à deux clés :

  • id (int) — L'ID de la première promesse tenue
  • value (mixed) — La valeur de retour de la promesse gagnante

Lève :

  • OxPHP\Async\AsyncException si le pool asynchrone est désactivé (ASYNC_WORKERS=0)
  • OxPHP\Async\AggregateAsyncException si toutes les promesses ont été rejetées. L'exception transporte chaque erreur via getErrors() (positionnel, indexé 0..N-1), getErrorMap() (indexé par id) et getPromiseIds().
  • OxPHP\Async\TimeoutException si aucune promesse n'a été tenue dans le délai $timeout. getPartialErrors() liste les promesses qui avaient déjà été rejetées avant l'échéance ; getCancelledPromiseIds() liste celles qui ne s'étaient pas résolues et ont donc été annulées. Leur drapeau d'annulation est positionné et leurs récepteurs sont abandonnés — passer l'un de ces ids à oxphp_async_await*() par la suite lève "unknown or already-awaited promise id". Cette liste est une piste d'audit, pas une file de travail reprenable.

Comportement :

  • Les promesses encore en attente au moment de la victoire restent attendables individuellement avec oxphp_async_await().
  • Les promesses déjà rejetées avant la gagnante ne le sont pas — leurs résultats ont été consommés lorsqu'ils ont été accumulés comme erreurs candidates.

Exemple :

php
<?php $mirror_a = oxphp_async(fn() => fetch('https://mirror-a.example.com/data')); $mirror_b = oxphp_async(fn() => fetch('https://mirror-b.example.com/data')); $mirror_c = oxphp_async(fn() => fetch('https://mirror-c.example.com/data')); try { $winner = oxphp_async_await_any([$mirror_a, $mirror_b, $mirror_c], 5.0); echo "Mirror {$winner['id']} responded: " . json_encode($winner['value']); } catch (\OxPHP\Async\AggregateAsyncException $e) { // every mirror rejected foreach ($e->getErrorMap() as $promise_id => $err) { error_log("mirror {$promise_id}: " . $err->getMessage()); } } catch (\OxPHP\Async\TimeoutException $e) { // deadline elapsed before any mirror fulfilled $partial = $e->getPartialErrors(); $cancelled = $e->getCancelledPromiseIds(); }

oxphp_register_decorator()

php
oxphp_register_decorator(string $class): bool

Enregistre une classe PHP comme décorateur qui enveloppe les appels de fonctions et de méthodes. La classe doit implémenter OxPHP\Decorator\AttributeInterface. Une fois enregistrée, OxPHP invoque les hooks before() et after() du décorateur autour de chaque appel de fonction ou de méthode qui correspond aux cibles #[Attribute] du décorateur.

Paramètres :

  • $class — Le nom de classe pleinement qualifié du décorateur à enregistrer

Renvoie : true en cas de succès, false si la classe n'existe pas ou n'implémente pas OxPHP\Decorator\AttributeInterface.

Exemple :

php
<?php use OxPHP\Decorator\AttributeInterface; use OxPHP\Decorator\Context; #[\Attribute(\Attribute::TARGET_METHOD)] class LogDecorator implements AttributeInterface { public function before(Context $ctx): void { error_log("Calling {$ctx->target} (request {$ctx->requestId})"); } public function after(Context $ctx): void { error_log("Finished {$ctx->target}"); } } // Register once at bootstrap (or worker startup) oxphp_register_decorator(LogDecorator::class);

oxphp_apm_trace()

php
oxphp_apm_trace(string $name, callable $callback, ?array $attributes = null): void

Exécute un callback à l'intérieur d'un span nommé. Le span est ouvert avant l'exécution du callback et fermé après son retour. Réservé à une future intégration améliorée des callbacks.

Paramètres :

  • $name — Nom du span
  • $callback — Callable à exécuter à l'intérieur du span
  • $attributes — Tableau associatif facultatif d'attributs clé-valeur de type chaîne

Renvoie : void

oxphp_apm_start()

php
oxphp_apm_start(string $name, ?array $attributes = null): int

Ouvre un nouveau span et renvoie un ID local pour référence ultérieure. Le span devient un enfant du span actuellement actif (ou du span racine de la requête si aucun span n'est actif). Utilisez oxphp_apm_end() pour le fermer.

Paramètres :

  • $name — Nom du span (par exemple "cache.warm", "payment.process")
  • $attributes — Tableau associatif facultatif d'attributs clé-valeur de type chaîne à définir sur le span à sa création

Renvoie : un ID de span local entier. Passez-le à oxphp_apm_end(), oxphp_apm_attribute() ou à d'autres fonctions qui acceptent un $span_id. Renvoie 0 lorsque l'APM est désactivé.

Exemple :

php
<?php $spanId = oxphp_apm_start('order.validate', [ 'order.type' => 'subscription', ]); validateOrder($order); oxphp_apm_end($spanId);

oxphp_apm_end()

php
oxphp_apm_end(int $span_id): void

Ferme le span ouvert par oxphp_apm_start(). L'heure de fin du span est enregistrée et il passe de la pile active à la liste des spans terminés, prêt pour l'export.

Paramètres :

  • $span_id — L'ID de span local renvoyé par oxphp_apm_start()

Renvoie : void

Note

Fermez toujours les spans dans l'ordre inverse. Si vous ouvrez le span A puis le span B, fermez B avant A. Les spans non fermés sont automatiquement fermés à la fin de la requête et marqués avec oxphp.span.leaked=true.

oxphp_apm_attribute()

php
oxphp_apm_attribute(string $key, mixed $value, ?int $span_id = null): void

Définit un attribut clé-valeur sur un span. Les valeurs sont converties en chaînes. Si aucun $span_id n'est fourni, l'attribut est ajouté au span actuellement actif.

Paramètres :

  • $key — Clé de l'attribut (par exemple "user.id", "cache.hit")
  • $value — Valeur de l'attribut (string, int, float, bool ou null -- convertie en chaîne)
  • $span_id — ID de span local facultatif. S'il est omis, cible le span courant

Renvoie : void

Exemple :

php
<?php $spanId = oxphp_apm_start('db.query'); oxphp_apm_attribute('db.system', 'mysql'); oxphp_apm_attribute('db.statement', 'SELECT * FROM users WHERE id = ?'); oxphp_apm_attribute('db.row_count', $rowCount, $spanId); oxphp_apm_end($spanId);

oxphp_apm_event()

php
oxphp_apm_event(string $name, ?array $attributes = null, ?int $span_id = null): void

Enregistre un événement horodaté sur un span. Les événements sont utiles pour consigner des occurrences discrètes au cours de la durée de vie d'un span (par exemple un cache miss, une tentative de réessai, une vérification d'autorisation).

Paramètres :

  • $name — Nom de l'événement (par exemple "cache.miss", "retry")
  • $attributes — Tableau associatif facultatif d'attributs d'événement clé-valeur de type chaîne
  • $span_id — ID de span local facultatif. S'il est omis, cible le span courant

Renvoie : void

Exemple :

php
<?php $spanId = oxphp_apm_start('payment.process'); oxphp_apm_event('payment.authorized', [ 'provider' => 'stripe', 'amount' => '49.99', ]); oxphp_apm_end($spanId);

oxphp_apm_error()

php
oxphp_apm_error(mixed $exception, ?int $span_id = null): void

Marque le statut d'un span comme erreur (code de statut 2). Utilisez ceci pour signaler les spans où une exception ou un échec s'est produit.

Paramètres :

  • $exception — L'exception ou l'erreur (utilisée pour le contexte ; le statut est défini quel que soit le type)
  • $span_id — ID de span local facultatif. S'il est omis, cible le span courant

Renvoie : void

Exemple :

php
<?php $spanId = oxphp_apm_start('external.api'); try { $result = callExternalApi(); } catch (\Throwable $e) { oxphp_apm_error($e, $spanId); throw $e; } finally { oxphp_apm_end($spanId); }

oxphp_apm_status()

php
oxphp_apm_status(int $code, ?string $description = null, ?int $span_id = null): void

Définit le code de statut et une description facultative sur un span.

Paramètres :

  • $code — Code de statut : 0 = Unset, 1 = Ok, 2 = Error
  • $description — Description de statut facultative, lisible par un humain
  • $span_id — ID de span local facultatif. S'il est omis, cible le span courant

Renvoie : void

Exemple :

php
<?php $spanId = oxphp_apm_start('validation'); if ($valid) { oxphp_apm_status(1, 'Validation passed', $spanId); } else { oxphp_apm_status(2, 'Invalid input: missing email', $spanId); } oxphp_apm_end($spanId);

oxphp_apm_trace_id()

php
oxphp_apm_trace_id(): string

Renvoie l'ID de trace W3C (32 caractères hexadécimaux) pour le contexte de trace de la requête courante. C'est la même valeur que $_SERVER['OXPHP_TRACE_ID'], disponible sans les superglobales.

Renvoie : une chaîne d'ID de trace hexadécimale de 32 caractères. Renvoie une chaîne vide lorsque l'APM est désactivé ou qu'aucun contexte de trace n'est actif.

Exemple :

php
<?php $traceId = oxphp_apm_trace_id(); error_log("Processing request in trace {$traceId}");

oxphp_apm_span_id()

php
oxphp_apm_span_id(): string

Renvoie l'ID de span (16 caractères hexadécimaux) du span actuellement actif. En cas de spans imbriqués, renvoie l'ID du span ouvert le plus interne.

Renvoie : une chaîne d'ID de span hexadécimale de 16 caractères. Renvoie une chaîne vide lorsqu'aucun span n'est actif.

oxphp_apm_header()

php
oxphp_apm_header(): string

Renvoie une valeur d'en-tête traceparent W3C pour le contexte de span courant. Utilisez ceci pour propager le contexte de trace vers les appels HTTP en aval.

Renvoie : une chaîne au format 00-{trace_id}-{span_id}-01. Renvoie une chaîne vide lorsqu'aucun contexte de trace n'est actif.

Exemple :

php
<?php $spanId = oxphp_apm_start('http.call'); $traceparent = oxphp_apm_header(); $response = file_get_contents('https://api.example.com/data', false, stream_context_create([ 'http' => [ 'header' => "traceparent: {$traceparent}\r\n", ], ]) ); oxphp_apm_end($spanId);

OxPHP\Profile\is_active()

php
OxPHP\Profile\is_active(): bool

Renvoie true lorsque la capture de profil est actuellement active pour cette requête — c'est-à-dire que le profileur a été déclenché (par en-tête, cookie, paramètre de requête ou taux d'échantillonnage) et que la capture n'a pas été mise en pause via pause().

Utile pour protéger une instrumentation coûteuse qui ne devrait s'exécuter que lorsque le profilage est activé.

Renvoie : bool.

Exemple :

php
<?php if (OxPHP\Profile\is_active()) { OxPHP\Profile\mark('checkpoint.before_query'); }

OxPHP\Profile\start()

php
OxPHP\Profile\start(): void

Active par programmation la capture de profil pour le reste de la requête courante, même si aucun déclencheur ne s'est activé au RINIT. Définit le mode de profilage sur PROFILE_ALL et efface le drapeau de pause.

Si un profil était déjà actif dans un mode différent, cet appel le promeut — tout span déjà collecté dans le mode inférieur est écarté afin que le profil capturé reste cohérent en interne. Utilisez ceci lorsque vous voulez faire adhérer un chemin de code spécifique au profilage sans dépendre des déclencheurs.

Renvoie : void.

Exemple :

php
<?php if ($request->header('x-debug') === 'on') { OxPHP\Profile\start(); }

OxPHP\Profile\stop()

php
OxPHP\Profile\stop(): void

Désactive toute nouvelle capture de span pour cette requête. Les spans actuellement ouverts se ferment naturellement à mesure que PHP en retourne, de sorte que la pile d'appels reste équilibrée — seuls les nouveaux spans cessent d'être enregistrés.

Renvoie : void.

Exemple :

php
<?php OxPHP\Profile\start(); expensive_work(); OxPHP\Profile\stop(); non_profiled_work();

OxPHP\Profile\pause()

php
OxPHP\Profile\pause(): void

Variante douce de stop(). Même effet (positionne le drapeau de pause) ; la distinction porte sur l'intention — pause() signale que la capture reprendra plus tard via resume(), tandis que stop() ne le signale pas.

Renvoie : void.

OxPHP\Profile\resume()

php
OxPHP\Profile\resume(): void

Efface le drapeau de pause positionné par pause() ou stop(). Le mode de profil lui-même n'est pas modifié — s'il n'a jamais été activé, resume() ne fait rien d'observable.

Renvoie : void.

Exemple :

php
<?php OxPHP\Profile\pause(); $secret = decrypt_payload($data); OxPHP\Profile\resume();

OxPHP\Profile\mark()

php
OxPHP\Profile\mark(string $label, ?array $attrs = null): void

Attache un événement Mark au span ouvert le plus haut, avec un sac d'attributs facultatif. Sans effet lorsqu'aucun span n'est ouvert (par exemple profilage non actif, ou mark() appelée au niveau supérieur de la requête, en dehors de tout cadre instrumenté).

Les clés et valeurs d'attributs sont converties en chaînes ; les valeurs non-chaînes deviennent une chaîne vide.

Paramètres :

  • $label — nom court, lisible par un humain, pour l'événement (par exemple "cache.miss", "db.slow_query")
  • $attrs — array<string, scalar> facultatif de paires clé/valeur attachées à l'événement

Renvoie : void.

Exemple :

php
<?php function load_user(int $id): array { $cached = $cache->get("user:$id"); if ($cached === null) { OxPHP\Profile\mark('cache.miss', ['key' => "user:$id"]); $cached = $db->fetchUser($id); } return $cached; }

OxPHP\Profile\metric()

php
OxPHP\Profile\metric(string $name, float $value): void

Ajoute un attribut metric.<name> au span actuellement ouvert. Sans effet lorsqu'aucun span n'est ouvert.

Contrairement à mark() (qui crée un événement discret), metric() écrit dans l'ensemble d'attributs du span existant — utile pour enregistrer des observations numériques liées à l'opération environnante (lignes récupérées, octets traités, nombre de réessais).

Paramètres :

  • $name — identifiant de la métrique ; sera stocké sous metric.<name>
  • $value — valeur numérique (convertie en float)

Renvoie : void.

Exemple :

php
<?php function search(string $query): array { $results = $index->search($query); OxPHP\Profile\metric('result_count', count($results)); return $results; }

Classes et interfaces

L'extension oxphp_sapi enregistre les classes suivantes :

HTTP

Classe Description
OxPHP\Http\Request Objet requête renvoyé par oxphp_http_request(). final — ne peut pas être étendu.
OxPHP\Http\Attributes Conteneur mutable d'attributs de requête (pour le middleware). final.
OxPHP\Http\Session Objet session accessible via $request->session(). final.
OxPHP\Http\UploadedFile Objet fichier téléversé issu de $request->files(). final.

Décorateurs

Classe / Interface Description
OxPHP\Decorator\AttributeInterface Interface pour les décorateurs. Requiert les méthodes before(Context $ctx) et after(Context $ctx).
OxPHP\Decorator\Context Objet de contexte passé aux hooks des décorateurs. final. Propriétés publiques : target, class, method, function, objectId, requestId, traceId. Méthodes : getParams(): array, getResult(): mixed, hasResult(): bool. Voir Décorateurs pour la référence complète.

Traçage

Classe Description
OxPHP\Apm\Trace Attribut intégré pour la création automatique de spans. À appliquer aux fonctions ou aux méthodes.

Async

Classe Description
OxPHP\Async\BorrowedProxy Objet proxy pour les valeurs empruntées entre threads.

Exceptions

Toutes les exceptions enregistrées par l'extension :

Exception Étend Quand elle est levée
OxPHP\Async\AsyncException \Exception Erreur dans une tâche asynchrone (oxphp_async_await()) ou arguments invalides dans oxphp_async()
OxPHP\Async\TimeoutException OxPHP\Async\AsyncException Délai dépassé dans l'une de oxphp_async_await(), oxphp_async_await_all(), oxphp_async_await_race() ou oxphp_async_await_any(). Pour les délais de oxphp_async_await_any(), les accesseurs getPartialErrors(): array<int, \Throwable> et getCancelledPromiseIds(): list<int> sont remplis ; pour les autres points d'appel, les deux renvoient [].
OxPHP\Async\AggregateAsyncException OxPHP\Async\AsyncException Levée par oxphp_async_await_any() lorsque toutes les promesses ont été rejetées. Méthodes : getErrors(): list<\Throwable> (positionnel, indexé 0..N-1 par position d'entrée), getErrorMap(): array<int, \Throwable> (indexé par id de promesse), getPromiseIds(): list<int> (ids de promesse d'entrée dans l'ordre).
OxPHP\Async\BorrowException \Exception Erreur lors de l'emprunt d'une valeur entre threads
OxPHP\Http\Exception\NoActiveRequestException \RuntimeException Appel de oxphp_http_request() en dehors d'une requête active
OxPHP\Http\Exception\AsyncContextException NoActiveRequestException Appel de oxphp_http_request() à l'intérieur d'un callback oxphp_async()
OxPHP\Http\Exception\WorkerIdleException NoActiveRequestException Appel de oxphp_http_request() en mode worker entre deux requêtes
OxPHP\Decorator\RejectedException \Exception Un décorateur a rejeté un appel de fonction/méthode

Vérification de l'extension

Vous pouvez vérifier que l'extension OxPHP est chargée et inspecter toutes les fonctions enregistrées :

php
<?php if (extension_loaded('oxphp_sapi')) { echo "OxPHP extension is loaded\n"; } $functions = get_extension_funcs('oxphp_sapi'); print_r($functions); // Array // ( // [0] => oxphp_http_request // [1] => oxphp_superglobals_enabled // [2] => oxphp_request_id // [3] => oxphp_worker_id // [4] => oxphp_server_info // [5] => oxphp_finish_request // [6] => oxphp_is_worker // [7] => oxphp_is_streaming // [8] => oxphp_stream_flush // [9] => oxphp_sleep // [10] => oxphp_usleep // [11] => oxphp_worker // [12] => oxphp_register_decorator // [13] => oxphp_async // [14] => oxphp_async_await // [15] => oxphp_async_await_all // [16] => oxphp_async_await_race // [17] => oxphp_async_await_any // [18] => oxphp_apm_trace // [19] => oxphp_apm_start // [20] => oxphp_apm_end // [21] => oxphp_apm_attribute // [22] => oxphp_apm_event // [23] => oxphp_apm_error // [24] => oxphp_apm_status // [25] => oxphp_apm_trace_id // [26] => oxphp_apm_span_id // [27] => oxphp_apm_header // )
Note

Les fonctions SAPI de base (jusqu'à oxphp_register_decorator) viennent en premier ; les familles oxphp_async_* et oxphp_apm_* — ainsi que le SDK OxPHP\Profile\* lorsque le profileur est intégré à la compilation — sont ajoutées par leurs plugins lors de l'initialisation du module. Considérez cette liste comme illustrative : l'ensemble exact et l'ordre dépendent des plugins compilés dans le build.

Compatibilité avec PHP-FPM

Si votre code doit fonctionner à la fois sur OxPHP et PHP-FPM, utilisez des wrappers de repli :

php
<?php function finish_request(): bool { if (function_exists('oxphp_finish_request')) { return oxphp_finish_request(); } if (function_exists('fastcgi_finish_request')) { return fastcgi_finish_request(); } return false; } // Worker-aware bootstrap if (function_exists('oxphp_is_worker') && oxphp_is_worker()) { // OxPHP worker mode } else { // PHP-FPM or OxPHP traditional mode }
Note

La famille de fonctions oxphp_async() est toujours enregistrée dans OxPHP, donc function_exists('oxphp_async') renvoie true même lorsque ASYNC_WORKERS=0. Lorsque le pool est désactivé, l'appel de n'importe quelle fonction asynchrone lève OxPHP\Async\AsyncException. Si votre code doit gérer les deux configurations, interceptez l'exception plutôt que de vérifier function_exists().

Voir aussi

code
Une erreur ? Signalez-la →