ftp_put()

La función ftp_put() de PHP

ftp_put() es una función integrada de PHP que sube un archivo local a un servidor FTP remoto. Es la contraparte de subida de ftp_get(), que descarga un archivo remoto a tu máquina. Esta página cubre la firma, los modos de transferencia (fundamentales), un flujo de trabajo completo, el manejo de errores y los problemas más comunes en producción.

Se utiliza ftp_put() después de abrir una conexión con ftp_connect() y autenticarse con ftp_login().

Sintaxis

ftp_put(
    FTP\Connection $ftp,
    string $remote_filename,
    string $local_filename,
    int $mode = FTP_BINARY
): bool

Devuelve true en caso de éxito y false en caso de error.

Nota de versión: Antes de PHP 8.1 el primer argumento era un resource devuelto por ftp_connect(). A partir de PHP 8.1 es un objeto FTP\Connection. El código no cambia — se sigue pasando lo que devuelve ftp_connect() — pero las comprobaciones con is_resource() ya no funcionan sobre él.

Modo binario vs. ASCII

Elegir el modo incorrecto es la causa más habitual de "la subida funcionó pero el archivo está corrupto":

• FTP_BINARY transfiere los bytes exactamente tal cual. Úsalo por defecto para todo — imágenes, archivos comprimidos, PDFs, ejecutables e incluso texto en la práctica.
• FTP_ASCII reescribe los finales de línea (\n ↔ \r\n) para adaptarlos a la plataforma de destino. Solo tiene sentido para texto plano, y destruirá silenciosamente cualquier archivo binario. En caso de duda, usa FTP_BINARY.

Una subida completa

Comprueba siempre los valores de retorno de cada llamada FTP en lugar de asumir que el paso tuvo éxito:

<?php

// 1. Open a connection (false on failure)
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    exit("Could not connect to FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("FTP login failed.\n");
}

// 3. Behind a firewall/NAT? Passive mode is almost always required.
ftp_pasv($ftp, true);

// 4. Upload: local file -> remote path, binary mode
$ok = ftp_put($ftp, '/public_html/index.html', './build/index.html', FTP_BINARY);

echo $ok
    ? "Upload succeeded.\n"
    : "Upload failed.\n";

// 5. Always close
ftp_close($ftp);

Ten en cuenta el orden de los argumentos: la ruta remota de destino va primero, la fuente local va segunda — al revés de lo que mucha gente espera. Confundirlos hace que PHP intente leer un archivo local inexistente y la llamada falla.

Manejo de errores

ftp_put() devuelve false y emite una advertencia de PHP al fallar. Convierte eso en un resultado claro y accionable en lugar de dejar que una advertencia inesperada se filtre en tu salida:

<?php

$remote = '/public_html/index.html';
$local  = './build/index.html';

// Catch the "no such local file" case before touching the network.
if (!is_readable($local)) {
    exit("Local file '$local' is missing or unreadable.\n");
}

if (!ftp_put($ftp, $remote, $local, FTP_BINARY)) {
    // Common causes: wrong remote directory, no write permission,
    // disk quota exceeded, or passive mode not enabled.
    echo "Failed to upload '$local' to '$remote'.\n";
} else {
    echo "Uploaded '$local' to '$remote'.\n";
}

ftp_close($ftp);

Causas frecuentes de error

• Orden incorrecto de argumentos — la ruta remota y la ruta local intercambiadas.
• Modo pasivo no configurado — la mayoría de servidores detrás de NAT necesitan ftp_pasv($ftp, true) después del inicio de sesión.
• Directorio remoto inexistente — ftp_put() no crea carpetas; usa ftp_mkdir() primero.
• Sin permiso de escritura o cuota superada en el servidor.
• Modo de transferencia incorrecto que corrompe un archivo binario (usa FTP_BINARY).

Subida desde un flujo abierto

Si tus datos ya son un manejador de archivo abierto (o provienen de un envoltorio de flujo en lugar de una ruta en disco), usa ftp_fput() en su lugar — acepta un recurso de flujo en lugar de un nombre de archivo local.

Conclusión

ftp_put() sube un archivo local a un servidor FTP remoto. Recuerda las tres cosas que causan la mayoría de los problemas: pasa la ruta remota primero, mantén FTP_BINARY a menos que tengas una razón específica para usar ASCII y comprueba cada valor de retorno. Para transferencias no bloqueantes que no detengan tu script, consulta ftp_nb_put().

Práctica