Description:
------------
The memory_limit configuration parameter is poorly documented.  There's no information on just what uses memory.

In particular, earlier versions of php read the entireity of uploaded files into memory.  (See bug 17606.)  If you do a bug search on "memory_limit" you will find quite a number of people have reported problems trying to upload large files and very often it seems likely that the problem was their memory_limit was set too low.  This is a big problem as there are a likely a large number of people out there useing versions of php where memory_limit limits file upload size.

Minimally, the documentation on memory_limit should mention it's relationship to file upload size _and_ the documentation on upload_max_size should refer you to the memory_limit documentation.  (Or maybe the reverse as it's increasing the upload size that causes memory problems.)  

Really, there should be an explaination of what uses memory in what versions of PHP so people can correctly configure their machines.

post_max_size does mention memory_limit.

Finally, it's worth noteing somewhere that when php runs out of memory the webserver hangs and must be stopped and restarted.  (
Linux <snip> 2.4.20-18.7 #1 Thu May 29 06:51:53 EDT 2003 i686 unknown
Red Hat Linux release 7.3 (Valhalla)
php-4.1.2-7.3.6
apache-1.3.27-2
)
(As you may have guessed, it was quite a hassle tracking down the cause of the every-other-month webserver hang.)