Doc #62997 [Opn->Wfx]: Section on variables: explain $1 is always literal

Edit report at https://bugs.php.net/bug.php?id=62997&edit=1 ID: 62997 Updated by: aharvey@php.net Reported by: php at richardneill dot org Summary: Section on variables: explain $1 is always literal -Status: Open +Status: Wont fix Type: Documentation Problem Package: Documentation problem Operating System: Linux PHP Version: Irrelevant Block user comment: N Private report: N New Comment: I can buy that logic, since it was the way I was leaning too. Previous Comments: ------------------------------------------------------------------------ [2012-09-13 03:12:56] googleguy@php.net We do document this actually. The documentation on variables explicitly states: "Variable names follow the same rules as other labels in PHP. A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: '[a-zA-Z_\x7f-\xff][a- zA-Z0-9_\x7f-\xff]*'" See http://php.net/language.variables.basics it's right there on the second line and couldn't be any clearer about what a valid variable name is in PHP. As for the part on strings and double quote interpolation of variable names in http://php.net/language.types.string.php#language.types.string.syntax.double towards the third paragraph down: "The most important feature of double-quoted strings is the fact that variable names will be expanded. See string parsing for details." Where we link to "variable parsing" at http://php.net/language.types.string.php#language.types.string.parsing It is explicitly stated there under "Simple syntax" that "If a dollar sign ($) is encountered, the parser will greedily take as many tokens as possible to form a valid variable name." Meaning that the parser does not attempt to disobey the variable naming rules defined in http://php.net/language.variables.basics and the documentation further goes on to describe the "Complex (curly) syntax" in string interpolation for variable parsing: "Any scalar variable, array element or object property with a string representation can be included via this syntax. Simply write the expression the same way as it would appear outside the string, and then wrap it in { and }. Since { can not be escaped, this syntax will only be recognised when the $ immediately follows the {. Use {\$ to get a literal {$. Some examples to make it clear:" So for example: <?php echo "$1"; // Does not produce a parse error. echo "{$1}"; // Will produce a parse error ?> The complex (curly) syntax forces the parser to try and parse the variable for interpolation. The simple syntax does not. As for providing literal '$1' in your SQL -- not to be confused as a parameter -- that's an escaping issue in your SQL. If you wanted to provide your SQL with a string of '$1' you would simply enclose it in quotes in the SQL statement as normal. "INSERT INTO table VALUES('$1')" I'm OK with this being closed as Won't Fix since it's already documented well enough for me to agree it doesn't need further elaboration. ------------------------------------------------------------------------ [2012-09-03 08:53:37] php at richardneill dot org I see your point entirely, and why you wouldn't want to encourage beginners into using that syntax. But especially for the cases like pg_query_params, I think it's worth mentioning. In particular, is "$1" intentionally literal, or is it merely an artefact of the parser that doesn't (yet) throw an error? $1, $2 etc do have meaning in bash/perl, so I think a definition is worth having. Perhaps the docs for pg_query_params() should be the place to state it? [Incidentally, on a similar note, how does one embed a raw '$1' into pg_query_params, without it being interpreted as a placeholder?] ------------------------------------------------------------------------ [2012-09-03 02:57:43] aharvey@php.net It's deliberate in the sense that it's not a valid variable name (it's kind of hinted at in the String Parsing section, if not explicitly stated), but I'm not sure that it's a code pattern that we want to be pushing, really: it's probably simpler for new developers to just understand that $ is magic in double quoted strings and push them towards single quoted strings in this case, and let them work out the corner cases later if need be. Does anyone else on the doc team have any thoughts? Not sure whether to Won't Fix this or not. ------------------------------------------------------------------------ [2012-09-02 14:10:57] php at richardneill dot org Description: ------------ In something like pg_query_params(), it is OK to use eg $sql = "select * from table where id=$1" In other words, because variable names cannot begin with numbers, constructs such as $1, $2 etc are literal, even within double-quotes. This is actually quite helpful - and it seems to be deliberate (at any rate, no errors appear in logfile). I think the documentation should make it clearer. Test script: --------------- echo 'You owe me $100'; echo "You owe me \$100"; echo "You owe me $100"; all produce the same output. The 3rd of these is (to me) rather surprising, though useful, and isn't documented, either in the variable-naming or the double-quoted string sections. It should also appear in the pg_query_params() docs. ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=62997&edit=1