About MondocBuilder

MondocBuilder is a simple and easy-to-use query builder that allows you to build complex queries without having to write the raw MongoDB queries. The query builder is available across the Mondoc library and is used to build queries for the MondocAbstractService.

Note: MondocBuilder does not require Mondoc to run. It can be used as a standalone library.

Basic usage

MondocBuilder is a collection of classes that allow you to build queries. The main class is the QueryBuilder class, which is used to add components to the query, and pass into the MondocAbstractService for execution.

<?php

use District5\MondocBuilder\QueryBuilder;
use District5\MondocBuilder\QueryTypes\ValueEqualTo;
use District5\MondocBuilder\QueryTypes\ValueNotEqualTo;

$queryBuilder = QueryBuilder::get();
// or, call the static method available across all MondocAbstractService classes
// MyService::getQueryBuilder();

$stringEquals = ValueEqualTo::get()->string('name', 'John Doe');
$ageNotEquals = ValueNotEqualTo::get()->integer('age', 25);

$queryBuilder->addQueryPart($stringEquals);
$queryBuilder->addQueryPart($ageNotEquals);

// Add options to your query (entirely optional, and is not required)
$options = $queryBuilder->getOptions();
$options->setSortBySimple('age', 1); // Sort by age ascending
$options->setLimit(10); // Limit to 10 results
$options->setCustom([
    'project' => ['name' => 1, 'age' => 1]
]); // Only return name and age fields
$options->setSkip(5); // Skip the first 5 results


// Get one...
// $result = \District5\Mondoc\Db\Service\MondocAbstractService::getOneByQueryBuilder($queryBuilder);
// Get multi...
// $result = \District5\Mondoc\Db\Service\MondocAbstractService::getMultiByQueryBuilder($queryBuilder);
// Or export the query to use directly with MongoDB
// $collection->find(
//      $queryBuilder->getArrayCopy(),
//      $queryBuilder->getOptions()->getArrayCopy()
// );

print_r($queryBuilder->getArrayCopy());
/*
Results in:
Array
(
    [name] => Array(
        [$eq] => John Doe
    )
    [age] => Array(
        [$ne] => 25
    )
)
*/

print_r($queryBuilder->getOptions()->getArrayCopy());
/*
Results in:
Array
(
    [sort] => Array(
        [age] => 1
    )
    [skip] => 5
    [limit] => 10
    [project] => Array(
        [name] => 1
        [age] => 1
    )
)
 */

Note:
There are many entry points for querying, using the QueryBuilder instance. Please refer to the description Service documentation for more information.

Exposed methods in QueryBuilder

Below is a list of the methods available in the QueryBuilder instance.

• get(): \District5\MondocBuilder\QueryBuilder

  Returns the singleton instance of the QueryBuilder class.

• addQueryPart(AbstractQueryType $part): QueryBuilder

  Adds a query part to the query. The query part must be an instance of AbstractQueryType.

• getArrayCopy(): array

  Returns the query as an array. This is used within the MondocAbstractService, but would also be used to export a query to be used directly with MongoDB.

• getOptions(): QueryOptions

  Returns the query options. This is used to set options such as sorting, limiting, skipping, and custom options.

• setOptions(QueryOptions $options): QueryBuilder

  Sets the query options. This is used to set options such as sorting, limiting, skipping, and custom options.

• addCustomArrayPart(array $custom): QueryBuilder

  Adds a custom array part to the query. This is used to add custom query components to the query.

  Note: If you need to add a custom query part that is not currently supported by MondocBuilder, please consider creating a pull request on the description MondocBuilder GitHub repository .

Special operators

MondocBuilder contains special operators to help build complex queries.

• \District5\MondocBuilder\QueryTypes\AndOperator

  Methods:

  • addQueryPart(AbstractQueryType $part): AndOperator

    Adds a query part to the $and operator.

  • getArrayCopy(): array

    Returns the contained query parts as an array.

• \District5\MondocBuilder\QueryTypes\OrOperator

  Methods:

  • addQueryPart(AbstractQueryType $part): OrOperator

    Adds a query part to the $or operator.

  • getArrayCopy(): array

    Returns the contained query parts as an array.

Equality query types

Equality query types are used to compare values in a query. For example, to check if a field is equal to a value, or if a field is not equal to a value, or if a field is greater than a value, etc.

