Getting Started With Custom PHP

Hooks: WordPress's Superpower #

One of WordPress's superpowers is its hooks! Hooks are the first thing you should learn if you want to add custom PHP to your site.

If you don't know what a WordPress hook is yet, please:

Read our definition of a hook
Learn more about hooks straight from WordPress

After you get a feel for what hooks can do, you'll need to learn how to add them to your site safely. This doc will guide you through the 2 ways we suggest you add custom PHP.

Easiest: Use the Code Snippets Plugin #

If you aren't comfortable or don't want to bother with editing server files, using the Code Snippets plugin (or equivalent) is the way to go!

Install the plugin by going to Plugins > Add New on the WordPress admin side menu. Then, search for Code Snippets, install and activate it.

Add a new snippet by going to Snippets > Add New on the WordPress admin side menu.

Once you see the Code editor, start typing your code or copy/paste/tweak an example snippet you have. When you're done editing, click Save Changes and Activate. If you don't see your changes for any reason, make sure your snippet is active and purge all caches.

Below is a screen capture of the Code Snippets code editor. This code snippet adds the wp_body_open action hook to display a top banner on a Twenty Twenty-One site.

What's happening in that example? Below is what that code does for us:

Callback function: Defines our function that runs when the wp_body_open action gets called
CSS: Declares the CSS to style our banner
HTML: Creates an HTML div tag to define our banner container and content
Front end: Tells the Code Snippet plugin to run this code only in the front end (public-facing) of our site
Priority: Gives our snippet the normal (execution) priority of 10

Here's the result.

Want to give it a try? Here's the source code on GitHub.

Adding PHP Without a Plugin #

If you don't want to use a plugin for your custom PHP, you'll need a child theme. After your child theme's set up, you can add your hooks directly into the child theme's functions.php file.

Remember when you created your child theme? A WordPress child theme needs at least a functions.php and style.css file. Here's a minimalist example of a child theme's web directory (/wp-content/themes/twentytwentyone-child/).

Editing a Child Theme's functions.php File #

Before you start editing server files, make sure you have a current backup of your site. You should also edit and test your changes on a staging copy instead of making changes directly on your live site.

Pro tip: Save a copy of the file you want to edit before you make any changes. You can save it in the same folder as the original. You'll just need to give it a different name, e.g., functions.php.bak. Then, if your edits crash your site, you can quickly revert to the backup file with a quick rename ;-). Just remember to either delete your bad version of the file or rename it to something else for debugging later.

Here are 3 ways you can edit your child's theme functions.php file.

SFTP (e.g. FileZilla)
cPanel File Manager
WordPress Theme Editor (only if there's no other way)

Just for the sake of an example, here's what a child theme functions.php file looks like in the Theme Editor.

In the example above, you'd start adding your custom PHP code (actions and filters) right after line 17. Even though you can use the built-in Theme Editor, we suggest you edit your functions.php using SFTP or File Manager. Learn more in the troubleshooting section coming up next.

Basic Troubleshooting #

Major caveat: Every time you add custom code, you take responsibility for testing and maintaining it. Here are some best practices you should follow:

Make sure you have a recent full backup of your site.
If you're editing your functions.php file, save a copy (as a backup) to your computer before editing it.
Test your code on a staging copy of your live site.
Remember that any custom code example you decide to reuse is exactly that—an example! Meaning, that you'll need to tweak and make sure the code works in your environment and meets your needs.

Whenever you need to troubleshoot your site for a possible plugin or theme conflict, make sure you disable all custom code.

If your site shows PHP error messages or a blank white page after making your PHP code changes, you'll need to "back out" or remove your last edits. Here are 4 ways you can do that:

If you're using the Code Snippets plugin (or something similar), deactivate your snippet.
Another option is to comment out your edits using // for a single line or /* */ for multiple lines. Remember to save your changes.
If copied your functions.php file before editing it, you can revert to your backup functions.php.
As a last resort, you can always restore your site from your last full backup.

Once you've backed out your last edits and your site working again like it was before, you can debug the code that caused the error.