ftp_get()

¿Qué es ftp_get()?

ftp_get() es una función integrada de PHP que descarga un archivo de un servidor FTP y lo escribe en un archivo local en tu máquina. Es la contrapartida de lectura de ftp_put(), que sube archivos. Úsala siempre que necesites obtener un archivo (una copia de seguridad, un registro, un informe) desde un servidor remoto a través de FTP.

Esta página explica qué hace ftp_get(), sus parámetros y valor de retorno, un flujo de trabajo completo (conectar → iniciar sesión → descargar → cerrar), cómo manejar fallos y los errores comunes que pueden surgir (modo de transferencia, modo pasivo y reanudación de descargas parciales).

Parámetros

ftp_get() acepta cinco parámetros: tres obligatorios y dos opcionales:

Valor de retorno

La función devuelve un boolean: true si tiene éxito, false si falla. Compruébalo siempre: una descarga fallida no lanza una excepción por defecto.

FTP_BINARY vs FTP_ASCII

FTP_BINARY transfiere el archivo byte a byte y es la opción correcta para casi todo: imágenes, PDFs, archivos comprimidos, ejecutables e incluso la mayoría de los archivos de texto. FTP_ASCII realiza una conversión automática de finales de línea entre las convenciones del servidor y del cliente, así que úsalo solo para archivos de texto plano donde realmente desees esa conversión. Usar FTP_ASCII con un archivo binario lo corromperá, por lo que ante la duda elige FTP_BINARY.

Sintaxis de ftp_get()

bool ftp_get ( resource $ftp_stream , string $local_file , string $remote_file [, int $mode = FTP_BINARY [, int $resumepos = 0 ]] )

Nota: En PHP 8.1+, el tipo resource para las conexiones FTP fue reemplazado por un objeto Ftp\Connection, y el parámetro mode pasó a ser opcional (con valor predeterminado FTP_BINARY). La firma heredada con resource se mantiene por compatibilidad con versiones anteriores — no es necesario cambiar tu código.

Uso de ftp_get()

Para usar ftp_get(), primero debes establecer una conexión con ftp_connect() y autenticarte con ftp_login(). A continuación se muestra el flujo completo:

Descargando un archivo con ftp_get()

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

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

// 3. Switch to passive mode (required behind most firewalls/NAT)
ftp_pasv($conn, true);

// 4. Download the remote file into a local path
if (ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY)) {
    echo "File retrieved successfully.\n";
} else {
    echo "Failed to retrieve the file.\n";
}

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

Los pasos son siempre los mismos: conectar, iniciar sesión, activar opcionalmente el modo pasivo, descargar y luego cerrar. El modo pasivo (ftp_pasv()) se habilita aquí porque la mayoría de los clientes están detrás de un firewall o NAT y las transferencias en modo activo podrían bloquearse o fallar. Ten en cuenta que debes llamar a ftp_pasv() después de iniciar sesión.

Manejo de errores en ftp_get()

ftp_get() devuelve false en caso de error en lugar de lanzar una excepción, por lo que debes comprobar el valor de retorno explícitamente. Las causas más comunes son un archivo remoto inexistente, permisos insuficientes o una ruta local que no tiene permisos de escritura. PHP también emite una advertencia, que puedes capturar para registrar:

Capturando el motivo de un fallo en la descarga

<?php
// $conn is an open, logged-in FTP connection
$ok = @ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($ok === false) {
    $error = error_get_last();
    echo "Failed to retrieve the file: " . ($error['message'] ?? 'unknown error') . "\n";
} else {
    echo "File retrieved successfully.\n";
}

El @ suprime la advertencia de PHP en bruto para que puedas formatear tu propio mensaje, mientras que error_get_last() te proporciona el detalle subyacente para registrarlo.

Reanudación de una descarga interrumpida

El parámetro opcional resumepos te permite continuar una descarga que se interrumpió, en lugar de comenzar de nuevo. Pasa el tamaño actual del archivo local parcialmente descargado como desplazamiento en bytes:

Reanudando con resumepos

<?php
// $conn is an open, logged-in FTP connection
$local = '/local/directory/big_archive.zip';

// Continue from however many bytes we already have locally
$offset = file_exists($local) ? filesize($local) : 0;

if (ftp_get($conn, $local, 'big_archive.zip', FTP_BINARY, $offset)) {
    echo "Download complete.\n";
} else {
    echo "Resume failed.\n";
}

La reanudación solo funciona de forma fiable con FTP_BINARY y en servidores que admiten el comando REST. Para transferencias grandes también puedes usar la variante no bloqueante ftp_nb_get(), que descarga en segundo plano para que tu script pueda realizar otras tareas.

Funciones relacionadas

• ftp_put() — sube un archivo local al servidor (la operación inversa de ftp_get()).
• ftp_fget() — descarga en un manejador de archivo ya abierto en lugar de una ruta.
• ftp_size() — obtiene el tamaño de un archivo remoto antes de descargarlo.
• ftp_connect() y ftp_login() — abre y autentica la conexión.
• ftp_close() — cierra la conexión cuando hayas terminado.

Resumen

ftp_get() descarga un archivo remoto a través de FTP y lo guarda localmente, devolviendo true si tiene éxito y false si falla. Conéctate e inicia sesión primero, prefiere FTP_BINARY a menos que necesites específicamente la conversión de finales de línea ASCII, habilita el modo pasivo cuando estés detrás de un firewall y comprueba siempre el valor de retorno para que los fallos no pasen desapercibidos.

Práctica