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 #
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_openaction 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
Remember when you created your child theme? A WordPress child theme needs at least a
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
- 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.
- 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 Code Snippets, deactivate your snippet.
- Comment out your edits using
//for a single line or
/* */for multiple lines. Save your changes.
- Revert to your backup
- 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.