task: #3522561 Fully type StatementInterface methods' parameters (ab14cc05) · Commits · project / drupal

core/lib/Drupal/Core/Database/Statement/StatementBase.php

+14 −11

Original line number	Diff line number	Diff line
		@@ -125,7 +125,7 @@ public function getConnectionTarget(): string {
		/**
		* {@inheritdoc}
		*/
		abstract public function execute($args = [], $options = []);
		abstract public function execute(?array $args = [], array $options = []);

		/**
		* Dispatches an event informing that the statement execution begins.
		@@ -208,13 +208,12 @@ public function getQueryString() {
		/**
		* {@inheritdoc}
		*/
		public function setFetchMode($mode, $a1 = NULL, $a2 = []) {
		public function setFetchMode(FetchAs\|int $mode, string\|int\|null $a1 = NULL, array $a2 = []) {
		if (is_int($mode)) {
		@trigger_error("Passing the \$mode argument as an integer to setFetchMode() is deprecated in drupal:11.2.0 and is removed from drupal:12.0.0. Use a case of \Drupal\Core\Database\Statement\FetchAs enum instead. See https://www.drupal.org/node/3488338", E_USER_DEPRECATED);
		$mode = $this->pdoToFetchAs($mode);
		}
		assert($mode instanceof FetchAs);

		$this->fetchMode = $mode;
		switch ($mode) {
		case FetchAs::ClassObject:
		@@ -245,12 +244,18 @@ public function setFetchMode($mode, $a1 = NULL, $a2 = []) {
		/**
		* {@inheritdoc}
		*/
		public function fetch($mode = NULL, $cursorOrientation = NULL, $cursorOffset = NULL) {
		public function fetch(FetchAs\|int\|null $mode = NULL, $cursorOrientation = NULL, $cursorOffset = NULL) {
		if (is_int($mode)) {
		@trigger_error("Passing the \$mode argument as an integer to fetch() is deprecated in drupal:11.2.0 and is removed from drupal:12.0.0. Use a case of \Drupal\Core\Database\Statement\FetchAs enum instead. See https://www.drupal.org/node/3488338", E_USER_DEPRECATED);
		$mode = $this->pdoToFetchAs($mode);
		}
		assert($mode === NULL \|\| $mode instanceof FetchAs);
		if ($cursorOrientation !== NULL) {
		@trigger_error("Passing the \$cursorOrientation value to " . __METHOD__ . "() is deprecated in drupal:11.4.0 and will be removed in drupal:12.0.0. There is no replacement. See https://www.drupal.org/node/3551924", E_USER_DEPRECATED);
		}
		if ($cursorOffset !== NULL) {
		@trigger_error("Passing the \$cursorOffset value to " . __METHOD__ . "() is deprecated in drupal:11.4.0 and will be removed in drupal:12.0.0. There is no replacement. See https://www.drupal.org/node/3551924", E_USER_DEPRECATED);
		}

		$fetchOptions = match(func_num_args()) {
		0 => $this->fetchOptions,
		@@ -305,7 +310,7 @@ public function fetchAssoc() {
		/**
		* {@inheritdoc}
		*/
		public function fetchField($index = 0) {
		public function fetchField(int $index = 0) {
		$column = $this->result->fetch(FetchAs::Column, ['column' => $index]);

		if ($column === FALSE) {
		@@ -320,14 +325,13 @@ public function fetchField($index = 0) {
		/**
		* {@inheritdoc}
		*/
		public function fetchAll($mode = NULL, $columnIndex = NULL, $constructorArguments = NULL) {
		public function fetchAll(FetchAs\|int\|null $mode = NULL, ?int $columnIndex = NULL, ?array $constructorArguments = NULL) {
		if (is_int($mode)) {
		@trigger_error("Passing the \$mode argument as an integer to fetchAll() is deprecated in drupal:11.2.0 and is removed from drupal:12.0.0. Use a case of \Drupal\Core\Database\Statement\FetchAs enum instead. See https://www.drupal.org/node/3488338", E_USER_DEPRECATED);
		$mode = $this->pdoToFetchAs($mode);
		}

		assert($mode === NULL \|\| $mode instanceof FetchAs);

		$fetchMode = $mode ?? $this->fetchMode;
		if (isset($columnIndex)) {
		$this->fetchOptions['column'] = $columnIndex;
		@@ -346,20 +350,19 @@ public function fetchAll($mode = NULL, $columnIndex = NULL, $constructorArgument
		/**
		* {@inheritdoc}
		*/
		public function fetchCol($index = 0) {
		public function fetchCol(int $index = 0) {
		return $this->fetchAll(FetchAs::Column, $index);
		}

		/**
		* {@inheritdoc}
		*/
		public function fetchAllAssoc($key, $fetch = NULL) {
		public function fetchAllAssoc(string $key, FetchAs\|int\|null $fetch = NULL) {
		if (is_int($fetch)) {
		@trigger_error("Passing the \$fetch argument as an integer to fetchAllAssoc() is deprecated in drupal:11.2.0 and is removed from drupal:12.0.0. Use a case of \Drupal\Core\Database\Statement\FetchAs enum instead. See https://www.drupal.org/node/3488338", E_USER_DEPRECATED);
		$fetch = $this->pdoToFetchAs($fetch);
		}
		assert($fetch === NULL \|\| $fetch instanceof FetchAs);

		$result = $this->result->fetchAllAssoc($key, $fetch ?? $this->fetchMode, $this->fetchOptions);
		$this->markResultsetFetchingComplete();
		return $result;
		@@ -368,7 +371,7 @@ public function fetchAllAssoc($key, $fetch = NULL) {
		/**
		* {@inheritdoc}
		*/
		public function fetchAllKeyed($keyIndex = 0, $valueIndex = 1) {
		public function fetchAllKeyed(int $keyIndex = 0, int $valueIndex = 1) {
		$result = $this->result->fetchAllKeyed($keyIndex, $valueIndex);
		$this->markResultsetFetchingComplete();
		return $result;

core/lib/Drupal/Core/Database/StatementInterface.php

+58 −45

Original line number	Diff line number	Diff line
		@@ -2,18 +2,20 @@

		namespace Drupal\Core\Database;

		use Drupal\Core\Database\Statement\FetchAs;

		/**
		* Represents a prepared statement.
		*
		* Child implementations should either extend StatementWrapperIterator:
		* Child implementations should either extend StatementBase:
		* @code
		* class Drupal\my_module\Driver\Database\my_driver\Statement extends Drupal\Core\Database\StatementWrapperIterator {}
		* class \Drupal\my_module\Driver\Database\my_driver\Statement extends \Drupal\Core\Database\Statement\StatementBase {}
		* @endcode
		* or define their own class. If defining their own class, they will also have
		* to implement either the \Iterator or \IteratorAggregate interface before
		* Drupal\Core\Database\StatementInterface:
		* @code
		* class Drupal\my_module\Driver\Database\my_driver\Statement implements Iterator, Drupal\Core\Database\StatementInterface {}
		* class \Drupal\my_module\Driver\Database\my_driver\Statement implements \Iterator, \Drupal\Core\Database\StatementInterface {}
		* @endcode
		*
		* @ingroup database
		@@ -24,15 +26,15 @@ interface StatementInterface extends \Traversable {
		* Executes a prepared statement.
		*
		* @param array\|null $args
		* An array of values with as many elements as there are bound parameters in
		* the SQL statement being executed. This can be NULL.
		* (Optional) An array of values with as many elements as there are bound
		* parameters in the SQL statement being executed. This can be NULL.
		* @param array $options
		* An array of options for this query.
		* (Optional) An array of options for this query.
		*
		* @return bool
		* TRUE on success, or FALSE on failure.
		*/
		public function execute($args = [], $options = []);
		public function execute(?array $args = [], array $options = []);

		/**
		* Gets the query string of this statement.
		@@ -69,20 +71,17 @@ public function rowCount();
		* One of the cases of the FetchAs enum, or (deprecated) a \PDO::FETCH_*
		* constant.
		* @param string\|int\|null $a1
		* An option depending of the fetch mode specified by $mode:
		* (Optional) An option depending of the fetch mode specified by $mode:
		* - for FetchAs::Column, the index of the column to fetch;
		* - for FetchAs::ClassObject, the name of the class to create.
		* @param list<mixed> $a2
		* If $mode is FetchAs::ClassObject, the optional arguments to pass to the
		* - for \PDO::FETCH_COLUMN, the index of the column to fetch.
		* - for \PDO::FETCH_CLASS, the name of the class to create.
		* - for \PDO::FETCH_INTO, the object to add the data to.
		* constructor.
		* (Optional) If $mode is FetchAs::ClassObject, the optional arguments to
		* pass to the constructor.
		*
		* @return bool
		* TRUE if successful, FALSE if not.
		*/
		public function setFetchMode($mode, $a1 = NULL, $a2 = []);
		public function setFetchMode(FetchAs $mode, string\|int\|null $a1 = NULL, array $a2 = []);

		/**
		* Fetches the next row from a result set.
		@@ -92,28 +91,36 @@ public function setFetchMode($mode, $a1 = NULL, $a2 = []);
		* \PDO::FETCH_* constant. If not specified, defaults to what is specified
		* by setFetchMode().
		* @param int\|null $cursor_orientation
		* Not implemented in all database drivers, don't use.
		* (deprecated) Not implemented in all database drivers, don't use. The
		* $cursor_orientation parameter is deprecated in drupal:11.4.0 and will be
		* removed in drupal:12.0.0. There is no replacement.
		* @param int\|null $cursor_offset
		* Not implemented in all database drivers, don't use.
		* (deprecated) Not implemented in all database drivers, don't use. The
		* $cursor_offset parameter is deprecated in drupal:11.4.0 and will be
		* removed in drupal:12.0.0. There is no replacement.
		*
		* @return array\|object\|false
		* A result, formatted according to $mode, or FALSE on failure.
		*
		* @see https://www.drupal.org/node/3551924
		*/
		public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL);
		public function fetch(?FetchAs $mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL);

		/**
		* Returns a single field from the next record of a result set.
		* Returns a single column value from the next record of a result set.
		*
		* @param int $index
		* The numeric index of the field to return. Defaults to the first field.
		* (Optional) The numeric index of the column to return. Defaults to the
		* first one.
		*
		* @return mixed
		* A single field from the next record, or FALSE if there is no next record.
		* A single column value from the next record, or FALSE if there is no next
		* record.
		*
		* @throws \ValueError
		* If there is a record and the column index is not defined.
		*/
		public function fetchField($index = 0);
		public function fetchField(int $index = 0);

		/**
		* Fetches the next row and returns it as an object.
		@@ -122,11 +129,11 @@ public function fetchField($index = 0);
		* StatementInterface::setFetchMode() or stdClass if not specified.
		*
		* @param string\|null $class_name
		* Name of the created class.
		* (Optional) Name of the created class.
		* @param array $constructor_arguments
		* Elements of this array are passed to the constructor.
		* (Optional) Elements of this array are passed to the constructor.
		*
		* @return mixed
		* @return object\|false\|null
		* The object of specified class or \stdClass if not specified. Returns
		* FALSE or NULL if there is no next row.
		*/
		@@ -152,15 +159,16 @@ public function fetchAssoc();
		* \PDO::FETCH_* constant. If not specified, defaults to what is specified
		* by setFetchMode().
		* @param int\|null $column_index
		* If $mode is FetchAs::Column, the index of the column to fetch.
		* @param array $constructor_arguments
		* If $mode is FetchAs::ClassObject, the arguments to pass to the
		* constructor.
		* (Optional) If $mode is FetchAs::Column, the index of the column to
		* fetch.
		* @param array\|null $constructor_arguments
		* (Optional) If $mode is FetchAs::ClassObject, the arguments to pass to
		* the constructor.
		*
		* @return array
		* An array of results.
		*/
		public function fetchAll($mode = NULL, $column_index = NULL, $constructor_arguments = NULL);
		public function fetchAll(?FetchAs $mode = NULL, ?int $column_index = NULL, ?array $constructor_arguments = NULL);

		/**
		* Returns an entire single column of a result set as an indexed array.
		@@ -168,7 +176,8 @@ public function fetchAll($mode = NULL, $column_index = NULL, $constructor_argume
		* Note that this method will run the result set to the end.
		*
		* @param int $index
		* The index of the column number to fetch.
		* (Optional) The index of the column number to fetch. By default, the
		* first one.
		*
		* @return array
		* An indexed array, or an empty array if there is no result set.
		@@ -176,46 +185,50 @@ public function fetchAll($mode = NULL, $column_index = NULL, $constructor_argume
		* @throws \ValueError
		* If there is at least one record but the column index is not defined.
		*/
		public function fetchCol($index = 0);
		public function fetchCol(int $index = 0);

		/**
		* Returns the entire result set as a single associative array.
		*
		* This method is only useful for two-column result sets. It will return an
		* associative array where the key is one column from the result set and the
		* value is another field. In most cases, the default of the first two columns
		* is appropriate.
		* value is another column. In most cases, the default of the first two
		* columns is appropriate.
		*
		* Note that this method will run the result set to the end.
		*
		* @param int $key_index
		* The numeric index of the field to use as the array key.
		* (Optional) The numeric index of the column to use as the array key. By
		* default, the first column.
		* @param int $value_index
		* The numeric index of the field to use as the array value.
		* (Optional) The numeric index of the column to use as the array value. By
		* default, the second column.
		*
		* @return array
		* An associative array, or an empty array if there is no result set.
		*/
		public function fetchAllKeyed($key_index = 0, $value_index = 1);
		public function fetchAllKeyed(int $key_index = 0, int $value_index = 1);

		/**
		* Returns the result set as an associative array keyed by the given field.
		* Returns the result set as an associative array keyed by the given column.
		*
		* If the given key appears multiple times, later records will overwrite
		* earlier ones.
		*
		* Note that this method will run the result set to the end.
		*
		* @param string $key
		* The name of the field on which to index the array.
		* @param \Drupal\Core\Database\Statement\FetchAs\|int\|string\|null $fetch
		* (Optional) the fetch mode to use. One of the cases of the FetchAs enum,
		* or (deprecated) a \PDO::FETCH_* constant. If set to FetchAs::Associative
		* or FetchAs::List the returned value with be an array of arrays. For any
		* other value it will be an array of objects. If not specified, defaults to
		* what is specified by setFetchMode().
		* The name of the column on which to index the array.
		* @param \Drupal\Core\Database\Statement\FetchAs\|null $fetch
		* (Optional) the fetch mode to use. One of the cases of the FetchAs enum.
		* If set to FetchAs::Associative or FetchAs::List the returned value will
		* be an array of arrays. For any other value it will be an array of
		* objects. If not specified, defaults to what is specified by
		* setFetchMode().
		*
		* @return array
		* An associative array, or an empty array if there is no result set.
		*/
		public function fetchAllAssoc($key, $fetch = NULL);
		public function fetchAllAssoc(string $key, ?FetchAs $fetch = NULL);

		}