doctrine / mongodb-odm

lib/Doctrine/ODM/MongoDB/Query/Query.php

<?php

declare(strict_types=1);

namespace Doctrine\ODM\MongoDB\Query;

use Doctrine\ODM\MongoDB\DocumentManager;
use Doctrine\ODM\MongoDB\Iterator\CachingIterator;
use Doctrine\ODM\MongoDB\Iterator\HydratingIterator;
use Doctrine\ODM\MongoDB\Iterator\Iterator;
use Doctrine\ODM\MongoDB\Iterator\PrimingIterator;
use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
use Doctrine\ODM\MongoDB\MongoDBException;
use MongoDB\Collection;
use MongoDB\Driver\Cursor;
use MongoDB\Operation\FindOneAndUpdate;
use function array_combine;
use function array_filter;
use function array_flip;
use function array_intersect_key;
use function array_keys;
use function array_map;
use function array_merge;
use function array_values;
use function is_array;
use function is_callable;

/**
 * ODM Query wraps the raw Doctrine MongoDB queries to add additional functionality
 * and to hydrate the raw arrays of data to Doctrine document objects.
 *
 */
class Query implements \IteratorAggregate
{
    public const TYPE_FIND            = 1;
    public const TYPE_FIND_AND_UPDATE = 2;
    public const TYPE_FIND_AND_REMOVE = 3;
    public const TYPE_INSERT          = 4;
    public const TYPE_UPDATE          = 5;
    public const TYPE_REMOVE          = 6;
    public const TYPE_GROUP           = 7;
    public const TYPE_MAP_REDUCE      = 8;
    public const TYPE_DISTINCT        = 9;
    public const TYPE_COUNT           = 11;

    /**
     * @deprecated 1.1 Will be removed for 2.0
     */
    public const TYPE_GEO_LOCATION = 10;

    public const HINT_REFRESH = 1;
    // 2 was used for HINT_SLAVE_OKAY, which was removed in 2.0
    public const HINT_READ_PREFERENCE = 3;
    public const HINT_READ_ONLY = 5;

    /**
     * The DocumentManager instance.
     *
     * @var DocumentManager
     */
    private $dm;

    /**
     * The ClassMetadata instance.
     *
     * @var ClassMetadata
     */
    private $class;

    /**
     * Whether to hydrate results as document class instances.
     *
     * @var bool
     */
    private $hydrate = true;

    /**
     * Array of primer Closure instances.
     *
     * @var array
     */
    private $primers = [];

    /**
     * Hints for UnitOfWork behavior.
     *
     * @var array
     */
    private $unitOfWorkHints = [];

    /**
     * The Collection instance.
     *
     * @var Collection
     */
    protected $collection;

    /**
     * Query structure generated by the Builder class.
     *
     * @var array
     */
    private $query;

    /** @var Iterator */
    private $iterator;

    /**
     * Query options
     *
     * @var array
     */
    private $options;

    /**
     *
     *
     * Please note that $requireIndexes was deprecated in 1.2 and will be removed in 2.0
     */
    public function __construct(DocumentManager $dm, ClassMetadata $class, Collection $collection, array $query = [], array $options = [], bool $hydrate = true, bool $refresh = false, array $primers = [], bool $readOnly = false)
    {
        $primers = array_filter($primers);

        if (! empty($primers)) {
            $query['eagerCursor'] = true;
        }

        if (! empty($query['eagerCursor'])) {
            $query['useIdentifierKeys'] = false;
        }

        switch ($query['type']) {
            case self::TYPE_FIND:
            case self::TYPE_FIND_AND_UPDATE:
            case self::TYPE_FIND_AND_REMOVE:
            case self::TYPE_INSERT:
            case self::TYPE_UPDATE:
            case self::TYPE_REMOVE:
            case self::TYPE_GROUP:
            case self::TYPE_MAP_REDUCE:
            case self::TYPE_DISTINCT:
            case self::TYPE_COUNT:
                break;

            default:
                throw new \InvalidArgumentException('Invalid query type: ' . $query['type']);
        }

        $this->collection = $collection;
        $this->query      = $query;
        $this->options    = $options;
        $this->dm = $dm;
        $this->class = $class;
        $this->hydrate = $hydrate;
        $this->primers = $primers;

        $this->setReadOnly($readOnly);
        $this->setRefresh($refresh);

        if (! isset($query['readPreference'])) {
            return;
        }

        $this->unitOfWorkHints[self::HINT_READ_PREFERENCE] = $query['readPreference'];
    }

    public function __clone()
    {
        $this->iterator = null;
    }

