WordPress.org

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Plugin API

Introduction

This page talks about the API documentation (Application Programming Interface) available for WordPress plugin developers, shows how developers of plugins can use them.

This article assumes that you've read Writing a Plugin, giving an overview (and many details) of how to develop a plugin. The same speaks specifically about the API "Hooks", also known as "Filters" and "Actions", used by WordPress to set your plugin at runtime.

These hooks can also be used in themes, as described here described here.

Ganchos, ações e filtros

Ganchos são fornecidos pelo WordPress para permitir que o mesmo interaja com outras funções do WordPress; isto quer dizer que agregam funções no seu plug-in a medida que vão sendo relacionadas e o mesmo é definido em tempo de execução. Existem dois tipos de ganchos:

  1. Actions (Codex Action Reference)
  2. Filters (Codex Filter Reference)

Você pode conseguir o mesmo objetivo com qualquer ação ou filtro. Por exemplo, se você quiser usar seu plugin para alterar o texto de um post, você pode adicionar uma função de ação publish_post (para modificar, uma vez que é salvo no banco de dados), ou uma função de filtro para the_content (que o post é modificado diretamente na tela do navegador).

Para obter uma lista completa de todos os ganchos de ação e filtro em WP der uma olhada em WordPress Hooks Database.

Reference function

Funções de filtro
  • has_filter() Verifique se qualquer filtro foi registrado por um gancho
  • add_filter() Faz a ligação de uma função ou método para uma ação de filtro específico.
  • apply_filters() Chamar as funções adicionadas a que tem relação com o filtro.
  • apply_filters_ref_array() Executar funções interligadas a um filtro específico, que por sua vez está ligada a uma matriz.
  • current_filter() Recuperar o nome do filtro ou ação atual.
  • remove_filter() Remove uma função ligada a um gancho do filtro especifico. Este método pode ser usado para remover funções com padrões presos a um gancho ou filtro específico e eventualmente substitui-los com um substituto.
  • remove_all_filters() Remove todos as ligações de um filtro.
  • doing_filter() Verifica se um filtro está sendo aplicado.
Actions Functions
  • has_action() Verifique se qualquer ação foi registrada por um gancho.
  • add_action() Faz a ligação de uma função a uma ação específica.
  • do_action() Executar funções dependente em um gancho de ação específica.
  • do_action_ref_array() Executar funções dependente em um gancho de ação específica, especificando os argumentos em uma matriz.
  • did_action() Recuperar o número de vezes que uma ação for acionada.
  • remove_action() Esta função remove uma função ligada a um gancho de ação especifica. Este método pode ser usado para remover funções padrão presa a um gancho de ação específico e possivelmente substituí-los com um substituto
  • remove_all_actions() Remover todos os ganchos de uma ação.
  • doing_action() Recuperar o nome de uma ação a ser processado.


Ativação / Funções desativação / Desinstalar

Ações

As ações são desencadeamentos de eventos específicos que ocorrem no WordPress, tais como a publicação de um post, alteração de temas, ou exibição de uma tela administrativa. A ação é uma função personalizada pelo código PHP que define seu plugin (ou tema) completamente dependente, ou seja, se limita a responder, para alguns desses eventos. Ações costumam fazer um ou mais dos seguintes procedimentos:

  • Modificar banco de dados.
  • Enviar uma mensagem de e-mail..
  • Modificar a tela do administração ou front-end de uma página gerada enviada para um navegador ou usuário.

Os passos básicos para que isso aconteça (descrito com mais detalhe abaixo) são os seguintes:

  1. Crie uma função PHP que deve ser executado quando um evento específico ocorre no WordPress, dentro do arquivo de plugin.
  2. Faça a ligação dessa função usando o evento add_action() function.
  3. Salve a sua função no formato PHP dentro arquivo de plugin, e é só ativá-lo..

Criar um ACTION FUNCTION

O primeiro passo na criação de uma ação no seu plug-in é criar uma função PHP com a funcionalidade do seu plug-in, e colocá-lo em seu arquivo de plug-in ‘’’(o arquivo plug-in deve ir para a pasta wp-content / plugins diretório).’’’ Por exemplo, se você quer enviar uma mensagem de e-mail para seus amigos sempre que criar um novo post, então você pode definir a seguinte função:

function email_amigos($post_ID)  {
    $amigos = 'bob@example.org,susie@example.org';
    mail($amigos, "sally's blog updated", 
      'I just put something on my blog: http://blog.example.com');
    return $post_ID;
}

Para a maioria das ações, a sua função deve aceitar um único parâmetro (geralmente o post ou comentário ID, dependendo da ação). Algumas ações demorar mais do que um parâmetro - verifique a documentação para a ação (se disponível) ou o código-fonte WordPress para mais informações. Além do um parâmetro, você também pode acessar as global variables of WordPress, e chamar outras funções do WordPress (ou funções em seu arquivo plugin).

Qualquer saída de texto pela função (por exemplo, com impressão) aparecerá no código fonte da página no local onde a ação foi invocado.

