From 7208adeff9653354cf9260f8bb8fd7f7305eef67 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Sat, 14 Nov 2026 12:05:26 +0000 Subject: [PATCH] [ds] Fix incorrect numeric string key caution on Ds\Map pages The Ds\Map::get(), Ds\Map::put() and Ds\Map::remove() pages warned that when using array syntax, scalar keys are coerced to integers by the engine, so that $map["1"] would access int(1). This is not the case: Ds\Map implements the dimension handlers natively and receives the offset unchanged, and the engine does not cast numeric string offsets for objects either (the same holds for the userland polyfill, which implements ArrayAccess). $map["1"] and $map->get("1") both look up the string key "1", and $map["1"] and $map[1] are two different keys. Verified against ext-ds built from master on PHP 8.5: reading, writing, isset() and unset() with array syntax all keep "1" and 1 distinct. ext-ds requires PHP 8.2 or later, so the warning does not apply to any supported version. Replace the caution with a note stating the actual behavior, since it differs from arrays, where such keys are cast to integers. Also correct the array syntax note on the remove() page, which showed reading a value ($map["key"]) instead of removing it (unset($map["key"])). Fixes #22 --- reference/ds/ds/map/get.xml | 15 ++++++--------- reference/ds/ds/map/put.xml | 15 ++++++--------- reference/ds/ds/map/remove.xml | 17 +++++++---------- 3 files changed, 19 insertions(+), 28 deletions(-) diff --git a/reference/ds/ds/map/get.xml b/reference/ds/ds/map/get.xml index 4524a38c7..d66b7a50b 100644 --- a/reference/ds/ds/map/get.xml +++ b/reference/ds/ds/map/get.xml @@ -37,17 +37,14 @@ - - - Be careful when using array syntax. Scalar keys will be coerced to - integers by the engine. For example, $map["1"] will attempt - to access int(1), while $map->get("1") will - correctly look up the string key. - + - See Arrays. + Unlike with arrays, + numeric string keys are not cast to integers, even when using array + syntax. For example, $map["1"] and $map[1] + refer to two different keys. - + diff --git a/reference/ds/ds/map/put.xml b/reference/ds/ds/map/put.xml index 4d57949cc..e11668fb8 100644 --- a/reference/ds/ds/map/put.xml +++ b/reference/ds/ds/map/put.xml @@ -37,17 +37,14 @@ - - - Be careful when using array syntax. Scalar keys will be coerced to - integers by the engine. For example, $map["1"] will attempt - to access int(1), while $map->get("1") will - correctly look up the string key. - + - See Arrays. + Unlike with arrays, + numeric string keys are not cast to integers, even when using array + syntax. For example, $map["1"] and $map[1] + refer to two different keys. - + diff --git a/reference/ds/ds/map/remove.xml b/reference/ds/ds/map/remove.xml index d672ca893..84da2ad25 100644 --- a/reference/ds/ds/map/remove.xml +++ b/reference/ds/ds/map/remove.xml @@ -33,21 +33,18 @@ - You can also use array syntax to access values by key, eg. $map["key"]. + You can also use array syntax to remove values by key, eg. unset($map["key"]). - - - Be careful when using array syntax. Scalar keys will be coerced to - integers by the engine. For example, $map["1"] will attempt - to access int(1), while $map->get("1") will - correctly look up the string key. - + - See Arrays. + Unlike with arrays, + numeric string keys are not cast to integers, even when using array + syntax. For example, $map["1"] and $map[1] + refer to two different keys. - +