ftp_rawlist() - Aprender PHP

Entendiendo la función PHP ftp_rawlist()

La función ftp_rawlist() devuelve un listado detallado de un directorio en un servidor FTP. Cada elemento del array que retorna es una línea del resultado bruto LIST del servidor — el mismo texto que verías en un cliente FTP de terminal, incluyendo permisos de archivo, propietario, tamaño y fecha de modificación.

Esta página cubre lo que devuelve ftp_rawlist(), su sintaxis, un ejemplo funcional completo, cómo analizar las líneas brutas para obtener datos utilizables, listados recursivos y manejo de errores. Si solo necesitas los nombres de los archivos en un directorio, usa ftp_nlist() en su lugar — es más simple y mucho más fácil de analizar.

¿Qué es ftp_rawlist()?

ftp_rawlist() acepta dos parámetros obligatorios y uno opcional:

ftp_stream — el objeto de conexión (PHP 8.1+) o el recurso devuelto por ftp_connect() (o ftp_ssl_connect()).
directory — el directorio a listar.
recursive (opcional) — establécelo en true para listar subdirectorios de forma recursiva.

En caso de éxito devuelve un array de strings, donde cada string es una línea bruta del resultado; en caso de fallo (o para un directorio vacío que no puede leer) devuelve false.

Lo fundamental es entender que este resultado no está estandarizado. Es lo que emite el comando LIST del servidor, por lo que su formato depende del sistema operativo y la configuración del servidor. Un servidor de estilo Unix típicamente devuelve líneas con el aspecto del resultado de ls -l:

drwxr-xr-x   2 owner group        4096 Jun 21 10:00 images
-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html

Los servidores de estilo Windows/DOS devuelven un formato completamente diferente. Debido a esto, ftp_rawlist() te proporciona información completa a costa de tener que analizar texto de formato libre tú mismo. Compáralo con:

ftp_nlist() — devuelve un array simple con solo los nombres de archivos.
ftp_mlsd() — devuelve un listado estructurado y legible por máquina (preferido cuando el servidor admite el comando MLSD).

Sintaxis de ftp_rawlist()

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

Sintaxis de ftp_rawlist()

array ftp_rawlist ( FTP\Connection|resource $ftp_stream , string $directory [, bool $recursive = false ] )

La función ftp_rawlist() recibe dos parámetros obligatorios, ftp_stream y directory. El parámetro ftp_stream es el identificador de conexión devuelto por la función ftp_connect(), y el parámetro directory es el directorio a listar. La función también tiene un parámetro opcional, recursive, que permite especificar si se deben listar los subdirectorios.

Uso de ftp_rawlist()

Para usar la función ftp_rawlist(), primero debes establecer una conexión al servidor FTP mediante la función ftp_connect(). A continuación se muestra un ejemplo:

Uso de ftp_rawlist()

<?php

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

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

// Get a detailed listing of the directory
$listing = ftp_rawlist($conn, '/public_html');

// Output the listing to the console
if ($listing) {
    foreach ($listing as $item) {
        echo $item . "\n";
    }
}

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

Aquí nos conectamos con ftp_connect(), nos autenticamos con ftp_login(), recuperamos el listado con ftp_rawlist(), imprimimos cada línea bruta y finalmente liberamos la conexión con ftp_close().

Consejo — modo pasivo: Muchas redes y cortafuegos bloquean el canal de datos en modo activo que usa ftp_rawlist() para obtener el listado, lo que hace que se quede bloqueada o devuelva false. Si eso ocurre, activa el modo pasivo con ftp_pasv($conn, true) después de iniciar sesión.

Nota de seguridad: El FTP estándar transmite las credenciales y los datos en texto plano. Para entornos de producción, considera usar ftp_ssl_connect() para FTP explícito sobre TLS, o cambia a SFTP (mediante la extensión ssh2) para transferencias cifradas.

Análisis del listado bruto

Dado que cada línea es texto no estructurado, normalmente querrás extraer campos individuales. Para un servidor de estilo Unix puedes dividir cada línea por espacios en blanco: los permisos son el primer token, el tamaño es el quinto, y el nombre del archivo es todo lo que hay a partir del noveno token (el nombre puede contener espacios).

Análisis de un listado bruto de estilo Unix

<?php

// One line of typical ftp_rawlist() output:
$line = '-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html';

// Split on runs of whitespace, limited so the name stays intact.
$parts = preg_split('/\s+/', $line, 9);

$type        = $parts[0][0] === 'd' ? 'directory' : 'file';
$permissions = $parts[0];
$size        = (int) $parts[4];
$name        = $parts[8];

echo "Name:        $name\n";
echo "Type:        $type\n";
echo "Size:        $size bytes\n";
echo "Permissions: $permissions\n";
?>

Esto imprime:

Name:        index.html
Type:        file
Size:        10240 bytes
Permissions: -rw-r--r--

Si tu servidor lo admite, prefiere ftp_mlsd(), que devuelve estos datos ya estructurados para que puedas omitir el frágil análisis de cadenas.

Listado de subdirectorios de forma recursiva

Pasar true como tercer argumento le indica al servidor que descienda a los subdirectorios. El resultado incluye entonces líneas en blanco y encabezados de directorio (una ruta seguida de dos puntos) que separan el contenido de cada subdirectorio — prepárate para omitirlos al iterar:

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html', true);

foreach ($listing as $line) {
    if ($line === '' || str_ends_with($line, ':')) {
        // Skip blank separators and "/path/to/dir:" headers
        continue;
    }
    echo $line . "\n";
}
?>

Ten en cuenta que no todos los servidores FTP respetan el indicador recursivo, y un árbol profundo puede ser lento, así que prueba con tu servidor de destino.

Manejo de errores en ftp_rawlist()

Es importante manejar los errores correctamente al usar la función ftp_rawlist(). Si la función devuelve false, significa que la operación no tuvo éxito. A continuación se muestra un ejemplo de cómo manejar los errores:

Manejo de errores en ftp_rawlist()

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html');

if (!$listing) {
    echo "Failed to get directory listing from FTP server.\n";
}

ftp_close($conn);
?>

Al manejar los errores de forma adecuada y comprobar el valor de retorno de la función, puedes garantizar el éxito de tus operaciones FTP usando la función ftp_rawlist().

Conclusión

ftp_rawlist() es la función a utilizar cuando necesitas metadatos completos de archivos — permisos, propietario, tamaño y fecha — de un directorio FTP, no solo nombres. La contrapartida es que su resultado es el texto LIST bruto y dependiente del sistema operativo del servidor, así que planifica su análisis (o usa el estructurado ftp_mlsd() cuando esté disponible). Comprueba siempre el valor de retorno, activa el modo pasivo cuando estés detrás de un cortafuegos y prefiere una conexión cifrada para producción.

Funciones relacionadas

ftp_nlist() — listar solo nombres de archivos
ftp_mlsd() — listado estructurado y legible por máquina
ftp_connect() / ftp_login() — abrir y autenticar una sesión
ftp_get() — descargar un archivo una vez encontrado
ftp_close() — cerrar la conexión

Práctica

¿Cuál es la función de ftp_rawlist en PHP?

Muestra una lista de archivos en un directorio especificado.Proporciona información sobre un archivo en un servidor.Devuelve una lista detallada de archivos en el directorio especificado de un servidor FTP.Obtiene el contenido de un archivo desde un servidor.