NOTA: Tenha em mente que outros plugins ou o núcleo WordPress já pode estar usando o nome da função que você tenha pensado. Consulte a próxima seção,Avoiding Function Name Collisions para obter mais informações.

Evitando Conflitos de Função Nome

É possível que alguém tenha criado um plugin com o mesmo nome do seu!

E isso é um grande problema porque o PHP não permite múltiplas funções com o mesmo nome. Se dois plug-ins fornecerem a função com o mesmo nome, ou um plug-in fornece uma função com um nome o mesmo de uma função nativa do WordPress, o blog poderia deixar de funcionar. Há duas maneiras de evitar esse problema.

A primeira solução é para prefixar cada função em seu plugin com um único conjunto de caracteres. Se seu nome é John Q. Public, você pode declarar suas funções como jqp_output function () {...}. A probabilidade de que alguém com as mesmas iniciais faz a mesma coisa com o seu plugin é possível, mas baixa.

A segunda - e possivelmente mais fácil - solução é encerrar suas funções de plugin em uma classe e chamar os métodos da classe estaticamente. Isso soa mais complicado do que é.

Considere esta classe, que se expande sobre os exemplos fornecidos acima:

class emailer {
  static function send($post_ID)  {
    $friends = 'bob@example.org,susie@example.org';
    mail($friends,"sally's blog updated",'I just put something on my blog: http://blog.example.com');
    return $post_ID;
  }
}

add_action('publish_post', array('emailer', 'send'));

Esta classe, chamada emailer tem um método send que implementa a funcionalidade plug-in.

A função add_action () fora da classe adiciona a ação para WordPress que diz-lhe para chamar o método de envio quando um post for publicado. A matriz utilizada no segundo parâmetro informando ao sistema de plug-in para chamar o método estático da classe 'emailer' nome 'Enviar'.

A função de envio é protegido do namespace global pela declaração de classe. Não é possível chamar send () diretamente, e assim por qualquer outra função chamada de envio não irá colidir com um presente. Se você quizer chamar send (), você precisar usar um operador de resolução de escopo, como este: emailer::send()

O exemplo acima é para métodos estáticos. Se você tiver uma instância de uma classe, tenha certeza, que não vai funcionar. Para chamar um método de uma instância que você precisa para instanciar como uma variável. Considere o exemplo acima modificado para levar isso em conta:

class emailer {
  function send($post_ID)  {
    $friends = 'bob@example.org,susie@example.org';
    mail($friends,"sally's blog updated",'I just put something on my blog: http://blog.example.com');
    return $post_ID;
  }
}
$myEmailClass = new emailer();
add_action('publish_post', array($myEmailClass, 'send'));

As aulas são muito complicadas. Leia mais sobre elas no PHP documentation on classes.

Link para WordPress

Após a sua função ser definida, o próximo passo é "linca-la" ou registrá-lo ao WordPress. Para fazer isso, chamamos a função add_action() na pasta de execução global do seu arquivo plugin:

add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] );

where:

hook_name 
É o nome que se dá a ação de lincar fornecida pelo WordPress, que informa ao evento que a sua função deve ser associado com o que se pede.
your_function_name 
Enforma o nome da função que você deseja que seja executada após o evento especificado pela hook_name. O mesmo pode ser uma função padrão do php, uma função presente no bloco do WordPress, ou uma função definida por você mesmo na pasta de plugin (tal como 'email_friends' acima definido).
priority 
É um argumento opcional utilizado para especificar a ordem em que as funções associadas a uma determinada ação é executada (default: 10). correspondem aos números mais baixos anteriormente executados e as funções com a mesma prioridade são executados na ordem adicionada à ação.
accepted_args 
Um argumento integer opcional que define quantos argumentos uma função pode aceitar (default 1), é bastante útil porque alguns links pode passar mais de um argumento para a sua função.Este parâmetro tem uma nova liberação 1.5.1.
Return Value 
O valor (opcionalmente modificado) do primeiro argumento passado para a função de filtro.

No exemplo acima, seria colocado a seguinte linha no arquivo plugin:

add_action ( 'publish_post', 'email_friends' );

Da mesma forma, você também pode Remove Actions lincar a ação. Veja essa seção para obter detalhes.

Instalar e ativar

O último passo para começarmos a trabalhar é instalar o arquivo e ativar os plugin. A função PHP que você escreveu e o add_action a mesma uma vez chamada deve ir para um arquivo PHP em conjunto, deve ser instalado na wp-content/pluginsdiretório. Uma vez instalado, você precisará visitar a seção de administração do WordPress e ative o seu plugin; Vejo Managing Plugins para mais detalhes.

Atuais Hooks para as ações

Veja Plugin API/Action Reference referente a lista atual de conexões com WordPress, e links para as versões anteriores do mesmo.

Filters

