Criando um plugin para o WordPress

Os plugins do WordPress permitem fácil modificação, personalização e recursos a um blog WordPress. Ao invés de alterar a programação base do WordPress, você pode adicionar funcionalidades com os plugins. Abaixo segue uma definição básica:
Um plugin WordPress é um programa, ou um conjunto de uma ou mais funções, escritas na linguagem de script PHP, que adiciona um conjunto específico de recursos ou serviços a um blog WordPress,  que pode ser integrado ao blog usando os pontos de acesso e métodos da Application Program Interface (API) do WordPress.

Desejando que o WordPress tivesse alguma funcionalidade nova ou modificada? A primeira coisa a fazer é perquisar entre os vários repositórios de plugins do WordPress para ver se alguém já não criou um plugin adequado as suas necessidades. Em caso contrário, esse artigo irá guia-lo através do processo de criação de seu próprio plugin.

Recursos

  • Para entender como os plugins do WordPress funcionam e como instala-los em seu blog, veja Plugins.
  • Existe uma lista extensa de artigos e recursos para desenvolvedores de plugins, incluindo artigos externos sobre o tema, e tópicos e artigos especiais, em Plugin Resources.
  • Para aprender os conceitos básicos sobre a criação de plugins, dê uma olhada no código fonte de plugins bem escritos, como o Hello Dolly distribuído com o WordPress.
  • Uma vez que tiver finalizado  a criação de seus plugins, leia o artigo Plugin Submission and Promotion para aprender como distribuir e compartilhar ele com outras pessoas.

Criando um plugin

Essa seção deste artigo atravessa os passos que você precisa seguir, e as coisas a considerar, quando se cria um plugin bem estruturado para o WordPress.

Nomes, arquivos e locais

Nome do Plugin

A primeira tarefa na criação de um plugin para WordPress é pensar o que o plugin fará, e criar um (esperançosamente único) nome para ele. Cheque pela página de Plugins e outros repositórios referenciados, para verificar que o nome escolhido seja único; você pode também fazer um pesquisa no Google pelo nome proposto. Muitos desenvolvedores de plugins escolhem usar nomes que descrevem de alguma fora o que o plugin faz; por exemplo, um plugin relacionado a Clima deve provavelmente ter a palavra “Clima” no nome. O nome pode ter múltiplas palavras.

Arquivos do Plugin

O próximo passo é criar um arquivo PHP com um nome derivado do nome escolhido para o seu plugin. Por exemplo, se o seu plugin será chamado “Fabulous Functionality”, você deve nomear seu arquivo como fabfunc.php. Novamente, tente escolher um nome único. As pessoas que  instalarão seu plugin estarão colocando esse arquivo no diretório de plugins de suas instalação WordPress, wp-content/plugins/, de forme que dois plugins não podem estar usando o mesmo arquivo PHP.
Outra opção é dividir seu plugin em múltiplos arquivos. Seu plugin WordPress precisa ter ao menos um arquivo PHP;pode conter também arquivos JavaScript, arquivos CSS, arquivos de imagem, arquivos de idioma, etc. Se houverem múltiplos arquivos, escolha um nome único para um diretório e para o arquivo PHP principal, como fabfunc and fabfunc.php em nosso exemplo, coloque todos os arquivos do plugin nesse diretório, e informe aos usuários de seu plugin para instalar o diretório inteiro em wp-content/plugins/. Porém, um instalação pode ser configurada para esse diretório e ser movida, então você precisa usar  plugin_dir_path() e plugins_url() para caminhos absolutos e URLs.
No restante desse artigo, “o arquivo PHP do plugin” se refere ao arquivo PHP principal, esteja ele no wp-content/plugins/ ou em um sub-diretório.

Arquivo Leia-me (Readme)

Se quiser hospedar o seu plugin no http://wordpress.org/extend/plugins/, você precisa criar também um arquivo readme.txt em um formato padrão, e inclui-lo em seu plugin. Veja http://wordpress.org/extend/plugins/about/readme.txt para obter uma descrição do formato.

Página inicial

É muito útil criar um página web que agirá como a página inicial de seu plugin. Essa página deve descrever como instalar o plugin, o que ele faz, com quais versões do WordPress ele é compatível, o quem tem mudado entre cada versão do plugin, e como usá-lo.

