RFC for Post Parse Extension

I hope this isn't a little overkill but any feedback on this would be appreciated. --------------------------- Post Parse PECL extension --------------------------- (name is still work in progress) Table of Contents: 1.0 Purpose 1.1 History 1.2 Advantages 1.3 Dis-Advantages 2.0 PHP API 2.1 Runtime Options/Configurations 2.2 Functions 3.0 Example usage 1.0 Purpose To Produce a userland method of handling uploaded files. 1.1 History Presently, php handles uploads by reading all input from the SAPI before any php code is executed. There have been a few attempts to integerate some userland callbacks within the core of php without success. This PECL extension is an attempt to avoid callbacks from within the core of php and to provide a means to for php scripts for processing file uploads from a client. 1.2 Advantages - Allows PHP programmers to make decisions on whether or not to accept a paticular upload(s), without wasting bandwidth. * Athentication before upload. * Find Magic header in file to determain actual file contents. * Ability to distinguish and limit size of POST vs. File upload seperatly. * Encrypt data directly to disk. - Allows PHP programmers to provide progress of uploads (although this should be the clients job!) 1.3 Dis-Advantage - Required minimal PHP core hacking. Perhaps a php.ini setting that tells php not to parse any post data via the sapi. On the other hand this option would enable people to use the php://stdin wrapper to parse out the post data themselves as well. 2.0 PHP API 2.1 Runtime Options/configurations auto_register_post - If this is set $_POST will be be automatically set when a variable is being read and postparse_eof() wont return at that point. 2.2 Functions proto mixed postparse_init(int $options) Initialze internal variables and returns resource if there is POST data to read in. Other wise false. proto int postparse_eof(resource handle, array &$headers) returns: POSTPARSE_EOF - (0) No more data to read POSTPARSE_VARIABLE - (1) A variable is about to be read POSTPARSE_FILE - (2) A file will be $headers will contain: $headers['name'] == Name of variable that will be read. - file uploads only - $headers['file'] == File name client sent $headers['content-type'] == Content-Type client sent. proto int postparse_read(resource $handle, int $bufsize, string $buffer) Reads bufsize (or end of data) from input. Sets $buffer to the buffer read. Returns number of bytes read. proto int postparse_write(resource $handle, resource $fp, int $bufsize) Writes directly to a valid file resource $bufize number of bytes. Returns number of bytes written. proto bool postparse_close(resource) Closes and releases all data related to resouces. 3.0 Example /* * Set up the environment and checks to see if multipart/form * exists. */ $pph = postparse_init(); if ( $pph) { /* * POST data has been sent from client */ while (! $rc = postparse_eof($pph) ) { switch ($rc) { case POSTPARSE_VARIABLE: /* * if no limit is desired for size of value * a loop would be more appropriate */ postparse_read($pph, 1024, $value); break; case POSTPARSE_FILE: $tmpname = tempnam('/tmp'); $fp = fopen($tmpname, 'w'); while ($bread = postparse_read($pph, 1024, $buf) ) { fwrite($fp, $buf); } flcose($fp); break; } } postparse_close($pph); } Curt -- "I used to think I was indecisive, but now I'm not so sure."