A php_user_filter subclass is installed with stream_filter_register() and processes data in buckets.
What Is php_user_filter::filter in PHP?
php_user_filter::filter() is a lifecycle method implemented in a custom stream filter class.
php_user_filter::filter($in, $out, $consumed, bool $closing)Parameters:
$in— Required. The in argument used to configure this operation; its accepted values follow the declared PHP type.$out— Required. The out argument used to configure this operation; its accepted values follow the declared PHP type.$consumed— Required. The consumed argument used to configure this operation; its accepted values follow the declared PHP type.$closing— Required. The closing argument used to configure this operation; its accepted values follow the declared PHP type.
Example 1: Understanding the Basic Behavior
<?php
class UppercaseFilter extends php_user_filter {
public function onCreate(): bool { return true; }
public function filter($input, $output, &$consumed, bool $closing): int {
while ($bucket = stream_bucket_make_writeable($input)) {
$consumed += $bucket->datalen;
$bucket->data = strtoupper($bucket->data);
stream_bucket_append($output, $bucket);
}
return PSFS_PASS_ON;
}
public function onClose(): void { }
}
stream_filter_register("guide.upper.0", UppercaseFilter::class);
$stream = fopen("php://temp", "w+");
stream_filter_append($stream, "guide.upper.0", STREAM_FILTER_WRITE);
fwrite($stream, "Hello world");
rewind($stream);
echo stream_get_contents($stream);
fclose($stream);Output:
HELLO WORLDExplanation: php_user_filter::filter() is a lifecycle method implemented in a custom stream filter class.
Example 2: Testing Another Case
<?php
class UppercaseFilter extends php_user_filter {
public function onCreate(): bool { return true; }
public function filter($input, $output, &$consumed, bool $closing): int {
while ($bucket = stream_bucket_make_writeable($input)) {
$consumed += $bucket->datalen;
$bucket->data = strtoupper($bucket->data);
stream_bucket_append($output, $bucket);
}
return PSFS_PASS_ON;
}
public function onClose(): void { }
}
stream_filter_register("guide.upper.1", UppercaseFilter::class);
$stream = fopen("php://temp", "w+");
stream_filter_append($stream, "guide.upper.1", STREAM_FILTER_WRITE);
fwrite($stream, "Hello world");
rewind($stream);
echo stream_get_contents($stream);
fclose($stream);Output:
HELLO WORLDExplanation: filter() processes brigade buckets, onCreate() is called during filter initialization, and onClose() runs when the filter is removed or its stream is closed.
Practical Example: Applying the Operation
<?php
class UppercaseFilter extends php_user_filter {
public function onCreate(): bool { return true; }
public function filter($input, $output, &$consumed, bool $closing): int {
while ($bucket = stream_bucket_make_writeable($input)) {
$consumed += $bucket->datalen;
$bucket->data = strtoupper($bucket->data);
stream_bucket_append($output, $bucket);
}
return PSFS_PASS_ON;
}
public function onClose(): void { }
}
stream_filter_register("guide.upper.2", UppercaseFilter::class);
$stream = fopen("php://temp", "w+");
stream_filter_append($stream, "guide.upper.2", STREAM_FILTER_WRITE);
fwrite($stream, "Hello world");
rewind($stream);
echo stream_get_contents($stream);
fclose($stream);Output:
HELLO WORLDExplanation: filter() must update the consumed-byte counter and move processed buckets to the output brigade.
Important Behavior and Edge Cases
- filter() processes brigade buckets, onCreate() is called during filter initialization, and onClose() runs when the filter is removed or its stream is closed.
- filter() must update the consumed-byte counter and move processed buckets to the output brigade.
Comparison With Related Approaches
| Approach | When to Use It |
|---|---|
php_user_filter::filter | php_user_filter::filter() is a lifecycle method implemented in a custom stream filter class. |
stream_filter_register() | stream_filter_append() attaches a filter to a stream, while the filter class controls how bytes are transformed. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
| Invoking a stream-filter lifecycle method directly instead of installing a filter on a stream. | filter() processes brigade buckets, onCreate() is called during filter initialization, and onClose() runs when the filter is removed or its stream is closed. |
| Choosing stream_filter_register() without checking whether it provides the same result. | stream_filter_append() attaches a filter to a stream, while the filter class controls how bytes are transformed. |
Key Takeaways
- php_user_filter::filter() is a lifecycle method implemented in a custom stream filter class.
- filter() processes brigade buckets, onCreate() is called during filter initialization, and onClose() runs when the filter is removed or its stream is closed.
- filter() must update the consumed-byte counter and move processed buckets to the output brigade.
The examples demonstrate where php_user_filter::filter fits within custom stream filters. Verify the relevant preconditions whenever you adapt the code to real data.