PHP: полный мануал с примерами, функциями и ООП

Сохранить цифры и понять тип значения

Внешняя система прислала длинный номер заказа, а каталог — цену 19.90. Нужно найти ровно тот заказ и получить правильную сумму, не меняя цифры по дороге. Здесь последовательно пройдём от строки и простого конструктора к настоящей записи, запросу, серверному расчёту и JSON-ответу.

Представьте подпись единицы на измерительном приборе. Одни и те же видимые цифры без контекста ещё не говорят, что и как измерено. BSON-тип также влияет на прочтение и расчёт значения. Аналогия объясняет необходимость явного типа; она не означает физическое устройство памяти или бесконечную точность.

$orderNumber = new MongoDB\BSON\Int64('9007199254740993');
$price = new MongoDB\BSON\Decimal128('19.90');
echo (string) $orderNumber; // 9007199254740993
echo (string) $price;       // 19.90

Знак $ начинает имя переменной; = сохраняет значение справа. new создаёт объект, а строка между скобками — аргумент конструктора. Полное имя MongoDB\BSON\... указывает класс расширения. (string) просит точное строковое представление. В этом коротком фрагменте базы данных ещё нет: это подготовка значений. Ниже каждая полная программа сама создаёт учебные документы и читает результат.

Если встречается незнакомое понятие, начните с переменных, массивов, функций и return, Manager, BulkWrite, Query и projection. Основы точных BSON-значений уже есть в главе ObjectId, UTCDateTime и Decimal128.

Целое, десятичное число, приближение и строка

Точность и оформление — разные задачи. Decimal128("19.90") сохраняет десятичную модель, но не всякий Decimal128 обязан выводиться ровно с двумя знаками. Int64 сохраняет числовое значение, но не начальные нули. Идентификатор, цена, счётчик и измерение должны получить собственные правила, прежде чем выбирать конструктор.

Подготовка и запуск восьми программ

Восемь архивов самостоятельны. Нужны PHP CLI 8.4+ x64, ext-mongodb 2.5+ и отдельный MongoDB Community 8.0+. Среда проверки пакета: PHP 8.5.11 / mongodb 2.5.5 / MongoDB 8.0.34. Composer не нужен. В README описаны установка расширения, проверка php.ini и запуск отдельного mongod; использовать рабочую базу не требуется.

$env:PHPMAN_MONGODB_URI='mongodb://127.0.0.1:27075/?directConnection=true&retryWrites=false'
$env:PHPMAN_MONGODB_DATABASE='php_manual_lab'
php example.php

Это команды PowerShell из распакованного каталога. Каждая программа создаёт одну собственную коллекцию mongodb127_numbers_ со случайной частью, записывает небольшой набор данных, выполняет ограниченные чтения и удаляет только созданное точное имя в finally. После удаления проверяется отсутствие коллекции. Непредвиденные отказы подключения или запроса не подменяются ожидаемой ошибкой ценового формата.

Найти заказ по большому внешнему номеру без потери цифр

Служба доставки прислала номер заказа 9007199254740993. На экране нужен статус именно этого заказа. Номер нужно донести до фильтра без изменения последней цифры и с тем BSON-типом, который хранится в поле external_id.

Исходные данные

Два документа с числовыми external_id 9007199254740993 и 9007199254740994. Первый имеет статус «готов», второй — «ожидает». Исходный номер приходит строкой. В этом примере источник определяет номер как signed64; если у идентификатора значимы ведущие нули или буквы, для него может быть нужна строковая модель.

Минимальный полезный вызов

$number = new MongoDB\BSON\Int64('9007199254740993');
$filter = ['external_id' => $number];
echo (string) $number; // 9007199254740993

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

new MongoDB\BSON\Int64($text) создаёт значение для BSON. Это ещё не запись: nm127Insert выполняет BulkWrite отдельно. Ключ external_id в фильтре указывает поле документа, а объект справа — искомое числовое значение. limit=1 ограничивает чтение, projection не запрашивает ненужные поля.

MongoDB отличает числовое значение от строки. Поэтому фильтр с Int64 находит первый документ, а тот же текст без конструктора не находит ни одного. При этом числовые BSON-типы в сравнениях не всегда изолированы друг от друга: для проверки именно long здесь отдельно применяется $type. Не путайте numeric equality с требованием конкретного типа хранения.

На 64-битном PHP обычный драйверный Cursor может вернуть BSON long как PHP int: обе границы signed64 помещаются в такой int. Для проверенного пути executeQuery это и происходит. Отдельный MongoDB\BSON\Document::get сохраняет raw BSON-тип и возвращает Int64. Программа не требует объекта Int64 от каждого способа чтения, а проверяет цифры и тип хранения отдельно.

Число превышает диапазон целых, которые двоичный double способен представлять подряд без пропусков. Промежуточный PHP float или JavaScript Number способен потерять единицу ещё до вызова MongoDB. После такой потери конструктор не восстановит исходный номер. При обмене с браузером передавайте исходный ID строкой или согласованным Extended JSON.

Границы и ошибки

