ftp_raw()

Entendendo a função PHP ftp_raw()

A função ftp_raw() é uma função PHP integrada que envia um comando arbitrário diretamente para um servidor FTP e retorna a resposta bruta e não interpretada do servidor. Ao contrário dos auxiliares FTP de nível mais alto, ftp_raw() não interpreta o resultado para você — ela retorna exatamente o que o servidor disse, linha por linha. Esta página explica o que a função faz, quando você realmente precisa dela e como usá-la com segurança.

O que é ftp_raw()?

FTP é um protocolo baseado em texto: os clientes enviam comandos curtos como SYST, PWD ou FEAT, e o servidor responde com linhas de status numeradas (por exemplo, 215 UNIX Type: L8). A maioria das funções FTP do PHP — como ftp_nlist(), ftp_get() e ftp_systype() — encapsula um desses comandos e analisa a resposta em um valor conveniente. ftp_raw() pula a análise e expõe o protocolo diretamente.

Ela recebe dois parâmetros:

1. ftp_stream — o identificador de conexão retornado por ftp_connect().
2. command — a string de comando FTP a ser enviada (por exemplo, 'SYST' ou 'PWD').

Em caso de sucesso, retorna um array de strings, um elemento por linha de resposta, contendo a resposta do servidor. Em caso de falha (por exemplo, uma conexão inválida), retorna false.

Quando usar?

Para tarefas cotidianas — listar, enviar, baixar — prefira as funções dedicadas; elas lidam com conexões de dados e análise para você. Use ftp_raw() apenas quando:

• Você precisar de um comando para o qual o PHP não tem um wrapper (por exemplo, FEAT para descobrir os recursos do servidor ou uma diretiva SITE personalizada).
• Você estiver depurando e quiser ver a linha de status exata que o servidor retorna.
• Você estiver implementando um comportamento de protocolo que a API de alto nível não expõe.

Observe que ftp_raw() destina-se apenas a comandos do canal de controle. Ela não pode transferir dados de arquivos — comandos como RETR ou LIST precisam de uma conexão de dados separada, razão pela qual você usa ftp_get() ou ftp_nlist() para esses casos.

Comandos brutos comuns

Sintaxe de ftp_raw()

A assinatura da função ftp_raw() é a seguinte:

ftp_raw(FTP\Connection $ftp, string $command): array

O parâmetro $ftp é a conexão retornada por ftp_connect(), e $command é a string de comando a ser enviada. Ambos são obrigatórios.

Uso de ftp_raw()

Para usar a função ftp_raw(), primeiro você precisa estabelecer uma conexão com o servidor FTP usando ftp_connect() e autenticar com ftp_login(). Veja um exemplo completo:

<?php

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

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

// Ask the server what operating system it runs
$response = ftp_raw($conn, 'SYST');

// Output the server's raw response, one line per element
echo "Server response: " . implode("\n", $response) . "\n";
// e.g. Server response: 215 UNIX Type: L8

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

Aqui nos conectamos com ftp_connect() e verificamos se a conexão foi bem-sucedida, autenticamos com ftp_login(), enviamos o comando SYST com ftp_raw() e imprimimos cada linha de resposta. O 215 é o código de resposta FTP; o texto após ele é a resposta do servidor. Por fim, liberamos a conexão com ftp_close().

Tratamento de erros em ftp_raw()

Sempre verifique o valor de retorno antes de usá-lo. ftp_raw() retorna false quando não consegue enviar o comando (por exemplo, porque a conexão não é mais válida), portanto, passar esse resultado diretamente para implode() provocaria um erro de tipo. Proteja-se contra isso:

<?php

$response = ftp_raw($conn, 'SYST');

if ($response === false) {
    echo "Failed to send the raw command to the FTP server.\n";
} else {
    echo implode("\n", $response) . "\n";
}

ftp_close($conn);

Tenha em mente que um array não false não garante que o comando em si foi bem-sucedido — significa apenas que o servidor respondeu. Inspecione o código de resposta (o número no início de cada linha, como 5xx para erros) quando precisar saber se o comando foi aceito.

Conclusão

A função ftp_raw() oferece acesso direto ao canal de controle FTP, o que é valioso para comandos que o PHP não encapsula (como FEAT) e para depuração. Para listagem, envio e download de rotina, prefira as funções dedicadas. Consulte a referência completa de funções FTP do PHP para o conjunto completo.

Prática