From 23bec26ba258bfe138bd0a91edf1b344b1416de8 Mon Sep 17 00:00:00 2001 From: Sara Golemon Date: Fri, 4 Apr 2003 00:56:29 +0000 Subject: [PATCH] Redocument Userfilters after rewrite git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@122458 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/stream/constants.xml | 22 ++- .../functions/stream-register-filter.xml | 145 ++++++------------ 2 files changed, 66 insertions(+), 101 deletions(-) diff --git a/reference/stream/constants.xml b/reference/stream/constants.xml index 262a0496a4..54e9ffec48 100644 --- a/reference/stream/constants.xml +++ b/reference/stream/constants.xml @@ -1,5 +1,5 @@ - +
&reftitle.constants; &extension.constants; @@ -39,6 +39,26 @@ STREAM_FILTER_WRITE + + PSFS_PASS_ON + Return Code indicating that the + userspace filter returned buckets in $out. + + + + PSFS_FEED_ME + Return Code indicating that the + userspace filter did not return buckets in $out + (i.e. No data available). + + + + PSFS_ERR_FATAL + Return Code indicating that the + userspace filter encountered an unrecoverable error + (i.e. Invalid data received). + + STREAM_USE_PATH Flag indicating if the stream diff --git a/reference/stream/functions/stream-register-filter.xml b/reference/stream/functions/stream-register-filter.xml index 0097819935..db7e243111 100644 --- a/reference/stream/functions/stream-register-filter.xml +++ b/reference/stream/functions/stream-register-filter.xml @@ -1,5 +1,5 @@ - + stream_register_filter @@ -34,75 +34,33 @@ - intwrite - stringdata + intfilter + resourcein + resourceout + int&consumed + booleanclosing - This method is called whenever data is written to the attached - stream (such as with fwrite). After - modifying data as needed your - filter should issue: return parent::write($data); - so that the next filter in the chain can perform its filter. - When no filters remain, the stream will write data - in its final form. - - - If your filter alters the length of data, for - example by removing the first character, before passing onto - parent::write($data); it must be certain to include - that stolen character in the return count. - - - - - - - - - - - stringread - intmaxlength - - - This method is called whenever data is read from the attached - stream (such as with fread). A filter - should first call parent::read($maxlength); to - retrieve the data from the previous filter who, ultimately, - retrieved it from the stream. Your filter may then modify the - data as needed and return it. - Your filter should never return more than maxlength - bytes. Since parent::read($maxlength); will also - not return more than maxlength bytes this - will ordinarily be a non-issue. However, if your filter - increases the size of the data being returned, you should either - call parent::read($maxlength-$x); where - x is the most your filter will grow - the size of the data read. Alternatively, you can build a - read-buffer into your class. - - - - intflush - boolclosing - - - This method is called in response to a request to flush the - attached stream (such as with fflush or - fclose). The closing - parameter tells you whether the stream is, in fact, in the - process of closing. The default action is to simply call: - return parent::flush($closing); , your - filter may wish to perform additional writes and/or cleanup - calls prior to or directly after a successful flush. + This method is called whenever data is read from or written to + the attached stream (such as with fread or fwrite). + in is a resource pointing to a bucket brigade + which contains one or more bucket objects containing data to be filtered. + out is a resource pointing to a second bucket brigade + into which your modified buckets should be placed. + consumed, which must always + be declared by reference, should be incremented by the length of the data + which your filter reads in and alters. In most cases this means you will + increment consumed by $bucket->datalen for each $bucket. + If the stream is in the process of closing (and therefore this is the last pass + through the filterchain), the closing parameter will be + set to &TRUE; The filter method must return one of + three values upon completion. PSFS_PASS_ON indicates + success with data available in the out bucket brigade. + PSFS_FEED_ME indicates that the filter has no data + available to return and requires additional data from the stream. + PSFS_ERR_FATAL indicates that the filter experienced an + unrecoverable error and cannot continue. If no value is returned by this method, + PSFS_ERR_FATAL will be assumed. @@ -128,47 +86,36 @@ class myfilter extends php_user_filter { - The example below implements a filter named rot13 - on the foo-bar.txt stream which will perform - ROT-13 encryption on all letter characters written to/read from - that stream. + The example below implements a filter named strtoupper + on the foo-bar.txt stream which will capitalize + all letter characters written to/read from that stream. - Filter for ROT13 encoding data on foo-bar.txt stream + Filter for capitalizing characters on foo-bar.txt stream = 'A' AND $tempstr[$i] <= 'M') OR - ($tempstr[$i] >= 'a' AND $tempstr[$i] <= 'm')) $tempstr[$i] = chr(ord($tempstr[$i]) + 13); - else if (($tempstr[$i] >= 'N' AND $tempstr[$i] <= 'Z') OR - ($tempstr[$i] >= 'n' AND $tempstr[$i] <= 'z')) $tempstr[$i] = chr(ord($tempstr[$i]) - 13); - return $tempstr; +class strtoupper_filter extends php_user_filter { + function filter($in, $out, &$consumed, $closing) { + while ($bucket = stream_bucket_make_writeable($in)) { + $bucket->data = strtoupper($bucket->data); + $consumed += $bucket->datalen; + stream_bucket_append($out, $bucket); + } + return PSFS_PASS_ON; } - - function write($data) { - for($i = 0; $i < strlen($data); $i++) - if (($data[$i] >= 'A' AND $data[$i] <= 'M') OR - ($data[$i] >= 'a' AND $data[$i] <= 'm')) $data[$i] = chr(ord($data[$i]) + 13); - else if (($data[$i] >= 'N' AND $data[$i] <= 'Z') OR - ($data[$i] >= 'n' AND $data[$i] <= 'z')) $data[$i] = chr(ord($data[$i]) - 13); - return parent::write($data); - } -} +} /* Register our filter with PHP */ -stream_register_filter("rot13", "rot13_filter") +stream_register_filter("strtoupper", "strtoupper_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); /* Attach the registered filter to the stream just opened */ -stream_filter_append($fp, "rot13"); +stream_filter_append($fp, "strtoupper"); fwrite($fp, "Line1\n"); fwrite($fp, "Word - 2\n"); @@ -176,18 +123,16 @@ fwrite($fp, "Easy As 123\n"); fclose($fp); -/* The filter only applies to the $fp stream - * so this readfile will read -without- applying - * a second pass of rot13 encoding +/* Read the contents back out */ readfile("foo-bar.txt"); /* Output * ------ -Yvar1 -Jbeq - 2 -Rnfl Nf 123 +LINE1 +WORD - 2 +EASY AS 123 */ ?>