Int64 не сохраняет вид записи: «07» нормализуется до «7». Поэтому код заказа «0007» с важными ведущими нулями нужно моделировать иначе. Номер должен укладываться в signed64; переполнение разобрано ниже. В рабочей коллекции частый поиск external_id обычно нуждается в подходящем индексе, а условие уникальности задаётся требованиями интеграции.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
$text='9007199254740993';$number=new MongoDB\BSON\Int64($text);
nm127Insert($manager,$namespace,[['_id'=>1,'external_id'=>$number,'status'=>'готов'],['_id'=>2,'external_id'=>new MongoDB\BSON\Int64('9007199254740994'),'status'=>'ожидает']]);
$found=nm127Read($manager,$namespace,['external_id'=>$number],['_id'=>1,'external_id'=>1,'status'=>1],1);
$wrong=nm127Read($manager,$namespace,['external_id'=>$text],['_id'=>1],1);
$long=nm127Read($manager,$namespace,['external_id'=>['$type'=>'long']],['_id'=>1],2);
$raw=MongoDB\BSON\Document::fromPHP(['external_id'=>$number])->get('external_id');
$rows=[['Int64 в фильтре',(string)$found[0]['external_id'],$found[0]['status']],['Строка в фильтре',(string)count($wrong),'совпадения нет'],['Байтовый BSON Document',(string)$raw,'Int64']];
$checks=['selected_exact_id'=>array_column($found,'_id')===[1],'exact_digits'=>(string)$found[0]['external_id']===$text,'string_not_number'=>$wrong===[],'stored_long_type'=>array_column($long,'_id')===[1,2],'raw_preserves_type'=>$raw instanceof MongoDB\BSON\Int64,'raw_preserves_value'=>(string)$raw===$text];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-int64-lookup', ['Действие', 'Значение / число совпадений', 'Результат'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-int64-lookup: saved result.html and result.json
';

mongodb127-numbers-int64-lookup: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. Поменяйте исходную строку на 9007199254740994. Ожидаемый выбранный статус станет «ожидает», но демонстрационный текстовый фильтр по-прежнему даст 0. Обновите ожидаемые проверки только вместе с исходными данными и объясните, почему объект значения в фильтре важен.

Проверить границы Int64 и не потерять тип небольшого счётчика

Импорт счётчиков должен принять два предельных 64-битных значения и небольшой счётчик 42, а некорректные строки вернуть в отчёт ошибок. При этом поле по договорённости обязано храниться как BSON long даже тогда, когда текущее число маленькое.

Исходные данные

Семь входных строк: нижняя и верхняя границы, 42, два выхода за диапазон, дробь 12.5 и текст abc. Это технический счётчик signed64, а не цена и не ID с ведущими нулями.

Минимальный полезный вызов

$counter = new MongoDB\BSON\Int64(42); // BSON long даже для малого значения
echo (string) $counter; // 42
// '9223372036854775808' уже выходит за верхнюю границу signed64.

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

Нижняя граница signed64 — −9223372036854775808, верхняя — 9223372036854775807. Конструктор принимает PHP int или строку целого. Строка удобна на входе интеграции и явно сохраняет большие значения. Десятичная дробь и abc не описывают допустимое целое, поэтому перехватывается именно InvalidArgumentException конструктора.

try/catch здесь окружает только создание отдельного значения. Ожидаемый отказ входа попадает в таблицу «не записан». Ошибки подключения или BulkWrite не превращаются в такой же мягкий отказ: они должны остановить программу, чтобы не выдавать недоступную базу за успешный импорт.

new Int64(42) задаёт BSON long. Если вместо этого сохранить обычный PHP int 42, драйвер может выбрать BSON int32 по диапазону. Прочитанный в x64 Cursor int сам по себе не говорит, какой BSON-тип был в базе: его проверяет серверный $type.

Современный Int64 поддерживает арифметические, побитовые операции и сравнения. Это не арифметика неограниченной точности: для проверенной среды 41+1 остаётся Int64, а выход MAX+1 переходит во float. Вторая операция показана как диагностическая граница, её результат намеренно не сохраняется как точный счётчик. Проверяйте бизнес-диапазон до расчёта; конкурентный счётчик обновляется отдельным серверным механизмом.

Границы и ошибки

Прямой публичный конструктор появился в mongodb 1.16.0, хотя класс существовал с 1.5.0 для декодирования. Эти версии нельзя смешивать. Разрешённость отрицательного значения, максимальный счётчик устройства и политика переполнения относятся к предметной области. Int64 не заменяет их.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
$inputs=['-9223372036854775808','9223372036854775807','42','9223372036854775808','-9223372036854775809','12.5','abc'];
$rows=[];$docs=[];$accepted=[];$rejected=[];
foreach($inputs as $i=>$text){
    try{$value=new MongoDB\BSON\Int64($text);$docs[]=['_id'=>$i,'counter'=>$value];$accepted[]=$text;$rows[]=[$text,'принят',(string)$value];}
    catch(MongoDB\Driver\Exception\InvalidArgumentException){$rejected[]=$text;$rows[]=[$text,'отклонён','не записан'];}
}
nm127Insert($manager,$namespace,$docs);
$stored=nm127Read($manager,$namespace,['counter'=>['$type'=>'long']],['_id'=>1,'counter'=>1]);
$sum=new MongoDB\BSON\Int64(41)+1;
$overflow=new MongoDB\BSON\Int64('9223372036854775807')+1;
$rows[]=['Int64(41) + 1',(string)$sum,'Int64'];$rows[]=['MAX + 1',get_debug_type($overflow),'не сохраняем как точный long'];
$checks=['three_valid_values'=>count($accepted)===3,'four_invalid_values'=>count($rejected)===4,'stored_as_long'=>array_column($stored,'_id')===[0,1,2],'small_long_digits'=>(string)$stored[2]['counter']==='42','minimum_roundtrip'=>(string)$stored[0]['counter']===$inputs[0],'maximum_roundtrip'=>(string)$stored[1]['counter']===$inputs[1],'bounded_addition'=>$sum instanceof MongoDB\BSON\Int64 && (string)$sum==='42','comparison_supported'=>new MongoDB\BSON\Int64(41)<new MongoDB\BSON\Int64(42),'overflow_not_int64'=>is_float($overflow)];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-int64-range', ['Вход / действие', 'Решение / результат', 'Сохранённое значение / пояснение'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-int64-range: saved result.html and result.json
';

