vendor/doctrine/mongodb-odm/lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php line 170

  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ODM\MongoDB\Aggregation;
  7. use Doctrine\ODM\MongoDB\Aggregation\Stage\Sort;
  8. use Doctrine\ODM\MongoDB\DocumentManager;
  9. use Doctrine\ODM\MongoDB\Iterator\Iterator;
  10. use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
  11. use Doctrine\ODM\MongoDB\Persisters\DocumentPersister;
  12. use Doctrine\ODM\MongoDB\Query\Expr as QueryExpr;
  13. use GeoJson\Geometry\Point;
  14. use MongoDB\Collection;
  15. use OutOfRangeException;
  16. use TypeError;
  18. use function array_map;
  19. use function array_unshift;
  20. use function func_get_arg;
  21. use function func_num_args;
  22. use function gettype;
  23. use function is_array;
  24. use function is_bool;
  25. use function sprintf;
  26. use function trigger_deprecation;
  28. /**
  29.  * Fluent interface for building aggregation pipelines.
  30.  *
  31.  * @psalm-import-type SortShape from Sort
  32.  */
  33. class Builder
  34. {
  35.     /**
  36.      * The DocumentManager instance for this query
  37.      */
  38.     private DocumentManager $dm;
  40.     /**
  41.      * The ClassMetadata instance.
  42.      */
  43.     private ClassMetadata $class;
  45.     /** @psalm-var class-string */
  46.     private ?string $hydrationClass = null;
  48.     /**
  49.      * The Collection instance.
  50.      */
  51.     private Collection $collection;
  53.     /** @var Stage[] */
  54.     private array $stages = [];
  56.     private bool $rewindable = true;
  58.     /**
  59.      * Create a new aggregation builder.
  60.      *
  61.      * @psalm-param class-string $documentName
  62.      */
  63.     public function __construct(DocumentManager $dm, string $documentName)
  64.     {
  65.         $this->dm         = $dm;
  66.         $this->class      = $this->dm->getClassMetadata($documentName);
  67.         $this->collection = $this->dm->getDocumentCollection($documentName);
  68.     }
  70.     /**
  71.      * Adds new fields to documents. $addFields outputs documents that contain all
  72.      * existing fields from the input documents and newly added fields.
  73.      *
  74.      * The $addFields stage is equivalent to a $project stage that explicitly specifies
  75.      * all existing fields in the input documents and adds the new fields.
  76.      *
  77.      * If the name of the new field is the same as an existing field name (including _id),
  78.      * $addFields overwrites the existing value of that field with the value of the
  79.      * specified expression.
  80.      *
  81.      * @see http://docs.mongodb.com/manual/reference/operator/aggregation/addFields/
  82.      */
  83.     public function addFields(): Stage\AddFields
  84.     {
  85.         $stage = new Stage\AddFields($this);
  86.         $this->addStage($stage);
  88.         return $stage;
  89.     }
  91.     /**
  92.      * Categorizes incoming documents into groups, called buckets, based on a
  93.      * specified expression and bucket boundaries.
  94.      *
  95.      * Each bucket is represented as a document in the output. The document for
  96.      * each bucket contains an _id field, whose value specifies the inclusive
  97.      * lower bound of the bucket and a count field that contains the number of
  98.      * documents in the bucket. The count field is included by default when the
  99.      * output is not specified.
  100.      *
  101.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucket/
  102.      */
  103.     public function bucket(): Stage\Bucket
  104.     {
  105.         $stage = new Stage\Bucket($this, $this->dm, $this->class);
  106.         $this->addStage($stage);
  108.         return $stage;
  109.     }
  111.     /**
  112.      * Categorizes incoming documents into a specific number of groups, called
  113.      * buckets, based on a specified expression.
  114.      *
  115.      * Bucket boundaries are automatically determined in an attempt to evenly
  116.      * distribute the documents into the specified number of buckets. Each
  117.      * bucket is represented as a document in the output. The document for each
  118.      * bucket contains an _id field, whose value specifies the inclusive lower
  119.      * bound and the exclusive upper bound for the bucket, and a count field
  120.      * that contains the number of documents in the bucket. The count field is
  121.      * included by default when the output is not specified.
  122.      *
  123.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/
  124.      */
  125.     public function bucketAuto(): Stage\BucketAuto
  126.     {
  127.         $stage = new Stage\BucketAuto($this, $this->dm, $this->class);
  128.         $this->addStage($stage);
  130.         return $stage;
  131.     }
  133.     /**
  134.      * Returns statistics regarding a collection or view.
  135.      *
  136.      * $collStats must be the first stage in an aggregation pipeline, or else
  137.      * the pipeline returns an error.
  138.      *
  139.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/collStats/
  140.      */
  141.     public function collStats(): Stage\CollStats
  142.     {
  143.         $stage = new Stage\CollStats($this);
  144.         $this->addStage($stage);
  146.         return $stage;
  147.     }
  149.     /**
  150.      * Returns a document that contains a count of the number of documents input
  151.      * to the stage.
  152.      *
  153.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/count/
  154.      */
  155.     public function count(string $fieldName): Stage\Count
  156.     {
  157.         $stage = new Stage\Count($this, $fieldName);
  158.         $this->addStage($stage);
  160.         return $stage;
  161.     }
  163.     /**
  164.      * Executes the aggregation pipeline
  165.      *
  166.      * @deprecated This method was deprecated in doctrine/mongodb-odm 2.2. Please use getAggregation() instead.
  167.      *
  168.      * @param array<string, mixed> $options
  169.      */
  170.     public function execute(array $options = []): Iterator
  171.     {
  172.         trigger_deprecation(
  173.             'doctrine/mongodb-odm',
  174.             '2.2',
  175.             'Using "%s" is deprecated. Please use "%s::getAggregation()" instead.',
  176.             __METHOD__,
  177.             self::class,
  178.         );
  180.         return $this->getAggregation($options)->getIterator();
  181.     }
  183.     public function expr(): Expr
  184.     {
  185.         return new Expr($this->dm, $this->class);
  186.     }
  188.     /**
  189.      * Processes multiple aggregation pipelines within a single stage on the
  190.      * same set of input documents.
  191.      *
  192.      * Each sub-pipeline has its own field in the output document where its
  193.      * results are stored as an array of documents.
  194.      */
  195.     public function facet(): Stage\Facet
  196.     {
  197.         $stage = new Stage\Facet($this);
  198.         $this->addStage($stage);
  200.         return $stage;
  201.     }
  203.     /**
  204.      * Outputs documents in order of nearest to farthest from a specified point.
  205.      *
  206.      * A GeoJSON point may be provided as the first and only argument for
  207.      * 2dsphere queries. This single parameter may be a GeoJSON point object or
  208.      * an array corresponding to the point's JSON representation. If GeoJSON is
  209.      * used, the "spherical" option will default to true.
  210.      *
  211.      * You can only use this as the first stage of a pipeline.
  212.      *
  213.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/
  214.      *
  215.      * @param float|array<string, mixed>|Point $x
  216.      * @param float                            $y
  217.      */
  218.     public function geoNear($x, $y = null): Stage\GeoNear
  219.     {
  220.         $stage = new Stage\GeoNear($this, $x, $y);
  221.         $this->addStage($stage);
  223.         return $stage;
  224.     }
  226.     /**
  227.      * Returns an aggregation object for the current pipeline
  228.      *
  229.      * @param array<string, mixed> $options
  230.      */
  231.     public function getAggregation(array $options = []): Aggregation
  232.     {
  233.         $class = $this->hydrationClass ? $this->dm->getClassMetadata($this->hydrationClass) : null;
  235.         return new Aggregation($this->dm, $class, $this->collection, $this->getPipeline(), $options, $this->rewindable);
  236.     }
  238.     // phpcs:disable Squiz.Commenting.FunctionComment.ExtraParamComment
  239.     /**
  240.      * Returns the assembled aggregation pipeline
  241.      *
  242.      * @param bool $applyFilters Whether to apply filters on the aggregation
  243.      * pipeline stage
  244.      *
  245.      * For pipelines where the first stage is a $geoNear stage, it will apply
  246.      * the document filters and discriminator queries to the query portion of
  247.      * the geoNear operation. For all other pipelines, it prepends a $match stage
  248.      * containing the required query.
  249.      *
  250.      * For aggregation pipelines that will be nested (e.g. in a facet stage),
  251.      * you should not apply filters as this may cause wrong results to be
  252.      * given.
  253.      *
  254.      * @return array<array<string, mixed>>
  255.      */
  256.     // phpcs:enable Squiz.Commenting.FunctionComment.ExtraParamComment
  257.     public function getPipeline(/* bool $applyFilters = true */): array
  258.     {
  259.         $applyFilters = func_num_args() > 0 ? func_get_arg(0) : true;
  261.         if (! is_bool($applyFilters)) {
  262.             throw new TypeError(sprintf(
  263.                 'Argument 1 passed to %s must be of the type bool, %s given',
  264.                 __METHOD__,
  265.                 gettype($applyFilters),
  266.             ));
  267.         }
  269.         $pipeline = array_map(
  270.             static fn (Stage $stage) => $stage->getExpression(),
  271.             $this->stages,
  272.         );
  274.         if ($this->getStage(0) instanceof Stage\IndexStats) {
  275.             // Don't apply any filters when using an IndexStats stage: since it
  276.             // needs to be the first pipeline stage, prepending a match stage
  277.             // with discriminator information will not work
  279.             $applyFilters = false;
  280.         }
  282.         if (! $applyFilters) {
  283.             return $pipeline;
  284.         }
  286.         if ($this->getStage(0) instanceof Stage\GeoNear) {
  287.             $pipeline[0]['$geoNear']['query'] = $this->applyFilters($pipeline[0]['$geoNear']['query']);
  289.             return $pipeline;
  290.         }
  292.         $matchExpression = $this->applyFilters([]);
  293.         if ($matchExpression !== []) {
  294.             array_unshift($pipeline, ['$match' => $matchExpression]);
  295.         }
  297.         return $pipeline;
  298.     }
  300.     /**
  301.      * Returns a certain stage from the pipeline
  302.      */
  303.     public function getStage(int $index): Stage
  304.     {
  305.         if (! isset($this->stages[$index])) {
  306.             throw new OutOfRangeException(sprintf('Could not find stage with index %d.', $index));
  307.         }
  309.         return $this->stages[$index];
  310.     }
  312.     /**
  313.      * Performs a recursive search on a collection, with options for restricting
  314.      * the search by recursion depth and query filter.
  315.      *
  316.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/graphLookup/
  317.      *
  318.      * @param string $from Target collection for the $graphLookup operation to
  319.      * search, recursively matching the connectFromField to the connectToField.
  320.      */
  321.     public function graphLookup(string $from): Stage\GraphLookup
  322.     {
  323.         $stage = new Stage\GraphLookup($this, $from, $this->dm, $this->class);
  324.         $this->addStage($stage);
  326.         return $stage;
  327.     }
  329.     /**
  330.      * Groups documents by some specified expression and outputs to the next
  331.      * stage a document for each distinct grouping.
  332.      *
  333.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/group/
  334.      */
  335.     public function group(): Stage\Group
  336.     {
  337.         $stage = new Stage\Group($this);
  338.         $this->addStage($stage);
  340.         return $stage;
  341.     }
  343.     /**
  344.      * Set which class to use when hydrating results as document class instances.
  345.      */
  346.     public function hydrate(?string $className): self
  347.     {
  348.         $this->hydrationClass = $className;
  350.         return $this;
  351.     }
  353.     /**
  354.      * Returns statistics regarding the use of each index for the collection.
  355.      *
  356.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/indexStats/
  357.      */
  358.     public function indexStats(): Stage\IndexStats
  359.     {
  360.         $stage = new Stage\IndexStats($this);
  361.         $this->addStage($stage);
  363.         return $stage;
  364.     }
  366.     /**
  367.      * Limits the number of documents passed to the next stage in the pipeline.
  368.      *
  369.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/limit/
  370.      */
  371.     public function limit(int $limit): Stage\Limit
  372.     {
  373.         $stage = new Stage\Limit($this, $limit);
  374.         $this->addStage($stage);
  376.         return $stage;
  377.     }
  379.     /**
  380.      * Performs a left outer join to an unsharded collection in the same
  381.      * database to filter in documents from the “joined” collection for
  382.      * processing.
  383.      *
  384.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/lookup/
  385.      */
  386.     public function lookup(string $from): Stage\Lookup
  387.     {
  388.         $stage = new Stage\Lookup($this, $from, $this->dm, $this->class);
  389.         $this->addStage($stage);
  391.         return $stage;
  392.     }
  394.     /**
  395.      * Filters the documents to pass only the documents that match the specified
  396.      * condition(s) to the next pipeline stage.
  397.      *
  398.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/match/
  399.      */
  400.     public function match(): Stage\MatchStage
  401.     {
  402.         $stage = new Stage\MatchStage($this);
  403.         $this->addStage($stage);
  405.         return $stage;
  406.     }
  408.     /**
  409.      * Returns a query expression to be used in match stages
  410.      */
  411.     public function matchExpr(): QueryExpr
  412.     {
  413.         $expr = new QueryExpr($this->dm);
  414.         $expr->setClassMetadata($this->class);
  416.         return $expr;
  417.     }
  419.     /**
  420.      * Takes the documents returned by the aggregation pipeline and writes them
  421.      * to a specified collection. This must be the last stage in the pipeline.
  422.      *
  423.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/out/
  424.      */
  425.     public function out(string $from): Stage\Out
  426.     {
  427.         $stage = new Stage\Out($this, $from, $this->dm);
  428.         $this->addStage($stage);
  430.         return $stage;
  431.     }
  433.     /**
  434.      * Passes along the documents with only the specified fields to the next
  435.      * stage in the pipeline. The specified fields can be existing fields from
  436.      * the input documents or newly computed fields.
  437.      *
  438.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/project/
  439.      */
  440.     public function project(): Stage\Project
  441.     {
  442.         $stage = new Stage\Project($this);
  443.         $this->addStage($stage);
  445.         return $stage;
  446.     }
  448.     /**
  449.      * Restricts the contents of the documents based on information stored in
  450.      * the documents themselves.
  451.      *
  452.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/redact/
  453.      */
  454.     public function redact(): Stage\Redact
  455.     {
  456.         $stage = new Stage\Redact($this);
  457.         $this->addStage($stage);
  459.         return $stage;
  460.     }
  462.     /**
  463.      * Promotes a specified document to the top level and replaces all other
  464.      * fields.
  465.      *
  466.      * The operation replaces all existing fields in the input document,
  467.      * including the _id field. You can promote an existing embedded document to
  468.      * the top level, or create a new document for promotion.
  469.      *
  470.      * @param string|mixed[]|Expr|null $expression Optional. A replacement expression that
  471.      * resolves to a document.
  472.      */
  473.     public function replaceRoot($expression = null): Stage\ReplaceRoot
  474.     {
  475.         $stage = new Stage\ReplaceRoot($this, $this->dm, $this->class, $expression);
  476.         $this->addStage($stage);
  478.         return $stage;
  479.     }
  481.     /**
  482.      * Controls if resulting iterator should be wrapped with CachingIterator.
  483.      */
  484.     public function rewindable(bool $rewindable = true): self
  485.     {
  486.         $this->rewindable = $rewindable;
  488.         return $this;
  489.     }
  491.     /**
  492.      * Randomly selects the specified number of documents from its input.
  493.      *
  494.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sample/
  495.      */
  496.     public function sample(int $size): Stage\Sample
  497.     {
  498.         $stage = new Stage\Sample($this, $size);
  499.         $this->addStage($stage);
  501.         return $stage;
  502.     }
  504.     /**
  505.      * Skips over the specified number of documents that pass into the stage and
  506.      * passes the remaining documents to the next stage in the pipeline.
  507.      *
  508.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/skip/
  509.      */
  510.     public function skip(int $skip): Stage\Skip
  511.     {
  512.         $stage = new Stage\Skip($this, $skip);
  513.         $this->addStage($stage);
  515.         return $stage;
  516.     }
  518.     /**
  519.      * Sorts all input documents and returns them to the pipeline in sorted
  520.      * order.
  521.      *
  522.      * If sorting by multiple fields, the first argument should be an array of
  523.      * field name (key) and order (value) pairs.
  524.      *
  525.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sort/
  526.      *
  527.      * @param array<string, int|string|array<string, string>>|string $fieldName Field name or array of field/order pairs
  528.      * @param int|string|null                                        $order     Field order (if one field is specified)
  529.      * @psalm-param SortShape|string $fieldName Field name or array of field/order pairs
  530.      */
  531.     public function sort($fieldName, $order = null): Stage\Sort
  532.     {
  533.         $fields = is_array($fieldName) ? $fieldName : [$fieldName => $order];
  534.         // fixme: move to sort stage
  535.         $stage = new Stage\Sort($this, $this->getDocumentPersister()->prepareSort($fields));
  536.         $this->addStage($stage);
  538.         return $stage;
  539.     }
  541.     /**
  542.      * Groups incoming documents based on the value of a specified expression,
  543.      * then computes the count of documents in each distinct group.
  544.      *
  545.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sortByCount/
  546.      */
  547.     public function sortByCount(string $expression): Stage\SortByCount
  548.     {
  549.         $stage = new Stage\SortByCount($this, $expression, $this->dm, $this->class);
  550.         $this->addStage($stage);
  552.         return $stage;
  553.     }
  555.     /**
  556.      * Deconstructs an array field from the input documents to output a document
  557.      * for each element. Each output document is the input document with the
  558.      * value of the array field replaced by the element.
  559.      *
  560.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/
  561.      */
  562.     public function unwind(string $fieldName): Stage\Unwind
  563.     {
  564.         // Fixme: move field name translation to stage
  565.         $stage = new Stage\Unwind($this, $this->getDocumentPersister()->prepareFieldName($fieldName));
  566.         $this->addStage($stage);
  568.         return $stage;
  569.     }
  571.     /**
  572.      * Allows adding an arbitrary stage to the pipeline
  573.      *
  574.      * @return Stage The method returns the stage given as an argument
  575.      */
  576.     public function addStage(Stage $stage): Stage
  577.     {
  578.         $this->stages[] = $stage;
  580.         return $stage;
  581.     }
  583.     /**
  584.      * Applies filters and discriminator queries to the pipeline
  585.      *
  586.      * @param array<string, mixed> $query
  587.      *
  588.      * @return array<string, mixed>
  589.      */
  590.     private function applyFilters(array $query): array
  591.     {
  592.         $documentPersister = $this->dm->getUnitOfWork()->getDocumentPersister($this->class->name);
  594.         $query = $documentPersister->addDiscriminatorToPreparedQuery($query);
  595.         $query = $documentPersister->addFilterToPreparedQuery($query);
  597.         return $query;
  598.     }
  600.     private function getDocumentPersister(): DocumentPersister
  601.     {
  602.         return $this->dm->getUnitOfWork()->getDocumentPersister($this->class->name);
  603.     }
  604. }