vendor/doctrine/mongodb-odm/lib/Doctrine/ODM/MongoDB/Aggregation/Stage.php line 41

  1. <?php
  3. declare(strict_types=1);
  5. namespace Doctrine\ODM\MongoDB\Aggregation;
  7. use Doctrine\ODM\MongoDB\Iterator\Iterator;
  8. use GeoJson\Geometry\Point;
  10. use function trigger_deprecation;
  12. /**
  13.  * Fluent interface for building aggregation pipelines.
  14.  *
  15.  * @internal
  16.  */
  17. abstract class Stage
  18. {
  19.     /** @var Builder */
  20.     protected $builder;
  22.     public function __construct(Builder $builder)
  23.     {
  24.         $this->builder = $builder;
  25.     }
  27.     /**
  28.      * Assembles the aggregation stage
  29.      *
  30.      * @return array<string, mixed>
  31.      */
  32.     abstract public function getExpression(): array;
  34.     /**
  35.      * Executes the aggregation pipeline
  36.      *
  37.      * @deprecated This method was deprecated in doctrine/mongodb-odm 2.2. Please use getAggregation() instead.
  38.      *
  39.      * @param array<string, mixed> $options
  40.      */
  41.     public function execute(array $options = []): Iterator
  42.     {
  43.         trigger_deprecation(
  44.             'doctrine/mongodb-odm',
  45.             '2.2',
  46.             'Using "%s" is deprecated, use "%s::getAggregation()" instead.',
  47.             __METHOD__,
  48.             self::class,
  49.         );
  51.         return $this->builder->execute($options);
  52.     }
  54.     /**
  55.      * Returns an aggregation object for the current pipeline
  56.      *
  57.      * @param array<string, mixed> $options
  58.      */
  59.     public function getAggregation(array $options = []): Aggregation
  60.     {
  61.         return $this->builder->getAggregation($options);
  62.     }
  64.     /**
  65.      * Adds new fields to documents. $addFields outputs documents that contain
  66.      * all existing fields from the input documents and newly added fields.
  67.      *
  68.      * The $addFields stage is equivalent to a $project stage that explicitly
  69.      * specifies all existing fields in the input documents and adds the new
  70.      * fields.
  71.      *
  72.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/addFields/
  73.      */
  74.     public function addFields(): Stage\AddFields
  75.     {
  76.         return $this->builder->addFields();
  77.     }
  79.     /**
  80.      * Categorizes incoming documents into groups, called buckets, based on a
  81.      * specified expression and bucket boundaries.
  82.      *
  83.      * Each bucket is represented as a document in the output. The document for
  84.      * each bucket contains an _id field, whose value specifies the inclusive
  85.      * lower bound of the bucket and a count field that contains the number of
  86.      * documents in the bucket. The count field is included by default when the
  87.      * output is not specified.
  88.      *
  89.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucket/
  90.      */
  91.     public function bucket(): Stage\Bucket
  92.     {
  93.         return $this->builder->bucket();
  94.     }
  96.     /**
  97.      * Categorizes incoming documents into a specific number of groups, called
  98.      * buckets, based on a specified expression.
  99.      *
  100.      * Bucket boundaries are automatically determined in an attempt to evenly
  101.      * distribute the documents into the specified number of buckets. Each
  102.      * bucket is represented as a document in the output. The document for each
  103.      * bucket contains an _id field, whose value specifies the inclusive lower
  104.      * bound and the exclusive upper bound for the bucket, and a count field
  105.      * that contains the number of documents in the bucket. The count field is
  106.      * included by default when the output is not specified.
  107.      *
  108.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/
  109.      */
  110.     public function bucketAuto(): Stage\BucketAuto
  111.     {
  112.         return $this->builder->bucketAuto();
  113.     }
  115.     /**
  116.      * Returns statistics regarding a collection or view.
  117.      *
  118.      * $collStats must be the first stage in an aggregation pipeline, or else
  119.      * the pipeline returns an error.
  120.      *
  121.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/
  122.      */
  123.     public function collStats(): Stage\CollStats
  124.     {
  125.         return $this->builder->collStats();
  126.     }
  128.     /**
  129.      * Returns a document that contains a count of the number of documents input
  130.      * to the stage.
  131.      *
  132.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/count/
  133.      */
  134.     public function count(string $fieldName): Stage\Count
  135.     {
  136.         return $this->builder->count($fieldName);
  137.     }
  139.     /**
  140.      * Processes multiple aggregation pipelines within a single stage on the
  141.      * same set of input documents.
  142.      *
  143.      * Each sub-pipeline has its own field in the output document where its
  144.      * results are stored as an array of documents.
  145.      */
  146.     public function facet(): Stage\Facet
  147.     {
  148.         return $this->builder->facet();
  149.     }
  151.     /**
  152.      * Outputs documents in order of nearest to farthest from a specified point.
  153.      * You can only use this as the first stage of a pipeline.
  154.      *
  155.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/
  156.      *
  157.      * @param float|array<string, mixed>|Point $x
  158.      * @param float                            $y
  159.      */
  160.     public function geoNear($x, $y = null): Stage\GeoNear
  161.     {
  162.         return $this->builder->geoNear($x, $y);
  163.     }
  165.     /**
  166.      * Returns the assembled aggregation pipeline
  167.      *
  168.      * @return array<array<string, mixed>>
  169.      */
  170.     public function getPipeline(): array
  171.     {
  172.         return $this->builder->getPipeline();
  173.     }
  175.     /**
  176.      * Performs a recursive search on a collection, with options for restricting
  177.      * the search by recursion depth and query filter.
  178.      *
  179.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/graphLookup/
  180.      *
  181.      * @param string $from Target collection for the $graphLookup operation to
  182.      * search, recursively matching the connectFromField to the connectToField.
  183.      */
  184.     public function graphLookup(string $from): Stage\GraphLookup
  185.     {
  186.         return $this->builder->graphLookup($from);
  187.     }
  189.     /**
  190.      * Groups documents by some specified expression and outputs to the next
  191.      * stage a document for each distinct grouping.
  192.      *
  193.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/group/
  194.      */
  195.     public function group(): Stage\Group
  196.     {
  197.         return $this->builder->group();
  198.     }
  200.     /**
  201.      * Returns statistics regarding the use of each index for the collection.
  202.      *
  203.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/indexStats/
  204.      */
  205.     public function indexStats(): Stage\IndexStats
  206.     {
  207.         return $this->builder->indexStats();
  208.     }
  210.     /**
  211.      * Limits the number of documents passed to the next stage in the pipeline.
  212.      *
  213.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/limit/
  214.      *
  215.      * @return Stage\Limit
  216.      */
  217.     public function limit(int $limit)
  218.     {
  219.         return $this->builder->limit($limit);
  220.     }
  222.     /**
  223.      * Performs a left outer join to an unsharded collection in the same
  224.      * database to filter in documents from the “joined” collection for
  225.      * processing.
  226.      *
  227.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/lookup/
  228.      */
  229.     public function lookup(string $from): Stage\Lookup
  230.     {
  231.         return $this->builder->lookup($from);
  232.     }
  234.     /**
  235.      * Filters the documents to pass only the documents that match the specified
  236.      * condition(s) to the next pipeline stage.
  237.      *
  238.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/match/
  239.      */
  240.     public function match(): Stage\MatchStage
  241.     {
  242.         return $this->builder->match();
  243.     }
  245.     /**
  246.      * Takes the documents returned by the aggregation pipeline and writes them
  247.      * to a specified collection. This must be the last stage in the pipeline.
  248.      *
  249.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/out/
  250.      */
  251.     public function out(string $collection): Stage\Out
  252.     {
  253.         return $this->builder->out($collection);
  254.     }
  256.     /**
  257.      * Passes along the documents with only the specified fields to the next
  258.      * stage in the pipeline. The specified fields can be existing fields from
  259.      * the input documents or newly computed fields.
  260.      *
  261.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/project/
  262.      */
  263.     public function project(): Stage\Project
  264.     {
  265.         return $this->builder->project();
  266.     }
  268.     /**
  269.      * Restricts the contents of the documents based on information stored in
  270.      * the documents themselves.
  271.      *
  272.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/redact/
  273.      */
  274.     public function redact(): Stage\Redact
  275.     {
  276.         return $this->builder->redact();
  277.     }
  279.     /**
  280.      * Promotes a specified document to the top level and replaces all other
  281.      * fields.
  282.      *
  283.      * The operation replaces all existing fields in the input document,
  284.      * including the _id field. You can promote an existing embedded document to
  285.      * the top level, or create a new document for promotion.
  286.      *
  287.      * @param string|mixed[]|null $expression Optional. A replacement expression that
  288.      * resolves to a document.
  289.      */
  290.     public function replaceRoot($expression = null): Stage\ReplaceRoot
  291.     {
  292.         return $this->builder->replaceRoot($expression);
  293.     }
  295.     /**
  296.      * Controls if resulting iterator should be wrapped with CachingIterator.
  297.      */
  298.     public function rewindable(bool $rewindable = true): self
  299.     {
  300.         $this->builder->rewindable($rewindable);
  302.         return $this;
  303.     }
  305.     /**
  306.      * Randomly selects the specified number of documents from its input.
  307.      *
  308.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sample/
  309.      */
  310.     public function sample(int $size): Stage\Sample
  311.     {
  312.         return $this->builder->sample($size);
  313.     }
  315.     /**
  316.      * Skips over the specified number of documents that pass into the stage and
  317.      * passes the remaining documents to the next stage in the pipeline.
  318.      *
  319.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/skip/
  320.      */
  321.     public function skip(int $skip): Stage\Skip
  322.     {
  323.         return $this->builder->skip($skip);
  324.     }
  326.     /**
  327.      * Groups incoming documents based on the value of a specified expression,
  328.      * then computes the count of documents in each distinct group.
  329.      *
  330.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sortByCount/
  331.      */
  332.     public function sortByCount(string $expression): Stage\SortByCount
  333.     {
  334.         return $this->builder->sortByCount($expression);
  335.     }
  337.     /**
  338.      * Sorts all input documents and returns them to the pipeline in sorted order.
  339.      *
  340.      * If sorting by multiple fields, the first argument should be an array of
  341.      * field name (key) and order (value) pairs.
  342.      *
  343.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/sort/
  344.      *
  345.      * @param array<string, int|string>|string $fieldName Field name or array of field/order pairs
  346.      * @param int|string                       $order     Field order (if one field is specified)
  347.      */
  348.     public function sort($fieldName, $order = null): Stage\Sort
  349.     {
  350.         return $this->builder->sort($fieldName, $order);
  351.     }
  353.     /**
  354.      * Deconstructs an array field from the input documents to output a document
  355.      * for each element. Each output document is the input document with the
  356.      * value of the array field replaced by the element.
  357.      *
  358.      * @see https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/
  359.      */
  360.     public function unwind(string $fieldName): Stage\Unwind
  361.     {
  362.         return $this->builder->unwind($fieldName);
  363.     }
  365.     /**
  366.      * Allows adding an arbitrary stage to the pipeline
  367.      *
  368.      * @return Stage The method returns the stage given as an argument
  369.      */
  370.     public function addStage(Stage $stage): Stage
  371.     {
  372.         return $this->builder->addStage($stage);
  373.     }
  374. }