Captain Hook

the Right Way to Extend WordPress

Arūnas Liuiza

WordPress Core Contributor, WordPress Kaunas Meetup co-organizer, WordCamp (Lithuania, Riga, Stockholm, Jyväskylä, Oslo, Norrköping) speaker and one of the editors of the Lithuanian WordPress translation team.

 

Free & premium WordPress plugin developer

 

Software Engineer at

  • Allows people to experience the world through travel and dining.
  • Part of Booking Holdings.
  • One of the engineering centers - in Kaunas.

Full-Stack PHP Engineer
kayak.com/careers/kaunas

/whois
WordPress

WordPress

  • A free and open-source content management system (CMS) based on PHP & MySQL.
  • Created in 2003
  • Licensed under GPL v2 license
  • The most popular CMS in the world (w3techs).
    • 33.5% of the internet*
    • 60.4% of CMS*
    • Joomla 2.9% Drupal - 1.9%

 

* - among top 10 million sites
      in Alexa ranking

Used by

.org vs .com

WordPress.org

  • The Open Source project
  • Dowladable, self-hosetd
  • Plugin repository
  • Theme repository
  • Support forums
  • Documentation
  • ....

WordPress.com

  • Hosted service
  • Free layer + paid plans
  • Akismet
  • Jetpack
  • Calypso
  • ...

Why WordPress?

  • Stability and compatibility
    • Safe and frequent updates
       
  • Big community
    • 967 WordCamps in 72 cities in 6 continents
    • 700+ regular local Meetups
       
  • Flexibility and extendability
    • 54,971 free plugins
    • 7,080 free themes

A brief history

b2/cafelog

WordPress

b2++

The year was 2003

b2evolution

0.7 - May 27, 2003

1.2 - May, 2004

  • Plugins
     
  • Moveable Type changes licence

 

1.5 - February, 2005

  • Static Pages
     
  • Comment moderation
     
  • Themes
    • Kubrik

2.0 - December, 2005

  • New Admin panel
    • DHTML
       
  • Akismet
  • WP-DB-Backup
     
  • functions.php

2008

  • Shortcodes
     
  • Plugin Installer
     
  • One-click updates
     
  • Admin panel UI
     
  • Child themes

3.0 - June 17, 2010

  • Custom post types
  • Custom taxonomies
     
  • Menu management
     
  • WordPress MU merge
  • One-click updates
     
  • Twenty Ten theme

2011 - 2013

  • 2011
    • Post Formats
    • Admin Bar
  • 2012
    • Theme Customizer
    • Theme Previews
    • New Media Manager
  • 2013
    • Most popular CMS
       
    • 3.7 - automatic updates
       
    • 3.8 - new admin interface

2014 - 2016

  • 2014
    • 3.9 - Post Editor updates
    • non-English downloads surpassed English
  • 2015
    • Localization
    • Emojis !!!
  • 2016
    • "Shiny" updates
    • Custom CSS
    • HTTPS
       
    • 4.7 - REST API

2017 - 2018

  • 2017
    • 4.8 - 4.9
    • New Widgets
    • Gutenberg the plugin
  • 2018
    • 5.0 - Gutenberg in Core

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
  • 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_filter( '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.

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?

Copy of Captain Hook - the Right Way to Extend WordPress

By Arūnas Liuiza

Copy of Captain Hook - the Right Way to Extend WordPress

  • 106
Loading comments...

More from Arūnas Liuiza