ftp_exec()

A Função PHP ftp_exec()

ftp_exec() era uma função nativa do PHP que solicitava a um servidor FTP remoto que executasse um comando shell em seu nome. Ela foi descontinuada no PHP 5.3.0 e removida no PHP 7.0.0, portanto não está disponível em nenhuma versão moderna do PHP. Esta página explica o que ela fazia, por que desapareceu e — mais importante — como executar comandos remotos com segurança hoje em dia.

Se você só precisa gerenciar arquivos via FTP (upload, download, listar, renomear), não é necessária execução de comandos. Consulte a visão geral do FTP no PHP e funções como ftp_connect() e ftp_raw().

O Que ftp_exec() Fazia

A função recebia dois parâmetros e retornava um boolean:

Ela retornava true se o servidor aceitasse e executasse o comando, e false em caso de falha. Internamente, enviava o comando FTP SITE EXEC, que só funciona se o servidor habilitar explicitamente esse recurso.

Sintaxe Histórica

bool ftp_exec(resource $ftp_stream, string $command)

A assinatura usava um identificador de conexão do tipo resource. A classe orientada a objetos FTP\Connection foi adicionada no PHP 8.0 — muito depois de ftp_exec() já ter sido removida —, portanto as duas nunca coexistiram.

Por Que Foi Removida

Dois problemas tornaram ftp_exec() inutilizável na prática:

• Quase nunca estava disponível. O SITE EXEC permite que um cliente FTP execute comandos shell arbitrários no servidor. Isso representa um risco clássico de execução remota de código, portanto servidores populares como vsftpd e ProFTPD o distribuem desabilitado, e a maioria dos hosts nunca o ativou.
• O próprio FTP é inseguro. O FTP simples transmite credenciais e dados em texto claro. Adicionar execução de comandos sobre um protocolo não criptografado é exatamente a direção errada. (Se precisar usar FTP para arquivos, prefira ftp_ssl_connect() para FTPS.)

Como o recurso era tanto perigoso quanto efetivamente morto, o PHP o descontinuou na versão 5.3.0 e o removeu completamente na 7.0.0.

Execução Remota de Comandos com Segurança Hoje

Para executar um comando em uma máquina remota a partir do PHP, use SSH, não FTP. Existem duas opções padrão:

• A extensão ssh2 — uma extensão PECL nativa que encapsula a libssh2.
• phpseclib — uma biblioteca escrita inteiramente em PHP que não requer extensão, tornando-a ideal em hospedagem compartilhada.

Opção 1: A Extensão ssh2

<?php

// 1. Open an SSH connection (default SSH port is 22)
$conn = ssh2_connect('example.com', 22);
if (!$conn) {
    die("Could not connect to server.\n");
}

// 2. Authenticate
if (!ssh2_auth_password($conn, 'username', 'password')) {
    die("SSH authentication failed.\n");
}

// 3. Run the command
$stream = ssh2_exec($conn, 'ls -al');
if ($stream === false) {
    die("Failed to execute command.\n");
}

// 4. Read its output
stream_set_blocking($stream, true);
$output = stream_get_contents($stream);

echo $output;

ssh2_connect() abre o canal criptografado, ssh2_auth_password() realiza o login e ssh2_exec() executa o comando e retorna um stream. Definir o stream como bloqueante com stream_set_blocking() garante que você leia a saída completa antes de o script continuar — uma armadilha comum que, do contrário, produz resultados vazios.

Opção 2: phpseclib (Sem Extensão Necessária)

<?php

require 'vendor/autoload.php';

use phpseclib3\Net\SSH2;

$ssh = new SSH2('example.com');
if (!$ssh->login('username', 'password')) {
    exit('SSH login failed');
}

echo $ssh->exec('ls -al');

Como o phpseclib é escrito inteiramente em PHP, funciona em qualquer lugar onde o PHP funcione — sem build PECL, sem extensão no servidor. Instale-o com composer require phpseclib/phpseclib.

Tratamento de Erros

Sempre verifique o valor de retorno antes de ler a saída. Com a extensão ssh2, ssh2_exec() retorna false em caso de falha:

<?php

$stream = ssh2_exec($conn, 'ls -al');

if ($stream === false) {
    echo "Failed to execute the command.\n";
} else {
    stream_set_blocking($stream, true);
    echo stream_get_contents($stream);
}

Para maior segurança, prefira autenticação por chave (ssh2_auth_pubkey_file()) em vez de senhas e nunca interpole entradas não confiáveis diretamente em uma string de comando — escape os argumentos com escapeshellarg() para evitar injeção de comandos.

Principais Conclusões

• ftp_exec() executava um comando em um servidor FTP via SITE EXEC; foi descontinuada no PHP 5.3.0 e removida no PHP 7.0.0.
• Foi removida porque o SITE EXEC representa um risco de execução remota de código que a maioria dos servidores desabilita, e o FTP não é criptografado.
• Para comandos remotos hoje, use SSH através da extensão ssh2 ou do phpseclib — nunca FTP.
• Para transferências simples de arquivos, a extensão FTP ainda funciona bem; comece com ftp_connect(), ftp_login() e a visão geral do FTP no PHP.

Prática