ftp_site()

Entendendo a Função PHP ftp_site()

A função ftp_site() é uma função PHP integrada que envia um comando SITE para um servidor FTP. SITE é um comando FTP genérico para instruções que ficam fora do protocolo FTP padrão — coisas que cada fornecedor de servidor implementa à sua maneira, como alterar permissões de arquivos, ajustar tempos limite de inatividade ou executar tarefas de manutenção específicas do servidor.

Como o significado de um comando SITE é definido inteiramente pelo servidor remoto, ftp_site() é a saída de emergência que você usa quando não existe nenhuma função PHP FTP dedicada para o que você precisa. Este artigo explica o que a função faz, quando usá-la (e quando não usá-la), e como lidar com seu resultado de forma segura.

Para trabalhar com ela, primeiro abra uma conexão com ftp_connect() e autentique-se com ftp_login(). Consulte a visão geral do PHP FTP para ver a família completa de funções.

O que é ftp_site()?

A função recebe dois parâmetros:

1. ftp — A conexão FTP retornada por ftp_connect() (ou ftp_ssl_connect()).
2. command — A string do comando SITE bruto a ser enviada, sem a palavra-chave inicial SITE (o PHP a adiciona automaticamente).

Ela retorna true se o servidor aceitou o comando e false em caso de falha. Um resultado true significa apenas que o servidor aceitou o comando — não garante que a ação subjacente (por exemplo, a mudança de permissão) tenha sido bem-sucedida, pois o comportamento de SITE é definido pelo servidor.

Sintaxe de ftp_site()

A sintaxe da função ftp_site() é a seguinte:

Sintaxe de ftp_site()

ftp_site(FTP\Connection $ftp, string $command): bool

A partir do PHP 8.1, o primeiro argumento é um objeto FTP\Connection (em versões anteriores era um resource). O argumento command é a instrução SITE a ser enviada — por exemplo, CHMOD 644 file.txt. Você passa apenas a parte após SITE; o PHP acrescenta a palavra-chave automaticamente.

Uso de ftp_site()

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

Uso de ftp_site()

<?php

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

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

// Send the SITE command
ftp_site($conn, 'CHMOD 755 /public_html/index.php');

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

Neste exemplo, nos conectamos com ftp_connect(), autenticamos com ftp_login(), enviamos SITE CHMOD 755 para alterar as permissões de index.php e, por fim, fechamos a conexão com ftp_close().

Nota: Comandos SITE são específicos do servidor. SITE CHMOD não é universalmente suportado em todos os servidores FTP. Para alterações padrão de permissões de arquivo, prefira a função dedicada ftp_chmod(), que é portável e retorna o novo valor de permissão. Use ftp_site() apenas para ações que não possuem uma função FTP dedicada.

Comandos SITE comuns

O conjunto exato de comandos suportados depende do software do servidor (ProFTPD, vsftpd, Pure-FTPd, etc.), mas alguns são amplamente disponíveis:

Em caso de dúvida, execute SITE HELP para descobrir o que um determinado servidor aceita:

Descobrindo comandos SITE suportados

<?php

$conn = ftp_connect('ftp.example.com');
ftp_login($conn, 'username', 'password');

if (ftp_site($conn, 'HELP')) {
    echo "Server accepted the SITE HELP command.\n";
}

ftp_close($conn);

Tratamento de erros em ftp_site()

É importante tratar os erros corretamente ao usar a função ftp_site(). Se a função retornar false, significa que a operação não foi bem-sucedida. Veja um exemplo de como tratar erros:

Tratamento de erros em ftp_site()

<?php

if (!ftp_site($conn, 'CHMOD 755 /public_html/index.php')) {
    echo "Failed to send SITE command.\n";
}

ftp_close($conn);

Ao verificar o valor de retorno, você evita continuar silenciosamente após um comando rejeitado pelo servidor. Observe que ftp_site() retorna false tanto quando a conexão é inválida quanto quando o servidor simplesmente não reconhece o comando — portanto, um resultado false é o seu sinal para recorrer a uma função dedicada ou a uma abordagem diferente.

ftp_site() vs. ftp_raw() e ftp_exec()

ftp_site() está intimamente relacionada a outras duas funções de "enviar uma instrução bruta", e é útil saber quando escolher cada uma:

• ftp_site() — envia um único comando SITE e retorna um boolean. Use para ações específicas do servidor, como CHMOD ou UMASK.
• ftp_raw() — envia qualquer comando FTP bruto (não apenas SITE) e retorna a resposta completa do servidor como um array, para que você possa ler o código de status por conta própria. Use quando precisar inspecionar a resposta.
• ftp_exec() — executa um programa no servidor via SITE EXEC, quando suportado. Use apenas em servidores que você controla e confia.

Para operações cotidianas (upload, download, listagem, renomeação), prefira as funções específicas abordadas na visão geral do PHP FTP; elas são mais portáveis do que comandos SITE construídos manualmente.

Conclusão

A função ftp_site() permite enviar comandos SITE específicos do servidor quando nenhuma função PHP FTP dedicada se aplica. Sempre verifique seu valor de retorno, lembre-se que um envio bem-sucedido não é o mesmo que uma ação bem-sucedida, e prefira funções portáveis como ftp_chmod() sempre que existir uma.

Prática