PHP stream_set_chunk_size() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Stream

Definition

In PHP, stream_set_chunk_size() sets how many bytes PHP prefers to read or write in one chunk on the given stream.

It returns the previous chunk size. On a fresh stream the first previous value is often 8192. Use it when you want to tune transfer granularity for large stream copies.

Syntax

Call stream_set_chunk_size() with the values you need. Start with this line.

PHP
$previous = stream_set_chunk_size($stream, 4096);
CallWhat it does
stream_set_chunk_size($stream, 4096)Sets the chunk size to 4096 and returns the previous size.
stream_set_chunk_size($stream, 8192)Restores the common 8 KiB chunk size.
stream_set_chunk_size($stream, 1)Uses 1-byte chunks (valid, but slow for large data).

In PHP 8, a size less than 1 throws ValueError. Chunk size is a tuning knob; your fread() length arguments still matter for how much you request in userland.

Library declarations
PHP
stream_set_chunk_size(resource $stream, int $size): int

Parameters

ParameterDescription
streamRequired. The stream whose chunk size you want to change.
sizeRequired. New chunk size in bytes (must be at least 1).

Return Value

Return ValueDescription
intThe previous chunk size on success.

PHP Examples

Example 1 — Read the Default Chunk Size

Set a new size once and print the previous value PHP returns.

PHP
<?php
$stream = fopen("php://memory", "r+");
$previous = stream_set_chunk_size($stream, 4096);
echo "previous=", $previous, PHP_EOL;
fclose($stream);

How It Works

  1. A memory stream starts with PHP's default chunk size.
  2. stream_set_chunk_size($stream, 4096) installs 4096.
  3. The function returns the old size, commonly 8192.
  4. That previous value is printed for the tutorial.

Example 2 — Change Size Twice

Set 2048, then 1024, and show that the second call returns 2048.

PHP
<?php
$stream = fopen("php://temp", "r+");
stream_set_chunk_size($stream, 2048);
$previous = stream_set_chunk_size($stream, 1024);
echo "previous=", $previous, PHP_EOL;
fclose($stream);

How It Works

  1. The first call sets the chunk size to 2048.
  2. The second call sets it to 1024.
  3. The returned previous value is therefore 2048.
  4. This proves the function reports the size you installed last time.

Example 3 — Reject an Invalid Size in PHP 8

Catch ValueError when the requested size is less than 1.

PHP
<?php
$stream = fopen("php://memory", "r+");

try {
    stream_set_chunk_size($stream, 0);
    echo "unexpected", PHP_EOL;
} catch (ValueError $e) {
    echo "invalid size", PHP_EOL;
}

fclose($stream);

How It Works

  1. Size 0 is not allowed.
  2. PHP 8 throws ValueError instead of returning false.
  3. The catch block prints a clear message.
  4. The stream is still closed normally afterward.

Frequently Asked Questions

It sets the preferred chunk size for a stream and returns the previous chunk size.
It is commonly 8192 bytes. The first stream_set_chunk_size() call often returns that value.
No. It only tunes how the stream layer prefers to split I/O. Your existing bytes stay the same.
In PHP 8 a ValueError is thrown because the size must be at least 1.
Chunk size affects stream chunking. stream_set_read_buffer() configures read buffering (0 means unbuffered reads). They are related tuning tools with different jobs.

Next: stream_set_read_buffer()

stream_set_read_buffer() sets the read buffer size for a stream, similar to stream_set_wri.

stream_set_read_buffer() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful