Melhores práticas objetivas para o desenvolvimento de plug-ins?

Carregar Scripts/CSS com wp_enqueue_script e wp_enqueue_style

Plugins não devem carregar/tentar carregar versões duplicadas de arquivos JS/CSS, especialmente jQuery e outros arquivos JS incluídos no WP Core.

Os plug-ins devem sempre usar wp_enqueue_script e wp_enqueue_style ao vincular arquivos JS e CSS e nunca diretamente por meio de tags <script>.

Relacionado

• Reutilizar funções existentes

Suporte I18n

Todas as sequências de saída devem ser vinculadas a um domínio de texto apropriado para permitir a internacionalização pelas partes interessadas, mesmo que o desenvolvedor não tenha interesse em traduzir seu próprio plug-in.

Observe que é muito importante carregar os arquivos de idioma durante a ação init para que o usuário possa conectar-se à ação.

Veja o Codex: I18n para desenvolvedores WordPress

E também este artigo: Carregando WP arquivos de idioma o corretamente .

Desde o WordPress 4.6 ou superior

O WP 4.6 alterou a ordem de carregamento e os locais, o que facilitou muito para desenvolvedores e usuários.

Considerando um plugin com um textdomain 'meu-plugin', o WordPress irá agora procurar por um arquivo de tradução em:
/wp-content/languages/plugins/my-plugin-en_US.mo

Se não encontrar um, então procurará um que o plugin diga para procurar (normalmente na pasta 'idioma' do pluigns se seguir o códice):
/wp-content/plugins/my-plugin/languages/my-plugin-en_US.mo

Por fim, se nenhum arquivo de idioma for encontrado, ele verificará o local padrão de:
/wp-content/languages/my-plugin-en_US.mo

A primeira checagem foi adicionada no 4.6 e dá aos usuários um lugar definido para adicionar um arquivo de idioma, pois antes eles precisariam saber onde o desenvolvedor adicionou o arquivo de idioma, agora o usuário só precisa saber o textdomain do plugin:/wp -content/languages ​​/ plugins/TEXTDOMAIN-LOCAL.mo

Abaixo está o caminho antigo (Não relevante desde WP 4.6+)

[...]
Por fim, gostaria de salientar que é importante carregar arquivos de idioma de usuário personalizados de WP_LANG_DIR antes de carregar os arquivos de idioma que acompanham o plug-in . Quando vários arquivos mo são carregados para o mesmo domínio, a primeira tradução encontrada será usada. Dessa forma, os arquivos de idiomas fornecidos pelo plug-in servirão como um substituto para cadeias não traduzidas pelo usuário.

public function load_plugin_textdomain()
{
    $domain = 'my-plugin';
    // The "plugin_locale" filter is also used in load_plugin_textdomain()
    $locale = apply_filters( 'plugin_locale', get_locale(), $domain );

    load_textdomain( 
            $domain, 
            WP_LANG_DIR . '/my-plugin/' . $domain . '-' . $locale . '.mo' 
    );
    load_plugin_textdomain( 
            $domain, 
            FALSE, 
            dirname( plugin_basename(__FILE__) ) . '/languages/' 
    );
}

Garantir que os plug-ins não gerem erros com WP_DEBUG

Sempre teste seus plugins com WP_DEBUG ligado e o ideal é que ele seja ativado durante todo o processo de desenvolvimento. Um plugin não deve lançar nenhum erro com WP_DEBUG on. Isso inclui avisos reprovados e índices não verificados.

Para ativar a depuração, edite seu arquivo wp-config.php para que a constante WP_DEBUG seja definida como true. Veja o Codex on Debug para mais detalhes.

Primeiro use as funções existentes no WordPress Core

Se você puder: usar funções existentes incluídas no núcleo do WordPress em vez de escrever o seu próprio. Somente desenvolva funções PHP personalizadas quando não houver uma função pré-existente apropriada no núcleo do WordPress.

Um benefício é que você pode usar o "log de avisos depreciados" para monitorar facilmente as funções que devem ser substituídas. Outro benefício é que os usuários podem ver a documentação da função no Codex e entender melhor o que o plug-in faz, mesmo que não sejam um desenvolvedor experiente PHP.

