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

От бинарного поля к понятному результату

У сервиса появились данные, которые не стоит считать обычным текстом: двоичный пакет датчика, UUID заказа и числовые признаки товара. В этой главе сохраним их в MongoDB, прочитаем обратно и построим понятные результаты: таблицу байтов, найденный заказ, поправки датчиков, комплектацию и небольшой экспорт выбранных признаков.

Байт — восемь битов, одна позиция со значением 0..255. PHP string способен хранить такие bytes, включая нулевой байт, но HTML и JSON ожидают текст по своим правилам. Binary добавляет к байтам BSON-подтип — подпись того, как их понимать. Эта подпись важна при сохранении и поиске.

Представьте конверт с образцом и подписью формата. Содержимое — bytes, подпись — subtype. Подпись помогает выбрать способ чтения, но не доказывает правильность содержимого. Аналогия не описывает физическое хранение MongoDB и не означает шифрования.

$binary = new MongoDB\BSON\Binary("A\0\xFF", MongoDB\BSON\Binary::TYPE_GENERIC);
echo strlen($binary->getData()); // 3 байта
echo bin2hex($binary->getData()); // 4100ff

Первая строка присваивает $binary созданный объект. new вызывает конструктор; запятая разделяет bytes и подтип. :: читает константу класса, -> вызывает метод объекта, скобки () показывают вызов без аргументов. Нулевой байт и FF входят в данные, но для их отображения выбран hex. Сам конструктор ещё не сделал запись в базу — это появится в первой полной программе.

Предварительные объяснения: строки и байты, списки и ключи массива, Manager, документы, Query и projection. Для других точных BSON-типов есть ObjectId, время и Decimal128; для текстовых условий — Regex и запросы.

Байты, подтип, UUID, вектор и текстовое представление

Номер Binary subtype не равен номеру BSON-типа поля. MongoDB относит любое Binary к BSON binData; внутри него уже выбирается subtype 0, 4, 9 и т. д. Поэтому getType() Binary читает именно внутреннюю метку. Нельзя передать номер 9 в общий BSON $type-фильтр и ожидать «vector»: у BSON-типов собственная нумерация.

Вектор — список компонент фиксированного смысла и порядка. Float32, Int8 и PackedBit — способы хранить компоненты. Они не вычисляют признаки, не обучают модель и не запускают поиск ближайших соседей. Здесь используются понятные вручную заданные значения, а не выдуманные эмбеддинги.

Подготовка и запуск самостоятельных программ

Все девять архивов самостоятельны. Нужны PHP CLI 8.4+ x64, ext-mongodb 2.5+ и отдельный локальный MongoDB 8.0+. Проверяемая среда пакета: PHP 8.5.11 / mongodb 2.5.5 / MongoDB 8.0.34. Векторные методы существуют с 2.2.0, но полный учебный комплект рассчитан на указанную среду. Composer не требуется.

$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 из распакованного каталога. README.txt каждого архива объясняет установку расширения, проверку CLI php.ini, отдельный dbpath и запуск mongod на loopback. Не подставляйте производственный URI. Helper требует явное учебное ASCII-имя базы и не принимает admin/local/config или учётные данные в URI.

Каждая программа создаёт ровно одну собственную коллекцию mongodb126_binary_ со случайной частью, записывает небольшой набор данных и выбирает нужные поля с пределом до десяти документов. В finally удаляется только созданное точное имя, после чего проверяется отсутствие коллекции. Первый пример также создаёт собственный файл через x+b и удаляет его. Прочие файлы и базы не меняются.

Сохранить байты файла и проверить их после чтения

Сервис принимает небольшой двоичный пакет датчика. В нём могут быть нулевой байт и значения, не являющиеся текстом UTF-8. Нужно сохранить пакет целиком, затем доказать, что чтение вернуло те же шесть байтов.

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

Программа сама создаёт отдельный sensor-frame.bin: A, NUL, FF, B, CR и LF. Это учебный бинарный фрагмент, а не повреждённая строка и не замена настоящего изображения. В MongoDB сохраняются имя пакета и поле payload.

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

$binary = new MongoDB\BSON\Binary("A\0\xFF", MongoDB\BSON\Binary::TYPE_GENERIC);
echo bin2hex($binary->getData()); // 4100ff

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

Результат выполнения

Как это устроено

new создаёт объект Binary. Первый аргумент — содержимое, второй — метка его формата. TYPE_GENERIC равен 0 и подходит произвольным байтам. Ни кодирование base64, ни сжатие здесь не происходят. Кавычки PHP с \0 и \xFF позволяют задать байты: после выполнения это уже не текст из четырёх символов «\xFF».

getData() возвращает исходную PHP-строку байтов. strlen() считает байты, bin2hex() даёт безопасное для чтения шестнадцатеричное представление: одному байту соответствуют две цифры. Приведение (string) вызывает __toString() и возвращает те же исходные байты.

x+b создаёт новый файл и отказывает при совпадении имени. Код сохраняет признак собственного создания, закрывает ресурс, удаляет только свой файл. Для коллекции применяется такой же принцип владения. Запись идёт до Query, поэтому таблица строится по реальному прочитанному полю payload.

SHA256 сравнивается до и после хранения. Дополнительное legacy Extended JSON представление годится для совместимого диагностического обмена: QQD/Qg0K — base64 этих шести байтов, а 00 — подтип. Такой журнал всё равно может содержать чувствительное содержимое: base64 легко декодируется.

Границы и типичные ошибки

