php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #42660 ob_start(): documentation of chunk_size param is inaccurate
Submitted: 2007-09-13 15:48 UTC Modified: 2007-11-21 16:54 UTC
From: robin_fernandes at uk dot ibm dot com Assigned:
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS: N/A
Private report: No CVE-ID: None
 [2007-09-13 15:48 UTC] robin_fernandes at uk dot ibm dot com
Description:
------------
The manual for ob_start() provides the following description for the chunk_size parameter:

"If the optional parameter chunk_size is passed, the callback function is called on every first newline after chunk_size bytes of output. Default value 0 means that the function is called only in the end, other special value 1 sets chunk_size to 4096."

I believe There are two problems with that statement.

1. Passing the chunk_size does not just cause the callback function to be called. It causes a flush of the buffer, which will in turn trigger the callback function, if one is available.
This is important, since the documentation explains how it is possible to set a chunk_size and erase flag without a callback function by providing null as the first argument.

2. The flush does not occur "on every first newline after chunk_size bytes". It occurs after any append to the buffer which has caused the buffer length to equal or exceed the chunk_size. Newlines are not treated differently from other characters.
Evidence for this is in the code in output.c in php_ob_append():

  if (OG(active_ob_buffer).chunk_size
    && OG(active_ob_buffer).text_length >= OG(active_ob_buffer).chunk_size) {
      php_end_ob_buffer(1, 1 TSRMLS_CC);
      return;
  }
	

So, I think the statement should read:

If the optional parameter chunk_size is passed, the buffer will be flushed after any output call which causes the buffer's length to equal or exceed chunk_size.
There are two special values:
  0 (default value): the buffer is flushed only when explicitly called for (for example with ob_flush()) or at the end of the request.
  1: equivalent to setting chunk_size to 4096.
Note that flushing the buffer will trigger the callback function, if it is available.

Reproduce code:
---------------
Here is a test demonstrating that a buffer is flushed after an output call causes its length to equal or exceed chunk_size, and that this is not dependent on the occurrence of new lines:
http://pastebin.com/f46cbdf76

Expected result:
----------------
N/A

Actual result:
--------------
N/A

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2007-11-21 16:54 UTC] vrana@php.net
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.

"If the optional parameter chunk_size is passed, the buffer will be flushed after any output call which causes the buffer's length to equal or exceed chunk_size."
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sun Dec 01 20:01:29 2024 UTC