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

Edit report at https://bugs.php.net/bug.php?id=70119&edit=1 ID: 70119 Comment by: tpunt@php.net 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: > 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(). Previous Comments: ------------------------------------------------------------------------ [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 ------------------------------------------------------------------------ [2015-07-23 17:58:23] chealer at gmail dot com Description: ------------ If the prepared statement included parameter markers, you must either: call PDOStatement::bindParam() to bind PHP variables to the parameter markers: bound variables pass their value as input and receive the output value, if any, of their associated parameter markers or pass an array of input-only parameter values --- From manual page: http://www.php.net/pdostatement.execute --- In fact, as shown in the examples on http://php.net/manual/en/pdostatement.bindvalue.php, PDOStatement::bindValue() can be used too. Note that this page should really link to http://php.net/manual/en/pdo.prepared-statements.php ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=70119&edit=1