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.

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?]

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.

I can buy that logic, since it was the way I was leaning too.