Conversión de valores

Toda llamada que cruza el límite PHP↔JS — setGlobal, call, una función del host invocada desde JS — pasa por un conversor:

• PHP → JS cuando los valores del host entran en el motor (argumentos de setGlobal(), call() y valores devueltos por funciones del host).
• JS → PHP cuando los valores de JS salen. Hay dos rutas con reglas ligeramente distintas: los resultados de eval() y call(), y los argumentos que JS pasa a una función del host.

La conversión copia los valores. Los primitivos se convierten en primitivos, y los arrays y objetos se copian en nuevas estructuras; las funciones invocables de PHP se envuelven como funciones de JS. Nada se comparte por referencia, salvo las propias funciones invocables.

PHP → JS

Los arrays con claves mixtas (el [0 => 'a', 'name' => 'b'] de PHP) se convierten en objetos simples porque los arrays de JS deben tener un espacio de índices enteros contiguo.

$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

Como los arrays se copian, los cambios en JS permanecen en JS:

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

Los objetos de PHP que no son invocables no se convierten; llegan como undefined (incidencia #18). Conviértalos primero en arrays, por ejemplo con get_object_vars(), o exponga sus métodos como cierres. Consulte Objetos compartidos.

JS → PHP: resultados de eval() y call()

La última fila indica que los objetos cuyo estado reside en ranuras internas se convierten en un array vacío: new Date(0), new Map([["a", 1]]) y Promise.resolve(5) devuelven []. Un Error devuelve su propio message y stack. Un objeto que se referencia a sí mismo convierte sus referencias internas en 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)');              // []

Convierta dentro de JS cuando necesite uno de esos valores en 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: argumentos de funciones del host

Los argumentos que JS pasa a una función del host de PHP siguen las mismas reglas para primitivos, arrays y objetos simples, con estas diferencias:

Aún no hay forma de recibir una función de retorno de llamada de JS en una función del host. Pase datos, no funciones, a través de este límite.

Números y precisión

Los números de JavaScript son dobles IEEE 754. Los enteros de PHP son nativos de la plataforma (de 64 bits en todas las compilaciones modernas). La conversión conserva exactamente los enteros hasta ±2^53; los enteros de PHP mayores se convierten en number y pierden precisión después de 16 dígitos decimales. Use BigInt dentro de JS si necesita aritmética exacta con enteros mayores, y devuelva el resultado como una cadena.

Cadenas

Las cadenas de PHP son arrays de bytes; las cadenas de JS son secuencias de unidades de código UTF-16. El motor conecta ambos formatos interpretando los bytes de PHP como UTF-8 y recodificándolos internamente en UTF-16. Esto no pierde información si la entrada es UTF-8 válida. Los bytes que no sean UTF-8 válido se pasan sin cambios, en vez de sustituirse por U+FFFD.

String.length, el acceso indexado (s[0]) y el corte cuentan unidades de código UTF-16 según la especificación de ECMAScript, no puntos de código ni bytes. Por eso, las cadenas con caracteres astrales como '🍕' tienen .length === 2 (las dos mitades sustitutas de U+1F355).

Estabilidad de ida y vuelta

Los datos simples sobreviven a un recorrido de ida y vuelta: un valor de PHP compuesto por escalares, listas y arrays asociativos que entra por setGlobal() y vuelve por eval() o call() produce la misma estructura, salvo que los números de coma flotante integrales regresan como int (1.0 devuelve 1).

Todo lo demás de las tablas anteriores que se convierte en null, undefined o [] no sobrevive al recorrido de ida y vuelta.