disk_total_space()

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

A função disk_total_space() no PHP retorna o tamanho total, em bytes, do sistema de arquivos (ou partição de disco) que contém um determinado diretório. Ela não mede o tamanho do diretório em si — ela informa a capacidade do volume subjacente. Isso a torna útil para administradores de servidores e desenvolvedores web que desejam monitorar a capacidade do disco, construir painéis de armazenamento ou avisar os usuários antes que um upload preencha uma partição.

Um ponto importante que frequentemente confunde os iniciantes: o argumento é qualquer caminho no volume, não o nó de dispositivo do volume. Passar /var/www, /home/user ou simplesmente / retorna o tamanho total de qualquer partição em que esses caminhos estejam. Para descobrir quanto espaço ainda está disponível, combine esta função com disk_free_space() — disk_total_space() fornece a capacidade e disk_free_space() fornece a porção não utilizada.

Esta página aborda a sintaxe, os parâmetros, o valor de retorno e exemplos práticos, incluindo como converter bytes brutos em um formato legível por humanos e como calcular a porcentagem do disco utilizado.

Sintaxe

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

A sintaxe do PHP disk_total_space()

disk_total_space(string $directory): float|false

Parâmetros

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

1. $directory: Um caminho localizado no sistema de arquivos que você deseja inspecionar. Qualquer caminho válido no volume funciona — a função o resolve para a partição à qual pertence. No Windows, use uma letra de unidade com uma barra invertida no final, por exemplo C:\ ou C:/.

Valor de Retorno

A função retorna o número total de bytes no sistema de arquivos como um float (um float é usado porque os volumes podem exceder o intervalo de um inteiro de 32 bits). Em caso de falha — por exemplo, um caminho inválido ou um erro de permissão — ela retorna false. Como um tamanho de disco válido poderia, em teoria, coincidir com um valor que o PHP trata como falsy, sempre teste o resultado com a comparação estrita !== false em vez de uma verificação de veracidade frouxa.

Exemplos

Aqui estão alguns exemplos de como usar a função disk_total_space():

Exemplo 1: Recuperar o tamanho total de um sistema de arquivos

O exemplo a seguir recupera o tamanho total do sistema de arquivos /home/:

Recuperar o tamanho total de um sistema de arquivos em PHP

echo disk_total_space("/home/");

A saída deste exemplo será o tamanho total do sistema de arquivos em bytes.

Exemplo 2: Recuperar o tamanho total de uma partição de disco

O exemplo a seguir recupera o tamanho total da partição de disco /dev/sda1:

Recuperar o tamanho total de uma partição de disco em PHP

echo disk_total_space("/dev/sda1");

A saída deste exemplo será o tamanho total da partição de disco em bytes.

Exemplo 3: Converter bytes em um formato legível por humanos

A função retorna bytes brutos, que são difíceis de ler. Converta o resultado em gigabytes e formate-o com number_format():

Converter o tamanho do disco em formato legível por humanos em PHP

$bytes = disk_total_space("/");
if ($bytes !== false) {
    echo number_format($bytes / 1024 / 1024 / 1024, 2) . " GB";
}
// e.g. "465.76 GB"

Para uma unidade que escala automaticamente (KB, MB, GB, TB, …), use um pequeno auxiliar:

Formatador de bytes com escala automática em PHP

function formatBytes(float $bytes, int $precision = 2): string {
    $units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
    $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(disk_total_space("/")); // e.g. "465.76 GB"

Exemplo 4: Calcular a porcentagem do disco utilizado

Combine disk_total_space() com disk_free_space() para relatar o quanto um volume está cheio — útil para alertas e scripts de monitoramento:

Calcular a porcentagem do disco utilizado em PHP

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

if ($total !== false && $free !== false) {
    $usedPercent = round(($total - $free) / $total * 100, 1);
    echo "Disk used: {$usedPercent}%";
}

Notas e Observações

• Ela mede o volume, não o diretório. Para obter o tamanho do conteúdo de uma pasta, some os tamanhos de seus arquivos (por exemplo, com filesize() durante a iteração), não com disk_total_space().
• Sempre verifique se há false. Um caminho ausente, uma unidade desmontada ou permissões insuficientes fazem a chamada falhar; use !== false.
• open-basedir / caminhos seguros. Se as restrições open_basedir estiverem ativas, o caminho deve estar dentro de um diretório permitido ou a chamada falhará.
• Função relacionada. disk_free_space() (e seu alias diskfreespace()) retorna o espaço disponível no mesmo volume.

Conclusão

A função disk_total_space() informa a capacidade total, em bytes, do sistema de arquivos que contém um determinado caminho. Combinada com disk_free_space(), ela permite que você construa painéis de armazenamento, imponha limites de upload e dispare alertas de pouco espaço. Lembre-se dos três pontos essenciais: passe qualquer caminho no volume de destino, trate o valor de retorno como um float e proteja-se contra falhas com uma verificação estrita !== false.

Prática