Relacionado

• Suporte I18n
• Carregar Scripts/CSS com wp_enqueue_script e wp_enqueue_style
• Oferecer formulários extensíveis

A desinstalação deve remover todos os dados de um plugin

Ao ser removido de uma instalação do WordPress, um plug-in deve excluir todos os arquivos, pastas, entradas do banco de dados e tabelas que ele criou, bem como os valores da opçãocriado.

Plugins podem oferecer uma opção para exportar/importar configurações, para que as configurações possam ser salvas fora do WordPress antes da exclusão.

Relacionado

• Desativação não deve provocar perda de dados

Evite a injeção de SQL com dados de entrada

Um plugin deve limpar todas as entradas do usuário recuperadas direta ou indiretamente (por exemplo, via $_POST ou $_GET) antes de usar valores de entrada para consultar o banco de dados MySQL.

Veja: Formatando instruções SQL .

Use um código PHP5 orientado a classes e objetos

Não há razão para não escrever código PHP5 limpo e orientado a objetos. O suporte ao PHP4 será eliminado após o próximo lançamento (WP 3.1). Claro, você pode prefixar todos os nomes de suas funções para terminar com endlessly_long_function_names_with_lots_of_underscores, mas é muito mais fácil apenas escrever uma classe simples e agrupar tudo nela. Além disso, coloque sua classe em um arquivo separado e nomeie-a de acordo para poder estendê-la e mantê-la facilmente:

// in functions.php
require 'inc/class-my-cool-plugin.php';
new MyCoolPlugin();

// in inc/class-my-cool-plugin.php
class MyCoolPlugin {
    function __construct() {
        // add filter hooks, wp_enqueue_script, etc.

        // To assign a method from your class to a WP 
        // function do something like this
        add_action('admin_menu', array($this, "admin"));
    }

    public function admin() {
        // public methods, for use outside of the class
        // Note that methods used in other WP functions 
        // (such as add_action) should be public
    }

    private function somethingelse() {
        // methods you only use inside this class
    }
}

Prefixar todos os itens do namespace global

Um plugin deve prefixar corretamente TODOS os itens do namespace global (constantes, funções, classes, variáveis, até mesmo coisas como taxonomias customizadas, tipos de postagens, widgets, etc.). Por exemplo, não crie uma função chamada init(); em vez disso, nomeie algo como jpb_init().

É comum usar um prefixo de três ou quatro letras na frente dos nomes ou fazer uso do recurso de namespace PHP . Compare: Prefixo de letra única para PHP constantes de classe?

Relacionado

• Namespace global é um recurso limitado

A desativação não deve provocar perda de dados

Um plugin não deve excluir qualquer um dos seus dados sobre desativação.

Relacionado

• Desinstalação deve remover todos os dados do plugin

Apenas inclua arquivos que você precisa ...

Se você estiver no front end, não inclua o código relacionado à área do administrador.

Anunciar perda de dados na desinstalação de plug-ins

Após a desinstalação a plugin deve Solicitar ao usuário que irá excluir seus dados e receber uma confirmação de que o usuário está certo em excluir os dados antes de fazer isso e um plugin deve também permite ao usuário manter os dados após a desinstalação. (Essa ideia do @EAMann.)

Relacionado

• Desinstalação deve remover todos os dados do plugin
• Desativação não deve provocar a perda de dados

Use o WordPress (embutido)

Não apenas return; se alguma entrada do usuário estiver errada. Entregue-lhes algumas informações sobre o que foi feito de errado.

function some_example_fn( $args = array() ) 
{
    // If value was not set, build an error message
    if ( ! isset( $args['some_value'] ) )
        $error = new WP_Error( 'some_value', sprintf( __( 'You have forgotten to specify the %1$s for your function. %2$s Error triggered inside %3$s on line %4$s.', TEXTDOMAIN ), '$args[\'some_value\']', "\n", __FILE__, __LINE__ ) );

    // die & print error message & code - for admins only!
    if ( isset( $error ) && is_wp_error( $error ) && current_user_can( 'manage_options' ) ) 
        wp_die( $error->get_error_code(), 'Theme Error: Missing Argument' );

    // Elseif no error was triggered continue...
}