Filters are functions that WordPress passes data through, at certain points in execution, just before taking some action with the data (such as adding it to the database or sending it to the browser screen). Filters sit between the database and the browser (when WordPress is generating pages), and between the browser and the database (when WordPress is adding new posts and comments to the database); most input and output in WordPress passes through at least one filter. WordPress does some filtering by default, and your plugin can add its own filtering.

The basic steps to add your own filters to WordPress (described in more detail below) are:

  1. Create the PHP function that filters the data.
  2. Hook to the filter in WordPress, by calling add_filter().
  3. Put your PHP function in a plugin file, and activate it.

Create a Filter Function

A filter function takes as input the unmodified data, and returns modified data (or in some cases, a null value to indicate the data should be deleted or disregarded). If the data is not modified by your filter, then the original data must be returned so that subsequent plugins can continue to modify the value if necessary.

So, the first step in creating a filter in your plugin is to create a PHP function to do the filtering, and put it in your plugin file (your plugin file must go into the wp-content/plugins directory). For example, if you want to make sure that your posts and comments contain no profanity, you might define a variable with a list of forbidden words, and then create the following PHP function:

function filter_profanity( $content ) {
	$profanities = array('badword','alsobad','...');
	$content = str_ireplace( $profanities, '{censored}', $content );
	return $content;
}

Why does this work without a loop? Because $profanities is an array, and str_ireplace loops through the array for you. The str_ireplace function is used instead of str_replace because str_ireplace is case insensitive.

NOTE: Keep in mind that other plugins or the WordPress core may already be using the function name you have thought of. See the Plugin Development Suggestions for more information.

Hook in your Filter

After your function is defined, the next step is to "hook" or register it with WordPress. To do this, call add_filter() in the global execution space of your plugin file:

add_filter ( 'hook_name', 'your_filter', [priority], [accepted_args] );

where:

hook_name 
The name of a filter hook provided by WordPress, which defines when your filter should be applied.
your_filter 
The name of the function that you want to use for filtering. This can be a standard PHP function, a function present in the WordPress core, or a function defined by you in the plugin file.
priority 
An optional integer argument that can be used to specify the order in which the functions associated with a particular filter are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.
accepted_args 
An optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function.

In the example above, we would put the following in the main executing section of the plugin file, to tell WordPress to filter comments for profanity:

add_filter( 'comment_text', 'filter_profanity' );

You can also remove filters from filter hooks using the remove_filter() function. See Removing Actions and Filters.

Install and Activate

The last step in getting your filter hook to work is to install the file and activate the plugin. The PHP function you wrote and the add_filter() call must go into a PHP file together, and the PHP file must be installed in the wp-content/plugins directory. Once it is installed, you will need to visit the admin section of WordPress and activate your plugin; see Managing Plugins for more details.

Current Hooks for Filters

See Plugin API/Filter Reference for a current list of filter hooks in WordPress, and links to previous versions of WordPress.

Example

This is an example, as described by Ozh on the wp-hackers email list, for a plugin to modify (or overwrite) the default bloginfo() function. This will require modifying a core function behavior.

add_filter( 'bloginfo', 'mybloginfo', 1, 2 );
add_filter( 'bloginfo_url', 'mybloginfo', 1, 2 );

function mybloginfo( $result='', $show='' ) {
	switch ( $show ) {
		case 'wpurl':
			$result = SITE_URL;
			break;
		case 'template_directory':
			$result = TEMPL_DIR;
			break;
		default: 
	}
	return $result;
}

Removing Actions and Filters

In some cases, you may find that you want your plugin to disable one of the actions or filters built into WordPress, or added by another plugin. You can do that by calling remove_filter('filter_hook','filter_function') or remove_action('action_hook','action_function').

For example, remove_action('publish_post','generic_ping'); would prevent your weblog from sending pings whenever a new post is created.

Note that if a hook was registered using a priority other than the default of 10, then you must also specify the priority in the call to remove_action(). Also note that in general, you shouldn't remove anything unless you know what it does and why it does it -- check the WordPress or other plugin source code to be sure.

Pluggable Functions

Besides the hooks (actions and filters) described above, another way for a plugin to modify WordPress's behavior is to override WordPress functions. In fact, there is a small set of functions WordPress intends for plugins to redefine. These are called Pluggable Functions and they are defined in wp-includes/pluggable.php. WordPress loads these functions only if they are still undefined after all plugins have been loaded. For more details examine wp-settings.php file.

Activation/Deactivation/Uninstall

If your plugin has tasks to complete only at activation or deactivation time, it can use register_activation_hook and register_deactivation_hook. Many plugins do not need to use these, as the plugins only modify current behavior. However, if your plugin (for example) needs to change a default option on activation, it can use these functions.

Creating Tables with Plugins has an example using the register_activation_hook function to make the database compatible with the current version of the plugin.

The register_uninstall_hook gives your plugin the option of cleaning up after itself when it is deleted from the WordPress installation. Users have reasons to temporarily deactivate plugins, so do not do anything from the deactivation hook that would lose any user settings. This is what the uninstall hook is for.

Related

External Resources