There is no bug to fix here. You're actually getting "Connection reset by peer" (ECONNRESET) and that makes recv() to return -1 -> PHP socket_read() returns an error and FALSE.

Here's simplified WORKING script:

#!/usr/local/bin/php
<?php
error_reporting(E_ALL);

/* Allow the script to hang around waiting for connections. */
set_time_limit(0);

/* Turn on implicit output flushing so we see what we're getting as it
comes in. */
ob_implicit_flush();

$address = '127.0.0.1';
$port = 1111;

$sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
socket_bind($sock, $address, $port);
socket_listen($sock, 5);

do {
   $msgsock = socket_accept($sock);

   do {
       $buf = socket_read($msgsock, 2048, PHP_NORMAL_READ);
       var_dump($buf);
   } while ($buf !== FALSE && $buf !== '');

   echo socket_strerror(socket_last_error($msgsock));
   socket_close($msgsock);

   echo "Closed msgsocket; waiting for another connection\n";

} while (true);

socket_close($sock);
echo "Closed main socket, exiting\n";

?>

Thanks. That makes sense. However, it still leaves a few problems, essentially with wrong documentation.

-------------------
1)The documentation for socket_read 
http://uk.php.net/manual/en/function.socket-read.php
claims:

"Note:  socket_read() may return a zero length string ("") indicating the end of communication (i.e. the remote end point has closed the connection)."

which is obviously not true.
---------------------

2)Example 1 on the sockets page
http://uk.php.net/manual/en/ref.sockets.php
also supports the interpretation that 
False => error; null => connection closed

       if (false === ($buf = socket_read($msgsock, 2048, PHP_NORMAL_READ))) {
           echo "socket_read() failed: reason: " . socket_strerror($ret) . "\n";
           break 2;
       }
       if (!$buf = trim($buf)) {
           continue;
       }


----------------------

3)How is one to determine the difference between 
 i)the other side closing the connection normally
and 
 ii)something going very wrong with the function?

According to the documentation, 

   ""   => (i)
  false =>  (ii)

In fact, it seems that 

  false  => (i) or (ii), with no way to tell
  ""     =>  never actually happens
  

Thanks for your help,

Richard

From recv() manpage:

"Upon successful completion, recv() shall return the length of the message in bytes. If no messages are available to be received and the peer has performed an orderly shutdown, recv() shall return 0. Otherwise, -1 shall be returned and errno set to indicate the error."

Forgot this part from that: recv() function is what socket_read() uses internally.

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.