Skip to content

PHPLIB-1227 Use void return types for operations without meaningful result document #1468

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 1, 2024
Merged

PHPLIB-1227 Use void return types for operations without meaningful result document #1468

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
260c266
PHPLIB-1227 Use void return type for operations without meaningful re…
GromNaN Sep 26, 2024
5ff7621
Revert change on modifyCollection
GromNaN Oct 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions UPGRADE-2.0.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Copy link
Member Author

@GromNaN GromNaN Sep 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of a tuple, we return the 2nd element (the encryptedFields), but the return type is not modified.

* @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