From 9babd9e6d1b5bddeb04cc548171147524112b414 Mon Sep 17 00:00:00 2001
From: Sergei Morozov <morozov@tut.by>
Date: Wed, 4 Nov 2020 19:40:41 -0800
Subject: [PATCH] Deprecate inappropriate usage of prepared statement
 parameters

---
 UPGRADE.md                                    | 31 +++++++++++++++++++
 .../data-retrieval-and-manipulation.rst       |  8 +++--
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index 161c9c75d73..2ea6c38351e 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -1,5 +1,36 @@
 # Upgrade to 2.12
 
+## Deprecated non-zero based positional parameter keys
+
+The usage of one-based and other non-zero-based keys when binding positional parameters is deprecated.
+
+It is recommended to not use any array keys so that the value of the parameter array complies with the [`list<>`](https://psalm.dev/docs/annotating_code/type_syntax/array_types/) type constraint.
+
+```php
+// This is valid (implicit zero-based parameter indexes)
+$conn->fetchNumeric('SELECT ?, ?', [1, 2]);
+
+// This is invalid (one-based parameter indexes)
+$conn->fetchNumeric('SELECT ?, ?', [1 => 1, 2 => 2]);
+
+// This is invalid (arbitrary parameter indexes)
+$conn->fetchNumeric('SELECT ?, ?', [-31 => 1, 5 => 2]);
+
+// This is invalid (non-sequential parameter indexes)
+$conn->fetchNumeric('SELECT ?, ?', [0 => 1, 3 => 2]);
+```
+
+## Deprecated skipping prepared statement parameters
+
+Some underlying drivers currently allow skipping prepared statement parameters. For instance:
+
+```php
+$conn->fetchOne('SELECT ?');
+// NULL
+```
+
+This behavior should not be relied upon and may change in future versions.
+
 ## Deprecated colon prefix for prepared statement parameters
 
 The usage of the colon prefix when binding named parameters is deprecated.
diff --git a/docs/en/reference/data-retrieval-and-manipulation.rst b/docs/en/reference/data-retrieval-and-manipulation.rst
index 7e85e3c3a82..7902584c3de 100644
--- a/docs/en/reference/data-retrieval-and-manipulation.rst
+++ b/docs/en/reference/data-retrieval-and-manipulation.rst
@@ -91,9 +91,11 @@ are then replaced by their actual values in a second step (execute).
     $stmt->bindValue(1, $id);
     $stmt->execute();
 
-Placeholders in prepared statements are either simple positional question marks (?) or named labels starting with
-a double-colon (:name1). You cannot mix the positional and the named approach. The approach
-using question marks is called positional, because the values are bound in order from left to right
+Placeholders in prepared statements are either simple positional question marks (``?``) or named labels starting with
+a colon (e.g. ``:name1``). You cannot mix the positional and the named approach. You have to bind a parameter
+to each placeholder.
+
+The approach using question marks is called positional, because the values are bound in order from left to right
 to any question mark found in the previously prepared SQL query. That is why you specify the
 position of the variable to bind into the ``bindValue()`` method: