PHPLIB-1363 PHPLIB-1355 Add enum for $type query and $meta expression

generator/config/expression/meta.yaml

@@ -11,3 +11,29 @@ arguments:
         name: keyword
         type:
             - string
+tests:
+    -
+        name: 'textScore'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta/#-meta---textscore-'
+        pipeline:
+            -
+                $match:
+                    $text:
+                        $search: 'cake'
+            -
+                $group:
+                    _id:
+                        $meta: 'textScore'
+                    count:
+                        $sum: 1
+    -
+        name: 'indexKey'
+        link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta/#-meta---indexkey-'
+        pipeline:
+            -
+                $match:
+                    type: 'apparel'
+            -
+                $addFields:
+                    idxKey:
+                        $meta: 'indexKey'

psalm-baseline.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.20.0@3f284e96c9d9be6fe6b15c79416e1d1903dcfef4">
+<files psalm-version="5.21.0@04ba9358e3f7d14a9dc3edd4e814a9d51d8c637f">
   <file src="src/Builder/Encoder/AbstractExpressionEncoder.php">
     <MixedAssignment>
       <code>$val</code>
@@ -52,6 +52,9 @@
     <ArgumentTypeCoercion>
       <code>$query</code>
     </ArgumentTypeCoercion>
+    <PossiblyInvalidArgument>
+      <code>$type</code>
+    </PossiblyInvalidArgument>
   </file>
   <file src="src/Builder/Query/ElemMatchOperator.php">
     <MixedArgumentTypeCoercion>

src/Builder/Encoder/OperatorEncoder.php

@@ -4,6 +4,7 @@
 
 namespace MongoDB\Builder\Encoder;
 
+use BackedEnum;
 use LogicException;
 use MongoDB\Builder\Stage\GroupStage;
 use MongoDB\Builder\Type\Encode;
