Skip to content

Commit

Permalink
PHPLIB-1227 Use void return types for operations without meaningful r…
Browse files Browse the repository at this point in the history 
…esult document (#1468)
  • Loading branch information
@GromNaN
GromNaN authored Oct 1, 2024
1 parent 3d46eaf commit f4962c9
Show file tree
Hide file tree
Showing 27 changed files with 89 additions and 272 deletions.
14 changes: 14 additions & 0 deletions UPGRADE-2.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,20 @@ UPGRADE FROM 1.x to 2.0
* `MongoDB\Model\IndexInfoIteratorIterator`
* `MongoDB\Operation\Executable`

Operations with no result
-------------------------

The following operations no longer return the raw command result. The return
type changed to `void`. In case of an error, an exception is thrown.

* `MongoDB\Client`: `dropDatabase`
* `MongoDB\Collection`: `drop`, `dropIndex`, `dropIndexes`, `dropSearchIndex`, `rename`
* `MongoDB\Database`: `createCollection`, `drop`, `dropCollection`, `renameCollection`
* `MongoDB\Database::createEncryptedCollection()` returns the list of encrypted fields

If you still need to access the raw command result, you can use a
[`CommandSubscriber`](https://www.php.net/manual/en/class.mongodb-driver-monitoring-commandsubscriber.php).

GridFS
------

Expand Down
15 changes: 0 additions & 15 deletions psalm-baseline.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -519,9 +519,6 @@
</MixedMethodCall>
</file>
<file src="src/Operation/CreateCollection.php">
<MixedArgument>
<code><![CDATA[$this->options['typeMap']]]></code>
</MixedArgument>
<MixedAssignment>
<code><![CDATA[$cmd[$option]]]></code>
<code><![CDATA[$options['session']]]></code>
Expand Down Expand Up @@ -593,9 +590,6 @@
</MixedMethodCall>
</file>
<file src="src/Operation/DropCollection.php">
<MixedArgument>
<code><![CDATA[$this->options['typeMap']]]></code>
</MixedArgument>
<MixedAssignment>
<code><![CDATA[$cmd['comment']]]></code>
<code><![CDATA[$options['session']]]></code>
Expand All @@ -606,9 +600,6 @@
</MixedMethodCall>
</file>
<file src="src/Operation/DropDatabase.php">
<MixedArgument>
<code><![CDATA[$this->options['typeMap']]]></code>
</MixedArgument>
<MixedAssignment>
<code><![CDATA[$cmd['comment']]]></code>
<code><![CDATA[$options['session']]]></code>
Expand All @@ -621,9 +612,6 @@
</MixedArgument>
</file>
<file src="src/Operation/DropIndexes.php">
<MixedArgument>
<code><![CDATA[$this->options['typeMap']]]></code>
</MixedArgument>
<MixedAssignment>
<code><![CDATA[$cmd[$option]]]></code>
<code><![CDATA[$options['session']]]></code>
Expand Down Expand Up @@ -755,9 +743,6 @@
</MixedAssignment>
</file>
<file src="src/Operation/RenameCollection.php">
<MixedArgument>
<code><![CDATA[$this->options['typeMap']]]></code>
</MixedArgument>
<MixedAssignment>
<code><![CDATA[$cmd[$option]]]></code>
<code><![CDATA[$options['session']]]></code>
Expand Down
15 changes: 2 additions & 13 deletions src/Client.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,6 @@
use function array_diff_key;
use function is_array;
use function is_string;
use function sprintf;
use function trigger_error;

use const E_USER_DEPRECATED;

class Client
{
Expand Down Expand Up @@ -217,19 +213,12 @@ public function createClientEncryption(array $options): ClientEncryption
* @see DropDatabase::__construct() for supported options
* @param string $databaseName Database 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 dropDatabase(string $databaseName, array $options = []): array|object
public function dropDatabase(string $databaseName, array $options = []): void
{
if (! isset($options['typeMap'])) {
$options['typeMap'] = $this->typeMap;
} else {
@trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', __FUNCTION__), E_USER_DEPRECATED);
}

$server = select_server_for_write($this->manager, $options);

if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
Expand All @@ -238,7 +227,7 @@ public function dropDatabase(string $databaseName, array $options = []): array|o

$operation = new DropDatabase($databaseName, $options);

return $operation->execute($server);
$operation->execute($server);
}

/**
Expand Down
30 changes: 9 additions & 21 deletions src/Collection.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -501,15 +501,13 @@ public function distinct(string $fieldName, array|object $filter = [], array $op
*
* @see DropCollection::__construct() for supported options
* @param array $options Additional 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 drop(array $options = []): array|object
public function drop(array $options = []): void
{
$options = $this->inheritWriteOptions($options);
$options = $this->inheritTypeMap($options, __FUNCTION__);

$server = select_server_for_write($this->manager, $options);

Expand All @@ -522,7 +520,7 @@ public function drop(array $options = []): array|object
? new DropEncryptedCollection($this->databaseName, $this->collectionName, $options)
: new DropCollection($this->databaseName, $this->collectionName, $options);

return $operation->execute($server);
$operation->execute($server);
}

/**
Expand All @@ -531,12 +529,11 @@ public function drop(array $options = []): array|object
* @see DropIndexes::__construct() for supported options
* @param string|IndexInfo $indexName Index name or model object
* @param array $options Additional 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 dropIndex(string|IndexInfo $indexName, array $options = []): array|object
public function dropIndex(string|IndexInfo $indexName, array $options = []): void
{
$indexName = (string) $indexName;

Expand All @@ -545,31 +542,28 @@ public function dropIndex(string|IndexInfo $indexName, array $options = []): arr
}

$options = $this->inheritWriteOptions($options);
$options = $this->inheritTypeMap($options, __FUNCTION__);

$operation = new DropIndexes($this->databaseName, $this->collectionName, $indexName, $options);

return $operation->execute(select_server_for_write($this->manager, $options));
$operation->execute(select_server_for_write($this->manager, $options));
}

/**
* Drop all indexes in the collection.
*
* @see DropIndexes::__construct() for supported options
* @param array $options Additional 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 dropIndexes(array $options = []): array|object
public function dropIndexes(array $options = []): void
{
$options = $this->inheritWriteOptions($options);
$options = $this->inheritTypeMap($options, __FUNCTION__);

$operation = new DropIndexes($this->databaseName, $this->collectionName, '*', $options);

return $operation->execute(select_server_for_write($this->manager, $options));
$operation->execute(select_server_for_write($this->manager, $options));
}

/**
Expand Down Expand Up @@ -909,23 +903,21 @@ public function listSearchIndexes(array $options = []): Iterator
* @param string $toCollectionName New name of the collection
* @param string|null $toDatabaseName New database name of the collection. Defaults to the original database.
* @param array $options Additional 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 rename(string $toCollectionName, ?string $toDatabaseName = null, array $options = []): array|object
public function rename(string $toCollectionName, ?string $toDatabaseName = null, array $options = []): void
{
if (! isset($toDatabaseName)) {
$toDatabaseName = $this->databaseName;
}

$options = $this->inheritWriteOptions($options);
$options = $this->inheritTypeMap($options);

$operation = new RenameCollection($this->databaseName, $this->collectionName, $toDatabaseName, $toCollectionName, $options);

return $operation->execute(select_server_for_write($this->manager, $options));
$operation->execute(select_server_for_write($this->manager, $options));
}

/**
Expand Down Expand Up @@ -1127,12 +1119,8 @@ private function inheritReadPreference(array $options): array
return $options;
}

private function inheritTypeMap(array $options, ?string $deprecatedFunction = null): array
private function inheritTypeMap(array $options): array
{
if ($deprecatedFunction !== null && isset($options['typeMap'])) {
@trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', $deprecatedFunction), E_USER_DEPRECATED);
}

// Only inherit the type map if no codec is used
if (! isset($options['typeMap']) && ! isset($options['codec'])) {
$options['typeMap'] = $this->typeMap;
Expand Down
60 changes: 12 additions & 48 deletions src/Database.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,7 @@
use Throwable;

use function is_array;
use function sprintf;
use function strlen;
use function trigger_error;

use const E_USER_DEPRECATED;

class Database
{
Expand Down Expand Up @@ -274,19 +270,12 @@ public function command(array|object $command, array $options = []): CursorInter
* @see CreateCollection::__construct() for supported options
* @see https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/client-side-encryption.rst#create-collection-helper
* @see https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/manage-collections/
* @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(string $collectionName, array $options = []): array|object
public function createCollection(string $collectionName, array $options = []): void
{
if (! isset($options['typeMap'])) {
$options['typeMap'] = $this->typeMap;
} else {
@trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', __FUNCTION__), E_USER_DEPRECATED);
}

if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
$options['writeConcern'] = $this->writeConcern;
}
Expand All @@ -301,7 +290,7 @@ public function createCollection(string $collectionName, array $options = []): a

$server = select_server_for_write($this->manager, $options);

return $operation->execute($server);
$operation->execute($server);
}

/**
Expand All @@ -319,19 +308,13 @@ public function createCollection(string $collectionName, array $options = []): a
* getPrevious() and getEncryptedFields() methods, respectively.
*
* @see CreateCollection::__construct() for supported options
* @return array A tuple containing the command result document from creating the collection and the modified "encryptedFields" option
* @return array The modified "encryptedFields" option
* @throws InvalidArgumentException for parameter/option parsing errors
* @throws CreateEncryptedCollectionException for any errors creating data keys or creating the collection
* @throws UnsupportedException if Queryable Encryption is not supported by the selected server
*/
public function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options): array
{
if (! isset($options['typeMap'])) {
$options['typeMap'] = $this->typeMap;
} else {
@trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', __FUNCTION__), E_USER_DEPRECATED);
}

if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
$options['writeConcern'] = $this->writeConcern;
}
Expand All @@ -340,10 +323,10 @@ public function createEncryptedCollection(string $collectionName, ClientEncrypti
$server = select_server_for_write($this->manager, $options);

try {
$operation->createDataKeys($clientEncryption, $kmsProvider, $masterKey, $encryptedFields);
$result = $operation->execute($server);
$encryptedFields = $operation->createDataKeys($clientEncryption, $kmsProvider, $masterKey);
$operation->execute($server);

return [$result, $encryptedFields];
return $encryptedFields;
} catch (Throwable $e) {
throw new CreateEncryptedCollectionException($e, $encryptedFields ?? []);
}
Expand All @@ -354,19 +337,12 @@ public function createEncryptedCollection(string $collectionName, ClientEncrypti
*
* @see DropDatabase::__construct() for supported options
* @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 drop(array $options = []): array|object
public function drop(array $options = []): void
{
if (! isset($options['typeMap'])) {
$options['typeMap'] = $this->typeMap;
} else {
@trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', __FUNCTION__), E_USER_DEPRECATED);
}

$server = select_server_for_write($this->manager, $options);

if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
Expand All @@ -375,7 +351,7 @@ public function drop(array $options = []): array|object

$operation = new DropDatabase($this->databaseName, $options);

return $operation->execute($server);
$operation->execute($server);
}

/**
Expand All @@ -384,19 +360,12 @@ public function drop(array $options = []): array|object
* @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(string $collectionName, array $options = []): array|object
public function dropCollection(string $collectionName, array $options = []): void
{
if (! isset($options['typeMap'])) {
$options['typeMap'] = $this->typeMap;
} else {
@trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', __FUNCTION__), E_USER_DEPRECATED);
}

$server = select_server_for_write($this->manager, $options);

if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
Expand All @@ -412,7 +381,7 @@ public function dropCollection(string $collectionName, array $options = []): arr
? new DropEncryptedCollection($this->databaseName, $collectionName, $options)
: new DropCollection($this->databaseName, $collectionName, $options);

return $operation->execute($server);
$operation->execute($server);
}

/**
Expand Down Expand Up @@ -534,21 +503,16 @@ public function modifyCollection(string $collectionName, array $collectionOption
* @param string $toCollectionName New name of the collection
* @param string|null $toDatabaseName New database name of the collection. Defaults to the original database.
* @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 renameCollection(string $fromCollectionName, string $toCollectionName, ?string $toDatabaseName = null, array $options = []): array|object
public function renameCollection(string $fromCollectionName, string $toCollectionName, ?string $toDatabaseName = null, array $options = []): void
{
if (! isset($toDatabaseName)) {
$toDatabaseName = $this->databaseName;
}

if (! isset($options['typeMap'])) {
$options['typeMap'] = $this->typeMap;
}

$server = select_server_for_write($this->manager, $options);

if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
Expand All @@ -557,7 +521,7 @@ public function renameCollection(string $fromCollectionName, string $toCollectio

$operation = new RenameCollection($this->databaseName, $fromCollectionName, $toDatabaseName, $toCollectionName, $options);

return $operation->execute($server);
$operation->execute($server);
}

/**
Expand Down
Loading

0 comments on commit f4962c9

Please sign in to comment.