diskfreespace()

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

A função diskfreespace() retorna o número de bytes de espaço livre disponível no sistema de arquivos ou partição de disco que contém um determinado diretório. Ela é útil quando você precisa verificar a capacidade antes de gravar arquivos grandes, criar dashboards de monitoramento de servidor ou alertar um administrador de que o armazenamento está baixo.

diskfreespace() é simplesmente um alias de disk_free_space() — ambos os nomes chamam exatamente a mesma implementação em C e se comportam de forma idêntica. A versão com sublinhado é o nome canônico no manual do PHP; a versão sem sublinhado existe por compatibilidade com versões anteriores. Novos códigos devem preferir disk_free_space(), mas você ainda encontrará diskfreespace() em bases de código mais antigas.

Este capítulo aborda a sintaxe, o único argumento que ela recebe, o que ela retorna, exemplos executáveis e os erros comuns.

Sintaxe

diskfreespace(string $directory): float|false

A função recebe um argumento obrigatório e retorna o espaço livre como um número de ponto flutuante em bytes. Um float é usado (em vez de um int) porque os discos modernos podem conter muito mais bytes do que um inteiro de 32 bits consegue representar. Em caso de falha, retorna false.

Parâmetro

• $directory (string, obrigatório) — Um diretório no sistema de arquivos que você deseja inspecionar (por exemplo "/", "C:", ou "." para o diretório atual). O PHP mede a partição em que esse diretório reside, não o tamanho do próprio diretório. O caminho deve ser um diretório; passar um arquivo regular gera um aviso e retorna false.

Valor de retorno

• Em caso de sucesso: um float — o número de bytes livres na partição.
• Em caso de falha (o caminho não existe, não é um diretório ou não pode ser lido): false, mais um E_WARNING.

Exemplos

Exemplo 1: Espaço livre na partição atual

A chamada portável mais segura usa "." (o diretório atual), que funciona em qualquer sistema operacional:

<?php
$bytes = diskfreespace(".");
echo $bytes, " bytes free\n";

A saída é uma contagem bruta de bytes, como:

123456789012 bytes free

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

Bytes brutos são difíceis de ler. Este auxiliar converte o valor para KB / MB / GB / TB:

<?php
function humanSize(float $bytes): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $i = 0;
    while ($bytes >= 1024 && $i < count($units) - 1) {
        $bytes /= 1024;
        $i++;
    }
    return round($bytes, 2) . ' ' . $units[$i];
}

echo humanSize(123456789012); // 114.98 GB

Saída:

114.98 GB

Exemplo 3: Verificar um caminho específico e tratar falhas

Sempre verifique se o resultado é false antes de usá-lo, pois o caminho pode ser inválido:

<?php
$path = "/no/such/directory";
$free = @diskfreespace($path);

if ($free === false) {
    echo "Could not read free space for $path";
} else {
    echo "Free: $free bytes";
}

O @ suprime o aviso para que você possa tratar o erro de forma adequada com sua própria mensagem.

Erros comuns

• Mede a partição, não a pasta. Chamar diskfreespace("/var/www") reporta o espaço livre no disco em que /var/www reside, não quanto aquela pasta específica utiliza.
• Passe um diretório, não um arquivo. Um caminho de arquivo (por exemplo, "/etc/hosts") retorna false e emite um aviso.
• Caminhos no Windows. Use uma letra de unidade como "C:" em vez de um caminho no estilo Unix.
• Espaço livre vs. espaço utilizável. Em alguns sistemas de arquivos, uma parte do espaço "livre" é reservada para o usuário root, portanto o valor pode diferir ligeiramente do que um processo não-root pode realmente usar.

Funções relacionadas

• disk_free_space() — o nome canônico para esta mesma função.
• disk_total_space() — capacidade total da partição; combine com esta função para calcular o percentual utilizado.
• filesize() — tamanho de um arquivo individual em bytes.

Conclusão

diskfreespace() retorna os bytes livres na partição que contém um determinado diretório e é um alias de disk_free_space(). Use-a para monitorar o armazenamento e proteger contra gravações que ultrapassariam o disco, sempre verifique se o valor de retorno é false e combine-a com disk_total_space() quando precisar calcular o percentual de espaço restante.

Prática