Captain Hook

the Right Way to Extend WordPress

Arūnas Liuiza

WordPress Core Contributor, WordPress Kaunas Meetup co-organizer, WordCamp (Lithuania, Riga, Stockholm) speaker and one of the editors of the Lithuanian WordPress translation team.

 

Free & premium WordPress plugin developer:

WordPress Expert on Codeable;

Founder of Arunas.co and EcoSim / Vini.lt;

Lecturer at Kaunas College.

Exp. level: Developer

I want to change
this one
simple thing(tm)...

General Rule

  • If there is a possibility some particular piece of code will get an update from the original author, you should not touch it.

In the ideal world

  • Do not modify WordPress Themes
    • Use Child Themes
       
  • Do not modify WordPress Plugins
    • Extend them via action and filter hooks
       
  • Do not modify WordPress Core
    • Extend it via action and filter hooks

Where do I put my
awesome
custom code?

Places for Custom Code

  • Child theme;
     
  • functions.php;
     
  • "My Custom Functions" plugin;
     
  • Custom plugin;

/whois a child theme?

  • It's a WP theme, based on another (parent) theme;
     
  • You can change only the templates that You need to change;
     
  • You can safely update parent theme;
     
  • Introduced in WordPress ~2.7​

/whois functions.php

  • A file in WordPress theme, where You can* put custom code;
     
  • Loaded with every page load;​
     
  • Very good for small presentation-centric/theme-specific snippets;
     
  • Changes will go away if You ever change Your theme;
     
  • 5.000 lines of code and 56 includes in functions.php
    • a REALLY bad idea

/whois My Custom Functions?

  • A plugin in WordPress.org repository;
     

  • Allows* You to enter custom code via WP Admin dashboard;
     
  • Your code stays active even when You switch themes;
     
  • Uses eval() to run the custom code - a major security issue.

/whois a Custom Plugin

  • A plugin You wrote ;)
     
  • In it's basic form - just a .php file in wp-content/plugins;
     
  • Needs a Plugin Header comment at the top of the file;
<?php
/*
Plugin Name: Health Check
Plugin URI: https://wordpress.org/plugins/health-check/
Description: Checks the health of your WordPress install
Version: 0.1.0
Author: The Health Check Team
Author URI: http://health-check-team.example.com
Text Domain: health-check
Domain Path: /languages
*/

?>

So, how do I
extend
WordPress?

Ways to Extend WordPress

  • Pluggable functions;
     
  • Action hooks;
     
  • Filter hooks;

/whois a pluggable function?

  • A WordPress function that can be overridden by a plugin;
     
  • Can be found in wp-includes/pluggable.php;
     
  • Just define a function with the same name in Your plugin;
     
  • Warning: some other plugin might do that before You do - potential for compatibility issues;

/whois a hook?

Design patterns

MVC

Event-driven

images by Tom McFarlin

So, /whois a hook?

  • Hooks are the way WordPress allows 3rd party-developers to extend their event-driven architecture.
     
  • Basically, hooks allow 3rd party developers to hook their own code to various events, that happen during WordPress pageload.
     
  • WordPress hooks come in two different flavors - action hooks and filter hooks.

/whois an action hook?

Actions are points in the WordPress lifecycle that allow you to add, remove, or modify certain functionality.

- Tom McFarlin

 

You, as a developer, can hook a custom function to be executed at that particular point. 

<?php add_action( 'wp_head', 'my_function' ); ?>

This line will execute my_function when WordPress is printing it's code in the <head> part of HTML document. 

An Example

<?php 
    add_action( 'wp_head', 'my_function' ); 
    function my_function() {
        echo '<!-- hello! -->';
    }
?>

The above code will print a '<!-- hello! -->' comment in the <head> part of any WordPress website.

/whois a filter hook?

Filters, on the other hand, are points in the WordPress lifecycle in which you can add, remove, or modify data.

- Tom McFarlin

 

You, as a developer, can hook a custom function to modify that piece of data. 

<?php add_action( 'the_title', 'title_filter' ); ?>

This line will make WordPress to pass article title to title_filter function and use the return value whenever WordPress prints an article title. 

An Example

<?php 
    add_filter( 'the_title', 'title_filter' ); 
    function title_filter( $title ) {
        $title = $title . ' :)';
        return $title;
    }
?>

The above code will make WordPress display a ':)' at the end of every post/page/menu item title.

Priority

  • When You are hooking a function, you can also set it's priority.
     
  • It will control the order of execution.
<?php 
    add_filter( 'the_title', 'function_1', 10 ); 
    add_filter( 'the_title', 'function_2', 9 ); 
    add_filter( 'the_title', 'function_3', 90 ); 
?>

Functions will be executed in this order: function_2, function_1, function_3

Accepted Arguments

  • Some hooks pass additional arguments to the hooked function.
  • You can tell how many arguments Your function expects to get.
<?php 
    add_filter( 'the_title', 'function_1', 10, 2 ); 
    add_filter( 'the_title', 'function_2', 10, 1 ); 
    add_filter( 'the_title', 'function_3', 10 ); 
?>

function_1 will receive 2 arguments (post title and post ID), while function_2 and function_3 will only get post title.

Note: filter functions will always receive one argument.

Where can I hook?

Where can I Hook?

Short answer - everywhere :)
 

Long answer - there are more than 2500 different action/filter hooks in current WordPress code base (and growing with every version).

 

  • WordPress Developer Reference has a list;

 

And if a list fail You, You can always just look at the relevant part in WordPress code.

Query Monitor

An awesome plugin by John Blackbourn

 

Top Menu > Hooks

 

Main action hooks in their execution order;

Together with all the functions that are attached to those hooks;

How can I
trigger
a hook?

Adding Hooks to Your Code

You can also add hooks to Your own code, to make it extendable and/or leverage features of other plugins or WordPress Core.

 

<?php 
    // trigger `wp_head` action
    do_action( 'wp_head' );

    // trigger `the_title` filter
    $title = apply_filters( 'the_title', $title, $post_id ); 
?>

Making Your Own Hooks 

Finally, You can also create Your own custom hooks, specific to Your code. Just use Your own hook name.

<?php 
    // trigger `arunas_action` action
    do_action( 'arunas_action' );

    // trigger `arunas_filter` filter
    $data = apply_filters( 'arunas_filter', $data ); 
?>

Recap

  • Do not modify code maintained by other people:
    • WordPress Core, themes & plugins.
  • Extend it using:
    • Child themes;
    • Pluggable functions;
    • Action and filter hooks.
  • Best place for custom code:
    • Child theme for theme-specific code;
    • Custom plugin for everything else;

Recap (continued)

  • Action hooks allow You to modify functionality;
     
  • Filter hooks allow You to modify data;
     
  • Remember, you might be not the only one hooking in;
     
  • Use hook triggers to make Your own code extendable;
     
  • You can create Your own hooks!

There always is
a hook
for that!

Questions?

ask@arunas.co

slid.es/arunas/captain-hook-stockholm