ftp_chmod()

Функция PHP ftp_chmod()

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

На этой странице рассматриваются синтаксис, истинный смысл значения mode, полный рабочий пример, обработка возвращаемого значения и типичные ошибки. Если вы только начинаете знакомиться с FTP-расширением, начните с ftp_connect() и ftp_login().

Синтаксис

ftp_chmod(FTP\Connection $ftp, int $permissions, string $filename): int|false

Параметры:

• $ftp — дескриптор соединения. До PHP 7.4 это был resource, возвращаемый функцией ftp_connect(); начиная с PHP 8.1 это объект FTP\Connection, но используется одинаково.
• $permissions — новый режим прав доступа в виде восьмеричного целого числа (например, 0644, 0755).
• $filename — путь к файлу или каталогу, права доступа которого вы хотите изменить.

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

Почему права доступа записываются в восьмеричной системе

Распространённая ошибка — передавать 644 вместо 0644. Ведущий 0 заставляет PHP интерпретировать число как восьмеричное, что соответствует способу представления прав доступа в Unix.

<?php

// 0644 (octal) is NOT the same as 644 (decimal)
var_dump(0644);          // int(420)  -> the value you actually want
var_dump(644);           // int(644)  -> wrong, this is 1204 in octal

// Each digit is owner / group / others:
//   6 = read + write (4 + 2)
//   4 = read only
// So 0644 means: owner can read & write, group and others can read.

Используйте 0644 для обычных файлов, которые должны быть доступны для чтения всем, но для записи — только владельцу, и 0755 для каталогов или исполняемых сценариев.

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

Для изменения прав доступа сначала установите соединение с помощью ftp_connect(), выполните аутентификацию через ftp_login(), вызовите ftp_chmod(), затем освободите соединение с помощью ftp_close().

<?php

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

// 2. Log in with your credentials
ftp_login($ftp, 'username', 'password');

// 3. Make the file readable by all, writable by the owner
ftp_chmod($ftp, 0644, '/path/to/file.txt');

// 4. Close the connection
ftp_close($ftp);

Проверка результата

Поскольку FTP-сервер может отклонить запрос (неверный путь, недостаточно прав или сервер не поддерживает SITE CHMOD), всегда проверяйте возвращаемое значение:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');

$result = ftp_chmod($ftp, 0644, '/path/to/file.txt');

if ($result === false) {
    echo "Failed to change permissions.\n";
} else {
    // $result is the new mode; printf with %o shows it back in octal
    printf("Permissions changed to %o successfully.\n", $result);
}

ftp_close($ftp);

Для 0644 выводится Permissions changed to 644 successfully. — форматный спецификатор %o преобразует возвращаемое целое число обратно в привычную восьмеричную нотацию.

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

• ftp_chmod() не является рекурсивной. Она воздействует только на один путь. Чтобы изменить права доступа ко всему дереву каталогов, необходимо получить список каталога (см. ftp_nlist()) и вызвать ftp_chmod() для каждого элемента.
• Не каждый сервер поддерживает эту функцию. ftp_chmod() зависит от команды FTP SITE CHMOD, которую некоторые серверы (в частности, многие Windows IIS FTP-серверы) не реализуют. В таком случае функция просто вернёт false.
• Передавайте восьмеричное, а не десятичное число. Как показано выше, 644 и 0644 — разные числа.
• Порядок важен. Необходимо войти в систему перед вызовом ftp_chmod(); вызов функции на неаутентифицированном соединении завершится ошибкой.

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

• ftp_connect() — открытие FTP-соединения.
• ftp_login() — аутентификация перед любой операцией.
• ftp_put() / ftp_get() — загрузка и скачивание файлов.
• ftp_close() — закрытие соединения.
• chmod() — изменение прав доступа в локальной файловой системе.

Итоги

ftp_chmod() изменяет режим прав доступа к удалённому файлу или каталогу через FTP. Передавайте режим в виде восьмеричного целого числа (0644, 0755), проверяйте возвращаемое значение с помощью === относительно false и помните, что операция применяется только к одному пути и зависит от поддержки сервером команды SITE CHMOD.

Практика