Binary хранится внутри BSON-документа, чей предел обычно 16 MiB вместе со всеми полями. Для больших файлов рассматривают файловое хранилище или GridFS, а не огромный массив документов в PHP. Совпадение SHA256 здесь доказывает целостность учебного фрагмента при переносе; оно не удостоверяет источник. В интерфейс выводятся hex и безопасные подписи, исходные байты в HTML не вставляются.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
$path=__DIR__.'/sensor-frame.bin';$ownedFile=false;$handle=null;
try{
    $handle=fopen($path,'x+b');if($handle===false){throw new RuntimeException('Cannot create an owned fixture file');}$ownedFile=true;
    $original="A\0\xFFB\r\n";
    if(fwrite($handle,$original)!==strlen($original)){throw new RuntimeException('Short file write');}
    rewind($handle);$bytes=stream_get_contents($handle);
    if($bytes===false){throw new RuntimeException('Cannot read owned file');}
    fclose($handle);$handle=null;
    $binary=new MongoDB\BSON\Binary($bytes,MongoDB\BSON\Binary::TYPE_GENERIC);
    bv126Insert($manager,$namespace,[['_id'=>101,'name'=>'Пакет датчика','payload'=>$binary]]);
    $doc=bv126Read($manager,$namespace,['_id'=>101],['_id'=>1,'name'=>1,'payload'=>1],1)[0];
    $read=$doc['payload'];$summary=bv126Summary($read);$sameHash=hash('sha256',$original)===hash('sha256',$read->getData());
    $safeDiagnostic=$read->jsonSerialize();
    $rows=[[$doc['name'],$summary['subtype'],$summary['bytes'],$summary['hex'],$sameHash,$safeDiagnostic['$binary']]];
    $checks=['raw_bytes_roundtrip'=>$read->getData()===$original,'string_alias_same'=>(string)$read===$original,
        'generic_type'=>$read->getType()===MongoDB\BSON\Binary::TYPE_GENERIC,'contains_nul_and_non_utf8'=>bin2hex($bytes)==='4100ff420d0a','sha256_matches'=>$sameHash,
        'diagnostic_binary_keeps_subtype'=>$safeDiagnostic===['$binary'=>'QQD/Qg0K','$type'=>'00']];
}finally{
    if(is_resource($handle)){fclose($handle);}
    if($ownedFile && !unlink($path)){throw new RuntimeException('Cannot remove own fixture file');}
}
$checks['own_file_removed']=$ownedFile && !file_exists($path);
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-binary-file', ['Запись', 'Подтип', 'Байт', 'Hex прочитанных байтов', 'SHA256 совпадает', 'Base64 для диагностики'], $rows, $checks, $runtime);
echo 'mongodb126-binary-binary-file: saved result.html and result.json
';

mongodb126-binary-binary-file: saved result.html and result.json

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

Попробуйте изменить. Замените B на C. Предполагаемый hex изменится с 4100ff420d0a на 4100ff430d0a, длина останется 6. Сравнение SHA256 между новым входом и его прочитанной копией по-прежнему должно дать true.

Найти заказ по UUID из текстового поля формы

Форма поиска заказа прислала UUID с дефисами. Заказ есть в MongoDB, но поиск этой строкой ничего не находит: в базе лежит бинарный UUID. Покажем переход от текста формы к значению того же BSON-типа.

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

Известный UUID 00112233-4455-4677-8899-aabbccddeeff принадлежит учебному заказу 201 на 4500 копеек. В примере есть верный ввод в верхнем регистре, заведомо неверный текст и попытка создать UUID из пяти байтов.

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

$bytes = hex2bin('00112233445546778899aabbccddeeff'); // известный корректный UUID
$uuid = new MongoDB\BSON\Binary($bytes, MongoDB\BSON\Binary::TYPE_UUID);
$filter = ['order_uuid' => $uuid]; // Binary, а не строка с дефисами

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

Результат выполнения

Как это устроено

UUID — 128-битный идентификатор, обычно отображаемый как 32 hex-цифры с четырьмя дефисами. Текст удобен человеку, а Binary subtype 4 представляет эти 16 байтов в BSON. Строка и Binary различаются даже тогда, когда человек видит в них «один UUID».

uuid126() сначала проверяет форму строки. Регулярное выражение здесь не учит генерировать UUID: оно лишь допускает шестнадцатеричные группы нужной длины. Затем str_replace убирает дефисы, strtolower унифицирует регистр, hex2bin превращает каждую пару цифр в один байт.

TYPE_UUID выбирает текущий стандартный подтип 4. Передавать конструктору сами 36 символов с дефисами нельзя: он ждёт 16 байтов. Конструктор обнаруживает неверную длину и бросает MongoDB\Driver\Exception\InvalidArgumentException; неверный формат формы отклоняет собственная функция ещё до Query.

В полном примере один Query получает ноль строк, другой — именно заказ 201. Это не потеря документа и не ошибка сортировки: отличается тип фильтра. Ограниченный projection возвращает только необходимые поля, limit равен 1.

Границы и типичные ошибки

Проверка формата не доказывает, что UUID выдан вашим сервисом, и не заменяет проверку доступа к заказу. Для действительного пользовательского запроса добавляют tenant/owner в фильтр. Пример не проверяет все семантические версии UUID и не является его генератором. Уже существующий ObjectId — другой BSON-тип; произвольная подмена его UUID недопустима.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
function uuid126(string $text): MongoDB\BSON\Binary {
    if(!preg_match('/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/iD',$text)){
        throw new InvalidArgumentException('Expected canonical UUID text');
    }
    $bytes=hex2bin(str_replace('-','',strtolower($text)));
    if($bytes===false){throw new RuntimeException('Validated UUID conversion failed');}
    return new MongoDB\BSON\Binary($bytes,MongoDB\BSON\Binary::TYPE_UUID);
}
$text='00112233-4455-4677-8899-aabbccddeeff';$uuid=uuid126($text);
bv126Insert($manager,$namespace,[['_id'=>201,'order_uuid'=>$uuid,'total_kopecks'=>4500]]);
$wrong=bv126Read($manager,$namespace,['order_uuid'=>$text],['_id'=>1],1);
$right=bv126Read($manager,$namespace,['order_uuid'=>uuid126(strtoupper($text))],['_id'=>1,'order_uuid'=>1,'total_kopecks'=>1],1);
$badForm=false;try{uuid126('00112233-wrong');}catch(InvalidArgumentException){$badForm=true;}
$badBytes=false;try{new MongoDB\BSON\Binary('short',MongoDB\BSON\Binary::TYPE_UUID);}catch(MongoDB\Driver\Exception\InvalidArgumentException){$badBytes=true;}
$rows=[['Строка UUID',count($wrong),'совпадения нет'],['Binary subtype 4',count($right),'заказ '.$right[0]['_id'].', 4500 коп.'],
    ['Неверный текст отклонён',$badForm,'до запроса'],['UUID из 5 байт отклонён',$badBytes,'конструктором Binary']];
