ftp_nlist()

La función ftp_nlist() de PHP

ftp_nlist() devuelve un array plano con los nombres de los archivos y subdirectorios dentro de un directorio de un servidor FTP. Es el equivalente FTP del comando nls/ls: obtienes solo los nombres, sin información de tamaño, permisos ni fechas.

Esta página cubre la sintaxis y los parámetros, un ejemplo completo y funcional, cómo luce el valor de retorno, cómo gestionar los errores, las trampas más comunes (modo pasivo, nombres sin prefijo de ruta) y cuándo conviene usar ftp_rawlist() en su lugar.

Sintaxis

ftp_nlist(FTP\Connection $ftp, string $directory): array|false

Valor de retorno: un array de nombres en caso de éxito, o false en caso de error.

Los nombres devueltos no incluyen el prefijo del directorio: listar /public_html/ te da index.php, no /public_html/index.php. Si el directorio está vacío, obtienes un array vacío [], que no es lo mismo que false.

Un ejemplo completo

Antes de poder listar nada, necesitas una conexión abierta y autenticada. El flujo típico es ftp_connect() → ftp_login() → ftp_pasv() → ftp_nlist() → ftp_close():

Uso de ftp_nlist()

<?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.');
}

// Enable passive mode (often required for directory listings)
ftp_pasv($conn, true);

// Get an array of filenames in the specified directory
$files = ftp_nlist($conn, '/public_html/');

// Output the array of filenames
print_r($files);

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

Cada paso está protegido: salimos si la conexión o el inicio de sesión falla. Habilitar el modo pasivo con ftp_pasv() es importante — muchos servidores (y la mayoría de los firewalls) lo requieren antes de que el listado de directorios funcione, por lo que omitir la llamada a ftp_pasv() es la razón más frecuente por la que ftp_nlist() retorna false silenciosamente.

Para un directorio que contiene dos archivos, print_r() produciría una salida similar a:

Array
(
    [0] => index.php
    [1] => style.css
)

ftp_nlist() vs ftp_rawlist()

Usa la función que se ajuste a tus necesidades:

• ftp_nlist() devuelve solo un array de nombres — ideal para "¿existe este archivo?" o para iterar sobre descargas.
• ftp_rawlist() devuelve la salida sin procesar del comando LIST (una cadena por línea, como ls -l), que incluye tamaños, permisos y fechas — útil cuando necesitas esos metadatos y estás dispuesto a parsearlos.

Si solo necesitas nombres, prefiere ftp_nlist(): su salida es consistente entre servidores, mientras que el formato de ftp_rawlist() varía según el tipo de servidor FTP.

Manejo de errores

Es importante gestionar correctamente los errores al usar la función ftp_nlist(). Si la función devuelve false, significa que el listado no tuvo éxito. Ten en cuenta que un directorio vacío devuelve un array vacío [], no false. Aquí tienes un ejemplo de cómo manejar los errores:

Manejo de errores en ftp_nlist()

<?php

// $conn is assumed to be established from the previous example
$file_list = ftp_nlist($conn, '/public_html/');

if ($file_list === false) {
    echo "Failed to list directory on remote server.\n";
}

ftp_close($conn);

Compara siempre con === (igualdad estricta). Usar un if (!$file_list) no estricto trataría un directorio legítimamente vacío ([]) como un error, ya que un array vacío es falsy en PHP.

Trampas comunes

• Olvidar el modo pasivo. Llama a ftp_pasv($conn, true) tras iniciar sesión si los listados devuelven false.
• Array vacío vs false. [] significa "el directorio existe pero está vacío"; false significa que el listado falló. Distingue entre ellos con ===.
• Los nombres no incluyen la ruta. Antepón el directorio tú mismo cuando necesites una ruta completa: $dir . '/' . $name.
• Archivos ocultos. Algunos servidores omiten los archivos punto (.htaccess) de ftp_nlist(). Pasa -a como parte del argumento de directorio (por ejemplo, '-a /public_html/') en servidores que lo soporten.

Conclusión

ftp_nlist() es la forma más sencilla de obtener los nombres de los archivos en un directorio remoto. Combínala con ftp_pasv() para mayor fiabilidad, verifica el valor de retorno con ===, y recurre a ftp_rawlist() cuando también necesites metadatos de los archivos. Para el flujo completo de FTP, consulta la descripción general de PHP FTP.

Práctica