See Release Notes
Long Term Support Release
<?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); } }