mongodb127-numbers-int64-range: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. Добавьте строку 07. Конструктор примет её, но строковый вывод будет 7. Это дополнительный принятый документ, поэтому изменятся число строк и ожидаемые проверки; подумайте, подходит ли такая нормализация вашему полю.

Практическая проблема в обсуждении: Как принудительно сохранить небольшое число как NumberLong в PHP. Разработчик хотел BSON long для небольшого42. Старое обсуждение относится к периоду, когда прямой new Int64 был недоступен; современный конструктор с1.16.0 решает эту задачу явно. Код и объяснение здесь оригинальные; контракт подтверждают официальные источники, а обсуждение показывает реальную задачу разработчика.

Передать большой номер через JSON с сохранением числа и типа

После чтения из MongoDB большой номер нужно отправить в другую систему или в браузер. Получатель должен получить все цифры. Для BSON-обмена также важно восстановить числовой тип, а для собственного HTTP API можно явно согласовать строковое поле external_id.

Исходные данные

Один сохранённый номер 9223372036854775807. Сравниваются jsonSerialize, обычный JSON-декодер, современный Canonical Extended JSON и простой API со строковым идентификатором.

Минимальный полезный вызов

$id = new MongoDB\BSON\Int64('9223372036854775807');
echo json_encode($id, JSON_THROW_ON_ERROR);
// {"$numberLong":"9223372036854775807"}

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

jsonSerialize() возвращает PHP-данные, пригодные для кодирования, а не готовую JSON-строку. Для Int64 это структура с ключом $numberLong и числом в строке. json_encode($typed) вызывает сериализатор автоматически. Проверки сравнивают оба результата, чтобы не полагаться только на внешнее сходство вывода.

Обычный json_decode(..., true) создаёт PHP-массив с ключом $numberLong. Он не знает, что нужен объект MongoDB\BSON\Int64. Поэтому в таблице рядом с цифрами показан тип array, а не ложное обещание восстановленного BSON long.

Для стандартного типизированного обмена документ создаётся через Document::fromPHP, превращается в Canonical Extended JSON и читается через Document::fromJSON. get("external_id") возвращает Int64; им выполняется второй реальный запрос. Это проверка пригодности восстановленного значения к использованию, а не только сравнение строк JSON.

Для своего браузерного API проще договориться: external_id — текст. Такой DTO не обещает автоматического BSON-восстановления, зато JavaScript не округлит длинный ID при JSON.parse. Явное создание Int64 после x64 Cursor также не даёт малому номеру при повторном BSON-кодировании случайно стать int32.

Границы и ошибки

Canonical сохраняет типы, но это не разрешение выполнять произвольный присланный документ как фильтр. Выбирайте известные поля и проверяйте их. Relaxed Extended JSON использует более обычную запись целых и потому требует особого внимания к возможностям получателя. Код использует Canonical для BSON-маршрута и строку для браузерного.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
$original=new MongoDB\BSON\Int64('9223372036854775807');
nm127Insert($manager,$namespace,[['_id'=>1,'external_id'=>$original]]);
$stored=nm127Read($manager,$namespace,['_id'=>1],['_id'=>0,'external_id'=>1],1)[0]['external_id'];
$typed=new MongoDB\BSON\Int64((string)$stored);$serialized=$typed->jsonSerialize();
$encoded=json_encode($typed,JSON_THROW_ON_ERROR);$plain=json_decode($encoded,true,512,JSON_THROW_ON_ERROR);
$document=MongoDB\BSON\Document::fromPHP(['external_id'=>$typed]);$canonical=$document->toCanonicalExtendedJSON();
$roundtrip=MongoDB\BSON\Document::fromJSON($canonical)->get('external_id');
$again=nm127Read($manager,$namespace,['external_id'=>$roundtrip],['_id'=>1],1);
$dto=json_encode(['external_id'=>(string)$typed],JSON_THROW_ON_ERROR);
$rows=[['jsonSerialize / json_encode',$serialized['$numberLong'],'$numberLong'],['Обычный json_decode',$plain['$numberLong'],'массив, не BSON-класс'],['Document::fromJSON',(string)$roundtrip,'Int64'],['Согласованный API',json_decode($dto,true,512,JSON_THROW_ON_ERROR)['external_id'],'строка external_id']];
$checks=['numberlong_shape'=>$serialized===['$numberLong'=>'9223372036854775807'],'serializer_used_by_json'=>$plain===$serialized,'plain_is_array'=>is_array($plain),'canonical_type_preserved'=>$roundtrip instanceof MongoDB\BSON\Int64,'canonical_value_preserved'=>(string)$roundtrip===(string)$original,'typed_filter_after_import'=>array_column($again,'_id')===[1],'dto_keeps_string'=>is_string(json_decode($dto,true,512,JSON_THROW_ON_ERROR)['external_id'])];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-int64-json', ['Маршрут', 'Значение', 'Форма'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-int64-json: saved result.html and result.json
';

