Edit: "Expected result" was accidentally switched with "Actual result".

On OSX (BSD) the kernel space read buffer is emptied when the socket is shutdown.

On Linux, it only rejects further packets (so the other side cannot write).

A note in the documentation would be nice.

The fix for this bug has been committed.

Snapshots of the sources are packaged every three hours; this change
will be in the next snapshot. You can grab the snapshot at
http://snaps.php.net/.

 For Windows:

http://windows.php.net/snapshots/
 
Thank you for the report, and for helping us make PHP better.

This documentation not is quite nice, maybe not 100% clear for beginners but anyway - it's somewhat weird how it's actually working.
Let's take a look at this code:

<?php

$server = stream_socket_server('tcp://127.0.0.1:9999');
$clientOnClient = stream_socket_client('tcp://127.0.0.1:9999');

$clientOnServer = stream_socket_accept($server, 0.5);
var_dump(stream_set_chunk_size($clientOnServer, 1));
var_dump(stream_set_read_buffer($clientOnServer, 1));
fwrite($clientOnClient, 'ping');

//This now works as defined in documentation
var_dump(fread($clientOnServer, 2));
stream_socket_shutdown($clientOnServer, STREAM_SHUT_RD);
var_dump(fread($clientOnServer, 3));

//This should not work since buffer is empty at call
stream_socket_shutdown($clientOnServer, STREAM_SHUT_RD);
fwrite($clientOnClient, 'still-broken');
var_dump(fread($clientOnServer, 12));

//...and iterestingly it works as expected if you use RDWR or WR
stream_socket_shutdown($clientOnServer, STREAM_SHUT_WR);
fwrite($clientOnClient, 'or-is-it');
var_dump(fread($clientOnServer, 8));


Since buffer is closed and in fact event emptied why it's still receiving data on Linux? ;)

To be entirely sure I've also tested it using PHP server on the one side and telnet at the other - stream still receives data. This behavior is also present while using sockets.
<?php
$server = stream_socket_server('tcp://127.0.0.1:9999');
$clientOnServer = stream_socket_accept($server, 10);
stream_socket_shutdown($clientOnServer, STREAM_SHUT_RD);

while(1) {
  sleep(1);
  var_dump(fread($clientOnServer, 1));
}

After digging in old Linux list archives I found the suspect - in fact it's how Linux handles (or actually not handles at all) shutdown(sock, SHUT_RD): http://oss.sgi.com/archives/netdev/2003-07/msg00692.html - it's a pretty interesting discussion about this particular issue.

Maybe, since PHP is trying to be platform-independent, interpreter can unify this behavior and discard data on recv() when socket/stream was closed for reading?