ftp_systype()

A Função PHP ftp_systype()

ftp_systype() consulta um servidor FTP conectado sobre o tipo de sistema operacional que ele executa e retorna essa resposta como uma string. Esta página explica o que a função retorna, por que a resposta é importante, como chamá-la com segurança e como ela se encaixa junto com as outras funções FTP do PHP.

Por que o tipo de sistema é importante

Os servidores FTP expõem dois comportamentos muito diferentes dependendo do sistema operacional do host:

• UNIX — os caminhos usam barras normais (/var/www), os nomes de arquivos diferenciam maiúsculas de minúsculas e as listagens de diretório seguem o formato familiar do ls -l.
• Windows_NT — os caminhos podem usar barras invertidas, os nomes de arquivos não diferenciam maiúsculas de minúsculas e os formatos de listagem são diferentes.

Conhecer o tipo de sistema antecipadamente permite construir caminhos remotos corretos, escolher o modo de transferência adequado e analisar listagens de diretório sem precisar adivinhar. O valor vem diretamente da resposta SYST do servidor, então ele reflete o que o servidor reporta — tipicamente UNIX Type: L8 ou Windows_NT.

Sintaxe

ftp_systype(FTP\Connection $ftp): string|false

ftp_systype() recebe um único argumento:

• $ftp — uma conexão FTP ativa retornada por ftp_connect() ou ftp_ssl_connect().

Ela retorna o tipo de sistema remoto como uma string em caso de sucesso (por exemplo "UNIX"), ou false em caso de falha.

Nota de versão: a partir do PHP 8.1, as funções FTP aceitam e retornam um objeto FTP\Connection. No PHP 8.0 e anteriores, o mesmo código usava um resource — seus scripts existentes continuam funcionando sem alteração, apenas o nome do tipo subjacente mudou.

Uso básico

Você deve conectar e fazer login antes de chamar ftp_systype(), depois fechar a conexão quando terminar:

<?php

// Connect to the remote FTP server
$conn = ftp_connect('ftp.example.com');

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Get the remote FTP server's system type
$system_type = ftp_systype($conn);

if ($system_type === false) {
    echo "Failed to retrieve the remote FTP server's system type.\n";
} else {
    echo "The remote FTP server's system type is: $system_type\n";
}

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

Em um servidor FTP Linux típico, isso imprime algo como:

The remote FTP server's system type is: UNIX

Observe que a resposta bruta do SYST é frequentemente mais longa (UNIX Type: L8); o PHP normaliza para a primeira palavra, portanto geralmente você recebe apenas UNIX ou Windows_NT.

Adaptando o comportamento ao tipo de sistema

O motivo prático para chamar ftp_systype() é ramificar sua lógica. Por exemplo, você pode escolher um separador de caminho com base no host:

<?php

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

$type = ftp_systype($conn);

$separator = ($type === 'Windows_NT') ? '\\' : '/';
$remotePath = 'public_html' . $separator . 'index.html';

echo "Using path: $remotePath\n";

ftp_close($conn);

Em um servidor UNIX, isso constrói public_html/index.html; em um servidor Windows, constrói public_html\index.html.

Tratamento de erros

ftp_systype() retorna false em caso de falha, e ftp_connect() também retorna false se não conseguir alcançar o host. Verifique ambos antes de confiar no resultado:

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false) {
    echo "Failed to connect to the remote FTP server.\n";
} else {
    $system_type = ftp_systype($conn);

    if ($system_type === false) {
        echo "Failed to retrieve the remote FTP server's system type.\n";
    } else {
        echo "The remote FTP server's system type is: $system_type\n";
    }

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

Sempre teste o valor de retorno com a comparação estrita === false. Uma verificação simples (!$type) pode dar falso positivo se algum servidor retornar uma string vazia mas válida.

Armadilhas comuns

• Chamá-la antes de fazer login. Alguns servidores recusam SYST até que a autenticação seja concluída. Faça login primeiro.
• Confiar na string cegamente. O valor é o que o servidor anuncia e alguns servidores reportam strings incomuns. Faça a correspondência em uma substring (str_contains($type, 'Windows')) em vez de uma correspondência exata quando precisar ser robusto.
• Confundi-la com transferência de arquivos. ftp_systype() apenas reporta o sistema operacional — não move arquivos. Use ftp_get() e ftp_put() para downloads e uploads.

Funções FTP relacionadas

• ftp_connect() — abre a conexão que você passa para ftp_systype().
• ftp_login() — autentica antes de emitir comandos.
• ftp_pwd() — obtém o diretório remoto atual.
• ftp_close() — libera a conexão quando terminar.

Conclusão

ftp_systype() é uma função pequena mas útil: uma única chamada informa se você está se comunicando com um servidor FTP UNIX ou Windows, permitindo construir caminhos corretos e analisar listagens de forma confiável. Combine-a com verificação rigorosa de erros e as funções FTP relacionadas acima para scripts de transferência de arquivos robustos.

Prática