ftp_raw()

Entendiendo la función PHP ftp_raw()

La función ftp_raw() es una función integrada de PHP que envía un comando arbitrario directamente a un servidor FTP y devuelve la respuesta sin procesar del servidor, sin analizar. A diferencia de los auxiliares FTP de nivel superior, ftp_raw() no interpreta el resultado por ti — devuelve exactamente lo que dijo el servidor, línea por línea. Esta página explica qué hace la función, cuándo realmente la necesitas y cómo usarla de forma segura.

¿Qué es ftp_raw()?

FTP es un protocolo basado en texto: los clientes envían comandos cortos como SYST, PWD o FEAT, y el servidor responde con líneas de estado numeradas (por ejemplo 215 UNIX Type: L8). La mayoría de las funciones FTP de PHP — como ftp_nlist(), ftp_get() y ftp_systype() — envuelven uno de estos comandos y analizan la respuesta en un valor conveniente. ftp_raw() omite el análisis y expone el protocolo directamente.

Toma dos parámetros:

1. ftp_stream — el identificador de conexión devuelto por ftp_connect().
2. command — la cadena del comando FTP a enviar (por ejemplo 'SYST' o 'PWD').

En caso de éxito devuelve un array de cadenas, un elemento por línea de respuesta, que contiene la respuesta del servidor. En caso de falla (por ejemplo una conexión inválida) devuelve false.

¿Cuándo deberías usarla?

Para tareas cotidianas — listar, subir, descargar — prefiere las funciones dedicadas; ellas se encargan de las conexiones de datos y el análisis por ti. Recurre a ftp_raw() solo cuando:

• Necesitas un comando que PHP no tiene un envoltorio (por ejemplo FEAT para descubrir características del servidor, o una directiva SITE personalizada).
• Estás depurando y quieres ver la línea de estado exacta que devuelve el servidor.
• Estás implementando un comportamiento de protocolo que la API de alto nivel no expone.

Ten en cuenta que ftp_raw() está pensada solo para comandos del canal de control. No puede transferir datos de archivos — los comandos como RETR o LIST necesitan una conexión de datos separada, razón por la cual se usa ftp_get() o ftp_nlist() para esos casos.

Comandos raw comunes

Sintaxis de ftp_raw()

La firma de la función ftp_raw() es la siguiente:

ftp_raw(FTP\Connection $ftp, string $command): array

El parámetro $ftp es la conexión devuelta por ftp_connect(), y $command es la cadena del comando a enviar. Ambos son obligatorios.

Uso de ftp_raw()

Para usar la función ftp_raw(), primero necesitas establecer una conexión al servidor FTP con ftp_connect() y autenticarte con ftp_login(). Aquí tienes un ejemplo completo:

<?php

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

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

// Ask the server what operating system it runs
$response = ftp_raw($conn, 'SYST');

// Output the server's raw response, one line per element
echo "Server response: " . implode("\n", $response) . "\n";
// e.g. Server response: 215 UNIX Type: L8

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

Aquí nos conectamos con ftp_connect() y verificamos que tuvo éxito, nos autenticamos con ftp_login(), enviamos el comando SYST con ftp_raw() e imprimimos cada línea de respuesta. El 215 es el código de respuesta FTP; el texto después de él es la respuesta del servidor. Finalmente liberamos la conexión con ftp_close().

Manejo de errores en ftp_raw()

Siempre verifica el valor de retorno antes de usarlo. ftp_raw() devuelve false cuando no puede enviar el comando (por ejemplo porque la conexión ya no es válida), por lo que pasar ese resultado directamente a implode() provocaría un error de tipo. Protégete contra ello:

<?php

$response = ftp_raw($conn, 'SYST');

if ($response === false) {
    echo "Failed to send the raw command to the FTP server.\n";
} else {
    echo implode("\n", $response) . "\n";
}

ftp_close($conn);

Ten en cuenta que un array no falso no garantiza que el comando en sí haya tenido éxito — solo significa que el servidor respondió. Inspecciona el código de respuesta (el número inicial en cada línea, como 5xx para errores) cuando necesites saber si el comando fue aceptado.

Conclusión

La función ftp_raw() te brinda acceso directo al canal de control FTP, lo cual es invaluable para comandos que PHP no envuelve (como FEAT) y para depuración. Para listar, subir y descargar de forma rutinaria, usa las funciones dedicadas en su lugar. Consulta la referencia completa de funciones FTP de PHP para el conjunto completo.

Práctica