$checks=['typed_query_selected_order'=>array_column($right,'_id')===[201],'text_query_misses'=>$wrong===[],
    'uuid_16_bytes'=>bv126Summary($right[0]['order_uuid'])===['subtype'=>4,'bytes'=>16,'hex'=>'00112233445546778899aabbccddeeff'],
    'form_rejected'=>$badForm,'bad_binary_length_rejected'=>$badBytes,'order_amount'=>$right[0]['total_kopecks']===4500];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-uuid-lookup', ['Фильтр / проверка', 'Результат', 'Смысл'], $rows, $checks, $runtime);
echo 'mongodb126-binary-uuid-lookup: saved result.html and result.json
';

mongodb126-binary-uuid-lookup: saved result.html and result.json

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

Попробуйте изменить. Замените последнюю hex-цифру UUID только в фильтре. Верный по форме Binary вернёт пустой результат; это нормальное «заказ не найден», а не исключение конструктора.

Реальная постановка проблемы: Obtain UUID from MongoDB in PHP. Идентификатор, записанный Java как legacy Binary, не получается прочитать ожидаемой UUID-строкой простым base64/hex. Урок разделяет bytes, subtype и канонический текст; неизвестный Java byte order не исправляется выдуманным общим алгоритмом. Решение здесь самостоятельное; контракт API подтверждается официальными источниками, а обсуждение показывает, с чем сталкивается разработчик.

Различить одинаковые байты с разными BSON-подтипами

После переноса между системами UUID выглядят одинаково, но фильтр снова не находит запись. Нужно отделить содержимое байтов от метки их формата и понять, почему массово менять subtype 3 на 4 без знания источника опасно.

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

Три документа намеренно получают одинаковые 16 байтов, но разные подтипы: generic 0, legacy UUID 3 и current UUID 4. Их ID — 300, 303 и 304. Это контролируемая демонстрация типов, а не образец реальных Java/C#/Python архивов.

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

$bytes = hex2bin('00112233445546778899aabbccddeeff');
$legacy = new MongoDB\BSON\Binary($bytes, MongoDB\BSON\Binary::TYPE_OLD_UUID);
$standard = new MongoDB\BSON\Binary($bytes, MongoDB\BSON\Binary::TYPE_UUID);
echo $legacy->getType(), '/', $standard->getType(); // 3/4; bytes сами не переставляются

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

Результат выполнения

Как это устроено

Binary — пара «байты + подтип». getType() возвращает вторую часть, getData() — первую. Подтип участвует в точном сравнении бинарного значения. Таблица показывает не три совпадения одного фильтра, а по одному совпадению каждого из трёх отдельных фильтров.

TYPE_OLD_UUID равен 3 и сохранён для совместимости. В разных старых драйверах порядок байтов UUID различался. PHP Binary не меняет его автоматически: при new Binary($bytes, 4) будут всё те же $bytes с другой меткой.

Общая функция bv126Summary принимает BinaryInterface и читает длину, hex и subtype. Это полезная граница кода: функция требует бинарное значение, но не обязана знать, относится оно к файлу, UUID или вектору. Интерфейс не добавляет функции getVectorType(), которой у его контракта нет.

Чтобы мигрировать исторические данные, сначала выясняют драйвер-производитель, соглашение UUID и сравнивают несколько известных идентификаторов. Только затем проектируют преобразование. Из таблицы нельзя вывести универсальное «перевернуть все байты».

Границы и типичные ошибки

Здесь одинаковые bytes специально заданы автором. В реальной миграции один логический UUID может иметь разные байты в старом и новом форматах. Подмена subtype не исправляет такую разницу. Для нового приложения выбирают subtype 4; legacy данные читают с их фактическим соглашением, не смешивая их с произвольными бинарными файлами.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
$bytes=hex2bin('00112233445546778899aabbccddeeff');
$docs=[];foreach([0,3,4] as $type){$docs[]=['_id'=>300+$type,'label'=>'subtype '.$type,'identifier'=>new MongoDB\BSON\Binary($bytes,$type)];}
bv126Insert($manager,$namespace,$docs);$rows=[];$selected=[];$allSame=true;
foreach([0,3,4] as $type){
    $matches=bv126Read($manager,$namespace,['identifier'=>new MongoDB\BSON\Binary($bytes,$type)],['_id'=>1,'identifier'=>1],1);
    if(count($matches)!==1){throw new RuntimeException('Expected one match per subtype');}
    $binary=$matches[0]['identifier'];$summary=bv126Summary($binary);$selected[]=$matches[0]['_id'];
    $rows[]=[$summary['subtype'],$summary['bytes'],$summary['hex'],$matches[0]['_id']];$allSame=$allSame && (string)$binary===$bytes;
}
$checks=['subtype_changes_equality'=>$selected===[300,303,304],'all_raw_bytes_same'=>$allSame,
    'interface_supported'=>$docs[0]['identifier'] instanceof MongoDB\BSON\BinaryInterface,
    'old_uuid_exact_length'=>strlen($docs[1]['identifier']->getData())===16];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-uuid-subtypes', ['Подтип', 'Байт', 'Одинаковые исходные bytes', 'Найденный ID'], $rows, $checks, $runtime);
echo 'mongodb126-binary-uuid-subtypes: saved result.html and result.json
';

mongodb126-binary-uuid-subtypes: saved result.html and result.json

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

Попробуйте изменить. Поменяйте subtype только в фильтре 3 на 4. Вы получите документ 304, а не 303. Затем измените один байт: ни один из старых документов этому новому фильтру не соответствует.

Реальная постановка проблемы: Convert BinData type 3 data to type 4 in MongoDB. Разработчику нужен перевод всех UUID с subtype3 на4. Демонстрация показывает, почему одинаковые bytes с разными метками по-разному выбираются, и почему для реальной миграции нужен известный производитель и порядок байтов. Решение здесь самостоятельное; контракт API подтверждается официальными источниками, а обсуждение показывает, с чем сталкивается разработчик.

Передать бинарное поле через JSON без потери подтипа

Интеграция должна отправить двоичное поле текстовым JSON. Простое json_encode исходных bytes завершается ошибкой UTF-8, а незаметная потеря подтипа ломает последующий поиск UUID. Выберем явное представление и проверим обратный путь.

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

Из MongoDB читается payload из трёх байтов 41 00 FF. Полный пример сравнивает ошибочную сериализацию bytes, собственный JsonSerializable-контракт Binary и современный Canonical Extended JSON документа.

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

$binary = new MongoDB\BSON\Binary("A\0\xFF");
echo json_encode($binary, JSON_THROW_ON_ERROR); // legacy Extended JSON
echo MongoDB\BSON\Document::fromPHP(['payload' => $binary])->toCanonicalExtendedJSON();

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

Результат выполнения

Как это устроено

Обычный JSON содержит текстовые строки Unicode и не имеет самостоятельного бинарного типа. Последовательность FF не является корректной UTF-8-строкой. JSON_THROW_ON_ERROR превращает проблему в JsonException; программа ловит только ожидаемый JSON_ERROR_UTF8.

Binary реализует JsonSerializable: json_encode($binary) автоматически вызывает его jsonSerialize(). Возвращаемое значение метода — структура, которую затем кодирует JSON, а не уже готовая строка JSON. Расширение выдаёт legacy Extended JSON: $binary содержит base64, $type — двухзначный hex-подтип.

Canonical Extended JSON использует другую вложенную форму: $binary содержит base64 и subType. Её явно получает Document::fromPHP(["payload" => $stored])->toCanonicalExtendedJSON(). Document сохраняет BSON-типы; обычный json_decode лишь даёт PHP-массив описания.

Восстановление BSON делает Document::fromJSON(), а get("payload") извлекает настоящий Binary. Проверяются bytes и subtype отдельно. Escape слеша в строке JSON может выглядеть по-разному; мы сравниваем декодированную структуру и значение, а не оформление пробелов.

Границы и типичные ошибки

Не смешивайте legacy Extended JSON с Canonical в одном неописанном протоколе. Передача base64 без subtype допустима только при отдельном договорённом типе поля. Base64 увеличивает текстовое представление и не защищает секреты. Для HTTP API можно выбрать собственный объект {encoding, subtype, data}, если обе стороны явно знают его контракт.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
$original=new MongoDB\BSON\Binary("A\0\xFF",MongoDB\BSON\Binary::TYPE_GENERIC);
bv126Insert($manager,$namespace,[['_id'=>401,'payload'=>$original]]);
$stored=bv126Read($manager,$namespace,['_id'=>401],['_id'=>0,'payload'=>1],1)[0]['payload'];
$rawRejected=false;try{json_encode($stored->getData(),JSON_THROW_ON_ERROR);}catch(JsonException $e){if($e->getCode()!==JSON_ERROR_UTF8){throw $e;}$rawRejected=true;}
$legacy=$stored->jsonSerialize();$encoded=json_encode($stored,JSON_THROW_ON_ERROR);$decodedLegacy=json_decode($encoded,true,512,JSON_THROW_ON_ERROR);
$document=MongoDB\BSON\Document::fromPHP(['payload'=>$stored]);$canonical=$document->toCanonicalExtendedJSON();
$visible=json_decode($canonical,true,512,JSON_THROW_ON_ERROR)['payload']['$binary'];
$roundtrip=MongoDB\BSON\Document::fromJSON($canonical)->get('payload');
$rows=[['JSON исходных bytes','отклонён: не UTF-8','не превращаем байты в текст'],
    ['Binary::jsonSerialize',$legacy['$binary'],$legacy['$type']],
    ['Canonical Extended JSON',$visible['base64'],$visible['subType']],
    ['После fromJSON',bin2hex($roundtrip->getData()),'subtype '.$roundtrip->getType()]];
$checks=['raw_non_utf8_rejected'=>$rawRejected,'legacy_shape'=>$legacy===['$binary'=>'QQD/','$type'=>'00'],
    'json_encode_uses_serializer'=>$decodedLegacy===$legacy,'canonical_shape'=>$visible===['base64'=>'QQD/','subType'=>'00'],
    'canonical_binary_roundtrip'=>$roundtrip instanceof MongoDB\BSON\Binary && $roundtrip->getData()===$stored->getData() && $roundtrip->getType()===$stored->getType()];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-binary-json', ['Операция', 'Данные / результат', 'Подтип / правило'], $rows, $checks, $runtime);
echo 'mongodb126-binary-binary-json: saved result.html and result.json
';

mongodb126-binary-binary-json: saved result.html and result.json

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

Попробуйте изменить. Повторите опыт с 16 байтами UUID subtype 4. Base64 будет другой, subType должен остаться 04, а после fromJSON поле должно снова подходить для бинарного UUID-фильтра.

Реальная постановка проблемы: What does the 0 mean in MongoDB BinData?. Видимый shell-вывод объединяет номер подтипа и base64, из-за чего их легко принять за сами bytes. Урок отличает бинарное содержимое, метку и две JSON-формы. Решение здесь самостоятельное; контракт API подтверждается официальными источниками, а обсуждение показывает, с чем сталкивается разработчик.

Сохранить два числовых признака и увидеть округление Float32

Карточка товара хранит несколько числовых характеристик в фиксированном порядке. Нужно записать компактное числовое представление и понимать, какую точность оно действительно сохраняет, прежде чем использовать его в расчётах.

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

Два вручную заданных признака: доля заполнения 0.1 и масса 1.5 кг. Соглашение manual-features-v1 определяет их порядок, dimensions равно 2. Это обычные учебные числа; они не выдаются за результат нейросети.

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

$features = MongoDB\BSON\Binary::fromVector([0.1, 1.5], MongoDB\BSON\VectorType::Float32);
$numbers = $features->toArray(); // [0.10000000149011612, 1.5]
echo $features->getVectorType()->name; // Float32

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

Результат выполнения

Как это устроено

