ftp_size()

Функция PHP ftp_size()

ftp_size() — встроенная функция PHP, которая запрашивает у FTP-сервера размер одного удалённого файла в байтах. Она нужна, когда требуется узнать размер файла без его скачивания — например, для отображения прогресс-бара, определения изменений с момента последней синхронизации, пропуска пустых файлов или проверки того, что загрузка завершилась с ожидаемым размером.

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

Синтаксис

ftp_size(FTP\Connection $ftp, string $filename): int

Возвращаемое значение: размер файла в байтах в виде целого числа при успехе или -1 при ошибке.

Важно: ftp_size() при неудаче возвращает целое число -1, а не false. Это отличает её от большинства других FTP-функций, поэтому всегда сравнивайте результат с -1, а не с false.

До PHP 8.1 аргумент $ftp имел тип resource; начиная с PHP 8.1 это объект FTP\Connection. Код изменять не нужно — меняется только внутренний тип.

Основное использование

Чтобы вызвать ftp_size(), сначала откройте соединение с помощью ftp_connect() и выполните аутентификацию через ftp_login():

<?php

// Open a connection to the FTP server
$conn = ftp_connect('ftp.example.com');

// Log in with your credentials
ftp_login($conn, 'username', 'password');

// Turn on passive mode (see the note below — this is almost always required)
ftp_pasv($conn, true);

// Ask the server how big the file is
$size = ftp_size($conn, '/public_html/index.php');

if ($size !== -1) {
    echo "The file is {$size} bytes.";
} else {
    echo "Could not determine the file size.";
}

// Always close the connection when you are done
ftp_close($conn);

Пассивный режим: самая распространённая ошибка

Если ftp_size() постоянно возвращает -1, хотя файл явно существует, причина, как правило, в активном или пассивном режиме, а не в опечатке в пути. За фаерволом или NAT (что характерно для большинства серверов сегодня) FTP-сервер не может открыть канал данных к вашему клиенту, поэтому базовая команда SIZE зависает.

Вызовите ftp_pasv() после входа в систему, чтобы переключиться в пассивный режим, при котором каждое соединение инициирует клиент:

<?php
ftp_login($conn, 'username', 'password');
ftp_pasv($conn, true); // do this before ftp_size(), ftp_get(), ftp_nlist(), etc.

Режим передачи влияет на результат

Размер, сообщаемый FTP-сервером, может зависеть от текущего режима передачи. В ASCII-режиме некоторые серверы преобразуют окончания строк, поэтому сообщаемый размер может не совпадать с количеством байт, получаемым в бинарном режиме. Для точного подсчёта байт убедитесь, что используется бинарный режим (FTP_BINARY) — именно он является режимом по умолчанию для запросов размера на большинстве серверов и именно его вы почти всегда хотите использовать для не текстовых файлов.

Надёжная обработка ошибок

Поскольку ftp_size() сигнализирует об ошибке значением -1, надёжная обёртка проверяет именно это значение и предупреждает, когда размер неизвестен:

<?php

function remoteFileSize($conn, string $path): ?int
{
    $size = ftp_size($conn, $path);

    if ($size === -1) {
        // The file is missing, the path is wrong, or the SIZE command failed.
        return null;
    }

    return $size;
}

$size = remoteFileSize($conn, '/public_html/index.php');

echo $size === null
    ? "File not found or size unavailable.\n"
    : "Size: {$size} bytes\n";

Использование null для случая ошибки не позволяет значению -1 попасть в последующие вычисления (где оно незаметно исказило бы итоги).

Получение размеров для множества файлов

ftp_size() работает с одним путём за раз. Чтобы получить размеры для целого каталога, объедините её с ftp_nlist(), которая возвращает array имён файлов:

<?php

$files = ftp_nlist($conn, '/public_html');

if ($files !== false) {
    foreach ($files as $file) {
        $size = ftp_size($conn, $file);
        $label = $size === -1 ? 'directory or unreadable' : "{$size} bytes";
        echo "{$file}: {$label}\n";
    }
}

Обратите внимание, что ftp_size() возвращает -1 для каталогов — это удобный способ отличить файлы от папок в листинге.

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

• ftp_connect() — открывает соединение, которое передаётся в ftp_size().
• ftp_login() — выполняет аутентификацию перед любым запросом размера.
• ftp_pasv() — включает пассивный режим, чтобы ftp_size() действительно работала.
• ftp_nlist() — выводит список каталога для получения размеров множества файлов в цикле.
• ftp_get() — скачивает файл, когда его размер уже известен.
• ftp_close() — закрывает соединение по завершении работы.
• Обзор PHP FTP — все FTP-функции в одном месте.

Заключение

ftp_size() — это самый быстрый способ узнать размер удалённого файла в байтах без его передачи. Помните два правила, обеспечивающие надёжную работу: включите пассивный режим с помощью ftp_pasv() после входа в систему и проверяйте результат на равенство -1 (а не false), чтобы обнаруживать ошибки и каталоги.

Практика