In PHP, what do memory_get_usage() and memory_get_peak_usage() report, and what does passing true for $real_usage change?

## The four numbers PHP's memory manager requests memory from the operating system in large **chunks** and carves them into small blocks for strings, arrays and objects. The two functions expose both levels: | Call | Reports | |---|---| | `memory_get_usage()` | bytes currently allocated to the script's values | | `memory_get_usage(true)` | bytes currently reserved from the system by the manager | | `memory_get_peak_usage()` | highest value of the first figure so far | | `memory_get_peak_usage(true)` | highest value of the second figure so far | Both have the signature `(bool $real_usage = false): int` and return bytes. ## Which one to read - **Tracking your own data**: use the default (`false`). It rises when you build an array and falls when you `unset()` it, so it is the right number for "how much does this step keep?" - **Explaining a memory-limit error**: use `true`. The manual states that the reserved figure is what `memory_limit` is enforced against. It moves in steps of whole chunks, and freed space inside a chunk still counts until the manager returns the chunk. - **Reporting the cost of a job**: use `memory_get_peak_usage()` at the end. A job that peaks at 900 MB but ends at 20 MB still needed 900 MB. ## Peaks and resets Before PHP 8.2, the peak could only rise, so measuring the peak of one phase of a long script meant subtracting guesses. PHP 8.2 added `memory_reset_peak_usage()`: ```php memory_reset_peak_usage(); importBatch($rows); $batchPeak = memory_get_peak_usage(); ``` That measures one phase in isolation, which is useful in workers and long CLI jobs. ## What the numbers do not include 1. **Memory allocated outside PHP's manager.** The manual notes that persistent allocations and memory an extension takes directly with the system allocator are not reported, even with `$real_usage = true`. Some libraries do exactly that. 2. **The PHP binary, shared libraries and shared memory**, such as OPcache's segment. The operating system counts them in the process size; PHP's functions do not. 3. **Memory already returned to the system.** Chunks the manager frees go back to the OS, but the OS may report them lazily. This is why the resident size shown by `top` or a container dashboard is normally much larger than `memory_get_usage(true)`, and why the two can move independently. ## Why usage often does not fall after unset() `unset($bigArray)` lowers `memory_get_usage()` immediately if nothing else references the array. The `true` figure may not move: the freed blocks sit inside chunks that still hold other data, so the manager keeps the chunks. `gc_mem_caches()` asks the manager to release cached memory it no longer needs and returns the number of bytes freed; it is rarely necessary outside long-running processes. ## Common misreadings | Observation | What it actually means | |---|---| | `memory_get_usage()` is far below `memory_limit`, yet the limit error fires | the limit is checked on the reserved figure, which can be much higher than the allocated one | | the reserved figure never goes down during a job | chunks are kept while any part is in use, or cached for reuse | | the container kills the process while PHP reports little | memory outside PHP's allocator, plus the binary and shared memory, is counted by the OS only | | the peak is huge but usage at the end is small | a temporary structure existed at some point; find it with a peak reset around each phase | Reading the right figure avoids chasing the wrong problem: allocated usage answers "what does my data cost", reserved usage and its peak answer "why did the limit fire". ## A measuring habit Inside a loop over many records, log both figures every few thousand iterations: ```php if ($i % 10_000 === 0) { error_log(sprintf('%d rows, %.1f MB used, %.1f MB reserved', $i, memory_get_usage() / 1048576, memory_get_usage(true) / 1048576)); } ``` A flat line means the loop releases what it uses; a steady staircase means something retains data per iteration — the first thing to find before touching `memory_limit`.