Um erro (objeto) para todos

Você pode configurar um objeto de erro global para seu tema ou plug-in durante o bootstrap:

function bootstrap_the_theme()
{
    global $prefix_error, $prefix_theme_name;
    // Take the theme name as error ID:
    $theme_data = wp_get_theme();
    $prefix_theme_name = $theme_data->Name;
    $prefix_error = new WP_Error( $theme_data->Name );

    include // whatever, etc...
}
add_action( 'after_setup_theme', 'bootstrap_the_theme' );

Mais tarde, você pode adicionar erros ilimitados sob demanda:

function some_theme_fn( $args )
{
    global $prefix_error, $prefix_theme_name;
    $theme_data = wp_get_theme();
    if ( ! $args['whatever'] && current_user_can( 'manage_options' ) ) // some required value not set
        $prefix_error->add( $prefix_theme_name, sprintf( 'The function %1$s needs the argument %2$s set.', __FUNCTION__, '$args[\'whatever\']' ) );

    // continue function...
}

Então você pode buscá-los todos no final do seu tema. Dessa forma, você não interrompe a renderização da página e ainda pode gerar todos os erros para desenvolver

function dump_theme_errors()
{
    global $prefix_error, $prefix_theme_name;

    // Not an admin? OR: No error(s)?
    if ( ! current_user_can( 'manage_options' ) ! is_wp_error( $prefix_error ) )
        return;

    $theme_errors = $prefix_error->get_error_messages( $prefix_theme_name );
    echo '<h3>Theme Errors</h3>';
    foreach ( $theme_errors as $error )
        echo "{$error}\n";
}
add_action( 'shutdown', 'dump_theme_errors' );

Você pode encontrar mais informações em this Q . Um ticket relacionado para corrigir o "trabalho em conjunto" de WP_Error e wp_die() está vinculado a partir dele e outro ticket será exibido. Comentários, críticas e tal é apreciado.

Permitir que o nome da pasta do plugin seja alterado

/ plugins/pluginname/{various}

O "pluginname" usado para a pasta deve sempre ser modificável.

Normalmente, isso é tratado definindo constantes e consistentemente usando-as em todo o plug-in.

Escusado será dizer que muitos plugins populares são pecadores.

Relacionado:

• plugins_url() para facilitar a vinculação a recursos, incluídos no plug-in.

Minimizar nomes adicionados ao espaço para nome global

Um plugin deve reduz seu impacto tanto quanto possível por minimizando o número de nomes que ele adiciona ao namespace global .

Isso pode ser feito encapsulando as funções do plugin em uma classe ou usando o recurso PHP namespaces . Prefixar tudo pode ajudar também, mas não é tão flexível.

Ao lado de funções e classes, um plugin não deve introduz variáveis ​​globais. O uso de classes normalmente as torna obsoletas e simplifica a manutenção do plug-in.

Relacionado

• Prefixo corretamente

Comente usando PhpDoc

A melhor prática está perto do estilo PhpDoc. Se você não usa um IDE como "Eclipse", você pode dar uma olhada no Manual do PhpDoc .

Você não precisa saber exatamente como isso funciona. Os desenvolvedores profissionais podem ler o código de qualquer maneira e só precisam disso como um resumo. Os codificadores e usuários do hobby podem apreciar a maneira como você explica isso no mesmo nível de conhecimento.

Use a API de configurações antes de add_option

Em vez de adicionar opções ao banco de dados através da função add_option, você deve armazená-las como um array usando a API Settings que cuida de tudo para você.

Use a API de modificação de temas antes de add_option

A API de modificações é uma construção bastante simples e uma maneira segura que permite adicionar e recuperar opções. Tudo é salvo como valor serializado em seu banco de dados. Fácil, seguro e simples.

Proteger Usuários de Plugin Privacidade

(Anteriormente: Comunicação Anônima da API)

Se um plug-in se comunicar com um sistema externo ou API (por exemplo, algum serviço da Web), deverá fazê-lo anonimamente ou fornecer ao usuário uma opção anônima que garanta que nenhum dado relacionado ao usuário do plug-in vaze para uma segunda pessoa descontrolada.

Fornecer controle de acesso usando permissões

