Signatur
Beschreibung
stream_set_chunk_size legt fest, in wie großen Blöcken (Chunks) Daten von einem Stream gelesen werden. Die Chunk-Größe beeinflusst, wie viele Bytes PHP intern puffert, bevor stream_filter_append-Filter oder ähnliche Mechanismen auf die Daten angewendet werden.
Diese Funktion ist besonders dann nützlich, wenn eigene Stream-Filter implementiert werden (über php_user_filter), da die gewählte Chunk-Größe direkt bestimmt, wie viele Daten auf einmal an die filter()-Methode des Filters übergeben werden. Eine kleinere Chunk-Größe führt zu häufigeren Filter-Aufrufen, eine größere Chunk-Größe reduziert den Overhead, kann aber zu höherem Speicherbedarf führen.
Der Standardwert der Chunk-Größe beträgt in der Regel 8192 Bytes (8 KB). Bei der Verarbeitung großer Dateien oder Netzwerk-Streams kann eine Anpassung der Chunk-Größe die Performance optimieren – etwa wenn bekannt ist, dass Nachrichten oder Datenpakete immer eine bestimmte Größe haben.
Zu beachten ist, dass der tatsächliche Effekt dieser Funktion vom verwendeten Stream-Wrapper abhängt. Bei manchen Wrappern oder wenn kein benutzerdefinierter Filter angehängt ist, zeigt sich möglicherweise kein spürbarer Unterschied im Verhalten.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $stream Pflicht | resource | Die Stream-Ressource, deren Chunk-Größe geändert werden soll. Muss ein gültiger, geöffneter Stream sein (z. B. von fopen() oder fsockopen()). |
|
| $size Pflicht | int | Die neue Chunk-Größe in Bytes. Muss ein positiver Ganzzahlwert sein. Werte kleiner oder gleich 0 führen zu einem Fehler. |
Rückgabewert
$size-Wert) wird FALSE zurückgegeben.Beispiele
Chunk-Größe eines Datei-Streams anpassen
<?php
// Datei öffnen
$stream = fopen('beispiel.txt', 'r');
if ($stream === false) {
die('Datei konnte nicht geöffnet werden.');
}
// Vorherige Chunk-Größe abfragen und neue setzen (4 KB)
$vorherige = stream_set_chunk_size($stream, 4096);
echo "Vorherige Chunk-Größe: {$vorherige} Bytes\n";
echo "Neue Chunk-Größe: 4096 Bytes\n";
fclose($stream);Chunk-Größe zusammen mit einem benutzerdefinierten Stream-Filter
<?php
// Eigenen Stream-Filter definieren
class UppercaseFilter extends php_user_filter {
public function filter($in, $out, &$consumed, $closing): int {
while ($bucket = stream_bucket_make_writeable($in)) {
$bucket->data = strtoupper($bucket->data);
$consumed += $bucket->datalen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
stream_filter_register('uppercase', 'UppercaseFilter');
// Temporären Stream erstellen und Filter anhängen
$stream = fopen('php://memory', 'r+');
fwrite($stream, 'hallo welt, dies ist ein test.');
rewind($stream);
// Chunk-Größe auf 10 Bytes setzen, damit der Filter kleinere Blöcke verarbeitet
$vorherige = stream_set_chunk_size($stream, 10);
echo "Vorherige Chunk-Größe: {$vorherige} Bytes\n";
stream_filter_append($stream, 'uppercase', STREAM_FILTER_READ);
// Stream lesen
echo stream_get_contents($stream) . "\n";
fclose($stream);// Wichtig · Fallstricke
Positive Werte erforderlich: Der Parameter $size muss eine positive ganze Zahl sein. Ein Wert von 0 oder negativ führt zu einem E_WARNING und gibt FALSE zurück.
Wirkung abhängig vom Wrapper: Nicht alle Stream-Wrapper reagieren gleich auf eine Änderung der Chunk-Größe. Bei Standard-Dateistreams ohne angehängten Filter ist der Effekt möglicherweise nicht messbar. Der größte Unterschied zeigt sich bei benutzerdefinierten Stream-Filtern (php_user_filter).
Speicher und Performance: Eine sehr kleine Chunk-Größe kann bei großen Datenmengen den Overhead durch häufige Filter-Aufrufe erhöhen. Eine sehr große Chunk-Größe kann temporär viel Speicher belegen. Die Wahl der optimalen Chunk-Größe sollte anwendungsfallbezogen getestet werden.