Add field type for Binary vectors by GromNaN · Pull Request #2854 · doctrine/mongodb-odm

GromNaN · 2025-10-13T19:25:59Z

Q	A
Type	feature
BC Break	no
Fixed issues	PHPORM-384

Summary

Vector can be compressed into a binary field thanks to the new MongoDB\BSON\Binary::TYPE_VECTOR introduced in MongoDB PHP Extension v2.2.0

Copilot

Pull Request Overview

This PR adds support for MongoDB binary vector field types, leveraging the new MongoDB\BSON\Binary::TYPE_VECTOR introduced in MongoDB PHP Extension v2.2.0. It enables compression of vector data into binary fields for improved performance.

Key changes:

Introduces three new vector types: vector_float32, vector_int8, and vector_packed_bit
Implements type conversion between PHP arrays and MongoDB binary vector format
Adds comprehensive test coverage for the new vector types

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
lib/Doctrine/ODM/MongoDB/Types/Type.php	Adds constants and type mappings for the three vector types
lib/Doctrine/ODM/MongoDB/Types/AbstractVectorType.php	Base implementation for vector type conversion and validation
lib/Doctrine/ODM/MongoDB/Types/VectorFloat32Type.php	Concrete implementation for Float32 vector type
lib/Doctrine/ODM/MongoDB/Types/VectorInt8Type.php	Concrete implementation for Int8 vector type
lib/Doctrine/ODM/MongoDB/Types/VectorPackedBitType.php	Concrete implementation for PackedBit vector type
tests/Doctrine/ODM/MongoDB/Tests/Types/VectorTypeTest.php	Comprehensive test suite for all vector types
tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/VectorSearchTest.php	Updates vector search test to use proper binary vector format
docs/en/reference/basic-mapping.rst	Documents the new vector types and requirements
phpstan-baseline.neon	Adds PHPStan suppressions for MongoDB extension 2.2+ features

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

lib/Doctrine/ODM/MongoDB/Types/AbstractVectorType.php

tests/Doctrine/ODM/MongoDB/Tests/Types/VectorTypeTest.php

paulinevos · 2025-10-14T10:11:33Z

lib/Doctrine/ODM/MongoDB/Types/AbstractVectorType.php

+        return $value->toArray();
+    }
+
+    public function closureToMongo(): string


What are these methods for? Might be helpful to document. At least to me it's unclear what they are

Ok, addressed your request in #2855

For the record, in all my years of working with ODM (on and off) I don't think I've ever fully understood why we needed all of these methods. The answer probably rests in what PHP 5.3 was capable of back in the day.

GromNaN · 2025-10-14T13:05:28Z

lib/Doctrine/ODM/MongoDB/Types/AbstractVectorType.php

+            throw new InvalidArgumentException(sprintf('Invalid binary vector data of vector type %s received for vector field, expected vector type %s', $value->getVectorType()->name, $this->getVectorType()->name));
+        }
+
+        return $value->toArray();


In the design, the property type is considered to be an array, so an array is always returned. However, it would be much more useful to know the type of the property in order to return a Binary if the property allows it, thus avoiding the need to decode the vector when it's not actually used.

Is this something not possible with the current design of the type, since we don't have any context for the class property to which we are associated?

jmikola · 2025-10-16T03:49:04Z

lib/Doctrine/ODM/MongoDB/Types/AbstractVectorType.php

+            throw new InvalidArgumentException(sprintf('Invalid binary vector data of vector type %s received for vector field, expected vector type %s', $value->getVectorType()->name, $this->getVectorType()->name));
+        }
+
+        return $value->toArray();


Is this something not possible with the current design of the type, since we don't have any context for the class property to which we are associated?

jmikola · 2025-10-16T03:52:51Z

tests/Doctrine/ODM/MongoDB/Tests/Types/VectorTypeTest.php

+use PHPUnit\Framework\TestCase;
+
+/** Binary Vector type added in ext-mongodb 2.2+ */
+#[RequiresMethod(Binary::class, 'fromVector')]


TIL https://docs.phpunit.de/en/11.5/writing-tests-for-phpunit.html#skipping-tests-using-attributes

Very handy. I don't get why Sebastian rejected RequiresClass: sebastianbergmann/phpunit#4792

I could have used RequiresPhpExtension('mongodb', '>= 2.2')

Could folks just use RequiresMethod(MyClass::class, '__construct()') since all classes have a constructor?

Edit: No they cannot. Not all classes have a constructor (even implicit): https://3v4l.org/Y5OdE#v8.4.13

jmikola

Do you want to block this on an ext-mongodb 2.2.0 release? I'll defer to you.

I assume no changes to composer.json or the CI workflow are required.

jmikola · 2025-10-16T13:31:37Z

lib/Doctrine/ODM/MongoDB/Types/AbstractVectorType.php

+PHP);
+    }
+
+    abstract protected function getVectorType(): VectorType;


Is the PHPStan error here just due to the class not being available?

I've skipped in PHPStan all errors related to binary vectors.

GromNaN · 2025-10-16T14:48:10Z

composer.json

        "phpstan/phpstan-deprecation-rules": "^2.0",
        "phpstan/phpstan-phpunit": "^2.0",
-        "phpunit/phpunit": "^10.4",
+        "phpunit/phpunit": "^10.5.58",


Updating the minimum version of PHPUnit as the version 10.4.0 load the data providers even if #[RequiresPhpExtension('mongodb', '>= 2.2')] is not matched.

GromNaN added this to the 2.13.0 milestone Oct 13, 2025

GromNaN added the Feature label Oct 13, 2025

GromNaN requested a review from Copilot October 13, 2025 19:26

Copilot AI reviewed Oct 13, 2025

View reviewed changes

GromNaN force-pushed the PHPORM-384 branch from 76b7451 to f5efc4a Compare October 13, 2025 19:41

GromNaN requested a review from jmikola October 13, 2025 19:42

GromNaN force-pushed the PHPORM-384 branch 3 times, most recently from e143a37 to 7a1f26b Compare October 13, 2025 19:52

paulinevos reviewed Oct 14, 2025

View reviewed changes

GromNaN mentioned this pull request Oct 14, 2025

Document methods Type::closureToMongo() and closureToPHP() #2855

Merged

GromNaN commented Oct 14, 2025

View reviewed changes

jmikola reviewed Oct 16, 2025

View reviewed changes

jmikola approved these changes Oct 16, 2025

View reviewed changes

GromNaN force-pushed the PHPORM-384 branch 3 times, most recently from e1b52dc to 82a1b5c Compare October 16, 2025 14:01

Add field type for binary vectors

fa54296

GromNaN force-pushed the PHPORM-384 branch from 82a1b5c to fa54296 Compare October 16, 2025 14:43

GromNaN commented Oct 16, 2025

View reviewed changes

GromNaN merged commit fa8affc into doctrine:2.13.x Oct 16, 2025
24 checks passed

GromNaN deleted the PHPORM-384 branch October 16, 2025 14:48

github-actions bot mentioned this pull request Oct 20, 2025

Merge release 2.13.0 into 3.0.x #2863

Merged

Uh oh!

Conversation

GromNaN commented Oct 13, 2025

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmikola Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmikola left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GromNaN Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jmikola Oct 16, 2025 •

edited

Loading

GromNaN Oct 16, 2025 •

edited

Loading