php
Improve documentation by renaming needle and haystack arguments
Affected page
https://www.php.net/manual/en/function.str-contains.php https://www.php.net/manual/en/function.strpos.php https://www.php.net/manual/en/function.in-array.php ...
Current issue
In the PHP documentation, many string and array-related functions use the argument names needle and haystack. While this metaphor may be familiar to native English speakers, it can be confusing for non-native speakers or beginners.
Suggested improvement
Renaming these arguments to something more descriptive — such as searchString and targetText, or substring and fullString — would make the documentation clearer and more accessible. Improving clarity in naming could greatly help learners understand function behavior without having to interpret idiomatic expressions.
Because of named parameters, this would be a (breaking) language change, not a documentation change, and would almost certainly require an RFC.
There's also many more functions that use this naming pattern (other string and array functions).
The terms haystack and needle are commonly used in programming across many languages, libraries, and articles in this context. Subsequently, while these terms are idiomatic, I think that it's useful for developers to learn and use these specific terms.
I would argue that your suggested replacements are not suitably unambiguous. Is searchString the string you're searching in, or the string you're searching for? Similarly for the term "target". The parameter names should be very clear about this (especially as the order of the haystack and needle change depending on which set of functions / extension you're using).
The terms haystack and needle are concise and subsequently quick to recognize when reading documentation or IDE hints. Even after a couple of decades working with PHP, I still often double-check whether some function is "haystack, needle" or "needle, haystack", and I think the terms being common across all these functions helps here.
