Conversion des valeurs

Tout appel qui franchit la frontière PHP↔JS — setGlobal, call, une fonction hôte appelée depuis JS — passe par un convertisseur :

• PHP → JS lorsque les valeurs hôtes entrent dans le moteur (arguments de setGlobal(), call() et valeurs renvoyées par les fonctions hôtes).
• JS → PHP lorsque les valeurs JS repartent vers l’extérieur. Deux chemins suivent des règles légèrement différentes : les résultats de eval() et call(), et les arguments que JS transmet à une fonction hôte.

La conversion effectue des copies. Les primitives deviennent des primitives, les tableaux et objets sont copiés dans de nouvelles structures, et les fonctions appelables PHP sont enveloppées comme fonctions JS. Seules les fonctions appelables elles-mêmes sont partagées par référence.

PHP → JS

Les tableaux à clés mixtes (PHP [0 => 'a', 'name' => 'b']) deviennent des objets simples, car les tableaux dans JS doivent avoir des indices entiers contigus.

$engine->setGlobal('list', [1, 2, 3]);                 // → JS Array
$engine->setGlobal('map',  ['a' => 1, 'b' => 2]);      // → JS Object
$engine->setGlobal('mixed', [0 => 'x', 'k' => 'v']);   // → JS Object

Comme les tableaux sont copiés, les modifications apportées à JS restent dans JS :

$list = [1, 2, 3];
$engine->setGlobal('list', $list);
$engine->eval('list.push(4)');
count($list);                 // 3
$engine->eval('list.length'); // 4

Les objets PHP qui ne sont pas appelables ne sont pas convertis ; ils arrivent sous forme de undefined (issue #18). Convertissez-les d’abord en tableaux, par exemple avec get_object_vars(), ou exposez leurs méthodes sous forme de closures. Voir Objets partagés.

JS → PHP : résultats de eval() et call()

La dernière ligne signifie que les objets dont l’état réside dans des slots internes deviennent des tableaux vides : new Date(0), new Map([["a", 1]]) et Promise.resolve(5) renvoient tous []. Un Error renvoie ses propres message et stack. Les références internes d’un objet autoréférentiel deviennent null.

$engine->eval('[1, 2, 3]');                // [1, 2, 3]
$engine->eval('({a: 1, b: 2})');           // ['a' => 1, 'b' => 2]
$engine->eval('new Uint8Array([1, 2, 3])'); // [1, 2, 3]
$engine->eval('1234567890123456789n');     // null
$engine->eval('new Date(0)');              // []

Effectuez la conversion dans JS lorsque vous avez besoin de l’une de ces valeurs dans PHP :

$engine->eval('(1234567890123456789n).toString()');  // "1234567890123456789"
$engine->eval('new Date(0).toISOString()');           // "1970-01-01T00:00:00.000Z"
$engine->eval('Object.fromEntries(new Map([["a", 1]]))'); // ['a' => 1]

JS → PHP : arguments des fonctions hôtes

Les arguments que JS transmet à une fonction hôte PHP suivent les mêmes règles pour les primitives, les tableaux et les objets simples, avec les différences suivantes :

Il n’est pas encore possible de recevoir une fonction de rappel JS dans une fonction hôte. Faites passer des données, et non des fonctions, par cette frontière.

Nombres et précision

Les nombres JavaScript sont des doubles IEEE 754. Les entiers PHP sont natifs de la plateforme (64 bits dans toutes les versions modernes). La conversion préserve exactement les entiers jusqu’à ±2^53 ; les entiers PHP plus grands deviennent des number et perdent en précision au-delà de 16 chiffres décimaux. Utilisez BigInt dans JS pour effectuer des calculs exacts sur des entiers plus grands, puis transmettez le résultat sous forme de chaîne.

Chaînes

Les chaînes PHP sont des tableaux d’octets ; les chaînes JS sont des séquences d’unités de code UTF-16. Le moteur fait le lien en interprétant les octets PHP comme de l’UTF-8, puis en les réencodant en interne en UTF-16. Cette conversion est sans perte pour les entrées UTF-8 valides. Les octets qui ne sont pas de l’UTF-8 valide sont transmis tels quels au lieu d’être remplacés par U+FFFD.

String.length, l’accès par index (s[0]) et le découpage comptent tous les unités de code UTF-16, conformément à la spécification ECMAScript — et non les points de code ni les octets. Les chaînes contenant des caractères hors du plan multilingue de base, comme '🍕', ont donc .length === 2 (les deux moitiés de la paire de substitution de U+1F355).

Stabilité aller-retour

Les données simples survivent à un aller-retour : une valeur PHP composée de scalaires, de listes et de tableaux associatifs, transmise via setGlobal() puis récupérée via eval() ou call(), conserve la même structure, à ceci près que les nombres à virgule flottante entiers reviennent sous forme de int (1.0 renvoie 1).

Tout le reste dans les tableaux ci-dessus qui devient null, undefined ou [] ne survit pas à un aller-retour.