disk_free_space()

Introdução à Função PHP disk_free_space()

A função disk_free_space() retorna o número de bytes disponíveis no sistema de arquivos que contém um determinado diretório. É uma ferramenta essencial para administradores de servidores e desenvolvedores web que precisam monitorar o uso do disco antes de salvar uploads, gerar relatórios ou rotacionar logs — para que uma aplicação possa emitir um aviso (ou recusar a escrita) antes que o disco fique cheio.

Um ponto importante a entender desde o início: o caminho que você passa identifica um sistema de arquivos, não uma única pasta. Seja passando /, /home ou /home/user/uploads, o PHP consulta o sistema de arquivos montado em que aquele caminho reside e reporta o espaço livre para toda a montagem. O valor é um float porque os discos facilmente excedem o intervalo de um inteiro de 32 bits.

Este capítulo cobre a sintaxe, os parâmetros, o valor de retorno e exemplos práticos — incluindo como converter a contagem bruta de bytes em um tamanho legível para humanos e como calcular a porcentagem de disco utilizado.

Sintaxe

disk_free_space(string $directory): float|false

A função recebe um único argumento e retorna o número de bytes livres como um float, ou false em caso de falha (por exemplo, quando o diretório não existe). Note que diskfreespace() é um alias desta função e se comporta de forma idêntica.

Parâmetros

A função disk_free_space() recebe um parâmetro obrigatório:

• $directory — Um caminho string para qualquer arquivo ou diretório no sistema de arquivos que você deseja inspecionar. A função reporta o espaço livre da montagem que contém esse caminho, não o tamanho do diretório em si.

Valor de retorno

Em caso de sucesso, disk_free_space() retorna o espaço disponível em bytes como um float. Em caso de falha, retorna false e emite um aviso, portanto sempre valide o caminho ou verifique o resultado antes de utilizá-lo.

Exemplos

Exemplo 1: Obter o espaço livre em um sistema de arquivos

Passe o diretório raiz para inspecionar o sistema de arquivos onde o sistema operacional está instalado:

<?php

$bytes = disk_free_space("/");

echo $bytes; // e.g. 21474836480 (raw bytes)

O número exato depende da sua máquina; em um disco com cerca de 20 GB livre, isso imprime 21474836480.

Exemplo 2: Formatar o resultado como um tamanho legível

Uma contagem bruta de bytes é difícil de ler. Este auxiliar converte bytes na unidade mais próxima (KB, MB, GB, …):

<?php

function formatBytes(float $bytes, int $precision = 2): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];

    $pow = $bytes > 0 ? floor(log($bytes, 1024)) : 0;
    $pow = min($pow, count($units) - 1);

    $bytes /= 1024 ** $pow;

    return round($bytes, $precision) . ' ' . $units[$pow];
}

echo formatBytes(21474836480); // 20 GB
echo "\n";
echo formatBytes(1536);        // 1.5 KB

Saída:

20 GB
1.5 KB

Exemplo 3: Calcular a porcentagem de disco utilizado

Combine disk_free_space() com disk_total_space() para reportar o quanto um volume está cheio:

<?php

$total = disk_total_space("/");
$free  = disk_free_space("/");
$used  = $total - $free;

$percentUsed = round(($used / $total) * 100, 1);

echo "Disk usage: {$percentUsed}%";

Para um disco de 100 GB com 20 GB livres, isso imprime Disk usage: 80%.

Exemplo 4: Proteger uma escrita com verificação de erro

Como a função retorna false para um caminho inválido, verifique o resultado antes de agir sobre ele:

<?php

$path = "/var/www/uploads";
$free = disk_free_space($path);

if ($free === false) {
    echo "Could not read free space for {$path}";
} elseif ($free < 100 * 1024 * 1024) { // less than 100 MB
    echo "Warning: low disk space!";
} else {
    echo "Enough space to continue.";
}

Armadilhas comuns

• Ela mede a montagem, não a pasta. Para encontrar o tamanho do conteúdo de um diretório, você precisa somar os tamanhos dos arquivos (veja filesize()) — disk_free_space() não fará isso.
• Trate o false. Um caminho inexistente ou ilegível retorna false e dispara um aviso. Valide a entrada antes de passá-la.
• O resultado é um float. Não o compare com inteiros usando ===, e não assuma que ele cabe em um int de 32 bits — discos grandes causam overflow.
• Restrições do open_basedir podem fazer a chamada falhar em hospedagem compartilhada se o caminho estiver fora dos diretórios permitidos.

Conclusão

A função disk_free_space() reporta os bytes disponíveis no sistema de arquivos que contém um determinado caminho — essencial para monitorar o armazenamento e proteger escritas contra um disco cheio. Combine-a com disk_total_space() para calcular percentuais de uso, formate o valor bruto de bytes para exibição e sempre verifique um retorno false. Para mais informações sobre as funções integradas do PHP, consulte o capítulo funções PHP.

Prática