Em muitos casos, os usuários podem não querer que todos tenham acesso a áreas criadas pelo seu plug-in, especialmente com plug-ins que realizam várias operações complexas, mas uma única verificação de capacidade codificada pode não ser suficiente.

No mínimo, tenha verificações de capacidade apropriadas para todos os diferentes tipos de procedimentos para os quais seu plugin pode ser usado.

Plugins de Host no WordPress.org

Use o SVN repository fornecido no WordPress.org para hospedar plugins. Isso facilita a atualização da experiência do usuário e, se você nunca usou o SVN anteriormente, ele faz com que você realmente entenda, usando-o em um contexto que o justifique.

Organize seu código

É difícil ler código que não está escrito na ordem em que é executado. Primeiro inclua/require, define, wp_enqueue_style & _script, etc., então as funções que o plugin/theme precisa e, finalmente, o construtor (ex. Tela admin, coisas que se integram no tema, etc.).

Tente separar coisas como css e js em suas próprias pastas. Também tente fazer isso com funções que são apenas ajudantes, como niveladores de matriz e similares. Manter o arquivo "principal" limpo e fácil de ler é uma maneira que ajuda os usuários, desenvolvedores e você, quando você tenta atualizar em um ano e não vê o código por mais tempo.

Também é bom ter uma estrutura que você repete com frequência, para que você sempre encontre o caminho. Desenvolver em uma estrutura conhecida em diferentes projetos lhe dará tempo para torná-lo melhor e mesmo que seu cliente mude para outro desenvolvedor, você nunca ouvirá "ele deixou um caos". Isso constrói sua reputação e deve ser um objetivo de longo prazo.

Configurações de plug-in de importação/exportação

Não é tão comum entre os plugins, mas se o seu plugin tem (algumas) configurações, deve fornecer Import/Export de dados como configuração e entrada do usuário .

Importar/Exportar melhora a usabilidade de um plugin.

Um plugin de exemplo que tem essa funcionalidade de importação e exportação (e também um mecanismo de desfazer) é Breadcrumb NavXT (Plugin Wordpress) (divulgação completa: algum pequeno código meu lá dentro, a maioria foi feita pelo mtekk) .

Relacionado

• Desinstalação deve remover todos os dados do plugin
• Desativação não deve provocar perda de dados

Morra com estilo

morre de forma decente Todas as funções de plugins (e até temas) devem usar wp_die() em lugares críticos para oferecer ao usuário um pouco de informação sobre o que aconteceu. Os erros de php são irritantes e o wp_die pode dar ao usuário uma mensagem com estilo Agradável sobre o que o plugin (ou eles) fizeram de errado. Além disso, se o usuário tiver depuração desativada, o plug-in será interrompido.

Usando wp_die() também ajuda que seus plugins/temas sejam compatíveis com o wordpress testsuite .

• Use WP tratamento de erros

Fornecer telas de ajuda para usuários

É melhor dizer RTFM (clique em ajuda) como resposta do que ter que responder a pergunta uma e outra vez.

/**
  * Add contextual help for this screen
  * 
  * @param $rtfm
  * @uses get_current_screen
  */ 
  function ContextualHelp( /*string*/ $rtfm) 
  { 
     $current_screen = get_current_screen();
     if ($current_screen->id == $this->_pageid) 
     {
        $rtfm .= '<h3>The WordPress Plugin - Screen A</h3>';
        $rtfm .= '<p>Here are some tips: donate to me ' .
     }
     return $rtfm; 
  }
add_action('contextual_help', array($this,'ContextualHelp'),1,1);

atualização/nota: (ver comentários do kaiser): o exemplo acima deve ser usado em uma classe

Oferecer formulários extensíveis

Quando um plugin oferece a possibilidade de inserir dados, ele deve sempre ter um gancho no final, logo antes do botão "enviar" e/ou "redefinir", para que os desenvolvedores possam estender facilmente o formulário com não apenas campos, mas também botões.

Veja: API de configurações

Relacionado

• Use ações e filtros
• Reutilizar funções existentes
• Suporte I18n

inclua a função sempre via gancho, não diretamente.

Exemplo:

• Não use para incluir a classe do plugin via novo sem gancho

