{"id":287,"date":"2026-05-13T16:00:23","date_gmt":"2026-05-13T19:00:23","guid":{"rendered":"http:\/\/neodoor.neo\/?p=287"},"modified":"2026-05-21T09:03:51","modified_gmt":"2026-05-21T12:03:51","slug":"clean-image-filenames","status":"publish","type":"post","link":"https:\/\/www.portanova.com.br\/notebook\/clean-image-filenames\/","title":{"rendered":"[MU] Clean Image Filenames"},"content":{"rendered":"<h2>Aula: Limpeza Autom\u00e1tica de Nomes de Arquivos de Imagem \u2013 Substituindo o Clean Image Filenames<\/h2>\n<p><strong>Objetivo:<\/strong> Substituir o plugin <code>clean-image-filenames<\/code> por um MU-Plugin que sanitiza automaticamente os nomes dos arquivos de imagem no momento do upload, removendo acentos, espa\u00e7os, caracteres especiais e convertendo para min\u00fasculas, gerando URLs amig\u00e1veis e SEO-friendly.<\/p>\n<p><strong>Contexto:<\/strong> O plugin original \u00e9 \u00fatil, mas \u00e9 mais um plugin externo que pode ser substitu\u00eddo por um c\u00f3digo simples. Quando usu\u00e1rios enviam arquivos com nomes como &#8220;Foto do Jo\u00e3o (final).jpg&#8221;, isso resulta em URLs feias e potencialmente problem\u00e1ticas. Nosso MU-Plugin corrige isso na hora, transformando para &#8220;foto-do-joao-final.jpg&#8221;.<\/p>\n<h3>Funcionalidades implementadas no nosso MU-Plugin<\/h3>\n<ul>\n<li>Sanitiza\u00e7\u00e3o autom\u00e1tica de nomes de arquivos de imagem no upload (tamb\u00e9m funciona para qualquer arquivo de m\u00eddia).<\/li>\n<li>Remove acentos: \u00e7, \u00e3, \u00e9, \u00ed, etc. \u2192 c, a, e, i.<\/li>\n<li>Substitui espa\u00e7os e caracteres especiais por h\u00edfen (<code>-<\/code>).<\/li>\n<li>Converte tudo para min\u00fasculas.<\/li>\n<li>Remove m\u00faltiplos h\u00edfens consecutivos.<\/li>\n<li>Remove pontos extras (mant\u00e9m apenas a extens\u00e3o).<\/li>\n<li>Preserva a extens\u00e3o original do arquivo.<\/li>\n<li>A\u00e7\u00e3o ocorre antes do salvamento no servidor, sem perder o original.<\/li>\n<\/ul>\n<h3>C\u00f3digo do MU-Plugin<\/h3>\n<p>Crie a pasta <code>wp-content\/mu-plugins\/neodoor-clean-filenames\/<\/code> e dentro dela o arquivo <strong><code>neodoor-clean-filenames.php<\/code><\/strong> com o conte\u00fado abaixo:<\/p>\n<pre><code>&lt;?php\n\/**\n * Plugin Name:  Neodoor Clean Image Filenames\n * Description:  Sanitiza automaticamente nomes de arquivos de imagem no upload: remove acentos, espa\u00e7os e caracteres especiais.\n * Version:      1.0\n * Author:       Reinaldo (Neodoor.neo)\n *\/\n\nif ( ! defined( 'ABSPATH' ) ) {\n    exit;\n}\n\nclass Neodoor_Clean_Filenames {\n\n    private static $instance = null;\n\n    public static function get_instance() {\n        if ( null === self::$instance ) {\n            self::$instance = new self();\n        }\n        return self::$instance;\n    }\n\n    private function __construct() {\n        add_filter( 'sanitize_file_name', [ $this, 'clean_filename' ], 10, 1 );\n    }\n\n    \/**\n     * Limpa o nome do arquivo: remove acentos, espa\u00e7os, caracteres especiais.\n     * @param string $filename Nome original do arquivo\n     * @return string Nome sanitizado\n     *\/\n    public function clean_filename( $filename ) {\n        \/\/ Separa nome e extens\u00e3o\n        $ext = pathinfo( $filename, PATHINFO_EXTENSION );\n        $name = pathinfo( $filename, PATHINFO_FILENAME );\n\n        \/\/ Remove acentos e caracteres especiais (converte para ASCII)\n        $name = remove_accents( $name );\n\n        \/\/ Remove qualquer caractere que n\u00e3o seja letra, n\u00famero, espa\u00e7o, h\u00edfen ou ponto\n        $name = preg_replace( '\/[^a-zA-Z0-9\\s\\-\\.]\/', '', $name );\n\n        \/\/ Substitui espa\u00e7os e m\u00faltiplos h\u00edfens por um \u00fanico h\u00edfen\n        $name = preg_replace( '\/[\\s\\-]+\/', '-', $name );\n\n        \/\/ Remove h\u00edfens no in\u00edcio ou fim\n        $name = trim( $name, '-' );\n\n        \/\/ Converte para min\u00fasculas\n        $name = strtolower( $name );\n\n        \/\/ Se o nome ficou vazio, usa 'arquivo'\n        if ( empty( $name ) ) {\n            $name = 'arquivo';\n        }\n\n        \/\/ Reconstr\u00f3i o nome com a extens\u00e3o\n        $clean_filename = $name . ( $ext ? '.' . $ext : '' );\n\n        return $clean_filename;\n    }\n}\n\nNeodoor_Clean_Filenames::get_instance();\n<\/code><\/pre>\n<h3>Como testar na pr\u00e1tica<\/h3>\n<ol>\n<li>Ap\u00f3s criar o MU-Plugin, acesse <strong>M\u00eddia \u2192 Adicionar novo<\/strong>.<\/li>\n<li>Envie um arquivo de imagem com um nome contendo acentos, espa\u00e7os e caracteres especiais, por exemplo: <code>Foto do Jo\u00e3o (final) \u00e1rvore.jpg<\/code>.<\/li>\n<li>Ap\u00f3s o upload, verifique o nome do arquivo na biblioteca de m\u00eddia. Ele deve aparecer como <code>foto-do-joao-final-arvore.jpg<\/code>.<\/li>\n<li>Teste tamb\u00e9m com nomes como <code>Teste_#123!.png<\/code> \u2192 deve virar <code>teste-123.png<\/code>.<\/li>\n<\/ol>\n<h4>Exemplo visual<\/h4>\n<pre><code>Antes do upload:       \"Caf\u00e9 da manh\u00e3 (delicioso!).jpg\"\nAp\u00f3s o upload:         \"cafe-da-manha-delicioso.jpg\"\n\nAntes:                 \"Imagem n\u00ba 001.PNG\"\nAp\u00f3s:                  \"imagem-n-001.png\"\n<\/code><\/pre>\n<h3>Funcionamento t\u00e9cnico<\/h3>\n<ul>\n<li>O filtro <code>sanitize_file_name<\/code> \u00e9 aplicado pelo WordPress sempre que um arquivo \u00e9 enviado para a biblioteca de m\u00eddia.<\/li>\n<li>A fun\u00e7\u00e3o <code>remove_accents()<\/code> \u00e9 nativa do WordPress (desde a vers\u00e3o 3.0) e converte caracteres acentuados para seus equivalentes ASCII.<\/li>\n<li>Express\u00f5es regulares removem tudo que n\u00e3o \u00e9 letra, n\u00famero, espa\u00e7o, h\u00edfen ou ponto.<\/li>\n<li>Espa\u00e7os e sequ\u00eancias de h\u00edfens s\u00e3o substitu\u00eddos por um \u00fanico h\u00edfen.<\/li>\n<li>O nome \u00e9 convertido para min\u00fasculas, garantindo consist\u00eancia.<\/li>\n<\/ul>\n<h3>Personaliza\u00e7\u00f5es poss\u00edveis<\/h3>\n<ul>\n<li><strong>Manter mai\u00fasculas:<\/strong> Remova a linha <code>$name = strtolower( $name );<\/code>.<\/li>\n<li><strong>Usar sublinhado em vez de h\u00edfen:<\/strong> Altere o padr\u00e3o <code>preg_replace( '\/[\\s\\-]+\/', '-', $name );<\/code> para <code>preg_replace( '\/[\\s\\-]+\/', '_', $name );<\/code>.<\/li>\n<li><strong>Adicionar um prefixo ou sufixo:<\/strong> Modifique a linha de reconstru\u00e7\u00e3o: <code>$clean_filename = 'img_' . $name . ( $ext ? '.' . $ext : '' );<\/code>.<\/li>\n<li><strong>Limitar o tamanho do nome:<\/strong> Adicione <code>$name = substr( $name, 0, 50 );<\/code> antes da reconstru\u00e7\u00e3o.<\/li>\n<li><strong>Manter apenas letras e n\u00fameros (sem h\u00edfen):<\/strong> Use <code>$name = preg_replace( '\/[^a-zA-Z0-9]\/', '', $name );<\/code> e depois junte com ponto.<\/li>\n<\/ul>\n<h3>Plugins que este MU-Plugin substitui<\/h3>\n<ul>\n<li><code>clean-image-filenames<\/code> (o alvo principal)<\/li>\n<li><code>smart-media-rename<\/code> (parte da renomea\u00e7\u00e3o autom\u00e1tica)<\/li>\n<li><code>enable-media-replace<\/code> (para limpeza de nomes, n\u00e3o para substitui\u00e7\u00e3o)<\/li>\n<li>Qualquer outro plugin que apenas sanitize nomes de arquivos no upload.<\/li>\n<\/ul>\n<h3>Observa\u00e7\u00f5es e boas pr\u00e1ticas<\/h3>\n<ul>\n<li><strong>Funciona para qualquer arquivo de m\u00eddia:<\/strong> Imagens, PDFs, v\u00eddeos, etc.<\/li>\n<li><strong>N\u00e3o afeta arquivos j\u00e1 existentes:<\/strong> A limpeza s\u00f3 ocorre no momento do upload. Para renomear arquivos antigos, voc\u00ea precisaria de um script adicional (n\u00e3o recomendado, pois quebra links).<\/li>\n<li><strong>Seguran\u00e7a:<\/strong> A fun\u00e7\u00e3o <code>remove_accents()<\/code> e os escapes previnem inje\u00e7\u00e3o de c\u00f3digo. O nome final ainda passa por outras valida\u00e7\u00f5es do WordPress.<\/li>\n<li><strong>Compatibilidade com Elementor e outros builders:<\/strong> Perfeito, pois a limpeza ocorre antes de qualquer processamento.<\/li>\n<li><strong>Cuidado com nomes muito curtos:<\/strong> Se o nome original for apenas caracteres especiais (ex: &#8220;#$%&#8221;), o plugin cair\u00e1 no fallback &#8220;arquivo&#8221;. Isso evita nomes vazios.<\/li>\n<\/ul>\n<h3>Poss\u00edveis problemas e solu\u00e7\u00f5es<\/h3>\n<ul>\n<li><strong>O nome do arquivo n\u00e3o muda:<\/strong> Verifique se o MU-Plugin est\u00e1 carregado corretamente. Adicione um <code>error_log<\/code> no in\u00edcio da fun\u00e7\u00e3o <code>clean_filename<\/code> para depurar.<\/li>\n<li><strong>Acentos n\u00e3o s\u00e3o removidos:<\/strong> O WordPress precisa ter a extens\u00e3o PHP <code>mbstring<\/code> habilitada para <code>remove_accents<\/code> funcionar plenamente. No LocalWP, ela vem ativada por padr\u00e3o.<\/li>\n<li><strong>Duplicidade de nomes:<\/strong> O WordPress automaticamente adiciona um sufixo num\u00e9rico (ex: <code>imagem-2.jpg<\/code>) se o nome j\u00e1 existir. Nosso plugin n\u00e3o interfere nesse comportamento nativo.<\/li>\n<\/ul>\n<h3>Registro no caderno<\/h3>\n<p>Data: <!--?php echo date('d\/m\/Y'); ?--><\/p>\n<p>Funcionalidade: Limpeza autom\u00e1tica de nomes de arquivos de m\u00eddia no upload<\/p>\n<p>Plugins substitu\u00eddos: clean-image-filenames, smart-media-rename (parcialmente)<\/p>\n<p>Tempo de implementa\u00e7\u00e3o: ~5 minutos (cria\u00e7\u00e3o e testes)<\/p>\n<p>Observa\u00e7\u00e3o: Este MU-Plugin \u00e9 leve e n\u00e3o requer configura\u00e7\u00e3o; funciona imediatamente ap\u00f3s criado.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Aula: Limpeza Autom\u00e1tica de Nomes de Arquivos de Imagem \u2013 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\u00e7os, caracteres especiais e convertendo para min\u00fasculas, gerando URLs amig\u00e1veis e SEO-friendly. Contexto: O plugin original \u00e9 [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"wpai_generated_summary":"","wpai_meta_description":"","footnotes":""},"categories":[2,4],"tags":[],"class_list":["post-287","post","type-post","status-publish","format-standard","hentry","category-lessons","category-pluginsmu"],"_links":{"self":[{"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/posts\/287","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/comments?post=287"}],"version-history":[{"count":0,"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/posts\/287\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/media?parent=287"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/categories?post=287"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.portanova.com.br\/notebook\/wp-json\/wp\/v2\/tags?post=287"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}