    /**
     * Return an array of information about the query structure for debugging.
     *
     * The $name parameter may be used to return a specific key from the
     * internal $query array property. If omitted, the entire array will be
     * returned.
     */
    public function debug(?string $name = null)
    {
        return $name !== null ? $this->query[$name] : $this->query;
    }

    /**
     * Execute the query and returns the results.
     *
     * @throws MongoDBException
     * @return Iterator|int|string|array
     */
    public function execute()
    {
        $results = $this->runQuery();

        if (! $this->hydrate) {
            return $results;
        }

        if ($results instanceof Cursor) {
            $results = $this->makeIterator($results);
        }

        $uow = $this->dm->getUnitOfWork();

        /* If a single document is returned from a findAndModify command and it
         * includes the identifier field, attempt hydration.
         */
        if (($this->query['type'] === self::TYPE_FIND_AND_UPDATE ||
                $this->query['type'] === self::TYPE_FIND_AND_REMOVE) &&
            is_array($results) && isset($results['_id'])) {
            $results = $uow->getOrCreateDocument($this->class->name, $results, $this->unitOfWorkHints);

            if (! empty($this->primers)) {
                $referencePrimer = new ReferencePrimer($this->dm, $uow);

                foreach ($this->primers as $fieldName => $primer) {
                    $primer = is_callable($primer) ? $primer : null;
                    $referencePrimer->primeReferences($this->class, [$results], $fieldName, $this->unitOfWorkHints, $primer);
                }
            }
        }

        return $results;
    }

    /**
     * Gets the ClassMetadata instance.
     */
    public function getClass(): ClassMetadata
    {
        return $this->class;
    }

    public function getDocumentManager(): DocumentManager
    {
        return $this->dm;
    }

    /**
     * Execute the query and return its result, which must be an Iterator.
     *
     * If the query type is not expected to return an Iterator,
     * BadMethodCallException will be thrown before executing the query.
     * Otherwise, the query will be executed and UnexpectedValueException will
     * be thrown if {@link Query::execute()} does not return an Iterator.
     *
     * @see http://php.net/manual/en/iteratoraggregate.getiterator.php
     * @throws \BadMethodCallException If the query type would not return an Iterator.
     * @throws \UnexpectedValueException If the query did not return an Iterator.
     * @throws MongoDBException
     */
    public function getIterator(): Iterator
    {
        switch ($this->query['type']) {
            case self::TYPE_FIND:
            case self::TYPE_GROUP:
            case self::TYPE_MAP_REDUCE:
            case self::TYPE_DISTINCT:
                break;

            default:
                throw new \BadMethodCallException('Iterator would not be returned for query type: ' . $this->query['type']);
        }

        if ($this->iterator === null) {
            $this->iterator = $this->execute();

It seems like $this->execute() can also be of type array or integer. However, the property $iterator is declared as type object<Doctrine\ODM\MongoDB\Iterator\Iterator>. Maybe add an additional type check?

        }

        return $this->iterator;
    }

    /**
     * Return the query structure.
     */
    public function getQuery(): array
    {
        return $this->query;
    }

