This is not a documentation problem; the documentation actually says TWICE that this should NOT be happening. Here's the second place:
>This works as expected, because when PHP hits the ?> closing tags, it simply starts outputting whatever it finds until it hits another opening tag

This bug involving LOSS OF DATA. That is serious IMHO; second only to crashes.

I have reproduced this in PHP 4.3.2-RC (cli) (built: Apr 25 2003 18:03:38) and also in apache module.

-- a simpler example script:
line1 <?php ?>
line2
-- output:
line1 line2

IMHO the docs are not misleading. The doc says: "The 
closing tag for the block will include the immediately trailing 
newline if one is present." Note the words "will include". 
 
After this, the docs says (what you also quoted): "This works 
as expected, because when PHP hits the ?> closing tags, it 
simply starts outputting whatever it finds until it hits another 
opening tag." 
 
Which is perfectly OK, if you read again the text above. The 
closing ?> includes the trailing newline. So everything after 
the closing ?> is output (not including the trailing newline, as it 
is included in the closing tag itself). 
 
Why this makes sense? PHP is a web scripting language (or it 
is fucused on web scripting). Conside that you have an 
include file "common.inc", and it is closed with a PHP closing 
tag ?>. You include this file from some index.php expecting it 
to provide some defined functions, and output a header() in 
index.php before doing anything. 
 
You won't succeed in outputting the header() if the newline 
after the ?> closing tag is treated as output, as there would be 
some output, and then headers cannot be sent. 
 
This is the expected behaviour, it won't be changed I can 
assure you, and it is documented. The docs says "...the 
closing tag includes the newline..." and "...after the closing 
tag...", this implies that "...after the newline if it is present after 
?>..." isn't it? 

I very much would like this reconsidered, for a number of reasons, including documentation and functionality.

Granted, the documentation does say "will include," but in combination with other statements it's simply not clear.  If this behavior is vital that it must remain, perhaps another look at this would avoid others opening bug reports.

More importantly, however, is the fact that this behavior occurs at all.  Yes, PHP is primarily a web scripting language, but even in this vein of usage, there's no reason for this.

First, included files generally don't contain trailing newlines.  For example, in your text editor of choice, going to the end of the document, placing the cursor directly after ?> and deleting everything to the right, you will not end up with any trailing newlines.  So, is this behavior in place to simply allow one newline, but not more than one?  Simply, there either is a character after the closing tag, or there isn't.

Secondly, and most importantly, is that this shouldn't even be an issue.  Included files shouldn't even contain a closing tag, for these exact reasons.  PHP will end parsing at an end-of-file and placing a closing tag will only cause problems with header() calls, etc. as pointed out.

Lastly, if this behavior is vital enough to keep, I hope that a consideration for CLI usage can be made.  Ambigously keeping a newline after a closing tag makes even less sense on the console.  At the very least, if PHP is compiled as a CLI, can this behavior can be eliminated?

Thank you,

Hans

"Included files shouldn't even contain a closing tag, for these exact reasons."

This is excellent advice, but it is *not* a documented practice. All of the examples in the Basic Syntax documentation include closing tags. 

In fact, the documentation for include() says:

"... any code inside the target file which should be executed as PHP code must be enclosed within valid PHP start and end tags."

I agree wholeheartedly that both the documentation and the behavior should be changed, but to do so is to risk breaking a lot of existing code.

I think it would be useful to have the option to negate this feature, perhaps with a modified end tag (\?> or something?). That way it would still be backwards-compatible.

I agree.  Now that the CLI interface has matured it's in fairly widespread use.  I use CLI continually and this "feature" is a royal pain.  Perhaps when running in CLI mode this behavior could be automatically disabled... this would be a much appreciated change.

Or, a special tag as suggested:

<?+
<?-

I would think putting something like this into PHP 5 wouldn't disrupt things.

Can not be fixed, as it breaks existing scripts.

How would it break existing scripts?  Firstly, CLI scripts aren't that common yet, and especially those that rely on this type of behavior.  Secondly, what if it was a config setting, available only when running as a CLI (akin to argv/argc).  When working with scripts on the console for interactive programs, or using a CLI script to generate raw XML for instance, this type of newline mangle makes no sense and is cause for very hackish scripts.

Heeeeeeeeeeeeeeyyy!!!
Wake UP! It wouldn't break ANY script if it was optional in the php.ini file!!!!  As I wrote to derick:

Are the PHP developers getting too lazy to improve PHP a bit?

Making a setting in php.ini would make writing portable scripts harder, so that's a no-go too.

Sorry but still I don't understand, why some new option in php.ini "would make writing portable scripts harder", if the default option would make PHP behave the SAME way as so far, that means (in this case), removing (\r)\n after ?>, and the second option would make it leave it there.  Or, if it's really true, why have we the options like arg_separator.input and magic_quotes_gpc then?  What's so hard in writing portable scripts like now and leaving this option with the default falue, while other people, using PHP for e.g. nice-formatted HTML, C++ code, ASCII, or XML, would change it? ... Doesn't make a sense...

I need an explanation on this claim: "Making a setting in php.ini would make writing portable scripts harder, so that's a no-go too."

It doesn't seem to have a valid sense.

Because working scripts may break if you change this behaviour in your php.ini 
file.  That means people trying to write portable code would have to check the 
.ini setting which in turn means it becomes harder to write portable code.

And by breaking I mean things that send out headers as the first output.  These 
would break if suddenly newlines started appearing that didn't appear before.  So 
no, this will not change and we won't add a php.ini switch for it either.