ftp_chmod()

La función PHP ftp_chmod()

ftp_chmod() es una función incorporada de PHP que cambia el modo de permisos de un archivo o directorio en un servidor FTP remoto — el equivalente FTP de ejecutar chmod desde una shell. Forma parte de la extensión FTP de PHP y resulta útil cuando un script de despliegue o carga necesita hacer que un archivo sea legible, escribible o ejecutable en el servidor después de transferirlo.

Esta página cubre la sintaxis, el significado real del valor mode, un flujo de trabajo completo, el manejo del valor de retorno y los errores más comunes que suelen cometerse. Si eres nuevo en la extensión FTP, comienza con ftp_connect() y ftp_login().

Sintaxis

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

Los parámetros son:

• $ftp — el manejador de conexión. Hasta PHP 7.4 era un resource devuelto por ftp_connect(); desde PHP 8.1 es un objeto FTP\Connection, pero se usa de la misma manera.
• $permissions — el nuevo modo de permisos como un entero octal (por ejemplo, 0644, 0755).
• $filename — la ruta al archivo o directorio cuyos permisos deseas cambiar.

Valor de retorno: si tiene éxito, la función devuelve los nuevos permisos del archivo como un entero; si falla, devuelve false. Compara siempre con === para que un modo válido como 0 (que es falsy) no se confunda con un fallo.

Por qué los permisos se escriben en octal

Un error común es pasar 644 en lugar de 0644. El 0 inicial hace que PHP lea el número como octal, que es la forma en que se expresan los permisos de archivo en 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.

Usa 0644 para archivos normales que deben ser legibles por todos pero solo escribibles por el propietario, y 0755 para directorios o scripts ejecutables.

Uso básico

Para cambiar los permisos, primero conéctate con ftp_connect(), autentícate con ftp_login(), llama a ftp_chmod() y luego libera la conexión con 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);

Verificar el resultado

Dado que el servidor FTP puede rechazar la solicitud (ruta incorrecta, privilegios insuficientes o un servidor que no admite SITE CHMOD), comprueba siempre el valor de retorno:

<?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);

Para 0644, esto imprime Permissions changed to 644 successfully. — el especificador de formato %o convierte el entero devuelto de vuelta a la notación octal familiar.

Errores comunes

• ftp_chmod() no es recursiva. Afecta a una sola ruta. Para hacer chmod a todo un árbol de directorios, debes listar el directorio (consulta ftp_nlist()) y llamar a ftp_chmod() en cada entrada.
• No todos los servidores lo admiten. ftp_chmod() depende del comando FTP SITE CHMOD, que algunos servidores (especialmente muchos servidores FTP IIS de Windows) no implementan. En esos casos simplemente devolverá false.
• Pasa octal, no decimal. Como se mostró antes, 644 y 0644 son números distintos.
• El orden importa. Debes haber iniciado sesión antes de llamar a ftp_chmod(); llamarla sobre una conexión no autenticada falla.

Funciones relacionadas

• ftp_connect() — abre la conexión FTP.
• ftp_login() — autentícate antes de cualquier operación.
• ftp_put() / ftp_get() — sube y descarga archivos.
• ftp_close() — cierra la conexión.
• chmod() — cambia los permisos en el sistema de archivos local.

Resumen

ftp_chmod() cambia el modo de permisos de un archivo o directorio remoto a través de FTP. Pasa el modo como un entero octal (0644, 0755), comprueba el valor de retorno con === contra false, y recuerda que la operación afecta solo a una ruta y depende del soporte del servidor para SITE CHMOD.

Práctica