Cabeçalhos dos arquivos

Agora é hora de colocar algumas informações em seu arquivo PHP.

Informação padrão do plugin

O topo do arquivo PHP principal do plugin precisa conter um cabeçalho de informações padrão do plugin. Esse cabeçalho deixa o WordPress reconhecer que o seu plugin existe, adiciona ele a tela de gerenciamento de plugins para que ele possa ser ativado, carrega-o, e executa suas funções; sem o cabeçalho, seu plugin nunca seria ativado e nunca seria executado. Abaixo segue o formato do cabeçalho:

<?php
/*
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
License: A "Slug" license name e.g. GPL2
*/
?>

A informação mínima que o WordPress precisa para reconhecer seu plugin é a linha “Plugin Name”. O resto das informações (se presentes) serão usadas para criar a tabela de plugins na tela de gerenciamento. A ordem das linhas não é importante.
Importante: o arquivo precisa ter a codificação UTF-8.

Licença

É de praxe colocar logo depois do cabeçalho padrão informações sobre a licença do plugin. Muitos plugins usam a licença GPL2 usada pelo WordPress ou uma licença compativel com o GPL2. Para indicar uma licença GPL2, inclua as seguintes linhas em seu plugin:

<?php
/*  Copyright YEAR  PLUGIN_AUTHOR_NAME  (email : PLUGIN AUTHOR EMAIL)
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2, as
    published by the Free Software Foundation.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/
?>

Programando o seu plugin

Agora chegou o momento de fazer o seu plugin fazer algo de fato. Essa seção contém algumas idéias gerais sobre o desenvolvimento de plugins, e descrevem como cumprir várias tarefas que seu plugin precisará fazer.

Ganchos dos plugins do WordPress

Muitos plugins para WordPress cumprem seus objetivos conectando um ou mais”ganchos”. A maneira que esses ganchos funcionam é que a vários momentos durante a execução do WordPress, o WordPress checa para ver seu algum plugin registrou funções para serem executadas nesse momento, e em caso afirmativo, as funções são executadas. Essas funções executam o comportamento padrão do WordPress.
Por exemplo, antes que o WordPress adicione o título de um post para exibição  no navegador, ele primeiro checa para verificar se algum plugin registrou uma função para o gancho de filtragem chamado “the_title”. Em caso afirmativo, o texto do titulo é passado para cada função registrada, e o resultado final dessas operações é o que é impresso. Assim, se seu plugin precisa adicionar alguma informação ao título impresso, pode registrar uma função de filtragem para “the_title”.
Outro exemplo é o gancho de ação chamado “wp_footer”. Logo antes do final da página HTML que o WordPress está gerando, ele verifica se algum plugin registrou funções para “wp_footer”, e executa elas.
Você pode aprender mais sobre como registrar funções tanto de filtragem quanto de ação, e quais ganchos estão disponíveis no WordPress, na página Plugin API. Se você encontrar um ponto no código do WordPress onde gostaria de ter uma ação ou filtro, mas o WordPress não tem um, pode sugerir novos ganchos (sugestões geralmente são consideradas); veja Reporting Bugs para ver como fazer isso.

Template Tags

Uma outra maneira para que plugins adicionem funcionalidade ao WordPress é criando Template Tags personalizadas. Alguém que queira usar o seu plugin poderá adicionar essas “tags” ao seu tema, na barra lateral, na seção do conteúdo do post,  ou onde for apropriado. Por exemplo, um plugin que adicione tags geográficas aos posts podem definir uma função de tag chamada tag_list_states() para a barra lateral, a qual lista todos os estados que os posts tem, com links para as páginas de arquivo que o plugin ativa.
To define a custom template tag, simply write a PHP function and document it for Plugin users on your Plugin’s home page and/or in the Plugin’s main PHP file. It’s a good idea when documenting the function to give an example of exactly what needs to be added to the theme file to use the function, including the <?php and ?>.
Para definir uma Template Tag personalizada, simplesmente escreve uma função PHP e documente ela para usuários do plugin em sua página inicial e/ou no arquivo PHP principal de plugin. É uma boa idéia quando documentar a função dar um exemplo do que precisa exatamente ser adicionado ao arquivo do tema para usar a função, incluindo o <?php e ?>.

Salvando dados do plugin no banco de dados

Muitos plugins do WordPress precisarão obter alguma entrada do dono do site ou dos usuários do blog e salvar essa entrada entre sessões, para uso em funções e filtragem, de ação ou de template. Essa informação tem que ser salva no banco de dados do WordPress, para que possa ser persistente entre as sessões. Existem três métodos para salvar dados do plugin no banco de dados:

  1. Use o mecanismo de opções do WordPress (descrito abaixo). Esse método é apropriado para armazenas quantidades relativamente pequenas de dados estáticos – o tipo de dados que você esperaria que o dono do site teria que informar quando fosse configurar pela primeira vez o plugin, e raramente alterado depois.
  2. Post Meta (ou Campos Personalizados). Apropriados para dados associados com post individuais, páginas ou atalhos. Veja post_meta Function Examples, add_post_meta(), e funções relacionadas.
  3. Crie uma nova tabela no banco de dados. Esse método é apropriado para dados não associados com post individuais, páginas, atalhos ou comentários – o tipo de dados que crescerá a medida que o tempo passa, e que não tem nomes individuais. Veja Creating Tables with Plugins para informações de como fazer isso.

Mecanismo de opções do WordPress

Veja Creating Options Pages para informações de como criar um página que automaticamente salvará as suas opções para você.
O WordPress possui um mecanismo para salvar, atualizar e recuperar pedaços de dados (“opções”) do banco de dados. Os valores das opções podem ser strings, arrays, ou objetos PHP (eles serão “serializados”, ou convertidos em uma string, antes de serem armazenados, e des-serializados quando precisarem ser recuperados). Os nomes das opções são strings, e precisam ser únicas, para que não entrem em conflito com opções do WordPress ou de outros plugins.
Abaixo segue as funções principais que seu plugin pode usar para acessar as opções do WordPress.

add_option($name, $value, $deprecated, $autoload);
Cria uma nova opção; não faz nada se a opção existir.
$name
Nome da opção a ser adicionada (Required).
$value
O valor da opção a ser armazenado. O padrão é uma string vazia (Optional).
$deprecated
Você deve passar uma string vazia ou nula para esse argumento se quiser usar o parâmetro $autoload (Optional).
$autoload
Se configurado para ‘yes’ a configuração é automaticamente recuperada pela função wp_load_alloptions .O padrão é ‘yes’. (Optiona).
get_option($option);
Recupera uma opção do banco de dados.
$option
Nome da opção cujo valor será retornado. Você pode encontrar uma lista das opções padrão que são instaladas com o WordPress em Option Reference (Required).
update_option($option_name, $newvalue);
Atualize ou cria um valor de opção no banco de dados (note que add_option não precisa ser chamada se você não quiser usar os parâmetros $deprecated ou $autoload).
$option_name
Nome da opção a ser atualizada (Required).
$newvalue
O valor da nova opção (Required).

Painéis administrativos

Assumindo que o seu plugin possui algumas opções armazenadas no banco de dados do WordPress, você irá provavelmente querer ter um painel administrativo que permitirá que os usuários de seu plugin visualizem e editem os valores das opções. Os métodos para fazer isso são descritos em Adding Administration Menus.

Internacionalizando o seu plugin

Uma vez que você tenha feito a programação de seu plugin, outra consideração (assumindo que você planeja distribuir o seu plugin) é internacionalização. A internacionalização é o processo de configurar o software de forma que ele possa ser localizado; localização é processo de tradução do texto exibido pelo software em diferentes linguagem. O WordPress é usado por todo o mundo, de forma que esses dois processoas são embutido em sua estrutura, incluindo a localização de plugins.
Por favor note que os arquivos de idioma dos plugins NÃO SÃO carregados automaticamente. Adicione isso ao código do plugin para garantir que o arquivo de idioma seja carregado:

	load_plugin_textdomain('your-unique-name', false, basename( dirname( __FILE__ ) ) . '/languages' );

Para buscar uma string simplesmente use __(‘String name’,’your-unique-name’); para retornar a tradução ou _e(‘String name’,’your-unique-name’); para mostra a tradução. As traduções estarão na pasta /languages do plugin

Recursos externos