From b60ab73746495cae125309d4d4dc3bf3254d7715 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Tue, 1 Oct 2024 14:08:22 +0200 Subject: [PATCH] Update MongoDB stubs for extension version 1.20.0 --- mongodb/BSON/PackedArray.php | 9 +++++++++ mongodb/BSON/UTCDateTime.php | 2 +- mongodb/BSON/functions.php | 6 ++++++ mongodb/ClientEncryption.php | 12 ++++++++++++ mongodb/Cursor.php | 8 ++++++-- mongodb/CursorInterface.php | 16 ++++++++-------- mongodb/Exception/SSLConnectionException.php | 1 + mongodb/Exception/WriteException.php | 1 + mongodb/Monitoring/CommandFailedEvent.php | 19 +++++++++++++++++++ mongodb/Monitoring/CommandStartedEvent.php | 19 +++++++++++++++++++ mongodb/Monitoring/CommandSucceededEvent.php | 19 +++++++++++++++++++ mongodb/ReadPreference.php | 10 ++++++++++ 12 files changed, 111 insertions(+), 11 deletions(-) diff --git a/mongodb/BSON/PackedArray.php b/mongodb/BSON/PackedArray.php index fdafa883a..33dbad4fd 100644 --- a/mongodb/BSON/PackedArray.php +++ b/mongodb/BSON/PackedArray.php @@ -10,6 +10,9 @@ final class PackedArray implements \ArrayAccess, \IteratorAggregate, \Serializab { private function __construct() {} + /** @since 1.20.0 */ + final static public function fromJSON(string $json): PackedArray {} + final public static function fromPHP(array $value): PackedArray {} final public function get(int $index): mixed {} @@ -20,6 +23,12 @@ final public function has(int $index): bool {} final public function toPHP(?array $typeMap = null): array|object {} + /** @since 1.20.0 */ + final public function toCanonicalExtendedJSON(): string {} + + /** @since 1.20.0 */ + final public function toRelaxedExtendedJSON(): string {} + /** @since 1.17.0 */ public function offsetExists(mixed $offset): bool {} diff --git a/mongodb/BSON/UTCDateTime.php b/mongodb/BSON/UTCDateTime.php index 00b08d015..81a4d16a2 100644 --- a/mongodb/BSON/UTCDateTime.php +++ b/mongodb/BSON/UTCDateTime.php @@ -16,7 +16,7 @@ final class UTCDateTime implements Type, UTCDateTimeInterface, \Serializable, \J * Construct a new UTCDateTime * @link https://php.net/manual/en/mongodb-bson-utcdatetime.construct.php */ - final public function __construct(int|string|float|DateTimeInterface|null $milliseconds = null) {} + final public function __construct(int|string|float|DateTimeInterface|Int64|null $milliseconds = null) {} public static function __set_state(array $properties) {} diff --git a/mongodb/BSON/functions.php b/mongodb/BSON/functions.php index cac34edda..9792b36ee 100644 --- a/mongodb/BSON/functions.php +++ b/mongodb/BSON/functions.php @@ -14,6 +14,7 @@ * @param string $bson BSON value to be converted * @return string The converted JSON value * @throws UnexpectedValueException + * @deprecated Use MongoDB\BSON\Document instead */ function toCanonicalExtendedJSON($bson) {} @@ -25,6 +26,7 @@ function toCanonicalExtendedJSON($bson) {} * @param string $bson BSON value to be converted * @return string The converted JSON value * @throws UnexpectedValueException + * @deprecated Use MongoDB\BSON\Document instead */ function toRelaxedExtendedJSON($bson) {} @@ -35,6 +37,7 @@ function toRelaxedExtendedJSON($bson) {} * @param string $json JSON value to be converted. * @return string The serialized BSON document as a binary string. * @throws UnexpectedValueException if the JSON value cannot be converted to BSON (e.g. due to a syntax error). + * @deprecated Use MongoDB\BSON\Document instead */ function fromJSON($json) {} @@ -45,6 +48,7 @@ function fromJSON($json) {} * @param array|object $value PHP value to be serialized. * @return string The serialized BSON document as a binary string * @throws UnexpectedValueException if the PHP value cannot be converted to BSON. + * @deprecated Use MongoDB\BSON\Document instead */ function fromPHP($value) {} @@ -56,6 +60,7 @@ function fromPHP($value) {} * @return string The converted JSON value. * @see https://docs.mongodb.org/manual/reference/mongodb-extended-json/ * @throws UnexpectedValueException if the input did not contain exactly one BSON document + * @deprecated Use MongoDB\BSON\Document instead */ function toJSON($bson) {} @@ -69,5 +74,6 @@ function toJSON($bson) {} * @return object The unserialized PHP value * @throws UnexpectedValueException if the input did not contain exactly one BSON document. * @throws InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable. + * @deprecated Use MongoDB\BSON\Document instead */ function toPHP($bson, array $typemap = []) {} diff --git a/mongodb/ClientEncryption.php b/mongodb/ClientEncryption.php index b087ea2cf..c2901a729 100644 --- a/mongodb/ClientEncryption.php +++ b/mongodb/ClientEncryption.php @@ -26,8 +26,14 @@ final class ClientEncryption */ public const ALGORITHM_UNINDEXED = 'Unindexed'; + /** + * @since 1.20.0 + */ + public const ALGORITHM_RANGE = 'Range'; + /** * @since 1.16.0 + * @deprecated */ public const ALGORITHM_RANGE_PREVIEW = 'RangePreview'; @@ -36,8 +42,14 @@ final class ClientEncryption */ public const QUERY_TYPE_EQUALITY = 'equality'; + /** + * @since 1.20.0 + */ + public const QUERY_TYPE_RANGE = 'range'; + /** * @since 1.16.0 + * @deprecated */ public const QUERY_TYPE_RANGE_PREVIEW = 'rangePreview'; diff --git a/mongodb/Cursor.php b/mongodb/Cursor.php index 9befc9a71..14d199015 100644 --- a/mongodb/Cursor.php +++ b/mongodb/Cursor.php @@ -2,6 +2,7 @@ namespace MongoDB\Driver; +use MongoDB\BSON\Int64; use MongoDB\Driver\Exception\InvalidArgumentException; /** @@ -26,11 +27,14 @@ final public function __wakeup() {} public function current(): array|object|null {} /** - * Returns the MongoDB\Driver\CursorId associated with this cursor. A cursor ID cursor uniquely identifies the cursor on the server. + * Returns the cursor ID associated with this cursor. A cursor ID cursor uniquely identifies the cursor on the server. + * Receiving a CursorId return type is deprecated and will be removed in 2.0. + * + * @param bool $asInt64 Pass true to receive the cursor as a MongoDB\BSON\Int64 instance * @link https://php.net/manual/en/mongodb-driver-cursor.getid.php * @throws InvalidArgumentException on argument parsing errors. */ - final public function getId(): CursorId {} + final public function getId(bool $asInt64 = false): CursorId|Int64 {} /** * Returns the MongoDB\Driver\Server associated with this cursor. This is the server that executed the query or command. diff --git a/mongodb/CursorInterface.php b/mongodb/CursorInterface.php index e4fc903a9..8ac028627 100644 --- a/mongodb/CursorInterface.php +++ b/mongodb/CursorInterface.php @@ -2,6 +2,7 @@ namespace MongoDB\Driver; +use MongoDB\BSON\Int64; use MongoDB\Driver\Exception\InvalidArgumentException; use Traversable; @@ -13,12 +14,12 @@ interface CursorInterface extends Traversable { /** - * Returns the MongoDB\Driver\CursorId associated with this cursor. A cursor ID uniquely identifies the cursor on the server. - * @return CursorId Returns the MongoDB\Driver\CursorId for this cursor. + * Returns the cursor ID associated with this cursor. A cursor ID uniquely identifies the cursor on the server. + * @return CursorId|Int64 Returns the cursor ID for this cursor. * @throws InvalidArgumentException * @link https://www.php.net/manual/en/mongodb-driver-cursorinterface.getid.php */ - public function getId(); + public function getId(): CursorId|Int64; /** * Returns the MongoDB\Driver\Server associated with this cursor. @@ -27,7 +28,7 @@ public function getId(); * @return Server Returns the MongoDB\Driver\Server associated with this cursor. * @throws InvalidArgumentException */ - public function getServer(); + public function getServer(): Server; /** * Checks whether the cursor may have additional results available to read. @@ -35,16 +36,15 @@ public function getServer(); * @return bool Returns TRUE if additional results are not available, and FALSE otherwise. * @throws InvalidArgumentException */ - public function isDead(); + public function isDead(): bool; /** * Sets a type map to use for BSON unserialization * @link https://www.php.net/manual/en/mongodb-driver-cursorinterface.settypemap.php * @param array $typemap Type map configuration. - * @return mixed * @throws InvalidArgumentException */ - public function setTypeMap(array $typemap); + public function setTypeMap(array $typemap): void; /** * Iterates the cursor and returns its results in an array. @@ -52,5 +52,5 @@ public function setTypeMap(array $typemap); * @return array Returns an array containing all results for this cursor. * @throws InvalidArgumentException */ - public function toArray(); + public function toArray(): array; } diff --git a/mongodb/Exception/SSLConnectionException.php b/mongodb/Exception/SSLConnectionException.php index 494c9566e..e38cb4b99 100644 --- a/mongodb/Exception/SSLConnectionException.php +++ b/mongodb/Exception/SSLConnectionException.php @@ -5,5 +5,6 @@ /** * Thrown when the driver fails to establish an SSL connection with the server. * @link https://php.net/manual/en/class.mongodb-driver-exception-sslconnectionexception.php + * @deprecated use ConnectionException instead */ class SSLConnectionException extends ConnectionException implements Exception {} diff --git a/mongodb/Exception/WriteException.php b/mongodb/Exception/WriteException.php index a50621ff1..2776ac13f 100644 --- a/mongodb/Exception/WriteException.php +++ b/mongodb/Exception/WriteException.php @@ -9,6 +9,7 @@ * The exception encapsulates a MongoDB\Driver\WriteResult object. * @link https://php.net/manual/en/class.mongodb-driver-exception-writeexception.php * @since 1.0.0 + * @deprecated use MongoDB\Driver\Exception\BulkWriteException instead */ abstract class WriteException extends ServerException implements Exception { diff --git a/mongodb/Monitoring/CommandFailedEvent.php b/mongodb/Monitoring/CommandFailedEvent.php index 21fc93a92..421d874c8 100644 --- a/mongodb/Monitoring/CommandFailedEvent.php +++ b/mongodb/Monitoring/CommandFailedEvent.php @@ -35,6 +35,15 @@ final public function getCommandName(): string {} */ final public function getDurationMicros(): int {} + /** + * Returns the server hostname for the command + * @link https://www.php.net/manual/en/mongodb-driver-monitoring-commandfailedevent.gethost.php + * @return string + * @throws \InvalidArgumentException on argument parsing errors. + * @since 1.20.0 + */ + final public function getHost(): string {} + /** * Returns the Exception associated with the failed command * @link https://secure.php.net/manual/en/mongodb-driver-monitoring-commandfailedevent.geterror.php @@ -55,6 +64,15 @@ final public function getError(): \Exception {} */ final public function getOperationId(): string {} + /** + * Returns the server port for the command + * @link https://www.php.net/manual/en/mongodb-driver-monitoring-commandfailedevent.getport.php + * @return int + * @throws \InvalidArgumentException on argument parsing errors. + * @since 1.20.0 + */ + final public function getPort(): int {} + /** * Returns the command reply document. * The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass). @@ -80,6 +98,7 @@ final public function getRequestId(): string {} * @link https://secure.php.net/manual/en/mongodb-driver-monitoring-commandfailedevent.getserver.php * @return \MongoDB\Driver\Server on which the command was executed. * @since 1.3.0 + * @deprecated Use getHost and getPort instead. */ final public function getServer(): Server {} diff --git a/mongodb/Monitoring/CommandStartedEvent.php b/mongodb/Monitoring/CommandStartedEvent.php index 31b18d037..c11a61bac 100644 --- a/mongodb/Monitoring/CommandStartedEvent.php +++ b/mongodb/Monitoring/CommandStartedEvent.php @@ -44,6 +44,15 @@ final public function getCommandName(): string {} */ final public function getDatabaseName(): string {} + /** + * Returns the server hostname for the command + * @link https://www.php.net/manual/en/mongodb-driver-monitoring-commandstartedevent.gethost.php + * @return string + * @throws \InvalidArgumentException on argument parsing errors. + * @since 1.20.0 + */ + final public function getHost(): string {} + /** * Returns the command's operation ID. * The operation ID is generated by the driver and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level. @@ -55,6 +64,15 @@ final public function getDatabaseName(): string {} */ final public function getOperationId(): string {} + /** + * Returns the server port for the command + * @link https://www.php.net/manual/en/mongodb-driver-monitoring-commandstartedevent.getport.php + * @return int + * @throws \InvalidArgumentException on argument parsing errors. + * @since 1.20.0 + */ + final public function getPort(): int {} + /** * Returns the command's request ID. * The request ID is generated by the driver and may be used to associate this CommandSucceededEvent with a previous CommandStartedEvent. @@ -70,6 +88,7 @@ final public function getRequestId(): string {} * @link https://secure.php.net/manual/en/mongodb-driver-monitoring-commandstartedevent.getserver.php * @return \MongoDB\Driver\Server on which the command was executed. * @since 1.3.0 + * @deprecated Use getHost and getPort instead. */ final public function getServer(): Server {} diff --git a/mongodb/Monitoring/CommandSucceededEvent.php b/mongodb/Monitoring/CommandSucceededEvent.php index d55afe0e0..ef0932632 100644 --- a/mongodb/Monitoring/CommandSucceededEvent.php +++ b/mongodb/Monitoring/CommandSucceededEvent.php @@ -35,6 +35,15 @@ final public function getCommandName(): string {} */ final public function getDurationMicros(): int {} + /** + * Returns the server hostname for the command + * @link https://www.php.net/manual/en/mongodb-driver-monitoring-commandsucceededevent.gethost.php + * @return string + * @throws \InvalidArgumentException on argument parsing errors. + * @since 1.20.0 + */ + final public function getHost(): string {} + /** * Returns the command's operation ID. * The operation ID is generated by the driver and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level. @@ -46,6 +55,15 @@ final public function getDurationMicros(): int {} */ final public function getOperationId(): string {} + /** + * Returns the server port for the command + * @link https://www.php.net/manual/en/mongodb-driver-monitoring-commandsucceededevent.getport.php + * @return int + * @throws \InvalidArgumentException on argument parsing errors. + * @since 1.20.0 + */ + final public function getPort(): int {} + /** * Returns the command reply document. * The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass). @@ -71,6 +89,7 @@ final public function getRequestId(): string {} * @link https://secure.php.net/manual/en/mongodb-driver-monitoring-commandsucceededevent.getserver.php * @return \MongoDB\Driver\Server on which the command was executed. * @since 1.3.0 + * @deprecated Use getHost and getPort instead. */ final public function getServer(): Server {} diff --git a/mongodb/ReadPreference.php b/mongodb/ReadPreference.php index cadb4e7e4..e410acd3c 100644 --- a/mongodb/ReadPreference.php +++ b/mongodb/ReadPreference.php @@ -13,10 +13,19 @@ */ final class ReadPreference implements Serializable, \Serializable { + /** @deprecated */ public const RP_PRIMARY = 1; + + /** @deprecated */ public const RP_PRIMARY_PREFERRED = 5; + + /** @deprecated */ public const RP_SECONDARY = 2; + + /** @deprecated */ public const RP_SECONDARY_PREFERRED = 6; + + /** @deprecated */ public const RP_NEAREST = 10; /** @@ -76,6 +85,7 @@ final public function getHedge(): ?object {} /** * Returns the ReadPreference's "mode" option * @link https://php.net/manual/en/mongodb-driver-readpreference.getmode.php + * @deprecated Use getModeString instead */ final public function getMode(): int {}