Como Criar Plugins para WordPress (Parte I)

O WordPress é uma das ferramentas para gestão de sites que tem vindo a crescer mais rapidamente nos últimos anos. Uma das razões provém da sua arquitetura altamente extensível através de plugins a par com a sua API simples de implementar. Recentemente um dos nossos leitores contatou-nos indicando que estava tendo dificuldades em encontrar tutoriais WordPress sobre criar plugins, e sugeriu-nos então que publicássemos uma série de artigos sobre como criar plugins para WordPress, ideia essa que decidimos aceitar!

O QUE SÃO OS PLUGINS NO WORDPRESS?

Um plugin no WordPress é uma porção de código escrito em PHP que é incluído na pasta wp-content/plugins e que aumenta as funcionalidades do WordPress através da implementação de Hooks – acções e filtros – em várias partes do código do WordPress.

Após a activação de um plugin, o WordPress encarrega-se de registá-lo sempre que há uma chamada ao site, analisando que acções e filtros é que ele implementa.

Desta maneira a extensabilidade torna-se algo muito simples de conquistar e de aprender. :)

COMO É QUE OS PLUGINS INTERAGEM COM O WORDPRESS

Existem várias APIs que o WordPress fornece para que os plugins possam trabalhar funcionalidades usando-as. Cada API, ou application programming interface (interface de programação da aplicação), ajuda a interagir de diferentes maneiras.

• Plugin – Providencia as hooks – um conjunto de acções e filtros – para que os plugins possam interagir em várias partes do WordPress de maneira muito simples;
• Widgets – Permite colocar pedaços de código nas sidebars registadas do nosso tema, fazendo com que haja o display de várias informações na parte do site.
• Shortcode – Permite que um editor chame uma função PHP definida no plugin de maneira simples no editor de posts.
• HTTP – Esta API é um meio standard para fazer chamadas HTTP a servidores remotos sem que o autor do plugin se tenha que preocupar se existe cURL instalado. Basta chamar através desta API e ela preocupa-se em determinar qual o método de chamada mais apropriado para o servidor em que corre.
• Settings – Permite a inserção de campos de opções personalizados na administração do WordPress para que estes possam ser usados pelos plugins facilmente. Com esta API o autor não se tem que preocupar com segurança nos ataques CRSF e XSS – ela faz tudo por si.
• Dashboard Widgets – Permite criar e alterar widgets para a Dashboard da administração e com controlo de acessos.
• Rewrite – Possibilita a criação de rewrite rules personalizadas para vários pontos do código dos plugins.
• Transients – Sistema de cache básico persistente na base de dados com tempo de expiração. Pode ser usado para adicionar opções temporárias.
• Database – Acesso rápido à base de dados sem haver necessidade de conhecimento de SQL. Permite inserir, atualizar, remover e selecionar registos.
• Pluggable Functions – Funções providenciadas pelo WordPress que podem ser completamente redefinidas. É o caso da função wp_mail() que pode ser alterada para usar um servidor SMTP em vez do atual Sendmail.

VANTAGENS DE SE CRIAR UM PLUGIN

Uma das principais vantagens é a de não se ser obrigado a alterar o código fonte do WordPress! Com isto podemos estar seguros que uma atualização da versão do WordPress não irá “destruir” as alterações que fizémos.

Outra vantagem é o que a comunidade chama de plugin sandbox: quando se ativa um plugin o WordPress “testa” o plugin por forma a que este não quebre a nossa instalação se gerar um erro fatal. Esta forma de procedimento salvaguarda todo o trabalho que tivemos anteriormente em contruir e manter o nosso site. :)

TIPOS DE PLUGINS

O que muita gente não sabe é que no WordPress existem três tipos de plugins. São estes:

• “Regulares” – que podem ser ativados e desativados a qualquer mamento a partir da página de plugins;
• “Must-Use” – ou simplesmente MUPlugins (não confundir com Multisite, não é a mesma coisa) que são ficheiros de plugins, normalmente constituidos por apenas um ficheiro PHP e que não necessitam de registar CSS nem JS. Esses pequenos plugins encontram-se na pasta /wp-content/mu-plugins/ e são ativados automaticamente pelo WordPress. A única forma de os desativar é removendo-os dessa diretoria. São os primeiros plugins a ser ativados e portanto servem principalmente para alterar funcionalidades da core e não para extender funcionalidades como faz a maior parte dos plugins regulares;
• “Drop-ins” – Algumas funcionalidades específicas do WordPress podem ser alteradas através de ficheiros com nomes específicos colocados na pasta /wp-content. Se os seguintes ficheiros forem encontrados, serão automaticamente carregados em momentos específicos:
  • advanced-cache.php – Para uso de cache avançada, como por exemplo, cache persistente. É normalmente usado para plugins de cache como o WP Super Cache e o W3 Total Cache.
  • db.php – Implementa uma nova classe PHP para gestão da base de dados. A classe irá sobrepor-se à classe nativa wpdb. Uma boa maneira de ver uma implementação disto é usando o plugin da Automattic Hyper DB que implementa uma classe PHP que faz a gestão de multiplas bases de dados MySQL.
  • db-error.php – Implementa uma mensagem de erro de acesso ao MySQL customizada
  • install.php – Possibilita a implementação de um script de instalação customizado.
  • maintenance.php – Mensagem customizada de site em manutenção.
  • object-cache.php – O WordPresstem uma cache não-ersistente no entanto é possível implementar uma classe de cache alternativa que use, por exemplo, o memcached ou o sistema PHP-APC.
  • sunrise.php – Permite implementar um sistema de mapeamento de domínios. Usado pelo plugin WordPress MU Domain Mapping.
  • blog-deleted.php – Mensagem de blog apagado customizada
  • blog-inative.php – Mensagem de blog inativo customizada
  • blog-suspended.php – Mensagem de blog suspenso customizada

TESTANDO FUNCIONALIDADES COMO SE FOSSEM PLUGINS

Este método serve como uma sandbox para testar ou implementar scripts feitos especialmente só em PHP. É óptimo para fazer o display de variáveis e uma óptima forma de implementar standalone scripts já criados.

<?php

// Se quisermos ativar o modo de depuração de erros
// definimos com o valor true a seguinte constante
define( 'WP_DEBUG', true );

// Vamos carregar o ambiente do WordPress a partir
//de um único local, o wp-load.php
require( './wp-load.php' );

// Ja temos o WordPress carregado, já é possível usar
// as suas potencialidades e testar os nossos códigos
// ou apenas incluir um script standalone.

?>

<?php include( 'script-standalone.php' ); ?>

Como visto, basta carregar o ficheiro wp-load.php para o nosso ficheiro de script para iniciar o ambiente do WordPress.

Embora isto não seja propriamente um plugin, não deixa de ser uma funcionalidade bastante interessante e que trás muitas vantagens.

CONVENÇÕES

Para que o seu plugin possa coexistir num ambiente em que outros plugins residem, algumas convenções devem ser seguidas:

• Mantenha sempre o seu plugin dentro de uma diretoria com o nome do seu plugin, permitindo assim uma organização dos ficheiros mais equilibrada.
• Se o seu plugin for criado para ser distribuido, não use as tags à lá ASP <? ?>, use por as tags <?php ?>. Inclua também comentários das suas funções ao estilo PHPDoc ou comumente conhecido, HereDoc.
• Prefixe sempre as suas funções com um nome comum, pode ser por exemplo, o nome do seu plugin.
• Use técnicas de código PHP compatíveis com o PHP versão 5.2. Evite técnicas superiores a essa versão.

O CABEÇALHO DO PLUGIN

O cabeçalho do plugin é um pequeno snippet de comentários em PHP que mantém a informação necessária para que o WordPress reconheça o plugin e mostre algumas informações relativas ao plugin.

Esse cabeçalho deve-se encontrar nos primeiros 8kB do ficheiro principal do plugin. Para evitar problemas, os developers colocam-no sempre no início.

Para o seu primeiro plugin, cria a diretoria o-meu-plugin dentro do wp-content. Dentro dessa diretoria vamos criar um ficheiro PHP chamado o-meu-plugin.php.

O cabeçalho que deve ser introduzido nesse ficheiro é o seguinte:

<?php
/*
Plugin Name: O meu Plugin
Plugin URI: http://exemplo.org/o-meu-plugin
Description: Um plugin de teste didático
Version: 1.0
Author: Aluno da Escola WordPress
Author URI: http://exemplo.org
License: GPLv2
*/
?>

Este cabeçalho é muito direto e as informações que contém devem ser adaptadas com o seu nome, endereço de email e URL.

Algo muito importante a ter em conta é o copyright do plugin. Existe muita discussão pela internet sobre se os plugins WordPress podem ter ou não licenças proprietárias, isto é, não compatível com as licenças OpenSource, nomeadamente a licença GPL que é a que a core do WordPress usa. Este é um assunto sério e que deve ser respeitado, pois a legislação de direitos de autor existe! A verdade é a seguinte: a licença GPL diz que qualquer trabalho derivativo de um trabalho licenciado em GPL deve ter a mesma licença ou pelo menos uma licença compatível com GPL. Os plugins, como usam código proveniente da core do WordPress são considerados trabalhos derivativos, sendo assim devem seguir o mesmo trâmite de licença.

Deverá colocar isto logo a seguir ao cabeçalho do plugin:

/*
 *      Copyright 2012 Aluno da Escola WordPress <email@exemplo.org>
 *
 *      This program is free software; you can redistribute it and/or modify
 *      it under the terms of the GNU General Public License as published by
 *      the Free Software Foundation; either version 3 of the License, or
 *      (at your option) any later version.
 *
 *      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 Street, Fifth Floor, Boston,
 *      MA 02110-1301, USA.
 */

Este comentário mostra é uma informação para mostrar a licença do plugin protegendo-o para que terceiros não “abusem” das suas criações.

Gostaria de dar ainda algumas notas acerca da licença GPL:

1. Ela permite a livre redistribuição do código, caso o autor o libere, mas não força o autor a redistribui-la se não for essa a intensão – o autor é que decide se quer manter só para si ou liberá-la à comunidade.
2. O código em GPL alterado deve manter os créditos ao(s) autor(es) origina(l/is).
3. Você pode pedir um valor monetário aos seus clientes pelo código GPL, porém não pode impossibilitar terceiros a redistribui-lo gratuitamente.

FUNÇÕES PARA DETERMINAR CAMINHOS E URLS

A partir deste ponto, você já tem um plugin que pode ser ativado a partir da administração! Todo o código seguinte irá ser incluido nesse ficheiro ou em ficheiros que ele inclua com as diretivas include ou require.

Determinar os caminhos para incluir ficheiros e os links para imprimir imagens, CSS e scripts pode ser uma tarefa muito complicada. Felizmente o WordPress graciona-nos com várias funções muito importantes:

• plugin_dir_path( $file ) – esta função aceita como argumento um nome do ficheiro retornando o caminho absoluto para a diretoria em que o ficheiro está incluído. Usando em combinação com a constante __FILE__, esta função é muito valiosa pois retornando a diretoria do plugin em questão, todos os caminhos a incluir passam a ser relativos, auxiliando assim a programação.
  Uso comum: <?php include( plugin_dir_path( __FILE__ ) . ‘ficheiro/a/incluir.php’ ); ?>
  Exemplo: /www/wp-content/o-meu-plugin/ficheiro/a/incluir.php
• plugins_url( $path, $file ) – esta função aceita como argumentos o caminho URL para uma imagem, CSS ou script relativo à diretoria onde o ficheiro passado no segundo no segundo argumento está incluído.
  Uso comum: <?php echo plugins_url( ‘images/imagem.png’, __FILE__ ); ?>
  Exemplo: http://exemplo.org/wp-content/plugins/o-meu-plugin/images/imagem.png
• includes_url() – retorna a URL para a diretoria wp-includes
  Exemplo: http://exemplo.org/wp-includes
• content_url() – retorna a URL para a diretoria wp-content
  Exemplo: http://exemplo.org/wp-content
• admin_url() – retorna o link para a área de administração
  Exemplo: http://exemplo.org/wp-admin
• home_url() – retorna o link para a homepage do site
  Exemplo: http://exemplo.org

É muito importante usar-se exclusivamente estas funções para determinar os caminhos. Algumas das vantagens são:

1. Elas suportam SSL, caso o site esteja a ser visualizado em https
2. Elas suportam as contantes e opções do multisite, retornando os valores atuais para o domínio do blog em questão. Assim, caso haja mapeamento de domínios, elas retornam o valor para esse domínio, em vez do subdomínio nativo.

Exemplos de uso:

<?php

// Incluir um ficheiro que se encontre na mesma
// diretoria do plugin.

include( plugin_dir_path( __FILE__ ) . 'ficheiro-a-incluir.php' );
// Fazer o display de uma imagem localizada
// na diretoria do plugin.

$imagem = '<img src="'.plugins_url( 'imagem.png', __FILE__ ).'" alt="" />';

// Criar um link para a homepage
$link = '<a href="'.home_url().'" title="Home">Homepage</a>';

Não se esqueça que este plugin é apenas um exemplo de implementação.

FUNÇÕES DE ATIVAÇÃO, DESATIVAÇÃO E DESINSTALAÇÃO

Quando um usuário ativa, desativa ou desistala um plugin, alguns métodos devem ser chamados por forma a permitir o plugin tomar certas decisões nessas alturas.

Porquê? Imagine por exemplo um plugin que necessita de criar opções iniciais para funcionar, usando uma função customizada, é possível criar essas opções durante a instalação.

Registar uma função de instalação

A função register_activation_hook( $file, $function ) regista uma função customizada para ser executada apenas na ativação do plugin. Esta função aceita como parâmetros essa função customizada e o ficheiro em que a função está localizada.

Exemplo de uso:

<?php

// Registamos a função para correr na ativação do plugin
register_activation_hook( __FILE__, 'ewp_install_hook' );

