ftp_chmod()

A Função PHP ftp_chmod()

ftp_chmod() é uma função nativa do PHP que altera o modo de permissão de um arquivo ou diretório em um servidor FTP remoto — o equivalente FTP de executar chmod via shell. Ela faz parte da extensão FTP do PHP e é útil quando um script de deploy ou upload precisa tornar um arquivo legível, gravável ou executável no servidor após transferi-lo.

Esta página aborda a sintaxe, o que o valor mode realmente significa, um fluxo de trabalho completo, o tratamento do valor de retorno e os erros comuns que as pessoas cometem. Se você é novo na extensão FTP, comece com ftp_connect() e ftp_login().

Sintaxe

ftp_chmod(FTP\Connection $ftp, int $permissions, string $filename): int|false

Os parâmetros são:

• $ftp — o identificador de conexão. Até o PHP 7.4, era um resource retornado por ftp_connect(); desde o PHP 8.1, é um objeto FTP\Connection, mas é usado da mesma forma.
• $permissions — o novo modo de permissão como um inteiro octal (por exemplo, 0644, 0755).
• $filename — o caminho para o arquivo ou diretório cujas permissões você deseja alterar.

Valor de retorno: em caso de sucesso, a função retorna as novas permissões do arquivo como um inteiro; em caso de falha, retorna false. Sempre compare com === para que um modo válido como 0 (que é falso) não seja confundido com falha.

Por que as permissões são escritas em octal

Um erro comum é passar 644 em vez de 0644. O 0 inicial faz o PHP interpretar o número como octal, que é a forma como as permissões de arquivo Unix são expressas.

<?php

// 0644 (octal) is NOT the same as 644 (decimal)
var_dump(0644);          // int(420)  -> the value you actually want
var_dump(644);           // int(644)  -> wrong, this is 1204 in octal

// Each digit is owner / group / others:
//   6 = read + write (4 + 2)
//   4 = read only
// So 0644 means: owner can read & write, group and others can read.

Use 0644 para arquivos regulares que devem ser legíveis por todos, mas graváveis apenas pelo proprietário, e 0755 para diretórios ou scripts executáveis.

Uso básico

Para alterar as permissões, primeiro conecte-se com ftp_connect(), autentique-se com ftp_login(), chame ftp_chmod() e em seguida libere a conexão com ftp_close().

<?php

// 1. Open a connection to the FTP server
$ftp = ftp_connect('ftp.example.com');

// 2. Log in with your credentials
ftp_login($ftp, 'username', 'password');

// 3. Make the file readable by all, writable by the owner
ftp_chmod($ftp, 0644, '/path/to/file.txt');

// 4. Close the connection
ftp_close($ftp);

Verificando o resultado

Como o servidor FTP pode rejeitar a requisição (caminho errado, privilégios insuficientes ou um servidor que não suporta SITE CHMOD), sempre verifique o valor de retorno:

<?php

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

$result = ftp_chmod($ftp, 0644, '/path/to/file.txt');

if ($result === false) {
    echo "Failed to change permissions.\n";
} else {
    // $result is the new mode; printf with %o shows it back in octal
    printf("Permissions changed to %o successfully.\n", $result);
}

ftp_close($ftp);

Para 0644, isso imprime Permissions changed to 644 successfully. — o especificador de formato %o converte o inteiro retornado de volta para a notação octal familiar.

Erros comuns

• ftp_chmod() não é recursivo. Afeta apenas um único caminho. Para aplicar chmod em uma árvore inteira, você deve listar o diretório (consulte ftp_nlist()) e chamar ftp_chmod() em cada entrada.
• Nem todo servidor suporta o comando. ftp_chmod() depende do comando FTP SITE CHMOD, que alguns servidores (em especial muitos servidores FTP Windows IIS) não implementam. Nesses casos, ele simplesmente retornará false.
• Passe octal, não decimal. Como mostrado acima, 644 e 0644 são números diferentes.
• A ordem importa. Você precisa estar autenticado antes de chamar ftp_chmod(); chamá-la em uma conexão não autenticada falhará.

Funções relacionadas

• ftp_connect() — abre a conexão FTP.
• ftp_login() — autentica antes de qualquer operação.
• ftp_put() / ftp_get() — envia e baixa arquivos.
• ftp_close() — fecha a conexão.
• chmod() — altera as permissões no sistema de arquivos local.

Resumo

ftp_chmod() altera o modo de permissão de um arquivo ou diretório remoto via FTP. Passe o modo como um inteiro octal (0644, 0755), verifique o valor de retorno com === contra false, e lembre-se de que a operação é de caminho único e depende do suporte do servidor ao SITE CHMOD.

Prática