Преобразуване на стойности

Всяко извикване, което преминава границата PHP↔JS — setGlobal, call или хост функция, извикана от JS — минава през конвертор:

• PHP → JS когато хост стойности влизат в енджина (setGlobal(), аргументи call(), връщани стойности от хост функции).
• JS → PHP когато стойностите JS се връщат навън. Има два пътя с малко различни правила: резултатите от eval() и call() и аргументите, които JS подава на хост функция.

Преобразуването създава копия. Примитивите се преобразуват в примитиви, масивите и обектите се копират в нови структури, а извикваемите обекти PHP се обвиват като функции JS. Нищо не се споделя по референция, освен самите извикваеми обекти.

PHP → JS

Масивите със смесени ключове (PHP — [0 => 'a', 'name' => 'b']) стават обикновени обекти, защото масивите в JS трябва да имат непрекъснат диапазон от цели индекси.

$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

Тъй като масивите се копират, промените в JS остават в JS:

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

Обектите PHP, които не са извикваеми, не се преобразуват; пристигат като undefined (issue #18). Първо ги преобразувайте в масиви, например с get_object_vars(), или предоставете методите им като затваряния. Вижте Споделени обекти.

JS → PHP: резултати eval() и call()

Последният ред означава, че обекти със състояние във вътрешни слотове се преобразуват в празен масив: new Date(0), new Map([["a", 1]]) и Promise.resolve(5) връщат []. Обект Error връща собствените си message и stack. Обект, който сочи към себе си, преобразува вътрешните си препратки в 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)');              // []

Преобразувайте в рамките на JS, когато ви трябва една от тези стойности в 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: аргументи на хост функция

Аргументите, които JS подава на хост функция PHP, следват същите правила за примитиви, масиви и обикновени обекти, но с тези разлики:

Засега няма начин да получите обратно обратен извикващ обект JS в хост функция. Предавайте данни, а не функции, през тази граница.

Числа и точност

Числата JavaScript са двойни числа IEEE 754. Целите числа PHP са нативни за платформата (64-битови във всяка модерна компилация). Преобразуването запазва точно цели числа до ±2^53; по-големите цели числа PHP стават number и губят точност след 16 десетични цифри. Използвайте BigInt в JS, ако са ви нужни точни аритметични операции с по-големи цели числа, и предайте резултата като низ.

Низове

Низовете PHP са байтови масиви; низовете JS са последователности от 16-битови кодови единици. Енджинът ги свързва, като интерпретира байтовете PHP като UTF-8 и ги кодира отново вътрешно като UTF-16. Това е без загуби за валиден UTF-8 вход. Невалидните UTF-8 байтове се предават без промяна, вместо да се заменят с U+FFFD.

String.length, индексираният достъп (s[0]) и изрязването броят 16-битовите кодови единици UTF-16 според спецификацията ECMAScript — не кодовите точки и не байтовете. Затова низовете с допълнителни символи като '🍕' имат .length === 2 (двата сурогатни фрагмента на U+1F355).

Стабилност при обратно преобразуване

Обикновените данни се запазват при преобразуване натам и обратно: стойност PHP, съставена от скалари, списъци и асоциативни масиви, която влиза чрез setGlobal() и се връща чрез eval() или call(), дава същата структура, с изключение на това, че цели числа с плаваща запетая се връщат като int (1.0 връща 1).

Всичко останало в таблиците по-горе, което се преобразува в null, undefined или [], не запазва стойността си при обратно преобразуване.