    /**
     * Execute the query and return the first result.
     *
     * @return array|object|null
     */
    public function getSingleResult()
    {
        $clonedQuery = clone $this;
        $clonedQuery->query['limit'] = 1;
        return $clonedQuery->getIterator()->current() ?: null;

It seems like you code against a concrete implementation and not the interface Traversable as the method current() does only exist in the following implementations of said interface: APCUIterator, AppendIterator, ArrayIterator, CachingIterator, CallbackFilterIterator, DirectoryIterator, Doctrine\Common\Collections\AbstractLazyCollection, Doctrine\Common\Collections\ArrayCollection, Doctrine\ODM\MongoDB\Iterator\CachingIterator, Doctrine\ODM\MongoDB\Iterator\HydratingIterator, Doctrine\ODM\MongoDB\Iterator\PrimingIterator, Doctrine\ODM\MongoDB\PersistentCollection, Doctrine\ODM\MongoDB\Tools\Console\MetadataFilter, EmptyIterator, FilesystemIterator, FilterIterator, Generator, GlobIterator, HttpMessage, HttpRequestPool, Imagick, ImagickPixelIterator, InfiniteIterator, Issue523, IteratorIterator, LimitIterator, MongoCommandCursor, MongoCursor, MongoDB\ChangeStream, MongoDB\Model\BSONIterator, MongoDB\Model\CachingIterator, MongoDB\Model\CollectionInfoCommandIterator, MongoDB\Model\DatabaseInfoLegacyIterator, MongoDB\Model\IndexInfoIteratorIterator, MongoDB\Model\TypeMapArrayIterator, MongoGridFSCursor, MultipleIterator, Nette\Iterators\CachingIterator, Nette\Iterators\Mapper, NoRewindIterator, PHPUnit\Framework\TestSuiteIterator, PHPUnit\Runner\Filter\ExcludeGroupFilterIterator, PHPUnit\Runner\Filter\GroupFilterIterator, PHPUnit\Runner\Filter\IncludeGroupFilterIterator, PHPUnit\Runner\Filter\NameFilterIterator, PHP_CodeSniffer\Files\FileList, PHP_CodeSniffer\Filters\ExactMatch, PHP_CodeSniffer\Filters\Filter, PHP_CodeSniffer\Filters\GitModified, PHP_Token_Stream, ParentIterator, Phar, PharData, PharIo\Manifest\AuthorCollectionIterator, PharIo\Manifest\AuthorElementCollection, PharIo\Manifest\BundledComponentCollectionIterator, PharIo\Manifest\ComponentElementCollection, PharIo\Manifest\ElementCollection, PharIo\Manifest\ExtElementCollection, PharIo\Manifest\RequirementCollectionIterator, RecursiveArrayIterator, RecursiveCachingIterator, RecursiveCallbackFilterIterator, RecursiveDirectoryIterator, RecursiveFilterIterator, RecursiveIteratorIterator, RecursiveRegexIterator, RecursiveTreeIterator, RegexIterator, SQLiteResult, SebastianBergmann\CodeCoverage\Node\Iterator, SebastianBergmann\FileIterator\Iterator, SimpleXMLIterator, SplDoublyLinkedList, SplFileObject, SplFixedArray, SplHeap, SplMaxHeap, SplMinHeap, SplObjectStorage, SplPriorityQueue, SplQueue, SplStack, SplTempFileObject, Symfony\Component\Finder\Iterator\CustomFilterIterator, Symfony\Component\Finder\Iterator\DateRangeFilterIterator, Symfony\Component\Finder\Iterator\DepthRangeFilterIterator, Symfony\Component\Finder\Iterator\ExcludeDirectoryFilterIterator, Symfony\Component\Finder\Iterator\FileTypeFilterIterator, Symfony\Component\Finder\Iterator\FilecontentFilterIterator, Symfony\Component\Finder\Iterator\FilenameFilterIterator, Symfony\Component\Finder\Iterator\MultiplePcreFilterIterator, Symfony\Component\Finder\Iterator\PathFilterIterator, Symfony\Component\Finder\Iterator\RecursiveDirectoryIterator, Symfony\Component\Finder\Iterator\SizeRangeFilterIterator, Symfony\Component\Finder\Tests\Iterator\InnerNameIterator, Symfony\Component\Finder\Tests\Iterator\InnerSizeIterator, Symfony\Component\Finder\Tests\Iterator\InnerTypeIterator, Symfony\Component\Finder\Tests\Iterator\Iterator, Symfony\Component\Finder\Tests\Iterator\MockFileListIterator, Symfony\Component\Finder\Tests\Iterator\TestMultiplePcreFilterIterator, TestIterator, TestIterator2, TheSeer\Tokenizer\TokenCollection.

    }

    /**
     * Return the query type.
     */
    public function getType(): int
    {
        return $this->query['type'];
    }

    /**
     * Sets whether or not to hydrate the documents to objects.
     */
    public function setHydrate(bool $hydrate): void
    {
        $this->hydrate = $hydrate;
    }

    /**
     * Set whether documents should be registered in UnitOfWork. If document would
     * already be managed it will be left intact and new instance returned.
     *
     * This option has no effect if hydration is disabled.
     */
    public function setReadOnly(bool $readOnly): void
    {
        $this->unitOfWorkHints[self::HINT_READ_ONLY] = $readOnly;
    }

    /**
     * Set whether to refresh hydrated documents that are already in the
     * identity map.
     *
     * This option has no effect if hydration is disabled.
     */
    public function setRefresh(bool $refresh): void
    {
        $this->unitOfWorkHints[self::HINT_REFRESH] = (bool) $refresh;
    }

    /**
     * Execute the query and return its results as an array.
     *
     * @see IteratorAggregate::toArray()
     */
    public function toArray(): array
    {
        return $this->getIterator()->toArray();

It seems like you code against a concrete implementation and not the interface Traversable as the method toArray() does only exist in the following implementations of said interface: Doctrine\Common\Collections\AbstractLazyCollection, Doctrine\Common\Collections\ArrayCollection, Doctrine\ODM\MongoDB\Iterator\CachingIterator, Doctrine\ODM\MongoDB\Iterator\PrimingIterator, Doctrine\ODM\MongoDB\PersistentCollection, Doctrine\ODM\MongoDB\Query\Query, SplFixedArray.

    }

