> instead of loading the whole result into memory at once
is not the full truth.
There is a certain risk of processes getting killed due to memory allocation with large iteration. This is caused by result buffering of the client not being visible to PHP and thus not from 'within' the process.
It is not certain that this occurs with all database clients but seems rather likely to at this point.
This is only a proposal for discussion as I am not certain how to best add the information or if to add it at all (was it obvious before?). Personally I got confused by the existing description and didn't notice the memory implication until further investigation using `top` reported the process to run at 3+GB memory while PHP reported 400M real peak usage.
If you have only $batchSize - 1 rows (amongst other cases), the entities are never flushed, you need a final flush outside the loop.
In the bulk insert you should also need a final flush if the number of entities inserted is not a multiple of the $batchSize.