• Use o gancho plugins_loaded

  // add the class to WP                                   
  function my_plugin_start() {                                                               
      new my_plugin();   
  }                                                        
  add_action( 'plugins_loaded', 'my_plugin_start' );
  

Update: um pequeno exemplo ao vivo: Plugin-svn-trunk-page e um pseudo exemplo

//avoid direct calls to this file where wp core files not present
if (!function_exists ('add_action')) {
        header('Status: 403 Forbidden');
        header('HTTP/1.1 403 Forbidden');
        exit();
}

if ( !class_exists( 'plugin_class' ) ) {
    class plugin_class {

        function __construct() {
        }

    } // end class

    function plugin_start() {

        new plugin_class();
    }

    add_action( 'plugins_loaded', 'plugin_start' );
} // end class_exists

Você também pode carregar via mu_plugins_loaded em multisite-install, veja o codex para referência de ação: http://codex.wordpress.org/Plugin_API/Action_Reference Também aqui você vê, como inlcude wP com este hook: http://adambrown.info/p/wp_hooks/hook/plugins_loaded?version=2.1&file=wp-settings.php Eu uso isso com muita freqüência e não é tão difícil e cedo, melhor como uma nova classe difícil ();

A descrição do seu plugin deve detalhar com precisão as funções do seu plugin. Existem 10 plugins de post em destaque. Todos eles exibem posts em destaque, mas muitos têm recursos diferentes. Deve ser fácil comparar o seu plugin com plugins semelhantes lendo a descrição.

Você deve evitar se gabar sobre o quão simples é o seu plugin, a menos que seja realmente muito básico. Você deve incluir links úteis na descrição, como o link para as configurações.

Plugins de Licença sob uma Licença GPL Compatível

Plug-ins e temas deve ser licenciado sob uma licença compatível com o WordPress. Isso permite que eles sejam redistribuídos com o WordPress como um "programa". Uma licença recomendada é a GPL . Tome cuidado para que todas as bibliotecas de código incluídas no plug-in sejam compatíveis com a mesma licença.

(Isso tem sido um problema e grave ponto de debate ambos no passado e presente .)

Minimize os efeitos colaterais de fontes de dados remotas e serviços Web

Um Plugin deveria Cache/Shield Webservice e/ou Pedidos XMLRPC/SOAP através de uma camada de caching/data-provider se você usá-los para não fazer solicitações antecipadas esperando ( lento) resposta de webservice.

Isso inclui o download de feed RSS e outras páginas. Projete seus plugins para que eles solicitem dados em segundo plano.

Um possível STEP é (Leve postagem para o ping.fm como exemplo): Crie uma tabela de buffer, digamos: ping_fm_buffer_post (data, hora, mensagem, submitted_time, status)

1. Para cada vez que você quiser enviar uma atualização para o ping.fm, adicione-o a esta tabela.
2. Agora, precisamos criar um plug-in para lidar com esses dados. Este plugin será executado via crontab para verificar todas as atualizações que ainda não foram enviadas
3. Como temos essa tabela, também podemos listar todas as mensagens enviadas ao ping.fm e verificar o status de cada postagem. Apenas no caso de haver algum problema no lado do ping.fm, podemos reenviá-lo.

Teste seu plugin

Devemos definitivamente ter algumas ferramentas de teste em nosso ambiente de desenvolvimento de plugins.

Com base em esta resposta por Ethan Seifert para uma questão de teste, estas são boas práticas a seguir:

• Seu Teste de Unidade deve testar a menor quantidade de comportamento que uma classe pode realizar.
• Quando você chega ao nível de testes funcionais, é onde você pode testar seu código com dependências do Wordpress.
• Dependendo do que o seu plug-in faz - considere o uso de testes baseados no Selenium que testam a presença de dados no DOM usando IDs

Use nomes próprios

Nome hooks e filters (classes, functions e vars), so que as pessoas podem identificá-los em até um ano , quando eles não se lembram mais, de onde vem aquele pedaço de bolo ou código. Não importa se os nomes de gancho/filtro são longos. Ex. youruniquename_hook/filter_whatitdoes.