Вектор в этой главе — упорядоченный список однотипных значений. Он полезен, когда схема уже говорит, что означает каждая позиция. Binary::fromVector() — статический метод: :: вызывает его у класса без предварительного new Binary. Второй аргумент — случай enum VectorType, а не строка "Float32".

PHP float обычно представляет double, а выбранный формат хранит только 32 бита на компоненту. 0.1 не представляется точно и в double, и в Float32; после сужения мы видим дополнительное отличие. 1.5 в этих форматах представляется точно. number_format задаёт ровно десять цифр после точки для понятной таблицы.

getType() возвращает 9 — общую BSON-метку вектора. getVectorType() возвращает объект enum Float32, Int8 или PackedBit. Его name — читаемая подпись; у этого enum нет свойства value с числовым кодом. toArray() распаковывает компоненты обратно в PHP-массив.

fromVector требует настоящие float для Float32: [1] с целым int не принимается, [1.0] подходит. Числовую строку из формы нужно отдельно проверить и преобразовать, а не надеяться на неявную догадку бинарного кодека.

Границы и типичные ошибки

Этот формат не подходит для точных денег: используйте целые копейки или Decimal128. Не сравнивайте произвольные вычисленные Float32 строгим === с исходными double; выбирайте обоснованную погрешность задачи. Формат не обучает модель, не строит индекс и не обеспечивает similarity search. Названия и единицы признаков должны быть закреплены вашей схемой.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
$input=[0.1,1.5];$binary=MongoDB\BSON\Binary::fromVector($input,MongoDB\BSON\VectorType::Float32);
bv126Insert($manager,$namespace,[['_id'=>501,'model_version'=>'manual-features-v1','dimensions'=>2,'features'=>$binary]]);
$doc=bv126Read($manager,$namespace,['_id'=>501],['_id'=>1,'features'=>1,'model_version'=>1,'dimensions'=>1],1)[0];
$stored=$doc['features'];$values=$stored->toArray();$rows=[];
foreach(['Доля заполнения','Масса, кг'] as $i=>$label){$rows[]=[$label,number_format($input[$i],10,'.',''),number_format($values[$i],10,'.',''),$stored->getVectorType()->name];}
$integerRejected=false;try{MongoDB\BSON\Binary::fromVector([1],MongoDB\BSON\VectorType::Float32);}catch(MongoDB\Driver\Exception\InvalidArgumentException){$integerRejected=true;}
$checks=['vector_subtype'=>$stored->getType()===MongoDB\BSON\Binary::TYPE_VECTOR,'float32_format'=>$stored->getVectorType()===MongoDB\BSON\VectorType::Float32,
    'one_value_rounded'=>$values[0]!==$input[0] && abs($values[0]-$input[0])<0.00000001,'exact_half'=>$values[1]===1.5,
    'two_float_values'=>count($values)===2 && is_float($values[0]) && is_float($values[1]),'int_not_implicitly_float'=>$integerRejected,
    'payload_header_and_values'=>bin2hex($stored->getData())==='2700cdcccc3d0000c03f','schema_retained'=>$doc['dimensions']===2 && $doc['model_version']==='manual-features-v1'];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-vector-float32', ['Признак', 'PHP double до записи', 'Float32 после чтения', 'Формат'], $rows, $checks, $runtime);
echo 'mongodb126-binary-vector-float32: saved result.html and result.json
';

mongodb126-binary-vector-float32: saved result.html and result.json

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

Попробуйте изменить. Замените 0.1 на 0.25. Для обеих компонент сравнение с исходными числами станет точным. Затем попробуйте [1, 1.5] и объясните, почему первый элемент надо записать как 1.0.

Хранить калибровочные поправки в Int8 с явными единицами

У трёх датчиков есть небольшие калибровочные поправки. Если они измеряются в десятых долях градуса и попадают в известный диапазон, их можно хранить целыми Int8 и отдельно явно указать масштаб.

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

Поправки в минимальных единицах: -128, 0, 127. Поле unit задаёт 0.1 C; следовательно, таблица должна показать -12.8, 0.0 и 12.7 °C. Намеренные неверные значения 128 и -129 не записываются.

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

$offsets = MongoDB\BSON\Binary::fromVector([-128, 0, 127], MongoDB\BSON\VectorType::Int8);
echo bin2hex($offsets->getData()); // 030080007f: metadata + три signed int8
$values = $offsets->toArray(); // [-128, 0, 127]; масштаб выбирает приложение

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

Результат выполнения

Как это устроено

Int8 — знаковое восьмибитное целое с диапазоном от -128 до 127. Один байт даёт 256 комбинаций: половина отрицательных, ноль и положительные. Верхняя граница 128 не входит. В текущем тексте PHP.net встречается опечатка -127..128; официальный BSON vector specification и работа расширения задают signed 8-bit диапазон -128..127.

Масштаб не встроен в Binary. Мы сами храним unit и сами делим прочитанное целое на 10 при отображении. Если другой потребитель применит иной масштаб, байты сохранятся верно, но смысл результата станет неверным.

Пять байтов в таблице проверки — два байта vector metadata и три компоненты. Это не полный размер BSON-документа: имена полей, _id и другие данные тоже занимают место. Для маленького примера не делается заявление о скорости или общем экономическом выигрыше.

Проверки крайних значений ловят InvalidArgumentException у конкретного fromVector. В реальном импорте следует сообщить пользователю номер неверной строки и не молча обрезать 128 до 127: такая правка изменила бы измерение.

Границы и типичные ошибки

