Bug #51933 [Opn->Csd]: file_put_contents(...,FILE_APPEND|LOCK_EX) wrongly documented

Edit report at http://bugs.php.net/bug.php?id=51933&edit=1 ID: 51933 Updated by: cataphract@php.net Reported by: dxjones at gmail dot com Summary: file_put_contents(...,FILE_APPEND|LOCK_EX) wrongly documented -Status: Open +Status: Closed Type: Bug Package: Documentation problem Operating System: ALL PHP Version: Irrelevant -Assigned To: +Assigned To: cataphract Block user comment: N New Comment: I fixed this a while back. See bug #52767. Previous Comments: ------------------------------------------------------------------------ [2010-05-27 19:09:21] dxjones at gmail dot com Description: ------------ This is a bug in the PHP documentation. I verified the bug using PHP 5.2.10, but the problem is not in the code; it is in the description. The doc INCORRECTLY states that FILE_APPEND and LOCK_EX are "mutually exclusive". This is just plain false. It also says something wonky about appends being atomic. Here is what I did to demonstrate the error. 1. I create a script "race.php" that appends to a file "race.csv" 2. The key line is: file_put_contents('race.csv', $s, FILE_APPEND); 3. I use a tool "Jakarta" to generate a large amount of traffic (5000 fetches in just a few seconds). 3. When I look at the output file, there are fewer than 5000 lines. 4. I repeat the same experiment with a flag to use this key line: file_put_contents('race-lock.csv', $s, FILE_APPEND|LOCK_EX); 5. The output file has exactly 5000 lines. This proves there is an error in the documentation. Goodness knows how much damage this error has caused. For me, there were corrupted log files in several large online applications. The error only manifests when there is heavy traffic and multiple PHP processes trying to append to the same file at the same time. The documentation falsely instructs developers *NOT* to use "FILE_APPEND|LOCK_EX". There was even a correct code example in late 2009 that included "FILE_APPEND|LOCK_EX". Rather than fix the documentation, they CHANGED THE EXAMPLE (!) to remove "LOCK_EX". Sigh. Please fix this. Test script: --------------- <? // race.php // you will only see the error if you hit this script many times in a brief period // so there are multiple PHP processes trying to append to the same file at the same time // The PHP documentation FALSELY says you can't combine "FILE_APPEND|LOCK_EX" // Call this script 5000 times within just a few seconds, see if you get 5000 lines of output -- without LOCK_EX, you will LOSE DATA!! $t = microtime(TRUE); $alpha = array('A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J'); $r = rand(0,9); $w = ''; for ($i = 0 ; $i < 20 ; ++$i) { $w .= $alpha[$r]; } $row = array( $alpha[$r] ); $row[]= sprintf('%.9f', $t); for ($i = 0 ; $i < 64 ; ++$i) { $row[] = $w . sprintf('%02d',$i); } $row[] = $alpha[$r]; $row[] = sprintf('%.9f', microtime(TRUE) - $t); $s = implode(',',$row) . "\n"; if (array_key_exists('reset', $_REQUEST)) { system('rm -f race.csv race-lock.csv'); } elseif (array_key_exists('lock', $_REQUEST)) { file_put_contents('race-lock.csv', $s, FILE_APPEND | LOCK_EX); } else { file_put_contents('race.csv', $s, FILE_APPEND); } ?> <html><head><title>race</title></head><body><h1>race</h1></body></html> Expected result: ---------------- look inside the output files: race.csv -- expect to have exactly 5000 lines, but might have fewer than 5000 lines because of error in documentation race-lock.csv -- will have exactly 5000 lines because FILE_APPEND|LOCK_EX is used Actual result: -------------- race.csv -- has fewer than 5000 lines because of error ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/bug.php?id=51933&edit=1