• Se o seu arquivo contiver uma classe chamada "dbdbInit", então o arquivo que contém a classe deve ser chamado "dbdbInit.class.php".
• Se você chegou dentro da sua classe dbdbInit-, uma função que registra ex. custom_post_types, em seguida, chame-o register_custom_post_types().
• Se você tem uma matriz que contém os nomes para custom_post_types, chame a variável onde a matriz é atribuída $custom_post_type_names.
• Se você tem uma função que lida com uma matriz, escreva function array_handler( $array ) { // handle the array} ..
• Apenas tente nomear as coisas de uma maneira que você saiba o que o signo faz/onde ele pertence ao seu nome.

Outra coisa: se você tiver que depurar coisas, em 99% de todos os casos, você recebe todas as suas mensagens não apenas para o seu código, mas também para o wordpress. Portanto, tente usar o mesmo prefixo ex. "dbdb" para suas classes, funções públicas e variáveis ​​/ objetos. Desta forma, você pode encontrá-los facilmente entre centenas de arquivos. (O Wordpress carrega 64 arquivos antes do seu tema e cerca de 1.550 funções, não falando sobre ganchos e filtros.)

Preocupe-se com as futuras versões do WordPress e do tema

Nota: Depois de reler este conselho, eu agora passo para trás desta prática, pois verificar todas as funções de existência pode tornar o site mais lento.

Verifique se as funções estão obsoletas diretamente no seu tema.

Este é um exemplo "poderia ser assim".

if ( ! function_exists( 'wp_some_fn' ) ) 
{
    $theme_data = wp_get_theme();
    $error = new WP_Error( 'wp_some_fn', sprintf( __( 'The function %1$s is deprecated. Please inform the author', TEXTDOMAIN ), "Theme: {$theme_data->Name}: Version {$theme_data->Version}" );

    // abort
    if ( is_wp_error( $error ) )
        return print $error->get_error_message();
} 
// else if no error - the function works and exists
wp_some_fn();

Para tratamento de erros adequado/melhor prática, veja esta resposta: link

Você poderia derrubar até mesmo a causa $ na função. Isso ajudará você e seus usuários a acompanhar as funções ou classes do seu tema que podem mudar.

Use os Padrões de Codificação do WordPress

http://codex.wordpress.org/WordPress_Coding_Standards

Você sabe o quanto é mais fácil atualizar o código em que você trabalhou versus o código que outra pessoa criou? Padrões de codificação tornam mais fácil para qualquer desenvolvedor trabalhando em um projeto entrar e ver o que está acontecendo.

Sabemos que o seu plug-in ou tema é seu, e a maneira como você quebra suas linhas e adiciona suas chaves é uma expressão de sua individualidade. Cada recuo é uma declaração cuidadosamente pensada. Mas com seu código personalizado, você está contribuindo para o WordPress, mesmo que seu código não esteja no aplicativo principal. Os padrões de codificação ajudam os desenvolvedores a se atualizar rapidamente com seu código.

Desacoplar do código principal do WordPress

Um Plugin should reduz o impacto da API do WordPress ao mínimo necessário so para separar o código do plugin do código WordPress. Isso reduz o impacto das alterações na base de código do WordPress no plug-in. Além disso, isso melhora a compatibilidade entre versões do código do seu plugin.

Isso não significa não usar funções do WordPress (use-as, como Reutilize funções existentes sugere), mas não para mesclar seu código com funções do WordPress muito mas para separar sua lógica de negócios de plugins da funcionalidade do WordPress.

Use as opções wp para as sequências de saída do plugin

Para tornar o plugin fácil de usar e personalizável, todas as seqüências de saída devem ser modificáveis. A melhor maneira de fazer isso é usar wp-options para armazenar as strings de saída e fornecer backend para alterar os valores padrão. O plug-in não deve usar strings exibidas que não podem ser alteradas facilmente usando o backend do plug-in.

Por exemplo: Sociável - permite alterar a frase que aparece antes da parte de ícones "compartilhar e desfrutar":

Use desinstalar, ativar e desativar ganchos

Existem três ganchos diferentes para isso:

• Desinstalar register_uninstall_hook();
• Desativação register_deactivation_hook();
• Ativação register_activation_hook();

Uma instrução detalhada com um exemplo de trabalho pode ser encontrada aqui. .