function ewp_install_hook() {
  // Vamos testar a versão do PHP e do WordPress
  // caso as versões sejam antigas, desativamos
  // o nosso plugin.
  if ( version_compare( PHP_VERSION, '5.2.1', '<' )
    or version_compare( get_bloginfo( 'version' ), '3.3', '<' ) ) {
      deactivate_plugins( basename( __FILE__ ) );
  }

  // Vamos criar um opção para ser guardada na base-de-dados
  // e incluir um valor por defeito.
  add_option( 'ewp_opcao', 'valor_por_defeito' );

}

Registar uma função de desinstalação

A função register_deactivation_hook( $file, $function ) tem o mesmo comportamento que a anterior porem apenas é corrida na desativação do plugin. Sendo assim, qualquer função de desativação customizada deve ser registada com isto.

Ficheiro de desinstalação uninstall.php

Todos os plugins devem ter este ficheiro na sua diretoria. Este ficheiro é chamado pelo WordPress quando um usuário remove o plugin em causa. É aqui que iremos remover quaisquer vestígios do plugin da base de dados do WordPress.

Por exemplo, aqui devemos remover as opções criadas durante a instalação.

Exemplo de ficheiro uninstall.php:

<?php

// Vamos garantir que é o WordPress que chama este ficheiro
// e que realmente está a desistalar o plugin.
if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) )
  die();

// Vamos remover as opções que criámos na instalação
delete_option( 'ewp_opcao' );

?>

HOOKS DE ACÇÃO E DE FILTRO – O CORE DOS PLUGINS

Nesta secção iremos falar das hooks, o core dos plugins do WordPress. É com as hooks que os plugins conseguem interagir com o WordPress em determinadas situações definidas por essas hooks.

Existem dois tipos de hooks:

• Acções: permitem aos developers “colocar” pedaços de códigos em pontos específicos na execução do WordPress.
• Filtros: permite filtrar informações (principalmente variáveis) e manipular o output do código. Ao contrário das acções, estas hooks permitem “reescrever” código em determinados pontos.

As funções add_action() e add_filter() possibilitam essa interação. Essas duas funções aceitam como argumentos o nome da hook que queremos alterar e a assinatura da função que providencia o código customizado.

O seguinte código é executado no início do WordPress, durante a hook init:

<?php

add_action( 'init', 'ewp_funcao_a_chamar' );

function ewp_funcao_a_chamar() {
  // Corre um código qualquer em PHP no init
}

?>

Lista de Acções mais usadas

• plugins_loaded – é usado pelos plugins. Nenhum código do seu plugin deve ser executado antes desta acção, assim, todo o código inicial deve ser colocado dentro desta acção.
• init – nesta hook já todo o código core do WordPress foi carregado, o que nos garante que podemos usar qualquer função e ler qualquer variável global do WordPress pois essas já estão carregadas.
• admin_init – é igual à init, só que é carregado após todo o interface da administração estar concluído.
• wp_head – esta hook possibilita a impressão de código no cabeçalho <head> da página. Ideal para colocar metatags e códigos script e style.
• admin_head – igual à anterior porem só funciona na administração.
• admin_menu – serve para adicionar páginas ao menu da administração.
• wp_footer – imprime ou executa código no rodapé da página.

Iremos falar mais sobre esta API na segunda parte desta série.

Download do código O Meu Plugin

Nota: peço especial atenção para não usar este código como plugin, pois, além de não implementar nenhum funcionalidade, pode comprometer a sua instalação. Serve apenas para fins didáticos.

LEITURA RECOMENDADA

Sugestões de leitura adicional prendem-se com o seu interesse em aprender mais acerca da criação de plugins para o WordPress. Se souber Inglês e for o seu caso, então sugiro:

1. Use o Codex do WordPress para procurar funções, aprender a API e conhecer novas técnicas de código. Como esta está em formato de wiki comunitária, ou seja, qualquer um pode editar, aproveite e colabore criando e atualizando novos conteúdos do Codex.
2. Inscreva-se na WordPress Hackers List e faça perguntas diretamente aos developers do WordPress.
3. Frequente e faça perguntas em sites da especialidade. Comente aqui no Escola WordPress os posts colocando novos códigos e tirando dúvidas; participe nas discussões do WP Tavern.
4. Adquira um bom livro que será como um bíblia para si. O Professional WordPress Plugin Development, criado por três developers do core do WordPress (Brad Williams, Ozh Richard, Justin Tadlock), profissionais com dezenas de plugins criados, é um bom começo para aprender novas técnicas, reunindo o essencial para a criação ótimos plugins.

E é tudo! Espero que este artigo lhe tenha trazido novas luzes para o desenvolvimento do seu plugin. Não se esqueça de comentar e aguarde pelo segundo artigo desta série que falará sobre a API do WordPress, algumas classes e segurança.

Até breve e um abraço,

Vitor