Como criar um mu-plugin WordPress

Um mu-plugin (must-use plugin) do WordPress é um arquivo PHP colocado em wp-content/mu-plugins/ que o WordPress carrega automaticamente a cada requisição. Ele não pode ser desativado pelo painel administrativo e é executado antes de qualquer plugin comum. Use-o para código que precisa estar sempre presente: hooks personalizados, regras de segurança, ajustes de desempenho ou constantes de carregamento antecipado.

Outro caso de uso para um mu-plugin é adicionar funções extras a um plugin ou ao núcleo do WP. Por exemplo, o WP STAGING conta com diversos filtros e hooks que podem agregar mais recursos às funcionalidades de staging ou de backup do WP STAGING. Todos esses filtros documentados podem ser adicionados a um mu-plugin personalizado.

Resposta rápida: Coloque um arquivo .php com um cabeçalho de plugin em wp-content/mu-plugins/. O WordPress o reconhece no próximo carregamento de página, sem necessidade de ativação. Verifique em Plugins → Plugins de uso obrigatório para confirmar que ele foi carregado.

Introdução aos Plugins Must-Use

Os mu-plugins ficam em wp-content/mu-plugins/ (o caminho é controlado pela constante WPMU_PLUGIN_DIR) e são carregados pelo WordPress antes de qualquer plugin em wp-content/plugins/. Eles não aparecem na lista padrão de plugins e não podem ser desativados pela interface administrativa.

O cenário mais comum em que os desenvolvedores recorrem a um mu-plugin: eles têm uma função ou filtro que fica quebrando porque outro administrador desativa o plugin que a continha, ou porque uma atualização de plugin sobrescreve uma personalização. Um mu-plugin elimina os dois riscos de uma vez.

A documentação oficial do WordPress aborda os plugins must-use em wordpress.org/documentation/article/must-use-plugins/.

Como um mu-plugin se compara a outros lugares onde você poderia colocar o mesmo código?

Vantagens dos Mu-Plugins

A principal vantagem em relação a um plugin comum é a resistência a adulterações. Um plugin comum pode ser desativado por qualquer usuário com nível de administrador ou removido se uma credencial for comprometida. Um mu-plugin, não.

Use um mu-plugin quando:

• O código precisa ser executado mesmo que todos os plugins comuns estejam desativados (um redirecionamento de manutenção, um cabeçalho de segurança, uma regra que força HTTPS)
• Você está registrando ações e filtros do WP STAGING que precisam carregar antes de o próprio plugin inicializar
• Você administra vários sites WordPress e quer um comportamento específico do site fora dos plugins versionados
• Você quer aplicar configurações PHP em tempo de execução (como memory_limit) no início do ciclo da requisição

Use um plugin comum quando:

• O recurso deve poder ser ligado e desligado pelo dono do site ou por um desenvolvedor
• A funcionalidade é distribuída como um produto instalável com atualizações automáticas
• Você está criando algo que outros plugins descobrem por meio de is_plugin_active()

Como criar um mu-plugin do WordPress

Passo 1: acesse os arquivos do seu site

Conecte-se ao seu site via FTP, SFTP ou pelo gerenciador de arquivos da sua hospedagem.

Passo 2: localize ou crie o diretório mu-plugins

Navegue até wp-content/. Procure a pasta mu-plugins/. Se ela não existir, crie-a. O WordPress começará a carregar arquivos PHP desse diretório imediatamente, sem nenhuma configuração adicional.

Passo 3: crie o arquivo do seu plugin

Crie um novo arquivo PHP, por exemplo my-mu-plugin.php. Use letras minúsculas e hifens (sem espaços) no nome do arquivo. O nome do arquivo aparece em Plugins → Plugins de uso obrigatório no painel do WordPress, então escolha um nome descritivo.

Passo 4: adicione o cabeçalho do plugin e o seu código

Todo mu-plugin precisa de um comentário de cabeçalho de plugin no topo, igual a um plugin comum. Abaixo está a estrutura mínima:

<?php
/*
Plugin Name: My Custom Mu-Plugin
Description: A custom must-use plugin to enhance my WordPress site.
Version: 1.0
Author: Mickey Mouse
*/

// Your custom code goes here

Passo 5: envie o seu mu-plugin

Envie o arquivo .php para wp-content/mu-plugins/ no seu servidor.

Passo 6: verifique a ativação

Não há etapa de ativação. Acesse Plugins → Plugins de uso obrigatório no painel do WordPress para confirmar que o arquivo foi carregado. Se ele não aparecer, verifique se o arquivo está diretamente em mu-plugins/ (e não dentro de um subdiretório).

Exemplo de Mu-Plugin: texto personalizado no rodapé do admin

Aqui está um exemplo completo e funcional que altera o texto do rodapé exibido na parte inferior de todas as telas administrativas do WordPress:

<?php
/*
Plugin Name: Custom Admin Footer
Description: Changes the footer text in the WordPress admin area.
Version: 1.0
Author: Your Name
*/

add_filter('admin_footer_text', function () {
    echo 'Customized by Tony Stark - Powered by WordPress';
});

Casos de uso comuns de mu-plugin

Estes são os padrões que mais aparecem nos chamados de suporte do WP STAGING e em fóruns de desenvolvedores:

1. Forçar o log de depuração sem editar o wp-config.php

<?php
/*
Plugin Name: Enable Debug Log
*/
if ( ! defined( 'WP_DEBUG' ) ) {
    define( 'WP_DEBUG', true );
}
if ( ! defined( 'WP_DEBUG_LOG' ) ) {
    define( 'WP_DEBUG_LOG', true );
}
if ( ! defined( 'WP_DEBUG_DISPLAY' ) ) {
    define( 'WP_DEBUG_DISPLAY', false );
}

