Description:
------------
preg_quote() is great for escaping a user-supplied search string.
There is no matching function to escape a user-supplied replacement string.

My wish is for preg_quote() to have an extra flag "IS_REPLACEMENT" or to have a 
function preg_quote_replacement(), which would escape only backslash and dollar 
signs.

Example below.


Might I also suggest this is a documentation bug, in that there is no explanation 
of the correct way to work around this?

Test script:
---------------
$text = 'Invoice: You owe me *#5* !';
$user_search  = "*#5*";
$user_replace = "*$5*";

$search = preg_quote($user_search, "/");
$replace_bad1 = $user_replace;
$replace_bad2 = preg_quote($user_replace);  

$new_text1 = preg_replace("/$search/", "$replace_bad1", $text);
$new_text2 = preg_replace("/$search/", "$replace_bad2", $text);
echo "Input: $text\nNew1:  $new_text1\nNew2:  $new_text2\n";


Expected result:
----------------
I want to return the string:
    Invoice: You owe me *$5* !


Actual result:
--------------
Input: Invoice: You owe me *#5* !
New1:  Invoice: You owe me ** !
New2:  Invoice: You owe me \*$5\* !

1. the '*' in the search string is not magic, thanks to the normal use of 
preg_quote(). This is what I expect.

2. If I replace with a literal, then '$5' becomes the 5th backreference, which is 
empty.

3. If I preg_quote the replacement, then we get spurious backslashes before the 
'*'s.