Int8 имеет смысл только при заранее согласованных диапазоне, единицах и масштабе. Для более широких значений выбирайте другой формат или обычные числовые поля. Квантизация с округлением — отдельное бизнес-правило; fromVector её за вас не выполняет. Binary не является удобным полем для произвольной серверной фильтрации по отдельной компоненте.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
$input=[-128,0,127];$binary=MongoDB\BSON\Binary::fromVector($input,MongoDB\BSON\VectorType::Int8);
bv126Insert($manager,$namespace,[['_id'=>601,'unit'=>'0.1 C','model_version'=>'calibration-v1','offsets'=>$binary]]);
$doc=bv126Read($manager,$namespace,['_id'=>601],['_id'=>1,'unit'=>1,'offsets'=>1],1)[0];$stored=$doc['offsets'];$values=$stored->toArray();
$rows=[];foreach($values as $i=>$n){$rows[]=['Датчик '.($i+1),$n,number_format($n/10,1,'.','').' °C',$stored->getVectorType()->name];}
$tooHigh=false;$tooLow=false;
try{MongoDB\BSON\Binary::fromVector([128],MongoDB\BSON\VectorType::Int8);}catch(MongoDB\Driver\Exception\InvalidArgumentException){$tooHigh=true;}
try{MongoDB\BSON\Binary::fromVector([-129],MongoDB\BSON\VectorType::Int8);}catch(MongoDB\Driver\Exception\InvalidArgumentException){$tooLow=true;}
$checks=['int8_values_exact'=>$values===$input,'int8_format'=>$stored->getVectorType()===MongoDB\BSON\VectorType::Int8,
    'payload_five_bytes'=>bv126Summary($stored)===['subtype'=>9,'bytes'=>5,'hex'=>'030080007f'],
    'upper_boundary_rejected'=>$tooHigh,'lower_boundary_rejected'=>$tooLow,'unit_selected'=>$doc['unit']==='0.1 C'];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-vector-int8', ['Позиция', 'Сохранённое целое', 'Поправка по scale 0.1', 'Формат'], $rows, $checks, $runtime);
echo 'mongodb126-binary-vector-int8: saved result.html and result.json
';

mongodb126-binary-vector-int8: saved result.html and result.json

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

Попробуйте изменить. Добавьте поправку 5: на экране это 0.5 °C, payload увеличится с 5 до 6 байтов. Значение 130 надо отклонить или изменить схему хранения; превращать его в 127 без объяснения нельзя.

Упаковать десять флагов комплектации и восстановить подписи

У модели устройства есть десять признаков комплектации. Для передачи фиксированного набора флагов нужен компактный битовый список, из которого потом можно восстановить понятные пользователю названия.

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

Список признаков equipment-v1: USB-C, HDMI, Wi-Fi, Ethernet, Bluetooth, NFC, SD, SIM, камера, микрофон. Вход смешивает bool и целые 0/1; после чтения ожидаются именно int 0/1 в прежнем порядке.

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

$flags = MongoDB\BSON\Binary::fromVector([true, false, 1, 0, 1, 0, 1, 0, 1, 1], MongoDB\BSON\VectorType::PackedBit);
echo bin2hex($flags->getData()); // 1006aac0
$bits = $flags->toArray(); // десять int 0/1, без шести битов заполнения

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

Результат выполнения

Как это устроено

PackedBit сохраняет по одному полезному биту на значение. PHP-метод принимает список bool или int 0/1. Восстановленный массив содержит int, поэтому сравнение $value === 1 корректно даже для входного true.

Десять полезных битов занимают два байта. В последнем остаётся шесть младших битов заполнения. Metadata сообщает, сколько игнорировать: toArray возвращает десять значений, а не шестнадцать. В hex 1006aac0 первые 10 и 06 — байты формата и padding, не первые два пользовательских признака.

Отдельный массив labels превращает позицию в смысл. Флаг 1 сам по себе не означает «есть Wi-Fi», пока неизвестно, какой позиции соответствует Wi-Fi. Поэтому schema_version сохраняется вместе с Binary.

Значение 2 не является битом и вызывает InvalidArgumentException. Не нужно заранее паковать восемь признаков в число 0..255: такой API бывает в других драйверах, но PHP fromVector PackedBit ждёт отдельные биты.

Границы и типичные ошибки

Для обычных фильтруемых свойств каталога понятный массив строк или именованные bool-поля часто удобнее. PackedBit полезен для компактного фиксированного протокола; он не заменяет понятную схему. Не меняйте порядок labels без новой версии. Показываемые четыре байта — payload Binary с metadata, не размер всего документа.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
$labels=['USB-C','HDMI','Wi-Fi','Ethernet','Bluetooth','NFC','SD','SIM','Камера','Микрофон'];
$input=[true,false,1,0,true,false,1,0,1,1];$bits=MongoDB\BSON\Binary::fromVector($input,MongoDB\BSON\VectorType::PackedBit);
bv126Insert($manager,$namespace,[['_id'=>701,'schema_version'=>'equipment-v1','flags'=>$bits]]);
$stored=bv126Read($manager,$namespace,['_id'=>701],['_id'=>1,'flags'=>1,'schema_version'=>1],1)[0];$binary=$stored['flags'];$values=$binary->toArray();
$rows=[];foreach($values as $i=>$value){$rows[]=[$i,$labels[$i],$value,$value===1?'есть':'нет'];}
$bad=false;try{MongoDB\BSON\Binary::fromVector([2],MongoDB\BSON\VectorType::PackedBit);}catch(MongoDB\Driver\Exception\InvalidArgumentException){$bad=true;}
$checks=['ten_values_with_positions'=>$values===[1,0,1,0,1,0,1,0,1,1],
    'packedbit_format'=>$binary->getVectorType()===MongoDB\BSON\VectorType::PackedBit,
    'two_payload_bytes_plus_header'=>bv126Summary($binary)===['subtype'=>9,'bytes'=>4,'hex'=>'1006aac0'],
    'output_integers'=>array_filter($values,fn($v)=>!is_int($v))===[],'invalid_bit_rejected'=>$bad,'schema_version_preserved'=>$stored['schema_version']==='equipment-v1'];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-vector-packed-bits', ['Индекс', 'Признак', 'Прочитанный int', 'На карточке'], $rows, $checks, $runtime);
echo 'mongodb126-binary-vector-packed-bits: saved result.html and result.json
';

mongodb126-binary-vector-packed-bits: saved result.html and result.json

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

Попробуйте изменить. Добавьте одиннадцатый флаг «GPS» со значением 0 в конец схемы. Полезных битов станет 11, padding — 5; toArray должен вернуть ровно 11 значений. Для изменённой схемы задайте новую версию.

Проверить формат, размерность и конечность чисел до сохранения