Isso é útil em ambientes de staging ou de desenvolvimento onde você quer manter o log ativo sem mexer no wp-config.php de produção. Consulte Enable WordPress Debug Log Mode para o fluxo completo de depuração.

2. Aumentar o limite de memória do PHP

A diretiva ini memory_limit pode ser alterada em tempo de execução via ini_set(), o que torna um mu-plugin um lugar limpo para aplicá-la antes de os plugins comuns carregarem:

<?php
/*
Plugin Name: Increase Memory Limit
*/
@ini_set( 'memory_limit', '256M' );

Observação: algumas configurações do PHP são fixas no nível do servidor e não podem ser alteradas em tempo de execução via ini_set(). Uma referência completa de quais diretivas aceitam mudanças em tempo de execução está em php.net/manual/en/ini.list.php.

3. Código de filtros do WP STAGING

O WP STAGING expõe ações e filtros documentados para controlar o comportamento de backup e de staging. Como eles precisam carregar antes de o próprio WP STAGING inicializar, um mu-plugin é o lugar certo para registrá-los. Coloque quaisquer chamadas add_filter() ou add_action() em um arquivo mu-plugin e elas estarão sempre presentes, independentemente da ordem de ativação dos plugins. Veja todos os hooks disponíveis na documentação de ações e filtros do WP STAGING, cujo link está em Artigos relacionados abaixo.

4. Redirecionamento forçado para HTTPS

<?php
/*
Plugin Name: Force HTTPS
*/
add_action( 'template_redirect', function () {
    if ( ! is_ssl() ) {
        wp_redirect( 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'], 301 );
        exit;
    }
} );

5. Desativar o XML-RPC

<?php
/*
Plugin Name: Disable XML-RPC
*/
add_filter( 'xmlrpc_enabled', '__return_false' );

Limitações e pegadinhas

Antes de se comprometer com um mu-plugin, há alguns comportamentos que vale a pena conhecer:

Sem hook de desativação ou desinstalação. O WordPress nunca dispara deactivate_{plugin} nem uninstall_{plugin} para mu-plugins. Se o seu plugin cria opções, tabelas personalizadas ou eventos cron agendados, você precisa limpá-los manualmente: exclua o arquivo e, em seguida, remova os dados armazenados à mão.

O carregamento a partir de subdiretório exige um arquivo carregador. O WordPress carrega apenas os arquivos PHP que estão diretamente em wp-content/mu-plugins/. Se você colocar o código em um subdiretório (por exemplo, mu-plugins/my-plugin/my-plugin.php), o WordPress não o reconhecerá. O padrão comum é criar um arquivo carregador enxuto na raiz de mu-plugins/ que chama require_once no arquivo dentro do subdiretório.

Comportamento em multisite. Em uma rede multisite do WordPress, os mu-plugins carregam em todos os sites a cada requisição. Não há um botão de ativação por site. Use is_main_site() ou get_current_blog_id() dentro do plugin se você precisar limitar o comportamento a um site específico da rede.

Ordem de carregamento. Os mu-plugins carregam em ordem alfabética crescente pelo nome do arquivo, antes de qualquer plugin em wp-content/plugins/. Se a sequência entre os seus mu-plugins importa, adicione um prefixo aos nomes dos arquivos: 00-runs-first.php, 10-runs-second.php.

Visibilidade no painel. Os mu-plugins aparecem em Plugins → Plugins de uso obrigatório, mas não mostram detalhes a menos que o cabeçalho do plugin inclua Plugin Name, Description e Version. Sempre inclua um cabeçalho; isso torna o diagnóstico muito mais rápido quando algo dá errado.

Sem mecanismo de atualização. O WordPress não tem uma forma nativa de notificar sobre ou atualizar mu-plugins. Se você estiver adaptando código de terceiros para um mu-plugin, é sua responsabilidade acompanhar as atualizações e aplicá-las manualmente. Para mu-plugins desenvolvidos internamente isso não é uma preocupação, mas vale observar se você está pensando em converter um plugin da comunidade em um mu-plugin.

Onde este código deve ficar?

Uma regra prática útil: se o seu código chama qualquer função do WordPress (add_filter, get_option, wp_redirect etc.), coloque-o em um mu-plugin. Se for um define() puro do PHP ou um ajuste que precisa rodar antes de o WordPress iniciar, wp-config.php é o lugar certo.

Conclusão

Um mu-plugin é a ferramenta certa para código que precisa sempre rodar e não pode correr o risco de ser desligado por acidente. A configuração leva alguns minutos: crie wp-content/mu-plugins/, adicione um arquivo .php com um cabeçalho de plugin, e o WordPress cuida do resto.

Se você está desenvolvendo ou testando código personalizado de mu-plugin, recomendamos verificá-lo em um ambiente de staging antes de implantar em produção. O WP STAGING facilita clonar o seu site em produção e confirmar que o mu-plugin se comporta como esperado antes de as suas mudanças entrarem no ar.

Artigos relacionados

• How to Create and Add an Admin User With MySQL in WordPress
• WP Staging Actions and Filters
• Enable WordPress Debug Log Mode
• Grant Custom User access to the Staging Site
• How to Delete a WordPress Plugin Manually via FTP

Autor: Rene Hermenau

Sobre o autor: René Hermenau é o fundador do WP STAGING. Ele trabalha com backups do WordPress, ambientes de staging, migrações, gestão de bases de dados e fluxos de implantação seguros.

Ver o perfil completo do autor Rene Hermenau