• \District5\MondocBuilder\QueryTypes\ValueEqualTo

  Represents an $eq operator in a query.

  Methods:

  • string(string $key, string $string): static

    Sets a string value for the query.

  • integer(string $key, int $integer): static

    Sets an integer value for the query.

  • float(string $key, float $float): static

    Sets a float value for the query.

  • boolean(string $key, bool $boolean): static

    Sets a boolean value for the query.

  • null(string $key): static

    Sets a null value for the query.

  • mongoNative(string $key, mixed $object): static

    Sets a MongoDB native object for the query. For example, a \MongoDB\BSON\UTCDateTime object.

  • objectId(string $key, \MongoDB\BSON\ObjectId $objectId): static

    Sets an \MongoDB\BSON\ObjectId for the query.

  • dateTime(string $key, \DateTime $dateTime): static

    Sets a PHP DateTime for the query.

  • utcDateTime(string $key, \MongoDB\BSON\UTCDateTime $date): static

    Sets a MongoDB UTCDateTime for the query.

  • getArrayCopy(): array

    Returns the query part as an array.

• \District5\MondocBuilder\QueryTypes\ValueNotEqualTo

  Represents a $ne operator in a query.

  Methods:

  See ValueEqualTo for available methods.

• \District5\MondocBuilder\QueryTypes\ValueGreaterThan

  Represents a $gt operator in a query.

  Methods:

  See ValueEqualTo for available methods.

• \District5\MondocBuilder\QueryTypes\ValueLessThan

  Represents a $lt operator in a query.

  Methods:

  See ValueEqualTo for available methods.

• \District5\MondocBuilder\QueryTypes\ValueGreaterThanOrEqualTo

  Represents a $gte operator in a query.

  Methods:

  See ValueEqualTo for available methods.

• \District5\MondocBuilder\QueryTypes\ValueLessThanOrEqualTo

  Represents a $lte operator in a query.

  Methods:

  See ValueEqualTo for available methods.

Other query types

Below is a list of other (non equality query types available in MondocBuilder. All query types extend the AbstractQueryType class and contain a get() method to retrieve an instance of themselves, as well as a getArrayCopy() method to return the query part as an array.

• \District5\MondocBuilder\QueryTypes\HasAllValues

  Represents a $all operator in a query.

  Methods:

  • anArray(string $key, array $values): static

    Sets an array of values for the query.

• \District5\MondocBuilder\QueryTypes\KeyExists

  Represents a $exists operator in a query.

  Methods:

  • true(string $key): static

    Sets the key to exist in the query.

  • false(string $key): static

    Sets the key to not exist in the query.

• \District5\MondocBuilder\QueryTypes\SizeOfValue

  Represents a $size operator in a query.

  Methods:

  • equals(string $key, int $int): static

    Sets the size of the value to be equal to the given integer.

• \District5\MondocBuilder\QueryTypes\ValueInValues

  Represents an $in operator in a query.

  Methods:

  • anArray(string $key, array $values): static

    Sets an array of values for the query.

• \District5\MondocBuilder\QueryTypes\ValueNotInValues

  Represents a $nin operator in a query.

  Methods:

  • anArray(string $key, array $values): static

    Sets an array of values for the query.

• \District5\MondocBuilder\QueryTypes\GeospatialPointNear

  Represents a geospatial $near operator in a query.

  Methods:

  • withinXMilesOfCoordinates(string $key, float|int $miles, float $longitude, float $latitude): static

    Sets the geospatial point to be within a given number of miles of the given coordinates.

  • withinXMetresOfCoordinates(string $key, int $metres, float $longitude, float $latitude): static

    Sets the geospatial point to be within a given number of metres of the given coordinates.

• \District5\MondocBuilder\QueryTypes\ GeospatialPointNearSphere

  Represents a geospatial $nearSphere operator in a query.

  Methods:

  • withinXMilesOfCoordinates(string $key, float|int $miles, float $longitude, float $latitude): static

    Sets the geospatial point to be within a given number of miles of the given coordinates, using a spherical calculation.

  • withinXMetresOfCoordinates(string $key, int $metres, float $longitude, float $latitude): static

    Sets the geospatial point to be within a given number of metres of the given coordinates, using a spherical calculation.

Recommended reading:

• description Advanced query Building » learn how to build advanced queries
• description Service » learn how to create a service for your model

Documentation homefast_rewind Advanced query buildingfast_forward