mongodb127-numbers-int64-json: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. Замените номер на 42. Его Canonical-представление всё ещё должно содержать $numberLong со строкой 42, потому что тип задан Int64 явно. В DTO значение тоже останется строкой. Это полезная проверка контракта независимо от текущего размера числа.

Сохранить цену строкой на входе и числом Decimal128 в базе

Каталог получает цену 19.90. Нам нужно сохранить десятичное значение, которое затем можно точно умножать и складывать в базе. Одинаково выглядящая цена на экране может скрывать разные типы: decimal, double или string.

Исходные данные

Три учебных документа получают Decimal128("19.90"), PHP float 19.90 и PHP string "19.90". Название source фиксирует выбранный путь. Сравнительные варианты нужны для понимания причины ошибки, а не как рекомендуемые способы хранения цены.

Минимальный полезный вызов

$price = new MongoDB\BSON\Decimal128('19.90');
$product = ['price' => $price, 'currency' => 'RUB'];
echo (string) $price; // 19.90; не float

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

Decimal128 хранит десятичное число. Двоичный PHP float хранит приближение в другой модели, а строка хранит символы. Тип поля влияет на сравнение и арифметику. В таблице серверный $type подтверждает результат каждого пути, а не выводит предположение по PHP-исходнику.

19.90 в PHP без кавычек становится float. Текстовый вывод может выглядеть аккуратно как 19.9, но это не доказательство точности двоичного хранения. В примере не придумана длинная ошибочная дробь для каждого float: показывается реальная строка и подтверждённый сервером double.

Конструктор вызывается от исходной строки до преобразования во float. new Decimal128((string)$alreadyRoundedFloat) не возвращает ранее потерянные цифры. Для цены валюта и допустимый диапазон задаются отдельно; правила формы разбираются в следующем примере проверки входа.

Агрегация здесь не выполняет расчёт суммы. Она выбирает три известных документа, сортирует их и показывает source, price и $type. Следующий фильтр совмещает требование BSON decimal с десятичной нижней границей 10.00. Это конкретный отбор нужных данных, а не выгрузка всего каталога с последующей фильтрацией в PHP.

Границы и ошибки

Decimal128 даёт до 34 значащих цифр и конечный диапазон экспонент. Он не гарантирует любой произвольный десятичный текст и сам не назначает валюту. Целые минимальные денежные единицы тоже возможны при фиксированной шкале; выбор зависит от диапазона и необходимых расчётов. Отображение с двумя знаками и округление налогов — отдельные правила.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
nm127Insert($manager,$namespace,[['_id'=>1,'source'=>'Decimal128','price'=>new MongoDB\BSON\Decimal128('19.90')],['_id'=>2,'source'=>'float','price'=>19.90],['_id'=>3,'source'=>'string','price'=>'19.90']]);
$docs=nm127Aggregate($manager,$database,$collection,[['$sort'=>['_id'=>1]],['$limit'=>3],['$project'=>['_id'=>1,'source'=>1,'price'=>1,'bson_type'=>['$type'=>'$price']]]]);
$rows=[];foreach($docs as $doc){$rows[]=[$doc['source'],(string)$doc['price'],$doc['bson_type']];}
$selected=nm127Read($manager,$namespace,['price'=>['$type'=>'decimal','$gte'=>new MongoDB\BSON\Decimal128('10.00')]],['_id'=>1,'price'=>1],3);
$checks=['three_storage_types'=>array_column($docs,'bson_type')===['decimal','double','string'],'decimal_remains_object'=>$docs[0]['price'] instanceof MongoDB\BSON\Decimal128,'exact_fraction'=>(string)$docs[0]['price']==='19.90','explicit_decimal_filter'=>array_column($selected,'_id')===[1],'double_is_not_decimal'=>is_float($docs[1]['price']),'text_is_not_decimal'=>is_string($docs[2]['price'])];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-decimal-price', ['Создано в PHP', 'Прочитанное значение', 'BSON-тип поля'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-decimal-price: saved result.html and result.json
';

mongodb127-numbers-decimal-price: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. Поменяйте цену во всех трёх документах на 0.10. BSON-типы останутся теми же, но фильтр ≥10.00 ничего не вернёт. Затем измените нижнюю границу на Decimal128("0.00"): подходящий decimal-документ снова попадёт в результат.

Практическая проблема в обсуждении: Почему round в PHP не гарантирует точную десятичную цену в базе. После округления и записи пользователь видел хвост двоичного приближения. Это повод различить красивый вывод float и десятичную модель хранения; наш пример показывает реальные BSON-типы трёх путей. Код и объяснение здесь оригинальные; контракт подтверждают официальные источники, а обсуждение показывает реальную задачу разработчика.

Получить итог одного заказа в базе без выгрузки всех позиций

На странице выбранного заказа нужен итог 40.10 RUB. База уже содержит строки других заказов и валют. Запрос должен посчитать только выбранный заказ на сервере и вернуть одну итоговую строку, а не передавать весь массив покупок в PHP.

Исходные данные

Заказ A17: две единицы по 19.90 RUB и три единицы по 0.10 RUB. Есть посторонний заказ B18 на 800 EUR. Цены учебного набора заранее выбраны в рамках правила ввода и сохранены как Decimal128; количества — положительные int32. После вставки этот набор не изменяется. Отдельная программа ниже показывает саму проверку внешнего ввода.

Минимальный полезный вызов

$pipeline = [
    ['$match' => ['order' => 'A17', 'currency' => 'RUB']],
    ['$group' => ['_id' => '$order',
        'total' => ['$sum' => ['$multiply' => ['$price', '$qty']]]]],
]; // 19.90 × 2 + 0.10 × 3 = Decimal128('40.10')

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

$match ставится до $group: сначала остаются документы конкретного заказа и одной валюты. $multiply вычисляет цену каждой строки, $sum собирает эти произведения. Другой $sum со значением 1 считает число товарных строк, а не общее количество единиц. Поэтому в результате lines=2, хотя товаров в штуках пять.

В выражении "$price" знак $ означает ссылку на поле документа MongoDB, а не PHP-переменную. Поэтому в PHP для такого текста используются одинарные кавычки. Decimal128 цены вместе с целочисленным qty даёт decimal-расчёт; сервер возвращает Decimal128, который для отчёта преобразуется в строку без float.

$sum игнорирует некоторые нечисловые входы. Поэтому нельзя безоговорочно рассчитывать, что он сам сообщит о цене, случайно сохранённой текстом. Здесь отдельная проверка типов и диапазона qty прерывает расчёт при подозрительной строке выбранного заказа. Она не выбрасывает плохие строки молча ради красивой неполной суммы.

До агрегации выполнена проверка фиксированного набора, но это два отдельных запроса. Она не обеспечивает согласованный счёт при конкурентном изменении документов. Кроме того, фильтр структуры не повторяет все правила цены: NaN, Infinity и отрицательная цена должны быть запрещены входным контрактом. Для действующего сервиса закрепите правила схемы и согласованность окончательного расчёта отдельно.

После группировки сервер отдаёт одну строку. В PHP остаётся только форматирование результата. Для частого отбора заказ/валюта нужен подходящий индекс исходных документов; limit после $group ограничивает ответ, но не уменьшает работу подсчёта всех подходящих позиций.

Границы и ошибки

Это точный учебный итог неизменяемых проверенных строк одной валюты. Здесь не реализованы скидки, налоги, обмен валют, деление и правила округления. Для пустого выбранного заказа $group не создаст строку: приложение должно отдельно показать отсутствие заказа или согласованное значение 0, а не обращаться вслепую к [0]. В программе ожидается созданный fixture A17.

Для изменяемого сервиса: транзакции и согласованный расчёт; проверки при атомарной записи.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
nm127Insert($manager,$namespace,[['_id'=>1,'order'=>'A17','currency'=>'RUB','price'=>new MongoDB\BSON\Decimal128('19.90'),'qty'=>2],['_id'=>2,'order'=>'A17','currency'=>'RUB','price'=>new MongoDB\BSON\Decimal128('0.10'),'qty'=>3],['_id'=>3,'order'=>'B18','currency'=>'EUR','price'=>new MongoDB\BSON\Decimal128('800.00'),'qty'=>1]]);
$selected=['order'=>'A17','currency'=>'RUB'];
$invalid=nm127Read($manager,$namespace,$selected+['$or'=>[['price'=>['$not'=>['$type'=>'decimal']]],['qty'=>['$not'=>['$type'=>'int']]],['qty'=>['$lt'=>1]],['qty'=>['$gt'=>1000]]]],['_id'=>1],1);
if($invalid!==[]){throw new RuntimeException('Reject order with an invalid line instead of ignoring it');}
$pipeline=[['$match'=>$selected],['$group'=>['_id'=>'$order','lines'=>['$sum'=>1],'total'=>['$sum'=>['$multiply'=>['$price','$qty']]]]],['$project'=>['_id'=>0,'order'=>'$_id','lines'=>1,'total'=>1,'total_type'=>['$type'=>'$total']]],['$limit'=>1]];
$result=nm127Aggregate($manager,$database,$collection,$pipeline);
if(count($result)!==1){throw new RuntimeException('Selected order does not exist');}
$total=$result[0]['total'];$rows=[[$result[0]['order'],'RUB',$result[0]['lines'],(string)$total,$result[0]['total_type']]];
$checks=['one_summary_only'=>count($result)===1,'two_selected_lines'=>$result[0]['lines']===2,'exact_decimal_total'=>(string)$total==='40.10','total_has_decimal_type'=>$total instanceof MongoDB\BSON\Decimal128 && $result[0]['total_type']==='decimal','other_order_excluded'=>$result[0]['order']==='A17','source_contract_checked'=>$invalid===[]];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-decimal-total', ['Заказ', 'Валюта', 'Строк заказа', 'Итого', 'Тип результата'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-decimal-total: saved result.html and result.json
';

mongodb127-numbers-decimal-total: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. У второй позиции A17 измените qty с 3 на 4. Итог будет 40.20 RUB, а lines останется 2. Посторонний B18 по-прежнему не должен изменить результат. Затем отдельно попробуйте испортить тип qty: пример обязан остановиться на проверке структуры, а не выдать неполный счёт.

Практическая проблема в обсуждении: Как посчитать сумму decimal-поля и почему важны типы и сервер. В обсуждении с Azure Cosmos DB возникла проблема суммы decimal. Совместимый протокол не гарантирует одинаковые операторы и поддержку типов. Здесь результат проверяется на MongoDB Community, а не объявляется доказательством совместимости Cosmos DB. Код и объяснение здесь оригинальные; контракт подтверждают официальные источники, а обсуждение показывает реальную задачу разработчика.

