Mutually exclusive flags on file_put_contents?

Question

On the file_put_contents() documentation, it says the following:

FILE_APPEND:

Mutually exclusive with LOCK_EX since appends are atomic and thus there is no reason to lock.

LOCK_EX:

Mutually exclusive with FILE_APPEND.

Yet, a couple of lines bellow I see the following code:

<?php
$file = 'people.txt';
// The new person to add to the file
$person = "John Smith\n";
// Write the contents to the file, 
// using the FILE_APPEND flag to append the content to the end of the file
// and the LOCK_EX flag to prevent anyone else writing to the file at the same time
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>

So, are the FILE_APPEND and LOCK_EX flags mutually exclusive or not? If yes, why do they use it in the example? Is this a case of bad documentation?

Thanks for your input!

Answer 1

That's just bad documentation. The manual clearly states:

FILE_APPEND : If file filename already exists, append the data to the file instead of overwriting it. Mutually exclusive with LOCK_EX since appends are atomic and thus there is no reason to lock.

LOCK_EX : Acquire an exclusive lock on the file while proceeding to the writing. Mutually exclusive with FILE_APPEND.

And the example you speak of:

<?php
$file = 'people.txt';
// The new person to add to the file
$person = "John Smith\n";
// Write the contents to the file, 
// using the FILE_APPEND flag to append the content to the end of the file
// and the LOCK_EX flag to prevent anyone else writing to the file at the same time
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>

It looks like the person who coded the example misunderstood the meaning of 'mutually exclusive', or that produces some secret, undocumented bahaviour.

Answer 2

Like @karim79 said, this was an error in the manual : see bug #49329, which I reported after seeing this question/answer, and has been corrected/closed a couple of minutes ago.

(It will take some time to be reflected in the online version of the manual, but ahs been corrected in its sources)