In PHP, why is fopen($path, 'w') followed by flock() the wrong way to update a shared file, and what is the correct sequence?

## What flock() gives you `flock($stream, $operation, &$would_block = null): bool` locks the **whole file** behind an open handle: | Operation | Meaning | |---|---| | `LOCK_SH` | shared lock: many readers may hold it together | | `LOCK_EX` | exclusive lock: one writer, no readers holding `LOCK_SH` | | `LOCK_UN` | release whatever lock this handle holds | | `… \| LOCK_NB` | do not wait; return `false` at once, setting `$would_block` to `1` if the lock is held elsewhere | By default `flock()` **blocks** until the lock is granted. The lock is also released by `fclose()`, when the handle is garbage collected, and therefore at the end of the request. The lock is **advisory**: it only coordinates processes that also call `flock()`. A process that opens the file and writes without locking is not stopped, and `file_get_contents()` never takes a lock. The manual adds platform notes: on Windows the lock is mandatory, flock is unsupported on old FAT file systems, and in a multithreaded server API it may not protect against other threads of the same process. ## Why 'w' then flock() loses data The order of operations is the whole bug: 1. `fopen($path, 'w')` opens **and truncates** the file to zero bytes. 2. `flock($h, LOCK_EX)` waits for the lock. 3. You write the new content. Step 1 has already destroyed the old content, without holding any lock. Consequences: - A reader that holds `LOCK_SH` and is halfway through the file suddenly reads an empty file. - A second writer doing read-modify-write (a counter, a JSON state file) opens with `'w'`, wipes the file, and then waits for the first writer; when it finally reads, there is nothing to read, and its update is built on nothing. - If the script dies between steps 1 and 3, the file stays empty. The manual says it directly: `'c'` exists because `'w'` "could truncate the file before the lock was obtained", and `ftruncate()` can be used after the lock is taken if truncation is wanted. ## The correct sequence ```php <?php declare(strict_types=1); $h = fopen('/var/app/counter.txt', 'c+'); if ($h === false || !flock($h, LOCK_EX)) { throw new RuntimeException('cannot lock counter'); } $count = (int) stream_get_contents($h); ftruncate($h, 0); rewind($h); fwrite($h, (string) ($count + 1)); fflush($h); flock($h, LOCK_UN); fclose($h); ``` Step by step: 1. **`'c+'`** creates the file if needed, keeps its content, allows reading and writing, and starts at offset 0. 2. **`LOCK_EX`** before touching the content, so no other cooperating process is inside. 3. **Read** the current value. 4. **`ftruncate($h, 0)`** empties the file; it does not move the pointer, so **`rewind($h)`** is needed or the write lands at the old offset and leaves a hole. 5. **`fflush($h)`** pushes pending output before the lock is dropped, as in the manual's own example. 6. **`LOCK_UN`**, then `fclose()`. Readers use the mirror image: open with `'r'`, `flock($h, LOCK_SH)`, read, release. ## What file_put_contents(..., LOCK_EX) does `file_put_contents($path, $data, LOCK_EX)` follows the same safe order internally: without `FILE_APPEND` it opens in `'c'` mode, takes `LOCK_EX`, **then** truncates and writes, and closes (releasing the lock). It refuses `LOCK_EX`, with a warning, on streams that cannot be locked, such as a non-`file://` wrapper. It is a good fit for "replace the whole file under a lock", but it cannot read the old value first, so read-modify-write still needs the handle sequence above. ## Mistakes around the lock itself - **Ignoring the return value.** `flock()` returns `false` on failure (for example on a file system without lock support); carrying on as if locked silently removes the protection. - **Slow work inside the lock.** Every other writer waits while you hold `LOCK_EX`; do network calls or heavy computation before taking the lock, and keep the locked section to read, compute, write. - **Releasing before flushing.** Unlocking first lets another process read before your bytes are handed to the operating system. - **Relying on the end of the request.** The lock does go away when the handle closes, but an explicit `LOCK_UN` or `fclose()` shortens the time others wait. ## Limits to know - Locks are per file, not per byte range. - A crash inside the locked section can still leave a half-written file; for a whole-file replacement, writing to a temporary file and moving it into place avoids that. - On network file systems, lock behaviour depends on the server; test it rather than assume it.