fread()

Функция fread() читает указанное количество байт из открытого файла. В отличие от вспомогательных функций, загружающих весь файл за один вызов, fread() даёт точный контроль над тем, сколько данных считывать за раз — именно то, что нужно при работе с большими файлами, двоичными данными или потоковым содержимым. На этой странице описаны синтаксис, возвращаемое значение, способ безопасного чтения файла по частям и типичные ошибки.

Синтаксис

fread(resource $stream, int $length): string|false

fread() останавливается, как только происходит одно из следующих событий: прочитано $length байт, достигнут конец файла (EOF), стал доступен пакет (для сетевых потоков) или прочитано 8192 байта после заполнения буфера потока (для нерегулярных файлов). Функция возвращает прочитанные байты в виде string или false в случае ошибки.

fread() является безопасной для работы с двоичными данными — она читает байты точно в том виде, в котором они хранятся, поэтому подходит для изображений, PDF-файлов и других нетекстовых форматов.

Чтение всего файла

Простейший вариант — прочитать весь файл за один вызов, передав его размер в качестве $length:

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'r');

if ($file) {
    $data = fread($file, filesize($filename));
    echo $data;
    fclose($file);
}

Здесь fopen() открывает файл в режиме только для чтения ('r'), filesize() возвращает размер файла в байтах, а fread() читает ровно столько байт. Всегда используйте fclose() в паре с fopen(), чтобы освободить дескриптор файла.

Если не нужен дескриптор, для чтения всего файла удобнее использовать file_get_contents() — это однострочная альтернатива. fread() нужен тогда, когда требуется контролировать размер чтения или обрабатывать файл поэтапно.

Чтение файла по частям

Для больших файлов не следует загружать всё содержимое в память сразу. Читайте фиксированный блок за одну итерацию и останавливайтесь при достижении конца файла с помощью feof():

<?php

$file = fopen('large.log', 'r');

if ($file) {
    while (!feof($file)) {
        $chunk = fread($file, 1024); // read up to 1 KB at a time
        echo $chunk;
    }
    fclose($file);
}

Благодаря этому использование памяти остаётся постоянным вне зависимости от размера файла, поскольку в памяти одновременно хранится лишь один блок размером 1 КБ. Увеличьте размер блока (например, до 8192), чтобы обменять память на меньшее количество операций чтения.

Возвращаемое значение и обработка ошибок

fread() возвращает string из прочитанных байт. При достижении конца файла возвращается пустая строка "", а при ошибке — false. Поскольку "" и false оба являются ложными значениями, используйте строгую проверку, когда нужно их различить:

<?php

$file = fopen('data.bin', 'rb');

if ($file === false) {
    exit('Could not open the file.');
}

$bytes = fread($file, 16);

if ($bytes === false) {
    echo 'Read failed.';
} else {
    echo 'Read ' . strlen($bytes) . " bytes.\n";
}

fclose($file);

Обратите внимание на режим 'rb': в Windows открытие файла в двоичном режиме (b) предотвращает преобразование окончаний строк, которое могло бы повредить двоичные данные. На других платформах это безвредно, поэтому использование флага b является хорошей практикой для любых нетекстовых файлов.

Типичные ошибки

• $length — это максимум, а не гарантия. Один вызов fread() может вернуть меньше байт, чем запрошено (например, ближе к концу файла или при работе с сетевым потоком). Чтобы прочитать точное количество байт, используйте цикл до получения нужного объёма данных или достижения EOF.
• Файл должен быть открыт в режиме чтения. Такие режимы, как 'w', открывают файл только для записи; используйте 'r', 'r+', 'a+' и т. д. Полный список режимов см. в описании fopen().
• Не забывайте закрывать файл с помощью fclose(). Утечка дескрипторов может исчерпать доступные файловые дескрипторы в долго работающих скриптах.
• Нужно читать построчно? Если вместо количества байт нужна одна строка, лучше использовать fgets().

Связанные функции

• fopen() — открывает файл и возвращает указатель, необходимый для fread().
• fwrite() — аналог для записи байт в файл.
• fgets() — читает одну строку вместо заданного количества байт.
• feof() — проверяет достижение конца файла при использовании в цикле.
• file-get-contents() — читает весь файл за один вызов.
• fclose() — закрывает дескриптор файла после завершения работы.

Заключение

fread() — это инструмент PHP для чтения точного количества байт из открытого файла. Используйте его вместе с filesize(), чтобы прочитать весь файл, или в цикле с feof() для потоковой обработки больших файлов с минимальным потреблением памяти. Помните, что $length — это верхняя граница, открывайте двоичные файлы с флагом b и всегда закрывайте дескриптор с помощью fclose().

Практика