Разделить допустимый BSON и допустимую цену формы

Цена из формы должна быть понятной покупателю и совместимой с расчётом. Не всякий текст, который умеет представить Decimal128, является допустимой ценой: NaN, Infinity и 1e2 не соответствуют правилу этой формы.

Исходные данные

Разрешены только строки от 0.00 до 999999.99 с точкой и ровно двумя дробными знаками. Восемь входов включают две допустимые цены, запятую, специальные значения, научную запись, уже полученный float и отрицательное число.

Минимальный полезный вызов

$input = '19.90'; // текст формы, пока ещё без преобразования во float
if (!preg_match('/\A(?:0|[1-9][0-9]{0,5})\.[0-9]{2}\z/D', $input)) {
    throw new InvalidArgumentException('Нужна цена с двумя цифрами после точки');
}
$price = new MongoDB\BSON\Decimal128($input);

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

nm127Price принимает mixed, чтобы явно показать отказ неподходящего входа, например float19.9. is_string проверяет исходный тип. Регулярное выражение задаёт именно контракт этой формы: 0 либо число без ведущих нулей, ещё до пяти цифр, литеральная точка и два знака после неё. Якоря \A и \z не позволяют оставить посторонние символы в начале или конце.

Для неподходящего прикладного формата функция выбрасывает обычный InvalidArgumentException приложения. Конструктор Decimal128 вызывается только после этой проверки. В этом разрешённом небольшом диапазоне точность Decimal128 достаточна. Отдельно программа показывает технический отказ строки с 35 существенными цифрами, которую нельзя представить точно.

Число символов не равно количеству значащих цифр. Текст с 35 цифрами и подходящим конечным нулём иногда представим точно после изменения экспоненты. Поэтому здесь не предлагается универсальная проверка Decimal128 через strlen($text)>34. Для произвольных десятичных значений применяйте контракт конструктора, а для цены — отдельный понятный диапазон.

Decimal128("NaN") технически создаётся, но nm127Price("NaN") его не допускает. Разделение показывает два уровня: возможности BSON и правила продукта. 19,90 не превращается в 19.90 скрыто: если интерфейс разрешит запятую, добавьте явную нормализацию до этой функции и покажите пользователю принятое значение.

Границы и ошибки

Правило с двумя дробными знаками относится к этой учебной цене, а не ко всем валютам и не ко всем финансовым величинам. Округлять произвольный float до двух знаков и объявлять его точным вводом нельзя. Ошибки MongoDB не перехватываются как «неверная цена»; они должны оставаться заметными.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
function nm127Price(mixed $raw): MongoDB\BSON\Decimal128 {
    if(!is_string($raw) || !preg_match('/\A(?:0|[1-9][0-9]{0,5})\.[0-9]{2}\z/D',$raw)){
        throw new InvalidArgumentException('Price must be text 0.00..999999.99 with two fractional digits');
    }
    return new MongoDB\BSON\Decimal128($raw);
}
$inputs=['19.90','0.00','19,90','NaN','Infinity','1e2',19.9,'-1.00'];$docs=[];$rows=[];$rejected=0;
foreach($inputs as $i=>$input){
    $label=is_string($input)?$input:'float 19.9';
    try{$price=nm127Price($input);$docs[]=['_id'=>$i,'price'=>$price];$rows[]=[$label,'принят',(string)$price];}
    catch(InvalidArgumentException){$rejected++;$rows[]=[$label,'отклонён','до записи'];}
}
nm127Insert($manager,$namespace,$docs);$stored=nm127Read($manager,$namespace,[],['_id'=>1,'price'=>1],3);
$inexact=false;try{new MongoDB\BSON\Decimal128('1.2345678901234567890123456789012345');}catch(MongoDB\Driver\Exception\InvalidArgumentException){$inexact=true;}
$nan=new MongoDB\BSON\Decimal128('NaN');
$checks=['two_valid_prices'=>array_column($stored,'_id')===[0,1],'six_business_rejections'=>$rejected===6,'stored_price_digits'=>array_map(fn($d)=>(string)$d['price'],$stored)===['19.90','0.00'],'inexact_35_digits_rejected'=>$inexact,'bson_accepts_nan'=>(string)$nan==='NaN','business_rejects_nan'=>$rows[3][1]==='отклонён'];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-decimal-validation', ['Вход', 'Политика цены', 'Что записано'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-decimal-validation: saved result.html and result.json
';

mongodb127-numbers-decimal-validation: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. Добавьте 999999.99 и 1000000.00 как строки. Первая должна пройти, вторая — нет. Добавьте 01.00: она также отклоняется из-за ведущего нуля, хотя Decimal128 способен представить числовое значение 1.00. Объясните, какая проверка приняла каждое решение.

Сделать типизированный экспорт цены и отдельный ответ для интерфейса

Сервис каталога отдаёт цену другому MongoDB-приложению и браузеру. Первому нужен BSON decimal после чтения, второму — согласованные amount и currency без случайного перехода к JavaScript Number.

Исходные данные

Документ с Decimal128("19.90") и валютой RUB. Сравниваются jsonSerialize, полный Canonical Extended JSON, обратное восстановление BSON и простой JSON для собственного API.

Минимальный полезный вызов

$price = new MongoDB\BSON\Decimal128('19.90');
echo json_encode($price, JSON_THROW_ON_ERROR); // {"$numberDecimal":"19.90"}
echo json_encode(['amount' => (string) $price, 'currency' => 'RUB'], JSON_THROW_ON_ERROR);

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

Для Decimal128 jsonSerialize возвращает структуру с ключом $numberDecimal и десятичным текстом. json_encode автоматически использует её. В отличие от самого метода, результат json_encode — строка JSON. Программа сравнивает данные, полученные обоими путями.

Конкретная форма Decimal128 с $numberDecimal совпадает в legacy и современном Canonical Extended JSON. Это не значит, что json_encode любого BSON-объекта всегда выдаёт Canonical: например Binary имеет различия. Для полного документа выбирайте Document::toCanonicalExtendedJSON явно, чтобы формат не зависел от догадки по одному полю.

Document::fromJSON понимает BSON-маркеры и возвращает типизированное поле через get. Обычный json_decode даёт массив, а не Decimal128. Повторный запрос по восстановленной цене подтверждает, что пример действительно вернулся к BSON-значению.

В собственном API amount намеренно строка. Браузер может её показать без перевода в Number. Строковое сложение или преобразование amount во float на следующем шаге снова изменит модель, поэтому вычисления должны идти по согласованному десятичному контракту. Валюта передаётся отдельным полем и не угадывается по знаку или количеству дробных цифр.

Границы и ошибки

Extended JSON — формат представления типов, а не средство проверки прав или правил цены. Импортируемые поля всё равно проверяются. Простое строковое API не обещает автоматическое BSON-декодирование: получатель сам валидирует amount и создаёт Decimal128, если это его внутренняя модель.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
nm127Insert($manager,$namespace,[['_id'=>1,'price'=>new MongoDB\BSON\Decimal128('19.90'),'currency'=>'RUB']]);
$stored=nm127Read($manager,$namespace,['_id'=>1],['_id'=>0,'price'=>1,'currency'=>1],1)[0];$price=$stored['price'];
$serialized=$price->jsonSerialize();$encoded=json_encode($price,JSON_THROW_ON_ERROR);$plain=json_decode($encoded,true,512,JSON_THROW_ON_ERROR);
$canonical=MongoDB\BSON\Document::fromPHP($stored)->toCanonicalExtendedJSON();$imported=MongoDB\BSON\Document::fromJSON($canonical);$restored=$imported->get('price');
$canonicalShape=json_decode($canonical,true,512,JSON_THROW_ON_ERROR)['price'];
$dto=['amount'=>(string)$price,'currency'=>$stored['currency']];$dtoJSON=json_encode($dto,JSON_THROW_ON_ERROR);$dtoBack=json_decode($dtoJSON,true,512,JSON_THROW_ON_ERROR);
$found=nm127Read($manager,$namespace,['price'=>$restored],['_id'=>1],1);
$rows=[['jsonSerialize',$serialized['$numberDecimal'],'$numberDecimal'],['Canonical JSON',$canonicalShape['$numberDecimal'],'$numberDecimal'],['fromJSON',(string)$restored,'Decimal128'],['API для экрана',$dtoBack['amount'],$dtoBack['currency']]];
$checks=['decimal_serializer_shape'=>$serialized===['$numberDecimal'=>'19.90'],'json_encode_uses_serializer'=>$plain===$serialized,'canonical_shape_matches_for_decimal'=>$canonicalShape===$serialized,'typed_import'=>$restored instanceof MongoDB\BSON\Decimal128,'typed_query_roundtrip'=>array_column($found,'_id')===[1],'dto_string_and_currency'=>$dtoBack===['amount'=>'19.90','currency'=>'RUB'],'json_decode_is_not_bson'=>is_array($plain)];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-decimal-json', ['Маршрут', 'Цена', 'Тип / валюта'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-decimal-json: saved result.html and result.json
';

mongodb127-numbers-decimal-json: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. Замените цену на 0.10. В обоих JSON-маршрутах должна остаться строка 0.10, а типизированный импорт — дать Decimal128. Затем прочитайте простой DTO через json_decode: amount останется string, и это предусмотренный контракт, а не ошибка.

Передать точную цену в функцию и объект представления

Цена из базы нужна в двух местах: в видимой подписи каталога и в JSON экспорте. Хочется явно требовать объект точного десятичного значения и не принимать случайный float или строку там, где валидация уже должна быть завершена.

Исходные данные

Два товара: CUP по 19.90 RUB и BOX по 2.50 EUR. Функция nm127Label строит подпись, а небольшой объект PriceCell127 хранит цену и валюту для экспорта. Их задача — представление уже проверенных данных, а не ввод цены.

Минимальный полезный вызов

function label(MongoDB\BSON\Decimal128Interface $amount): string {
    return (string) $amount;
}
echo label(new MongoDB\BSON\Decimal128('19.90')); // 19.90

Короткий фрагмент выделяет текущую операцию. Подключение, исходные документы, чтение и очистка находятся в полной программе ниже.

Что получится при выполнении

Пошаговое объяснение

Интерфейс описывает доступные операции объекта. Decimal128Interface содержит __toString():string; встроенный Decimal128 его реализует. Его имя в параметре означает «ожидается совместимый объект». Оно не создаёт цену и не выполняет конвертацию строки автоматически.

nm127Label($amount,$currency) получает значение, проверяет разрешённую валюту и возвращает текст. return отдаёт строку вызывающему коду. (string)$amount обращается к __toString; арифметика и float здесь не появляются. В тесте намеренно передана обычная строка, и ожидаемый TypeError подтверждает границу функции.