@@ -65,6 +66,10 @@ public function encode(mixed $value): stdClass
      */
     private function encodeAsArray(OperatorInterface $value): stdClass
     {
+        if ($value instanceof BackedEnum) {
+            return $this->wrap($value, [$value->value]);
+        }
+
         $result = [];
         /** @var mixed $val */
         foreach (get_object_vars($value) as $val) {
@@ -142,6 +147,10 @@ private function encodeAsDollarObject(OperatorInterface $value): stdClass
      */
     private function encodeAsSingle(OperatorInterface $value): stdClass
     {
+        if ($value instanceof BackedEnum) {
+            return $this->wrap($value, $value->value);
+        }
+
         foreach (get_object_vars($value) as $val) {
             $result = $this->recursiveEncode($val);
 

src/Builder/Meta.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Builder;
+
+use MongoDB\Builder\Type\Encode;
+use MongoDB\Builder\Type\ExpressionInterface;
+use MongoDB\Builder\Type\OperatorInterface;
+
+/**
+ * Returns the metadata associated with a document, e.g. "textScore" when performing text search.
+ *
+ * @see https://www.mongodb.com/docs/manual/reference/operator/aggregation/meta/
+ */
+enum Meta: string implements OperatorInterface, ExpressionInterface
+{
+    public const ENCODE = Encode::Single;
+
+    /**
+     * Returns the score associated with the corresponding $text query for each
+     * matching document. The text score signifies how well the document matched
+     * the search term or terms.
+     */
+    case TextScore = 'textScore';
+
+    /**
+     * Returns an index key for the document if a non-text index is used. The
+     * { $meta: "indexKey" } expression is for debugging purposes only, and
+     * not for application logic, and is preferred over cursor.returnKey().
+     */
+    case IndexKey = 'indexKey';
+
+    /**
+     * Display search terms in their original context.
+     */
+    case SearchHighlights = 'searchHighlights';
+
+    public function getOperator(): string
+    {
+        return '$meta';
+    }
+}

src/Builder/Query.php

@@ -7,6 +7,7 @@
 use MongoDB\BSON\Regex;
 use MongoDB\BSON\Type;
 use MongoDB\Builder\Query\RegexOperator;
+use MongoDB\Builder\Query\TypeOperator;
 use MongoDB\Builder\Type\CombinedFieldQuery;
 use MongoDB\Builder\Type\FieldQueryInterface;
 use MongoDB\Builder\Type\QueryInterface;
@@ -25,6 +26,27 @@ final class Query
 {
     use Query\FactoryTrait {
         regex as private generatedRegex;
+        type as private generatedType;
+    }
+
+    /**
+     * Selects documents if a field is of the specified type.
+     *
+     * @see https://www.mongodb.com/docs/manual/reference/operator/query/type/
+     *
+     * @param int|non-empty-string|QueryType ...$type
+     *
+     * @no-named-arguments
+     */
+    public static function type(string|int|QueryType ...$type): TypeOperator
+    {
+        foreach ($type as &$value) {
+            if ($value instanceof QueryType) {
+                $value = $value->value;
+            }
+        }
+
+        return self::generatedType(...$type);
     }
 
     /**

src/Builder/QueryType.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Builder;
+
+use MongoDB\Builder\Query\TypeOperator;
+use MongoDB\Builder\Type\Encode;
+use MongoDB\Builder\Type\FieldQueryInterface;
+use MongoDB\Builder\Type\OperatorInterface;
+
+/**
+ * Shortcut for $type field query operator
+ *
+ * @see https://www.mongodb.com/docs/manual/reference/operator/query/type/#available-types
+ * @see TypeOperator
+ */
+enum QueryType: string implements OperatorInterface, FieldQueryInterface
+{
+    public const ENCODE = Encode::Array;
+
+    case Array = 'array';
+    case Binary = 'binData';
+    case Bool = 'bool';
+    case Decimal64 = 'double';
+    case Decimal128 = 'decimal';
+    case Int32 = 'int';
+    case Int64 = 'long';
+    case Javascript = 'javascript';
+    case Object = 'object';
+    case ObjectId = 'objectId';
+    case MaxKey = 'maxKey';
+    case MinKey = 'minKey';
+    case Null = 'null';
+    /** Alias for Int32, Int64, Decimal64, Decimal128 */
+    case Number = 'number';
+    case Regex = 'regex';
+    case String = 'string';
+    case Timestamp = 'timestamp';
+    case UTCDateTime = 'date';
+
+    public function getOperator(): string
+    {
+        return '$type';
+    }
+}

tests/Builder/Expression/MetaOperatorTest.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Tests\Builder\Expression;
+
+use MongoDB\Builder\Accumulator;
+use MongoDB\Builder\Expression;
+use MongoDB\Builder\Meta;
+use MongoDB\Builder\Pipeline;
+use MongoDB\Builder\Query;
+use MongoDB\Builder\Stage;
+use MongoDB\Tests\Builder\PipelineTestCase;
+
+/**
+ * Test $meta expression
+ */
+class MetaOperatorTest extends PipelineTestCase
+{
+    public function testIndexKey(): void
+    {
+        $pipeline = new Pipeline(
+            Stage::match(
+                type: 'apparel',
+            ),
+            Stage::addFields(
+                idxKey: Expression::meta('indexKey'),
+            ),
+        );
+
+        $this->assertSamePipeline(Pipelines::MetaIndexKey, $pipeline);
+    }
+
+    public function testIndexKeyWithEnum(): void
+    {
+        $pipeline = new Pipeline(
+            Stage::match(
+                type: 'apparel',
+            ),
+            Stage::addFields(
+                idxKey: Meta::IndexKey,
+            ),
+        );
+
+        $this->assertSamePipeline(Pipelines::MetaIndexKey, $pipeline);
+    }
+
+    public function testTextScore(): void
+    {
+        $pipeline = new Pipeline(
+            Stage::match(
+                Query::text('cake'),
+            ),
+            Stage::group(
+                _id: Expression::meta('textScore'),
+                count: Accumulator::sum(1),
+            ),
+        );
+
+        $this->assertSamePipeline(Pipelines::MetaTextScore, $pipeline);
+    }
+
+    public function testTextScoreWithEnum(): void
+    {
+        $pipeline = new Pipeline(
+            Stage::match(
+                Query::text('cake'),
+            ),
+            Stage::group(
+                _id: Meta::TextScore,
+                count: Accumulator::sum(1),
+            ),
+        );
+
+        $this->assertSamePipeline(Pipelines::MetaTextScore, $pipeline);
+    }
+}

tests/Builder/Query/TypeOperatorTest.php

@@ -6,6 +6,7 @@
 
 use MongoDB\Builder\Pipeline;
 use MongoDB\Builder\Query;
+use MongoDB\Builder\QueryType;
 use MongoDB\Builder\Stage;
 use MongoDB\Tests\Builder\PipelineTestCase;
 
@@ -32,16 +33,16 @@ public function testQueryingByDataType(): void
                 zipCode: Query::type(2),
             ),
             Stage::match(
-                zipCode: Query::type('string'),
+                zipCode: QueryType::String,
             ),
             Stage::match(
                 zipCode: Query::type(1),
             ),
             Stage::match(
-                zipCode: Query::type('double'),
+                zipCode: Query::type(QueryType::Decimal64),
             ),
             Stage::match(
-                zipCode: Query::type('number'),
+                zipCode: QueryType::Number,
             ),
         );
 
@@ -69,7 +70,7 @@ public function testQueryingByMultipleDataType(): void
                 zipCode: Query::type(2, 1),
             ),
             Stage::match(
-                zipCode: Query::type('string', 'double'),
+                zipCode: Query::type(QueryType::String, 'double'),
             ),
         );