fgetc()

Введение в функцию PHP fgetc()

Функция fgetc() в PHP читает ровно один символ из открытого файла и перемещает файловый указатель на один байт вперёд. Название расшифровывается как «file get character» («получить символ из файла»). Каждый вызов возвращает следующий символ, поэтому, вызывая функцию многократно, можно обойти файл посимвольно.

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

На этой странице рассматриваются синтаксис, параметры, возвращаемые значения, исполняемые примеры и распространённые ловушки (особенно ловушка конца файла со значением "0").

Синтаксис

fgetc(resource $stream): string|false

Функция принимает один аргумент и возвращает либо прочитанный символ, либо false.

Параметры

Тип resource по-прежнему полностью поддерживается в PHP 8+. Никаких изменений для современной совместимости не требуется.

Возвращаемые значения

• При успехе возвращает string, содержащий один символ, прочитанный из файла.
• Возвращает false при достижении конца файла (EOF) или в случае ошибки.

Примеры

Пример 1: Чтение одного символа из файла

В этом примере читается только первый символ файла. Всегда проверяйте, что fopen() выполнился успешно, прежде чем использовать дескриптор, и вызывайте fclose() по завершении работы.

<?php

$fileHandle = fopen('example.txt', 'r');
if ($fileHandle) {
    echo fgetc($fileHandle); // prints the first character
    fclose($fileHandle);
}

Пример 2: Чтение всего файла посимвольно

Чтобы прочитать весь файл, вызывайте fgetc() в цикле и останавливайтесь, когда функция вернёт false (EOF).

<?php

$fileHandle = fopen('example.txt', 'r');
if ($fileHandle) {
    while (($char = fgetc($fileHandle)) !== false) {
        echo $char;
    }
    fclose($fileHandle);
}

Этот код выводит каждый символ файла вплоть до EOF.

Почему важно использовать !== false (ловушка с «0»)

Очень распространённая ошибка — написать цикл с нестрогим сравнением:

// BUGGED: stops early on the first "0" or "" it reads
while ($char = fgetc($fileHandle)) {
    echo $char;
}

PHP считает string "0" и "" ложными значениями. Если файл содержит символ 0, цикл завершится на нём, а не на EOF. Всегда используйте строгое, идентичностное сравнение !== false, чтобы цикл останавливался только при получении реального значения EOF. Это же правило применяется к fgets() и fread().

Пример 3: Подсчёт вхождений символа

Поскольку fgetc() выдаёт по одному символу за раз, функция удобна для потокового подсчёта без загрузки всего файла в память:

<?php

$fileHandle = fopen('example.txt', 'r');
$vowels = 0;
if ($fileHandle) {
    while (($char = fgetc($fileHandle)) !== false) {
        if (str_contains('aeiouAEIOU', $char)) {
            $vowels++;
        }
    }
    fclose($fileHandle);
    echo "Vowels: $vowels";
}

fgetc() vs fgets() vs fread()

Для двоичных файлов предпочтительнее использовать fread() — цикл с fgetc() работает, но значительно медленнее в расчёте на байт.

Замечания и ловушки

• fgetc() работает с бинарно-безопасными потоками: функция возвращает один байт даже для нетекстовых символов. Многобайтовые символы UTF-8 занимают несколько байт, поэтому один вызов fgetc() может вернуть лишь часть такого символа.
• Открывайте файл с нужным режимом ('r', 'rb' и т.д.) с помощью fopen() и не забывайте закрывать его функцией fclose().
• Конец файла также можно проверить явно с помощью feof(), хотя сравнение результата fgetc() с false обычно достаточно.

Заключение

fgetc() читает по одному символу из открытого файлового указателя и возвращает false при достижении конца файла, что делает её идеальной для посимвольного разбора и подсчёта. Запомните два ключевых правила: передавайте открытый ресурс из fopen() и завершайте цикл чтения строгой проверкой !== false, чтобы символ 0 не прерывал цикл раньше времени. Для построчной или блочной работы используйте fgets() или fread().

Подробнее о работе с файлами в PHP — в руководстве PHP File Handling.

Практика