В PriceCell127 запись public readonly в конструкторе объявляет и инициализирует свойства. value():Decimal128Interface возвращает объект цены, export():array возвращает два понятных поля для JSON. Эти типы показывают три места применения интерфейса: параметр, свойство и результат метода. Если синтаксис ООП пока незнаком, сначала разберите короткую функцию над примером, затем переходите к классу.

Интерфейс не гарантирует две дробные цифры, положительную цену или допустимую валюту. Текущий пример читает известные проверенные Decimal128. Пользовательский класс с тем же интерфейсом обязан соблюдать сигнатуру, но одним фактом implements нельзя гарантировать автоматическое BSON-кодирование как встроенного Decimal128. DTO создан явно и не выдаётся за новый BSON-тип.

Границы и ошибки

Создать new Decimal128Interface нельзя: это контракт, а не реализация. Он не содержит jsonSerialize и не обещает методы MongoDB\BSON\Document. Для финансового приложения валидация и валюта должны быть закреплены до создания представления; демонстрационный PriceCell127 сам не проверяет произвольные входные данные как полноценный денежный объект.

Связанные понятия: интерфейсы; параметры и возвращаемое значение.

<?php
declare(strict_types=1);
require __DIR__.'/nm127-helper.php';
$settings=nm127Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=nm127Command($manager,$database,['buildInfo'=>1])[0]['version'];
if(version_compare($version,'8.0','<')){throw new RuntimeException('MongoDB 8.0+ required');}
$runtime=['php'=>PHP_VERSION,'extension'=>phpversion('mongodb'),'server'=>$version,'execution'=>'database'];
$namespace=nm127Create($manager,$database,$owned);$collection=$owned[0];
function nm127Label(MongoDB\BSON\Decimal128Interface $amount,string $currency): string {
    if(!in_array($currency,['RUB','EUR'],true)){throw new InvalidArgumentException('Unsupported currency');}
    return (string)$amount.' '.$currency;
}
final class PriceCell127 {
    public function __construct(public readonly MongoDB\BSON\Decimal128Interface $amount,public readonly string $currency){}
    public function value(): MongoDB\BSON\Decimal128Interface{return $this->amount;}
    public function export(): array{return ['amount'=>(string)$this->value(),'currency'=>$this->currency];}
}
nm127Insert($manager,$namespace,[['_id'=>1,'sku'=>'CUP','price'=>new MongoDB\BSON\Decimal128('19.90'),'currency'=>'RUB'],['_id'=>2,'sku'=>'BOX','price'=>new MongoDB\BSON\Decimal128('2.50'),'currency'=>'EUR']]);
$docs=nm127Read($manager,$namespace,[],['_id'=>1,'sku'=>1,'price'=>1,'currency'=>1],2);$rows=[];$interfaces=true;$exports=[];
foreach($docs as $doc){
    $cell=new PriceCell127($doc['price'],$doc['currency']);$export=$cell->export();$exports[]=$export;
    $interfaces=$interfaces && $cell->value() instanceof MongoDB\BSON\Decimal128Interface;
    $rows[]=[$doc['sku'],nm127Label($cell->value(),$doc['currency']),$export['amount'],$export['currency']];
}
$wrongType=false;try{nm127Label('19.90','RUB');}catch(TypeError){$wrongType=true;}
$checks=['both_values_support_interface'=>$interfaces,'distinct_exports'=>$exports===[['amount'=>'19.90','currency'=>'RUB'],['amount'=>'2.50','currency'=>'EUR']],'literal_string_rejected_by_type'=>$wrongType,'no_float_conversion'=>is_string($exports[0]['amount']) && $exports[0]['amount']==='19.90','two_database_documents'=>array_column($docs,'_id')===[1,2]];
}finally{
    foreach(array_reverse($owned) as $name){nm127Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(nm127Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
nm127Report('mongodb127-numbers-decimal-interface', ['Товар', 'Подпись на экране', 'amount для API', 'currency для API'], $rows, $checks, $runtime);
echo 'mongodb127-numbers-decimal-interface: saved result.html and result.json
';

mongodb127-numbers-decimal-interface: saved result.html and result.json

Разберите результат: большие целые и десятичные значения в HTML и JSON показаны строками, чтобы их отображение не изменило точность. Реальный BSON-тип, выбранный документ или результат серверной операции проверяются отдельно в полной программе.

Открыть фактическую таблицу · JSON результата

Попробуйте изменить. Добавьте товар PEN с Decimal128("3.00") и валютой RUB. Его подпись будет 3.00 RUB, а export вернёт amount="3.00". Не складывайте CUP и BOX в один итог: у них разные валюты, и интерфейс сам не выполняет конвертацию.

Выбрать маршрут по задаче

Справочник Int64, Decimal128 и Decimal128Interface

Новые карточки ниже раскрывают полные контракты. Конструктор и строковое представление Decimal128 сохраняют прежние канонические адреса: __construct и __toString.

Закрепить числовой контракт поля

Выберите одно числовое поле своей интеграции и опишите его: целое или десятичное, допустимый диапазон, важны ли ведущие нули, где выполняются расчёты и какой тип получает браузер. Затем пройдите один из разобранных маршрутов от входа до видимого результата. Такой контракт поможет сохранить цифры при каждом преобразовании.

Продолжение: BSON Document и типизированный JSON; ObjectId и время UTC; ограниченное чтение результатов.