Интеграция присылает числовой профиль товара. Технически кодек умеет хранить много форм данных, но вашему сервису нужны ровно три конечных Float32 в фиксированном порядке. Отделим ограничения API от требований приложения.

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

Шесть неверных входов: пропуски ключей, пустота, две компоненты, строка, INF и конечное double 1e100. Корректный профиль [0.25, 0.5, 0.75] должен стать единственной записью 801. Отдельно проверяется ошибочное чтение обычного Binary как вектора.

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

$values = [0.25, 0.5, 0.75];
if (!array_is_list($values) || count($values) !== 3) {
    throw new InvalidArgumentException('Нужны три упорядоченных признака');
}
$binary = MongoDB\BSON\Binary::fromVector($values, MongoDB\BSON\VectorType::Float32);

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

Результат выполнения

Как это устроено

array_is_list проверяет последовательные ключи 0..n-1, а count — нужное число компонент. Пропуски могут возникнуть после array_filter. Не применяйте array_values автоматически, пока не ясно, что исчезновение позиции допустимо: оно может сместить смысл признаков.

is_float исключает строки и целые, is_finite исключает NAN и INF. Но конечное PHP double 1e100 всё ещё больше наибольшего конечного Float32. Поэтому приложение отдельно ограничивает модуль значением 3.4028234663852886e38 до кодирования.

Пустой список fromVector принимает и сохраняет только два байта metadata. Наш profile126 отклоняет его, потому что пустота не является товарным профилем из трёх признаков. Это предметное решение, а не приписанное библиотеке ограничение.

getVectorType и toArray для Binary generic бросают LogicException: они не возвращают null и не угадывают содержимое строки. В полном опыте оба неверных вызова происходят реально и ловятся только ожидаемым типом исключения.

Запись выполняется после всех проверок; Query показывает только один корректный документ. Сообщения list_required и dimensions_3_required — короткие коды нашей валидации. Интерфейс приложения может переводить их в понятные подписи.

Границы и типичные ошибки

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

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
function profile126(array $values): MongoDB\BSON\Binary {
    if(!array_is_list($values)){throw new InvalidArgumentException('list_required');}
    if(count($values)!==3){throw new InvalidArgumentException('dimensions_3_required');}
    foreach($values as $n){
        if(!is_float($n) || !is_finite($n)){throw new InvalidArgumentException('finite_float_required');}
        if(abs($n)>3.4028234663852886e38){throw new InvalidArgumentException('float32_range_required');}
    }
    return MongoDB\BSON\Binary::fromVector($values,MongoDB\BSON\VectorType::Float32);
}
$cases=[['Пропуски ключей',[0=>1.0,2=>2.0,3=>3.0],'list_required'],['Пустой профиль',[],'dimensions_3_required'],
    ['Две компоненты',[1.0,2.0],'dimensions_3_required'],['Строка вместо числа',[1.0,'2.0',3.0],'finite_float_required'],
    ['Бесконечность',[1.0,INF,3.0],'finite_float_required'],['Конечное, но слишком большое',[1.0,1e100,3.0],'float32_range_required']];$rows=[];$rejected=0;
foreach($cases as [$label,$input,$expected]){try{profile126($input);throw new RuntimeException('Invalid profile accepted');}
    catch(InvalidArgumentException $e){if($e->getMessage()!==$expected){throw $e;}$rejected++;$rows[]=[$label,'отклонён',$expected];}}
$empty=MongoDB\BSON\Binary::fromVector([],MongoDB\BSON\VectorType::Float32);
$nonvector=new MongoDB\BSON\Binary('plain');$logicErrors=0;
foreach(['getVectorType','toArray'] as $method){try{$nonvector->$method();throw new RuntimeException('Non-vector accepted');}catch(MongoDB\Driver\Exception\LogicException){$logicErrors++;}}
$sparse=false;try{MongoDB\BSON\Binary::fromVector([0=>1,2=>2],MongoDB\BSON\VectorType::Int8);}catch(MongoDB\Driver\Exception\InvalidArgumentException){$sparse=true;}
$good=profile126([0.25,0.5,0.75]);bv126Insert($manager,$namespace,[['_id'=>801,'dimensions'=>3,'features'=>$good]]);
$docs=bv126Read($manager,$namespace,[],['_id'=>1,'features'=>1,'dimensions'=>1],10);
$rows[]=['Корректный профиль','записан','ID '.$docs[0]['_id'].', 3 компоненты'];
$rows[]=['Обычный Binary','не вектор','2 LogicException'];
$checks=['six_invalid_profiles_rejected'=>$rejected===6,'only_valid_record_saved'=>array_column($docs,'_id')===[801],
    'values_preserved'=>$docs[0]['features']->toArray()===[0.25,0.5,0.75],'empty_allowed_by_codec'=>count($empty->toArray())===0 && strlen($empty->getData())===2,
    'nonvector_access_rejected'=>$logicErrors===2,'sparse_list_rejected_by_driver'=>$sparse];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-vector-validation', ['Вход', 'Результат', 'Причина / сохранение'], $rows, $checks, $runtime);
echo 'mongodb126-binary-vector-validation: saved result.html and result.json
';

mongodb126-binary-vector-validation: saved result.html and result.json

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

Попробуйте изменить. Измените dimensions на 4 и добавьте четвёртый признак. Правильное решение меняет проверку длины, схему и версию одновременно; изменение только count оставит потребителям непонятную четвёртую позицию.

Сначала показать карточки, затем получить только выбранные векторы

Список товаров должен открываться без ненужных двоичных полей. Числовые признаки нужны только после выбора двух конкретных товаров для внешнего расчёта. Пусть база вернёт ровно нужные записи и поля.

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

В коллекции три карточки: Кабель 901 и Зарядка 903 с features-v2, Чехол 902 со старой features-v1. Первый Query выбирает заголовки и версию; второй выбирает только ID 901/903, features-v2 и dimensions=3.

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

$filter = ['_id' => ['$in' => [901, 903]], 'model_version' => 'features-v2', 'dimensions' => 3];
$options = ['projection' => ['_id' => 1, 'features' => 1, 'model_version' => 1, 'dimensions' => 1], 'limit' => 2];
$query = new MongoDB\Driver\Query($filter, $options); // выбираем нужное на сервере

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

