Como tratar nome de arquivo em PHP sem acentos e caracteres especiais

Ao trabalhar com upload de arquivos em PHP, é muito comum enfrentar problemas com nomes contendo acentos, espaços e caracteres especiais. Isso pode gerar inconsistências em URLs, falhas em integrações e até erros no sistema operacional. Neste post, você vai aprender como padronizar nomes de arquivos de forma segura e reutilizável.

O Problema

Arquivos enviados por usuários geralmente vêm com nomes como:

• Relatório de Férias 2024.PDF
• Comprovante João (Final).jpg
• Planilha#Financeira!.xlsx

Esses formatos podem causar:

• Problemas em URLs (encoding)
• Incompatibilidade entre sistemas
• Dificuldade de organização e versionamento

A Solução

A função abaixo resolve esses problemas ao normalizar o nome do arquivo:

• Remove acentos
• Substitui caracteres especiais por hífen
• Padroniza para minúsculo
• Mantém a extensão original
• Permite adicionar timestamp e sigla

Função completa

/**
 * Trata o nome do arquivo removendo acentos e caracteres especiais,
 * mantendo a extensão e permitindo sufixos.
 */
function tratarNomeArquivo(string $string, bool $includeTime = false, string $sigla = ''): string
{
    $pathInfo = pathinfo($string);
    $nome = $pathInfo['filename'];
    $extensao = isset($pathInfo['extension']) ? $pathInfo['extension'] : '';

    $nome = trim($nome);
    $nome = mb_strtolower($nome, "UTF-8");
    
    $acentos = 'ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýýþÿŔŕ';
    $semAcento = 'aaaaaaaceeeeiiiidnoooooouuuuybsaaaaaaaceeeeiiiidnoooooouuuuyybyRr';
    
    $nome = strtr(utf8_decode($nome), utf8_decode($acentos), $semAcento);
    $nome = utf8_encode($nome);

    $nome = str_replace(".", "", $nome);
    $nome = preg_replace("/[^0-9a-z]+/", '-', $nome);
    $nome = trim($nome, '-'); 

    if ($includeTime) {
        $nome .= "_" . time();
    }
    
    if (!empty($sigla)) {
        $nome .= "_" . trim($sigla);
    }

    $nomeFinal = !empty($extensao) ? $nome . "." . strtolower($extensao) : $nome;
    
    return $nomeFinal;
}

Exemplos de Uso

Nome simples

echo tratarNomeArquivo("Relatório de Férias 2024.PDF");

Resultado: relatorio-de-ferias-2024.pdf

Com timestamp

echo tratarNomeArquivo("Relatório de Férias 2024.PDF", true);

Resultado: relatorio-de-ferias-2024_1712584800.pdf

Com sigla

echo tratarNomeArquivo("Relatório de Férias 2024.PDF", false, "RH");

Resultado: relatorio-de-ferias-2024_RH.pdf

Completo (timestamp + sigla)

echo tratarNomeArquivo("Relatório de Férias 2024.PDF", true, "RH");

Resultado: relatorio-de-ferias-2024_1712584800_RH.pdf

Arquivo com caracteres especiais

echo tratarNomeArquivo("Comprovante João (Final).jpg");

Resultado: comprovante-joao-final.jpg

Sem extensão

echo tratarNomeArquivo("arquivo_teste");

Resultado: arquivo-teste

Uso em upload

$nomeOriginal = $_FILES['arquivo']['name'];
$nomeTratado = tratarNomeArquivo($nomeOriginal, true, "USR");

move_uploaded_file($_FILES['arquivo']['tmp_name'], "uploads/" . $nomeTratado);

Conclusão

Padronizar nomes de arquivos é essencial para evitar problemas técnicos e manter consistência no sistema. Essa função oferece uma solução simples, eficiente e reutilizável para qualquer projeto PHP.

Além disso, com o uso de timestamp e siglas, você ganha rastreabilidade e controle de versões sem depender de hash.