    /**
     * Returns an array containing the specified keys and their values from the
     * query array, provided they exist and are not null.
     */
    private function getQueryOptions(string ...$keys): array
    {
        return array_filter(
            array_intersect_key($this->query, array_flip($keys)),
            function ($value) {
                return $value !== null;
            }
        );
    }

    private function makeIterator(Cursor $cursor): Iterator
    {
        if ($this->hydrate && $this->class) {
            $cursor = new HydratingIterator($cursor, $this->dm->getUnitOfWork(), $this->class, $this->unitOfWorkHints);
        }

        $cursor = new CachingIterator($cursor);

        if (! empty($this->primers)) {
            $referencePrimer = new ReferencePrimer($this->dm, $this->dm->getUnitOfWork());
            $cursor = new PrimingIterator($cursor, $this->class, $referencePrimer, $this->primers, $this->unitOfWorkHints);
        }

        return $cursor;
    }

    /**
     * Returns an array with its keys renamed based on the translation map.
     *
     * @return array $rename Translation map (from => to) for renaming keys
     */
    private function renameQueryOptions(array $options, array $rename): array
    {
        if (empty($options)) {
            return $options;
        }

        return array_combine(
            array_map(
                function ($key) use ($rename) {
                    return $rename[$key] ?? $key;
                },
                array_keys($options)
            ),
            array_values($options)
        );
    }

    /**
     * Execute the query and return its result.
     *
     * The return value will vary based on the query type. Commands with results
     * (e.g. aggregate, inline mapReduce) may return an ArrayIterator. Other
     * commands and operations may return a status array or a boolean, depending
     * on the driver's write concern. Queries and some mapReduce commands will
     * return an Iterator.
     *
     * @return Iterator|string|int|array
     */
    public function runQuery()
    {
        $options = $this->options;

        switch ($this->query['type']) {
            case self::TYPE_FIND:
                $queryOptions = $this->getQueryOptions('select', 'sort', 'skip', 'limit', 'readPreference');
                $queryOptions = $this->renameQueryOptions($queryOptions, ['select' => 'projection']);

                $cursor = $this->collection->find(
                    $this->query['query'],
                    $queryOptions
                );

                return $this->makeIterator($cursor);

            case self::TYPE_FIND_AND_UPDATE:
                $queryOptions = $this->getQueryOptions('select', 'sort', 'upsert');
                $queryOptions = $this->renameQueryOptions($queryOptions, ['select' => 'projection']);
                $queryOptions['returnDocument'] = ($this->query['new'] ?? false) ? FindOneAndUpdate::RETURN_DOCUMENT_AFTER : FindOneAndUpdate::RETURN_DOCUMENT_BEFORE;

                return $this->collection->findOneAndUpdate(
                    $this->query['query'],
                    $this->query['newObj'],
                    array_merge($options, $queryOptions)
                );

            case self::TYPE_FIND_AND_REMOVE:
                $queryOptions = $this->getQueryOptions('select', 'sort');
                $queryOptions = $this->renameQueryOptions($queryOptions, ['select' => 'projection']);

                return $this->collection->findOneAndDelete(
                    $this->query['query'],
                    array_merge($options, $queryOptions)
                );

            case self::TYPE_INSERT:
                return $this->collection->insertOne($this->query['newObj'], $options);

            case self::TYPE_UPDATE:
                if ($this->query['multiple'] ?? false) {
                    return $this->collection->updateMany(
                        $this->query['query'],
                        $this->query['newObj'],
                        array_merge($options, $this->getQueryOptions('upsert'))
                    );
                }

                return $this->collection->updateOne(
                    $this->query['query'],
                    $this->query['newObj'],
                    array_merge($options, $this->getQueryOptions('upsert'))
                );

            case self::TYPE_REMOVE:
                return $this->collection->deleteMany($this->query['query'], $options);

            case self::TYPE_DISTINCT:
                $collection = $this->collection;
                $query = $this->query;

                return $collection->distinct(
                    $query['distinct'],
                    $query['query'],
                    array_merge($options, $this->getQueryOptions('readPreference'))
                );

            case self::TYPE_COUNT:
                $collection = $this->collection;
                $query = $this->query;

                return $collection->count(

The method MongoDB\Collection::count() has been deprecated with message: 1.4

                    $query['query'],
                    array_merge($options, $this->getQueryOptions('hint', 'limit', 'skip', 'readPreference'))
                );
        }
    }
}