Результат выполнения

Как это устроено

projection перечисляет поля на стороне MongoDB: тяжёлое features не передаётся для общего экрана. PHP не получает все векторы, чтобы потом выбросить их. sort делает порядок ожидаемым, limit ограничивает число документов; batchSize не подменяет этот предел.

Второй фильтр одновременно проверяет выбранные ID, версию модели и размерность. Две одинаково длинные последовательности разных моделей не становятся совместимыми только из-за длины. ID 902 не попадает в экспорт.

Перед распаковкой читается getVectorType. Потребителю нужны числа, поэтому API получает явный объект с id, model, dimensions, format и values. Это наш предметный JSON-контракт, а не попытка скрытно превратить Binary в обычный массив.

В учебном опыте собираются ровно две небольшие строки. Если задача — экспорт многих документов, применяют последовательное чтение курсора и запись результата по частям. Для реального пользователя также добавляется фильтр tenant/owner и серверный предел разрешённых ID.

Границы и типичные ошибки

Это загрузка выбранных признаков для отдельного расчёта, а не поиск ближайших векторов. Здесь нет модели, Atlas, vectorSearch или оценки качества рекомендаций. Число байтов относится к одному Binary payload. Измерения скорости на таком маленьком наборе не давали бы оснований обещать ускорение production.

<?php
declare(strict_types=1);
require __DIR__.'/bv126-helper.php';
$settings=bv126Settings();$database=$settings['database'];
$manager=new MongoDB\Driver\Manager($settings['uri'],['serverSelectionTimeoutMS'=>1500,'connectTimeoutMS'=>500,'socketTimeoutMS'=>2000,'retryReads'=>false]);
$owned=[];
try{
$version=bv126Command($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=bv126Create($manager,$database,$owned);
$seed=[[901,'Кабель','features-v2',[0.25,0.5,0.75]],[902,'Чехол','features-v1',[0.5,0.5,0.5]],[903,'Зарядка','features-v2',[0.75,0.5,0.25]]];$docs=[];
foreach($seed as [$id,$title,$versionName,$features]){$docs[]=['_id'=>$id,'title'=>$title,'model_version'=>$versionName,'dimensions'=>3,
    'features'=>MongoDB\BSON\Binary::fromVector($features,MongoDB\BSON\VectorType::Float32),'internal_note'=>'не для клиента'];}
bv126Insert($manager,$namespace,$docs);
$cards=bv126Read($manager,$namespace,[],['_id'=>1,'title'=>1,'model_version'=>1],3);
$selected=bv126Read($manager,$namespace,['_id'=>['$in'=>[901,903]],'model_version'=>'features-v2','dimensions'=>3],['_id'=>1,'features'=>1,'model_version'=>1,'dimensions'=>1],2);
$rows=[];$export=[];$allTypes=true;
foreach($selected as $doc){$binary=$doc['features'];$allTypes=$allTypes && $binary->getVectorType()===MongoDB\BSON\VectorType::Float32;
    $values=$binary->toArray();$summary=bv126Summary($binary);
    $export[]=['id'=>$doc['_id'],'model'=>$doc['model_version'],'dimensions'=>$doc['dimensions'],'format'=>$binary->getVectorType()->name,'values'=>$values];
    $rows[]=[$doc['_id'],$doc['model_version'],$binary->getVectorType()->name,implode(', ',array_map(fn($v)=>number_format($v,2,'.',''),$values)),$summary['bytes']];}
$api=json_encode($export,JSON_THROW_ON_ERROR);$decoded=json_decode($api,true,512,JSON_THROW_ON_ERROR);
$checks=['screen_three_metadata_rows'=>array_column($cards,'_id')===[901,902,903],
    'screen_does_not_fetch_vectors'=>array_filter($cards,fn($d)=>array_key_exists('features',$d)||array_key_exists('internal_note',$d))===[],
    'selected_model_only'=>array_column($selected,'_id')===[901,903],'selected_format_float32'=>$allTypes,
    'explicit_api_values'=>$decoded[0]['values']===[0.25,0.5,0.75] && $decoded[1]['values']===[0.75,0.5,0.25],
    'export_has_model_and_dimensions'=>$decoded[0]['model']==='features-v2' && $decoded[0]['dimensions']===3];
}finally{
    foreach(array_reverse($owned) as $name){bv126Command($manager,$database,['drop'=>$name],true);}
}
$removed=true;foreach($owned as $name){if(bv126Exists($manager,$database,$name)){$removed=false;}}
$checks['only_owned_collections_removed']=$removed && count($owned)===1;
bv126Report('mongodb126-binary-selected-vector-export', ['ID выбранного товара', 'Версия признаков', 'Формат', 'Числа для клиента', 'Байт Binary payload'], $rows, $checks, $runtime);
echo 'mongodb126-binary-selected-vector-export: saved result.html and result.json
';

mongodb126-binary-selected-vector-export: saved result.html and result.json

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

Попробуйте изменить. Выберите [901, 902], сохранив условие features-v2. Вернётся только 901. Интерфейс должен сообщить, что второй товар использует другую версию, а не молча сравнивать несовместимые профили.

Как выбрать представление для текущей задачи

Полный справочник Binary, BinaryInterface и VectorType

Сводка Binary сохраняет все константы и методы класса. Каждая карточка раскрывает сигнатуру, параметры, результат, ошибки, версии и два содержательно разных применения. Ссылки ведут к тем же девяти реальным программам, а не к искусственно размноженным копиям.

Закрепить формат и переходить к следующей задаче

Теперь можно выбрать представление по задаче: хранить bytes без потерь, искать UUID с правильным типом, переносить типизированное поле через JSON и получать только нужные векторы. Следующее действие — закрепить формат собственного поля: кто его создаёт, как проверяются входные данные и какие сведения нужны получателю.

Продолжение: Regex для отбора текстовых документов; даты, ObjectId и точные Decimal128; BSON Document и Extended JSON; постраничное чтение и экспорт без накопления всех строк.