ftp_site()

Comprendiendo la función PHP ftp_site()

La función ftp_site() es una función incorporada de PHP que envía un comando SITE a un servidor FTP. SITE es un comando FTP de uso general para instrucciones que quedan fuera del protocolo FTP estándar — cosas que cada proveedor de servidor implementa a su manera, como cambiar permisos de archivos, ajustar tiempos de espera de inactividad o ejecutar tareas de mantenimiento específicas del servidor.

Dado que el significado de un comando SITE lo define completamente el servidor remoto, ftp_site() es la vía de escape a la que se recurre cuando no existe ninguna función FTP dedicada en PHP para lo que necesitas. Este artículo explica qué hace la función, cuándo usarla (y cuándo no hacerlo) y cómo manejar su resultado de forma segura.

Para trabajar con ella, primero debes abrir una conexión con ftp_connect() y autenticarte con ftp_login(). Consulta la descripción general de PHP FTP para ver la familia completa de funciones.

¿Qué es ftp_site()?

La función toma dos parámetros:

1. ftp — La conexión FTP devuelta por ftp_connect() (o ftp_ssl_connect()).
2. command — La cadena de comando SITE sin procesar que se enviará, sin la palabra clave SITE inicial (PHP la añade por ti).

Devuelve true si el servidor aceptó el comando y false en caso de error. Un resultado true solo significa que el servidor aceptó el comando — no garantiza que la acción subyacente (por ejemplo, el cambio de permiso) haya tenido éxito, ya que el comportamiento de SITE está definido por el servidor.

Sintaxis de ftp_site()

La sintaxis de la función ftp_site() es la siguiente:

Sintaxis de ftp_site()

ftp_site(FTP\Connection $ftp, string $command): bool

A partir de PHP 8.1 el primer argumento es un objeto FTP\Connection (en versiones anteriores era un resource). El argumento command es la instrucción SITE que se enviará — por ejemplo CHMOD 644 file.txt. Solo se pasa la parte después de SITE; PHP antepone la palabra clave automáticamente.

Uso de ftp_site()

Para usar la función ftp_site(), primero debes establecer una conexión con el servidor FTP mediante la función ftp_connect(). Aquí tienes un ejemplo:

Uso de ftp_site()

<?php

// Set up an FTP connection
$conn = @ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Send the SITE command
ftp_site($conn, 'CHMOD 755 /public_html/index.php');

// Close the FTP connection
ftp_close($conn);

En este ejemplo, nos conectamos con ftp_connect(), nos autenticamos con ftp_login(), enviamos SITE CHMOD 755 para cambiar los permisos de index.php y finalmente cerramos la conexión con ftp_close().

Nota: Los comandos SITE son específicos del servidor. SITE CHMOD no está soportado universalmente en todos los servidores FTP. Para cambios estándar de permisos de archivos, se prefiere la función dedicada ftp_chmod(), que es portátil y devuelve el nuevo valor de permiso. Recurre a ftp_site() solo para acciones que no tengan una función FTP dedicada.

Comandos SITE comunes

El conjunto exacto de comandos soportados depende del software del servidor (ProFTPD, vsftpd, Pure-FTPd, etc.), pero algunos están ampliamente disponibles:

En caso de duda, ejecuta SITE HELP para descubrir qué acepta un servidor en particular:

Descubriendo los comandos SITE soportados

<?php

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

if (ftp_site($conn, 'HELP')) {
    echo "Server accepted the SITE HELP command.\n";
}

ftp_close($conn);

Manejo de errores en ftp_site()

Es importante manejar los errores correctamente al usar la función ftp_site(). Si la función devuelve false, significa que la operación no fue exitosa. Aquí tienes un ejemplo de cómo manejar errores:

Manejo de errores en ftp_site()

<?php

if (!ftp_site($conn, 'CHMOD 755 /public_html/index.php')) {
    echo "Failed to send SITE command.\n";
}

ftp_close($conn);

Al comprobar el valor de retorno, evitas continuar silenciosamente después de un comando que el servidor rechazó. Ten en cuenta que ftp_site() devuelve false tanto cuando la conexión es incorrecta como cuando el servidor simplemente no reconoce el comando — por lo que un resultado false es tu señal para recurrir a una función dedicada o a un enfoque diferente.

ftp_site() vs. ftp_raw() y ftp_exec()

ftp_site() está estrechamente relacionada con otras dos funciones de "enviar una instrucción sin procesar", y conviene saber cuándo elegir cada una:

• ftp_site() — envía un único comando SITE y devuelve un boolean. Úsala para acciones específicas del servidor como CHMOD o UMASK.
• ftp_raw() — envía cualquier comando FTP sin procesar (no solo SITE) y devuelve la respuesta completa del servidor como un array, para que puedas leer el código de estado tú mismo. Úsala cuando necesites inspeccionar la respuesta.
• ftp_exec() — ejecuta un programa en el servidor mediante SITE EXEC, donde esté soportado. Úsala solo en servidores que controles y en los que confíes.

Para operaciones cotidianas (subir, descargar, listar, renombrar) prefiere las funciones de propósito específico cubiertas en la descripción general de PHP FTP; son más portátiles que los comandos SITE construidos manualmente.

Conclusión

La función ftp_site() te permite enviar comandos SITE específicos del servidor cuando ninguna función FTP dedicada de PHP se adapta. Comprueba siempre su valor de retorno, recuerda que un envío exitoso no es lo mismo que una acción exitosa, y prefiere funciones portátiles como ftp_chmod() siempre que exista una.

Práctica