Can you please tell us where in the documentation this is done wrong?

I don't think it's a documentation problem of fread().

The posted code worked fine in 4.3.1 but failed when upgrading to 4.3.2 (Win32 version).

Problem 1: fread($fp, 4096) returns max 1024 bytes.
Problem 2: fread($fp, 1024) hangs until timeout if buffer only contains 1023 bytes.

/Thomas

I too am experiencing this changed behavior. Previously, my code was as follows:

     $contents = fread ($fp, 2097152);

And that would return up to 2mb from the given socket. In my case, the socket was a fopen() url.
  
However, when I upgraded to PHP 4.3.2 it would ONLY return 2481 bytes no matter what. As a quick fix I had to move the fread() inside of a while loop, in order to fix this issue. Like this:

     $contents = "";
     while (($data = fread ($fp, 2097152)) !== "") 
     {
          $contents .= $data;
     }

The only change on my system and the files being read was my upgrading to PHP 4.3.2. This definitely appears to be changed behavior of fread().
-PJ

From the manual:

When reading from network streams or pipes, such as those returned when reading remote files or from popen() and proc_open(), reading will stop after a packet is available. This means that you should collect the data together in chunks as shown in the example below.

A bug existed in 4.3.0-1 that made it "work", so, it's not considered changed behavior, just a bug.  This bug, for example, did not exist in 4.2.3

Regarding Thomas "problem #2", not sure about that, will see what Wez has to say.

Regarding the last proposed example by PJ, just use file_get_contents().

Ok. Since I'm was not the only having the problem I examined it some more... here we goes again...

Problem #1: When using a chunk size >= 8192 bytes it's just to concatenate the data and continue reading (as examplified in the documentation). So to what I understand, this is not a bug, rather than a timing issue that fread() returns the number of bytes available at the moment? Anyway, in this case problem #2 doesn't occurs!!

Problem #2: The fread() still hangs until timeout if I try to read data in chunks of <= 4096 bytes!!

This is your loop:

  while (!feof($fp) && $length > 0) {
    $size = min(1024, $length);
    $reply .= fread($fp, $size);
    $length -= $size;
  }

It looks wrong to me, since you are not checking the return value of fread and are just assuming that it read the chunk you asked for.

This is a better loop:

while ($length > 0) {
   $size = min(8192, $length);
   $data = fread($fp, $size);
   if (strlen($data) == 0) {
       break; // EOF
   }
   $reply .= $data;
   $length -= strlen($data);
}

It is recommended that you fread() in chunks of 8kb from sockets, as you will get better performance than using a smaller value.  Using a larger value is wasteful as the streams layer will only allocate in 8KB chunks; Win32 has a maximum internal packet size of 8KB too.

I'm marking this as bogus since it is the expected behaviour of PHP (I actually spent a couple of days correcting and testing this for HTTP/1.1 keep alives).