Doc #70119 [Csd]: PDOStatement::execute - ignores bindValue()

Edit report at https://bugs.php.net/bug.php?id=70119&edit=1 ID: 70119 User updated by: chealer at gmail dot com Reported by: chealer at gmail dot com Summary: PDOStatement::execute - ignores bindValue() Status: Closed Type: Documentation Problem Package: Documentation problem PHP Version: Irrelevant Assigned To: tpunt Block user comment: N Private report: N New Comment: >> I find it irritating to see examples which do not describe their effects. >Perhaps I'm taking too much for granted here, by I see the code as pretty self-explanatory. >A search is being made on the colours field where the calorie count is less than 150. I would agree that much is obvious, but which such search? I believe readers should be able to fully understand examples. And not only that, but even if they fully understand the purpose, they should be able to validate their understanding. >I avoid littering code examples with inline comments because it is distracting and completely >unnecessary when the behaviour of the code is self-explanatory. In my book, there are 2 cases: *Unneeded examples *Useful examples, which should be described. Note that I am not suggesting inline comments. The effect can be described in normal text. >Not to mention the code examples for execute() shouldn't be describing the purposes/usages >of bindParam() or bindValue(), since they both have separate pages specifically for them in the >manual. That is correct, but the example proposed uses execute() in combination with these. Note that I am not against "removing" that example and moving it to a page about prepared statements in general, if the page about execute() links to that page. >> Are you saying that bindParam() does not allow wildcards? >No, not at all. By using bindValue(), we simply avoid having to making an unnecessary variable >assignment just to bind the search value using bindParam(). I see. Looking at this again, to properly use bindValue(), we would have to be in a situation where a user determines the pattern, for example. It seems unlikely that a user would search green or grey fruits under 150 calories using search term "gre", but I am OK with that example as long as it is explained. But perhaps we could just avoid this problem by replacing "gre" with "[...]" or something showing it is variable, such as $_REQUEST['colorFilter']. Previous Comments: ------------------------------------------------------------------------ [2016-03-27 20:55:00] tpunt@php.net > There may be a use case for the example, but it is not obvious. The use-case is mentioned in both the example title and example comment: demonstrating the binding of variables and values to a prepared query. > I find it irritating to see examples which do not describe their effects. Perhaps I'm taking too much for granted here, by I see the code as pretty self-explanatory. A search is being made on the colours field where the calorie count is less than 150. I avoid littering code examples with inline comments because it is distracting and completely unnecessary when the behaviour of the code is self-explanatory. Not to mention the code examples for execute() shouldn't be describing the purposes/usages of bindParam() or bindValue(), since they both have separate pages specifically for them in the manual. > Are you saying that bindParam() does not allow wildcards? No, not at all. By using bindValue(), we simply avoid having to making an unnecessary variable assignment just to bind the search value using bindParam(). ------------------------------------------------------------------------ [2016-03-27 19:52:23] chealer at gmail dot com Thanks tpunt. I understood why one call to bindParam() was replaced with bindValue(). What I did not understand is why colour = 'red' was replaced with colour LIKE '%gre%'. I now see that %gre% does match "green" and "grey". However, I still find that example strange. There may be a use case for the example, but it is not obvious. And even if there was an obvious use case, I would be unimpressed to read code matching grey and green fruits using a pattern rather than using an OR, at least for clarity. If I would see such code used because it was deemed better for performance, I would expect the pattern "gre%" to be used and I would expect a comment explaining which values are expected to be matched. I would in fact find it much less strange and much more acceptable to see an OR and the pattern "gr?y", since grey has 2 spellings. Perhaps those for whom English is a native language will understand the example more easily, but for the record, I find it irritating to see examples which do not describe their effects. I am not saying everyone would prefer to have no example than unexplained examples, but I find unexplained examples sub-optimal. They make it seem like the manual addresses readers who already know the topic documented. Failure to explain the goal is of course less problematic when that goal is obvious, but I wish we aimed for 0 such cases. By the way, I wonder why you say the change is "showing a common scenario of when bindValue is used over bindParam() (wildcard insertion)". Are you saying that bindParam() does not allow wildcards? I do not use bindParam(), but it was my understanding that it allowed wildcards. If that is not the case, I do not see where the manual says so. ------------------------------------------------------------------------ [2016-03-27 17:25:57] tpunt@php.net The updated first code example was for didactic reasons. Since we now mention bindValue() on the page, it would be nice to demonstrate it. Moreover, none of the examples on the bindParam() or bindValue() pages demonstrate the usage of both methods when preparing a single query. So I updated the first example to show this, where "gre" could match "grey" or "green," whilst showing a common scenario of when bindValue is used over bindParam() (wildcard insertion). ------------------------------------------------------------------------ [2016-03-27 16:48:32] chealer at gmail dot com Thank you. Note that revision 338832 changes $colour = 'red'; to $colour = 'gre'; and Example #1 now uses colour LIKE '%gre%' rather than colour = 'red'. It is fairly clear that "green" would match, but I find the new version somewhat strange. I recommend to stay simple or to provide a short description of what the example achieves. ------------------------------------------------------------------------ [2016-03-27 15:52:48] tpunt@php.net Automatic comment from SVN on behalf of tpunt Revision: http://svn.php.net/viewvc/?view=revision&revision=338832 Log: Resolve doc bug #70119 ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at https://bugs.php.net/bug.php?id=70119 -- Edit this bug report at https://bugs.php.net/bug.php?id=70119&edit=1