As explained by Johannes in the other bug report http://bugs.php.net/52434 the hostname "localhost" has a special meaning for MySQL. Ever since "localhost" stands for "create a socket connection".

The intend of "mysql:host=localhost;port=3307;dbname=testdb" is not "clearly to connect via TCP". That's simply wrong. "host=localhost" sets the rule "if you are on Unix, use a Unix domain socket to connect to MySQL".

No bug here. The proposed Note must not be added to the documentation. 

What could be improved is the connection string example. As this bug report makes clear it has confused at least one user. This is something the docs folks can have a look at. The doc team may decide, for example, to link to some place which explains the special meaning of "localhost".

It's still a backward incompatibility when the same php.ini is used with php 
linked against libmysqlclient.

Saying that this is how MySQL does it, isn't a convincing argument given the 
following.

Reference:
http://dev.mysql.com/doc/refman/5.0/en/connecting.html

"The examples here use the mysql client program, but the principles apply to other 
clients such as mysqldump, mysqladmin, or mysqlshow."

"On Unix, MySQL programs treat the host name localhost specially, in a way that is 
likely different from what you expect compared to other network-based programs."

[ed. There is no requirement here for non-MySQL clients (eg php scripts) to follow 
MySQL's localhost semantics, which are noted as being unexpected/unconventional.]

"For connections to localhost, MySQL programs attempt to connect to the local 
server by using a Unix socket file. This occurs even if a --port or -P option is 
given to specify a port number. To ensure that the client makes a TCP/IP 
connection to the local server, use --host or -h to specify a host name value of 
127.0.0.1, or the IP address or name of the local server. You can also specify the 
connection protocol explicitly, even for localhost, by using the --protocol=TCP 
option. For example:
shell> mysql --host=127.0.0.1
shell> mysql --protocol=TCP
The --protocol option enables you to establish a particular type of connection 
even when the other options would normally default to some other protocol."

[ed. To allow for the special case of "localhost", MySQL programs provide a 
"protocol" option.  This is absent from mysqlnd.  If MySQL semantics is a PHP 
requirement, then the mysqlnd implementation is incomplete.]

"On Windows, you can force a MySQL client to use a named-pipe connection by 
specifying the --pipe or --protocol=PIPE option, or by specifying . (period) as 
the host name. If named-pipe connections are not enabled, an error occurs. Use the 
--socket option to specify the name of the pipe if you do not want to use the 
default pipe name."

[ed. Ditto. http://bugs.php.net/bug.php?id=48082 ]

This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.