<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Register a user defined stream filter</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.stream-filter-prepend.html">stream_filter_prepend</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.stream-filter-remove.html">stream_filter_remove</a></div>
<div class="up"><a href="ref.stream.html">Stream Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.stream-filter-register" class="refentry">
<div class="refnamediv">
<h1 class="refname">stream_filter_register</h1>
<p class="verinfo">(PHP 5)</p><p class="refpurpose"><span class="refname">stream_filter_register</span> — <span class="dc-title">Register a user defined stream filter</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.stream-filter-register-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">bool</span> <span class="methodname"><strong>stream_filter_register</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$filtername</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$classname</code></span>
)</div>
<p class="para rdfs-comment">
<span class="function"><strong>stream_filter_register()</strong></span> allows you to implement
your own filter on any registered stream used with all the other
filesystem functions (such as <span class="function"><a href="function.fopen.html" class="function">fopen()</a></span>,
<span class="function"><a href="function.fread.html" class="function">fread()</a></span> etc.).
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.stream-filter-register-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">filtername</code></em></span>
<dd>
<p class="para">
The filter name to be registered.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">classname</code></em></span>
<dd>
<p class="para">
To implement a filter, you need to define a class as an extension of
<a href="class.php-user-filter.html" class="classname">php_user_filter</a> with a number of member
functions. When performing read/write operations on the stream
to which your filter is attached, PHP will pass the data through your
filter (and any other filters attached to that stream) so that the
data may be modified as desired. You must implement the methods
exactly as described in <a href="class.php-user-filter.html" class="classname">php_user_filter</a> - doing
otherwise will lead to undefined behaviour.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.stream-filter-register-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
<p class="para">
<span class="function"><strong>stream_filter_register()</strong></span> will return <strong><code>FALSE</code></strong> if the
<em><code class="parameter">filtername</code></em> is already defined.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.stream-filter-register-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4017">
<p><strong>Example #1 Filter for capitalizing characters on <var class="filename">foo-bar.txt</var> stream</strong></p>
<div class="example-contents"><p>
The example below implements a filter named <em>strtoupper</em>
on the <var class="filename">foo-bar.txt</var> stream which will capitalize
all letter characters written to/read from that stream.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">/* Define our filter class */<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">strtoupper_filter </span><span style="color: #007700">extends </span><span style="color: #0000BB">php_user_filter </span><span style="color: #007700">{<br /> function </span><span style="color: #0000BB">filter</span><span style="color: #007700">(</span><span style="color: #0000BB">$in</span><span style="color: #007700">, </span><span style="color: #0000BB">$out</span><span style="color: #007700">, &</span><span style="color: #0000BB">$consumed</span><span style="color: #007700">, </span><span style="color: #0000BB">$closing</span><span style="color: #007700">)<br /> {<br /> while (</span><span style="color: #0000BB">$bucket </span><span style="color: #007700">= </span><span style="color: #0000BB">stream_bucket_make_writeable</span><span style="color: #007700">(</span><span style="color: #0000BB">$in</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">data </span><span style="color: #007700">= </span><span style="color: #0000BB">strtoupper</span><span style="color: #007700">(</span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">data</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$consumed </span><span style="color: #007700">+= </span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">datalen</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">stream_bucket_append</span><span style="color: #007700">(</span><span style="color: #0000BB">$out</span><span style="color: #007700">, </span><span style="color: #0000BB">$bucket</span><span style="color: #007700">);<br /> }<br /> return </span><span style="color: #0000BB">PSFS_PASS_ON</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #FF8000">/* Register our filter with PHP */<br /></span><span style="color: #0000BB">stream_filter_register</span><span style="color: #007700">(</span><span style="color: #DD0000">"strtoupper"</span><span style="color: #007700">, </span><span style="color: #DD0000">"strtoupper_filter"</span><span style="color: #007700">)<br /> or die(</span><span style="color: #DD0000">"Failed to register filter"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">"foo-bar.txt"</span><span style="color: #007700">, </span><span style="color: #DD0000">"w"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Attach the registered filter to the stream just opened */<br /></span><span style="color: #0000BB">stream_filter_append</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"strtoupper"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"Line1\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"Word - 2\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"Easy As 123\n"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Read the contents back out<br /> */<br /></span><span style="color: #0000BB">readfile</span><span style="color: #007700">(</span><span style="color: #DD0000">"foo-bar.txt"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
LINE1
WORD - 2
EASY AS 123
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-4018">
<p><strong>Example #2 Registering a generic filter class to match multiple filter names.</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">/* Define our filter class */<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">string_filter </span><span style="color: #007700">extends </span><span style="color: #0000BB">php_user_filter </span><span style="color: #007700">{<br /> var </span><span style="color: #0000BB">$mode</span><span style="color: #007700">;<br /><br /> function </span><span style="color: #0000BB">filter</span><span style="color: #007700">(</span><span style="color: #0000BB">$in</span><span style="color: #007700">, </span><span style="color: #0000BB">$out</span><span style="color: #007700">, &</span><span style="color: #0000BB">$consumed</span><span style="color: #007700">, </span><span style="color: #0000BB">$closing</span><span style="color: #007700">)<br /> {<br /> while (</span><span style="color: #0000BB">$bucket </span><span style="color: #007700">= </span><span style="color: #0000BB">stream_bucket_make_writeable</span><span style="color: #007700">(</span><span style="color: #0000BB">$in</span><span style="color: #007700">)) {<br /> if (</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">mode </span><span style="color: #007700">== </span><span style="color: #0000BB">1</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">data </span><span style="color: #007700">= </span><span style="color: #0000BB">strtoupper</span><span style="color: #007700">(</span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">data</span><span style="color: #007700">);<br /> } elseif (</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">mode </span><span style="color: #007700">== </span><span style="color: #0000BB">0</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">data </span><span style="color: #007700">= </span><span style="color: #0000BB">strtolower</span><span style="color: #007700">(</span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">data</span><span style="color: #007700">);<br /> }<br /><br /> </span><span style="color: #0000BB">$consumed </span><span style="color: #007700">+= </span><span style="color: #0000BB">$bucket</span><span style="color: #007700">-></span><span style="color: #0000BB">datalen</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">stream_bucket_append</span><span style="color: #007700">(</span><span style="color: #0000BB">$out</span><span style="color: #007700">, </span><span style="color: #0000BB">$bucket</span><span style="color: #007700">);<br /> }<br /> return </span><span style="color: #0000BB">PSFS_PASS_ON</span><span style="color: #007700">;<br /> }<br /><br /> function </span><span style="color: #0000BB">onCreate</span><span style="color: #007700">()<br /> {<br /> if (</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">filtername </span><span style="color: #007700">== </span><span style="color: #DD0000">'str.toupper'</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">mode </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /> } elseif (</span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">filtername </span><span style="color: #007700">== </span><span style="color: #DD0000">'str.tolower'</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">mode </span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br /> } else {<br /> </span><span style="color: #FF8000">/* Some other str.* filter was asked for,<br /> report failure so that PHP will keep looking */<br /> </span><span style="color: #007700">return </span><span style="color: #0000BB">false</span><span style="color: #007700">;<br /> }<br /><br /> return </span><span style="color: #0000BB">true</span><span style="color: #007700">;<br /> }<br />}<br /><br /></span><span style="color: #FF8000">/* Register our filter with PHP */<br /></span><span style="color: #0000BB">stream_filter_register</span><span style="color: #007700">(</span><span style="color: #DD0000">"str.*"</span><span style="color: #007700">, </span><span style="color: #DD0000">"string_filter"</span><span style="color: #007700">)<br /> or die(</span><span style="color: #DD0000">"Failed to register filter"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$fp </span><span style="color: #007700">= </span><span style="color: #0000BB">fopen</span><span style="color: #007700">(</span><span style="color: #DD0000">"foo-bar.txt"</span><span style="color: #007700">, </span><span style="color: #DD0000">"w"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Attach the registered filter to the stream just opened<br /> We could alternately bind to str.tolower here */<br /></span><span style="color: #0000BB">stream_filter_append</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"str.toupper"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"Line1\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"Word - 2\n"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">fwrite</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">, </span><span style="color: #DD0000">"Easy As 123\n"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$fp</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Read the contents back out<br /> */<br /></span><span style="color: #0000BB">readfile</span><span style="color: #007700">(</span><span style="color: #DD0000">"foo-bar.txt"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
LINE1
WORD - 2
EASY AS 123
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.stream-filter-register-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.stream-wrapper-register.html" class="function" rel="rdfs-seeAlso">stream_wrapper_register()</a> - Register a URL wrapper implemented as a PHP class</span></li>
<li class="member"> <span class="function"><a href="function.stream-filter-append.html" class="function" rel="rdfs-seeAlso">stream_filter_append()</a> - Attach a filter to a stream</span></li>
<li class="member"> <span class="function"><a href="function.stream-filter-prepend.html" class="function" rel="rdfs-seeAlso">stream_filter_prepend()</a> - Attach a filter to a stream</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.stream-filter-prepend.html">stream_filter_prepend</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.stream-filter-remove.html">stream_filter_remove</a></div>
<div class="up"><a href="ref.stream.html">Stream Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
