Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
  • Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
<?php
/*
< * Copyright 2015-2017 MongoDB, Inc.
> * Copyright 2015-present MongoDB, Inc.
* * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at *
< * http://www.apache.org/licenses/LICENSE-2.0
> * https://www.apache.org/licenses/LICENSE-2.0
* * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ namespace MongoDB;
> use Iterator;
use MongoDB\Driver\Cursor; use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException; use MongoDB\Driver\Manager; use MongoDB\Driver\ReadConcern; use MongoDB\Driver\ReadPreference; use MongoDB\Driver\WriteConcern; use MongoDB\Exception\InvalidArgumentException; use MongoDB\Exception\UnexpectedValueException; use MongoDB\Exception\UnsupportedException; use MongoDB\GridFS\Bucket; use MongoDB\Model\BSONArray; use MongoDB\Model\BSONDocument; use MongoDB\Model\CollectionInfoIterator; use MongoDB\Operation\Aggregate; use MongoDB\Operation\CreateCollection;
> use MongoDB\Operation\CreateIndexes;
use MongoDB\Operation\DatabaseCommand; use MongoDB\Operation\DropCollection; use MongoDB\Operation\DropDatabase;
> use MongoDB\Operation\ListCollectionNames;
use MongoDB\Operation\ListCollections; use MongoDB\Operation\ModifyCollection;
> use MongoDB\Operation\RenameCollection;
use MongoDB\Operation\Watch; use Traversable;
>
use function is_array; use function strlen; class Database { /** @var array */ private static $defaultTypeMap = [ 'array' => BSONArray::class, 'document' => BSONDocument::class, 'root' => BSONDocument::class, ]; /** @var integer */
< private static $wireVersionForReadConcern = 4; < < /** @var integer */ < private static $wireVersionForWritableCommandWriteConcern = 5; < < /** @var integer */
private static $wireVersionForReadConcernWithWriteStage = 8; /** @var string */ private $databaseName; /** @var Manager */ private $manager; /** @var ReadConcern */ private $readConcern; /** @var ReadPreference */ private $readPreference; /** @var array */ private $typeMap; /** @var WriteConcern */ private $writeConcern; /** * Constructs new Database instance. * * This class provides methods for database-specific operations and serves * as a gateway for accessing collections. * * Supported options: * * * readConcern (MongoDB\Driver\ReadConcern): The default read concern to * use for database operations and selected collections. Defaults to the * Manager's read concern. * * * readPreference (MongoDB\Driver\ReadPreference): The default read * preference to use for database operations and selected collections. * Defaults to the Manager's read preference. * * * typeMap (array): Default type map for cursors and BSON documents. * * * writeConcern (MongoDB\Driver\WriteConcern): The default write concern * to use for database operations and selected collections. Defaults to * the Manager's write concern. * * @param Manager $manager Manager instance from the driver * @param string $databaseName Database name * @param array $options Database options * @throws InvalidArgumentException for parameter/option parsing errors */
< public function __construct(Manager $manager, $databaseName, array $options = [])
> public function __construct(Manager $manager, string $databaseName, array $options = [])
{ if (strlen($databaseName) < 1) { throw new InvalidArgumentException('$databaseName is invalid: ' . $databaseName); } if (isset($options['readConcern']) && ! $options['readConcern'] instanceof ReadConcern) { throw InvalidArgumentException::invalidType('"readConcern" option', $options['readConcern'], ReadConcern::class); } if (isset($options['readPreference']) && ! $options['readPreference'] instanceof ReadPreference) { throw InvalidArgumentException::invalidType('"readPreference" option', $options['readPreference'], ReadPreference::class); } if (isset($options['typeMap']) && ! is_array($options['typeMap'])) { throw InvalidArgumentException::invalidType('"typeMap" option', $options['typeMap'], 'array'); } if (isset($options['writeConcern']) && ! $options['writeConcern'] instanceof WriteConcern) { throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], WriteConcern::class); } $this->manager = $manager;
< $this->databaseName = (string) $databaseName; < $this->readConcern = isset($options['readConcern']) ? $options['readConcern'] : $this->manager->getReadConcern(); < $this->readPreference = isset($options['readPreference']) ? $options['readPreference'] : $this->manager->getReadPreference(); < $this->typeMap = isset($options['typeMap']) ? $options['typeMap'] : self::$defaultTypeMap; < $this->writeConcern = isset($options['writeConcern']) ? $options['writeConcern'] : $this->manager->getWriteConcern();
> $this->databaseName = $databaseName; > $this->readConcern = $options['readConcern'] ?? $this->manager->getReadConcern(); > $this->readPreference = $options['readPreference'] ?? $this->manager->getReadPreference(); > $this->typeMap = $options['typeMap'] ?? self::$defaultTypeMap; > $this->writeConcern = $options['writeConcern'] ?? $this->manager->getWriteConcern();
} /** * Return internal properties for debugging purposes. *
< * @see http://php.net/manual/en/language.oop5.magic.php#language.oop5.magic.debuginfo
> * @see https://php.net/manual/en/language.oop5.magic.php#language.oop5.magic.debuginfo
* @return array */ public function __debugInfo() { return [ 'databaseName' => $this->databaseName, 'manager' => $this->manager, 'readConcern' => $this->readConcern, 'readPreference' => $this->readPreference, 'typeMap' => $this->typeMap, 'writeConcern' => $this->writeConcern, ]; } /** * Select a collection within this database. * * Note: collections whose names contain special characters (e.g. ".") may * be selected with complex syntax (e.g. $database->{"system.profile"}) or * {@link selectCollection()}. *
< * @see http://php.net/oop5.overloading#object.get < * @see http://php.net/types.string#language.types.string.parsing.complex
> * @see https://php.net/oop5.overloading#object.get > * @see https://php.net/types.string#language.types.string.parsing.complex
* @param string $collectionName Name of the collection to select * @return Collection */
< public function __get($collectionName)
> public function __get(string $collectionName)
{ return $this->selectCollection($collectionName); } /** * Return the database name. * * @return string */ public function __toString() { return $this->databaseName; } /** * Runs an aggregation framework pipeline on the database for pipeline * stages that do not require an underlying collection, such as $currentOp * and $listLocalSessions. Requires MongoDB >= 3.6 * * @see Aggregate::__construct() for supported options * @param array $pipeline List of pipeline operations * @param array $options Command options * @return Traversable * @throws UnexpectedValueException if the command response was malformed * @throws UnsupportedException if options are not supported by the selected server * @throws InvalidArgumentException for parameter/option parsing errors * @throws DriverRuntimeException for other driver errors (e.g. connection errors) */ public function aggregate(array $pipeline, array $options = []) { $hasWriteStage = is_last_pipeline_operator_write($pipeline); if (! isset($options['readPreference']) && ! is_in_transaction($options)) { $options['readPreference'] = $this->readPreference; }
< if ($hasWriteStage) { < $options['readPreference'] = new ReadPreference(ReadPreference::RP_PRIMARY); < } < < $server = select_server($this->manager, $options);
> $server = $hasWriteStage > ? select_server_for_aggregate_write_stage($this->manager, $options) > : select_server($this->manager, $options);
/* MongoDB 4.2 and later supports a read concern when an $out stage is * being used, but earlier versions do not. * * A read concern is also not compatible with transactions. */
< if (! isset($options['readConcern']) && < server_supports_feature($server, self::$wireVersionForReadConcern) &&
> if ( > ! isset($options['readConcern']) &&
! is_in_transaction($options) && ( ! $hasWriteStage || server_supports_feature($server, self::$wireVersionForReadConcernWithWriteStage)) ) { $options['readConcern'] = $this->readConcern; } if (! isset($options['typeMap'])) { $options['typeMap'] = $this->typeMap; }
< if ($hasWriteStage && < ! isset($options['writeConcern']) && < server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && < ! is_in_transaction($options)) {
> if ($hasWriteStage && ! isset($options['writeConcern']) && ! is_in_transaction($options)) {
$options['writeConcern'] = $this->writeConcern; } $operation = new Aggregate($this->databaseName, null, $pipeline, $options); return $operation->execute($server); } /** * Execute a command on this database. * * @see DatabaseCommand::__construct() for supported options * @param array|object $command Command document * @param array $options Options for command execution * @return Cursor * @throws InvalidArgumentException for parameter/option parsing errors * @throws DriverRuntimeException for other driver errors (e.g. connection errors) */ public function command($command, array $options = []) {
< if (! isset($options['readPreference']) && ! is_in_transaction($options)) { < $options['readPreference'] = $this->readPreference; < } <
if (! isset($options['typeMap'])) { $options['typeMap'] = $this->typeMap; } $operation = new DatabaseCommand($this->databaseName, $command, $options); $server = select_server($this->manager, $options); return $operation->execute($server); } /** * Create a new collection explicitly. * * @see CreateCollection::__construct() for supported options
< * @param string $collectionName < * @param array $options
* @return array|object Command result document * @throws UnsupportedException if options are not supported by the selected server * @throws InvalidArgumentException for parameter/option parsing errors * @throws DriverRuntimeException for other driver errors (e.g. connection errors) */
< public function createCollection($collectionName, array $options = [])
> public function createCollection(string $collectionName, array $options = [])
{ if (! isset($options['typeMap'])) { $options['typeMap'] = $this->typeMap; } $server = select_server($this->manager, $options);
< if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
> if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
$options['writeConcern'] = $this->writeConcern; }
> $encryptedFields = $options['encryptedFields'] $operation = new CreateCollection($this->databaseName, $collectionName, $options); > ?? get_encrypted_fields_from_driver($this->databaseName, $collectionName, $this->manager) > ?? null; return $operation->execute($server); > } > if ($encryptedFields !== null) { > // encryptedFields is passed to the create command /** > $options['encryptedFields'] = $encryptedFields; * Drop this database. > * > $encryptedFields = (array) $encryptedFields; * @see DropDatabase::__construct() for supported options > $enxcolOptions = ['clusteredIndex' => ['key' => ['_id' => 1], 'unique' => true]]; * @param array $options Additional options > (new CreateCollection($this->databaseName, $encryptedFields['escCollection'] ?? 'enxcol_.' . $collectionName . '.esc', $enxcolOptions))->execute($server); * @return array|object Command result document > (new CreateCollection($this->databaseName, $encryptedFields['eccCollection'] ?? 'enxcol_.' . $collectionName . '.ecc', $enxcolOptions))->execute($server); * @throws UnsupportedException if options are unsupported on the selected server > (new CreateCollection($this->databaseName, $encryptedFields['ecocCollection'] ?? 'enxcol_.' . $collectionName . '.ecoc', $enxcolOptions))->execute($server); * @throws InvalidArgumentException for parameter/option parsing errors > } * @throws DriverRuntimeException for other driver errors (e.g. connection errors) >
< return $operation->execute($server);
> $result = $operation->execute($server); > > if ($encryptedFields !== null) { > (new CreateIndexes($this->databaseName, $collectionName, [['key' => ['__safeContent__' => 1]]]))->execute($server); > } > > return $result;
public function drop(array $options = []) { if (! isset($options['typeMap'])) { $options['typeMap'] = $this->typeMap; } $server = select_server($this->manager, $options);
< if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
> if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
$options['writeConcern'] = $this->writeConcern; } $operation = new DropDatabase($this->databaseName, $options); return $operation->execute($server); } /** * Drop a collection within this database. * * @see DropCollection::__construct() for supported options * @param string $collectionName Collection name * @param array $options Additional options * @return array|object Command result document * @throws UnsupportedException if options are unsupported on the selected server * @throws InvalidArgumentException for parameter/option parsing errors * @throws DriverRuntimeException for other driver errors (e.g. connection errors) */
< public function dropCollection($collectionName, array $options = [])
> public function dropCollection(string $collectionName, array $options = [])
{ if (! isset($options['typeMap'])) { $options['typeMap'] = $this->typeMap; } $server = select_server($this->manager, $options);
< if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
> if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
$options['writeConcern'] = $this->writeConcern; }
> $encryptedFields = $options['encryptedFields'] $operation = new DropCollection($this->databaseName, $collectionName, $options); > ?? get_encrypted_fields_from_driver($this->databaseName, $collectionName, $this->manager) > ?? get_encrypted_fields_from_server($this->databaseName, $collectionName, $this->manager, $server) return $operation->execute($server); > ?? null; } > > if ($encryptedFields !== null) { /** > // encryptedFields is not passed to the drop command * Returns the database name. > unset($options['encryptedFields']); * > * @return string > $encryptedFields = (array) $encryptedFields; */ > (new DropCollection($this->databaseName, $encryptedFields['escCollection'] ?? 'enxcol_.' . $collectionName . '.esc'))->execute($server); public function getDatabaseName() > (new DropCollection($this->databaseName, $encryptedFields['eccCollection'] ?? 'enxcol_.' . $collectionName . '.ecc'))->execute($server); { > (new DropCollection($this->databaseName, $encryptedFields['ecocCollection'] ?? 'enxcol_.' . $collectionName . '.ecoc'))->execute($server); return $this->databaseName; > } } >
/** * Return the Manager. * * @return Manager */ public function getManager() { return $this->manager; } /** * Return the read concern for this database. *
< * @see http://php.net/manual/en/mongodb-driver-readconcern.isdefault.php
> * @see https://php.net/manual/en/mongodb-driver-readconcern.isdefault.php
* @return ReadConcern */ public function getReadConcern() { return $this->readConcern; } /** * Return the read preference for this database. * * @return ReadPreference */ public function getReadPreference() { return $this->readPreference; } /** * Return the type map for this database. * * @return array */ public function getTypeMap() { return $this->typeMap; } /** * Return the write concern for this database. *
< * @see http://php.net/manual/en/mongodb-driver-writeconcern.isdefault.php
> * @see https://php.net/manual/en/mongodb-driver-writeconcern.isdefault.php
* @return WriteConcern */ public function getWriteConcern() { return $this->writeConcern; } /**
> * Returns the names of all collections in this database * Returns information for all collections in this database. > * * > * @see ListCollectionNames::__construct() for supported options * @see ListCollections::__construct() for supported options > * @throws InvalidArgumentException for parameter/option parsing errors * @param array $options > * @throws DriverRuntimeException for other driver errors (e.g. connection errors) * @return CollectionInfoIterator > */ * @throws InvalidArgumentException for parameter/option parsing errors > public function listCollectionNames(array $options = []): Iterator * @throws DriverRuntimeException for other driver errors (e.g. connection errors) > { */ > $operation = new ListCollectionNames($this->databaseName, $options); public function listCollections(array $options = []) > $server = select_server($this->manager, $options); { > $operation = new ListCollections($this->databaseName, $options); > return $operation->execute($server); $server = select_server($this->manager, $options); > } > return $operation->execute($server); > /**
< * @param array $options
/** * Modifies a collection or view. * * @see ModifyCollection::__construct() for supported options * @param string $collectionName Collection or view to modify * @param array $collectionOptions Collection or view options to assign * @param array $options Command options * @return array|object * @throws InvalidArgumentException for parameter/option parsing errors * @throws DriverRuntimeException for other driver errors (e.g. connection errors) */
< public function modifyCollection($collectionName, array $collectionOptions, array $options = [])
> public function modifyCollection(string $collectionName, array $collectionOptions, array $options = [])
{ if (! isset($options['typeMap'])) { $options['typeMap'] = $this->typeMap; } $server = select_server($this->manager, $options);
< if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
> if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
$options['writeConcern'] = $this->writeConcern; } $operation = new ModifyCollection($this->databaseName, $collectionName, $collectionOptions, $options); return $operation->execute($server); } /**
> * Rename a collection within this database. * Select a collection within this database. > * * > * @see RenameCollection::__construct() for supported options * @see Collection::__construct() for supported options > * @param string $fromCollectionName Collection name * @param string $collectionName Name of the collection to select > * @param string $toCollectionName New name of the collection * @param array $options Collection constructor options > * @param string|null $toDatabaseName New database name of the collection. Defaults to the original database. * @return Collection > * @param array $options Additional options * @throws InvalidArgumentException for parameter/option parsing errors > * @return array|object Command result document */ > * @throws UnsupportedException if options are unsupported on the selected server public function selectCollection($collectionName, array $options = []) > * @throws InvalidArgumentException for parameter/option parsing errors { > * @throws DriverRuntimeException for other driver errors (e.g. connection errors) $options += [ > */ 'readConcern' => $this->readConcern, > public function renameCollection(string $fromCollectionName, string $toCollectionName, ?string $toDatabaseName = null, array $options = []) 'readPreference' => $this->readPreference, > { 'typeMap' => $this->typeMap, > if (! isset($toDatabaseName)) { 'writeConcern' => $this->writeConcern, > $toDatabaseName = $this->databaseName; ]; > } > return new Collection($this->manager, $this->databaseName, $collectionName, $options); > if (! isset($options['typeMap'])) { } > $options['typeMap'] = $this->typeMap; > } /** > * Select a GridFS bucket within this database. > $server = select_server($this->manager, $options); * > * @see Bucket::__construct() for supported options > if (! isset($options['writeConcern']) && ! is_in_transaction($options)) { * @param array $options Bucket constructor options > $options['writeConcern'] = $this->writeConcern; * @return Bucket > } * @throws InvalidArgumentException for parameter/option parsing errors > */ > $operation = new RenameCollection($this->databaseName, $fromCollectionName, $toDatabaseName, $toCollectionName, $options); public function selectGridFSBucket(array $options = []) > { > return $operation->execute($server); $options += [ > } 'readConcern' => $this->readConcern, > 'readPreference' => $this->readPreference, > /**
< public function selectCollection($collectionName, array $options = [])
> public function selectCollection(string $collectionName, array $options = [])
'writeConcern' => $this->writeConcern, ]; return new Bucket($this->manager, $this->databaseName, $options); } /** * Create a change stream for watching changes to the database. * * @see Watch::__construct() for supported options * @param array $pipeline List of pipeline operations * @param array $options Command options * @return ChangeStream * @throws InvalidArgumentException for parameter/option parsing errors */ public function watch(array $pipeline = [], array $options = []) { if (! isset($options['readPreference']) && ! is_in_transaction($options)) { $options['readPreference'] = $this->readPreference; } $server = select_server($this->manager, $options);
< if (! isset($options['readConcern']) && server_supports_feature($server, self::$wireVersionForReadConcern) && ! is_in_transaction($options)) {
> if (! isset($options['readConcern']) && ! is_in_transaction($options)) {
$options['readConcern'] = $this->readConcern; } if (! isset($options['typeMap'])) { $options['typeMap'] = $this->typeMap; } $operation = new Watch($this->manager, $this->databaseName, null, $pipeline, $options); return $operation->execute($server); } /** * Get a clone of this database with different options. * * @see Database::__construct() for supported options * @param array $options Database constructor options * @return Database * @throws InvalidArgumentException for parameter/option parsing errors */ public function withOptions(array $options = []) { $options += [ 'readConcern' => $this->readConcern, 'readPreference' => $this->readPreference, 'typeMap' => $this->typeMap, 'writeConcern' => $this->writeConcern, ]; return new Database($this->manager, $this->databaseName, $options); } }