Notebook

[MU] Clean Image Filenames

Aula: Limpeza Automática de Nomes de Arquivos de Imagem – Substituindo o Clean Image Filenames

Objetivo: Substituir o plugin clean-image-filenames por um MU-Plugin que sanitiza automaticamente os nomes dos arquivos de imagem no momento do upload, removendo acentos, espaços, caracteres especiais e convertendo para minúsculas, gerando URLs amigáveis e SEO-friendly.

Contexto: O plugin original é útil, mas é mais um plugin externo que pode ser substituído por um código simples. Quando usuários enviam arquivos com nomes como “Foto do João (final).jpg”, isso resulta em URLs feias e potencialmente problemáticas. Nosso MU-Plugin corrige isso na hora, transformando para “foto-do-joao-final.jpg”.

Funcionalidades implementadas no nosso MU-Plugin

  • Sanitização automática de nomes de arquivos de imagem no upload (também funciona para qualquer arquivo de mídia).
  • Remove acentos: ç, ã, é, í, etc. → c, a, e, i.
  • Substitui espaços e caracteres especiais por hífen (-).
  • Converte tudo para minúsculas.
  • Remove múltiplos hífens consecutivos.
  • Remove pontos extras (mantém apenas a extensão).
  • Preserva a extensão original do arquivo.
  • Ação ocorre antes do salvamento no servidor, sem perder o original.

Código do MU-Plugin

Crie a pasta wp-content/mu-plugins/neodoor-clean-filenames/ e dentro dela o arquivo neodoor-clean-filenames.php com o conteúdo abaixo:

<?php
/**
 * Plugin Name:  Neodoor Clean Image Filenames
 * Description:  Sanitiza automaticamente nomes de arquivos de imagem no upload: remove acentos, espaços e caracteres especiais.
 * Version:      1.0
 * Author:       Reinaldo (Neodoor.neo)
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class Neodoor_Clean_Filenames {

    private static $instance = null;

    public static function get_instance() {
        if ( null === self::$instance ) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    private function __construct() {
        add_filter( 'sanitize_file_name', [ $this, 'clean_filename' ], 10, 1 );
    }

    /**
     * Limpa o nome do arquivo: remove acentos, espaços, caracteres especiais.
     * @param string $filename Nome original do arquivo
     * @return string Nome sanitizado
     */
    public function clean_filename( $filename ) {
        // Separa nome e extensão
        $ext = pathinfo( $filename, PATHINFO_EXTENSION );
        $name = pathinfo( $filename, PATHINFO_FILENAME );

        // Remove acentos e caracteres especiais (converte para ASCII)
        $name = remove_accents( $name );

        // Remove qualquer caractere que não seja letra, número, espaço, hífen ou ponto
        $name = preg_replace( '/[^a-zA-Z0-9\s\-\.]/', '', $name );

        // Substitui espaços e múltiplos hífens por um único hífen
        $name = preg_replace( '/[\s\-]+/', '-', $name );

        // Remove hífens no início ou fim
        $name = trim( $name, '-' );

        // Converte para minúsculas
        $name = strtolower( $name );

        // Se o nome ficou vazio, usa 'arquivo'
        if ( empty( $name ) ) {
            $name = 'arquivo';
        }

        // Reconstrói o nome com a extensão
        $clean_filename = $name . ( $ext ? '.' . $ext : '' );

        return $clean_filename;
    }
}

Neodoor_Clean_Filenames::get_instance();

Como testar na prática

  1. Após criar o MU-Plugin, acesse Mídia → Adicionar novo.
  2. Envie um arquivo de imagem com um nome contendo acentos, espaços e caracteres especiais, por exemplo: Foto do João (final) árvore.jpg.
  3. Após o upload, verifique o nome do arquivo na biblioteca de mídia. Ele deve aparecer como foto-do-joao-final-arvore.jpg.
  4. Teste também com nomes como Teste_#123!.png → deve virar teste-123.png.

Exemplo visual

Antes do upload:       "Café da manhã (delicioso!).jpg"
Após o upload:         "cafe-da-manha-delicioso.jpg"

Antes:                 "Imagem nº 001.PNG"
Após:                  "imagem-n-001.png"

Funcionamento técnico

  • O filtro sanitize_file_name é aplicado pelo WordPress sempre que um arquivo é enviado para a biblioteca de mídia.
  • A função remove_accents() é nativa do WordPress (desde a versão 3.0) e converte caracteres acentuados para seus equivalentes ASCII.
  • Expressões regulares removem tudo que não é letra, número, espaço, hífen ou ponto.
  • Espaços e sequências de hífens são substituídos por um único hífen.
  • O nome é convertido para minúsculas, garantindo consistência.

Personalizações possíveis

  • Manter maiúsculas: Remova a linha $name = strtolower( $name );.
  • Usar sublinhado em vez de hífen: Altere o padrão preg_replace( '/[\s\-]+/', '-', $name ); para preg_replace( '/[\s\-]+/', '_', $name );.
  • Adicionar um prefixo ou sufixo: Modifique a linha de reconstrução: $clean_filename = 'img_' . $name . ( $ext ? '.' . $ext : '' );.
  • Limitar o tamanho do nome: Adicione $name = substr( $name, 0, 50 ); antes da reconstrução.
  • Manter apenas letras e números (sem hífen): Use $name = preg_replace( '/[^a-zA-Z0-9]/', '', $name ); e depois junte com ponto.

Plugins que este MU-Plugin substitui

  • clean-image-filenames (o alvo principal)
  • smart-media-rename (parte da renomeação automática)
  • enable-media-replace (para limpeza de nomes, não para substituição)
  • Qualquer outro plugin que apenas sanitize nomes de arquivos no upload.

Observações e boas práticas

  • Funciona para qualquer arquivo de mídia: Imagens, PDFs, vídeos, etc.
  • Não afeta arquivos já existentes: A limpeza só ocorre no momento do upload. Para renomear arquivos antigos, você precisaria de um script adicional (não recomendado, pois quebra links).
  • Segurança: A função remove_accents() e os escapes previnem injeção de código. O nome final ainda passa por outras validações do WordPress.
  • Compatibilidade com Elementor e outros builders: Perfeito, pois a limpeza ocorre antes de qualquer processamento.
  • Cuidado com nomes muito curtos: Se o nome original for apenas caracteres especiais (ex: “#$%”), o plugin cairá no fallback “arquivo”. Isso evita nomes vazios.

Possíveis problemas e soluções

  • O nome do arquivo não muda: Verifique se o MU-Plugin está carregado corretamente. Adicione um error_log no início da função clean_filename para depurar.
  • Acentos não são removidos: O WordPress precisa ter a extensão PHP mbstring habilitada para remove_accents funcionar plenamente. No LocalWP, ela vem ativada por padrão.
  • Duplicidade de nomes: O WordPress automaticamente adiciona um sufixo numérico (ex: imagem-2.jpg) se o nome já existir. Nosso plugin não interfere nesse comportamento nativo.

Registro no caderno

Data:

Funcionalidade: Limpeza automática de nomes de arquivos de mídia no upload

Plugins substituídos: clean-image-filenames, smart-media-rename (parcialmente)

Tempo de implementação: ~5 minutos (criação e testes)

Observação: Este MU-Plugin é leve e não requer configuração; funciona imediatamente após criado.

★★★★★
Média: 3.0 (24 votos)