Evaluating and Implementing Custom WordPress Code

Last week I looked at what you needed to know to understand how to customize WordPress. WordPress is awesome because with very little work, you can have a totally functional and great looking site. But this isn’t Wix, the real power of WordPress is that you have the power to customize it any way you need. Of course that isn’t always easy. basics of what languages WordPress is written in and how to use WordPress hooks and JavaScript events to customize your site.

In this article, I want to help you choose the best place to put code and how to test to make sure it’s the right code. I’ll cover some ways to ensure the code is secure and test that it really works before going live.

Where Do I Put Custom Code to WordPress?

In my article last week, I gave you an what kind of code does what on a WordPress site. As WordPress site developers we often find ourselves looking to code to solve problems.

We might want to change the way something looks. That means we need CSS code, but also we need to add that CSS code somewhere, which means we need to add PHP code to load a CSS file or add the CSS to our page.

We might want to add additional information to the checkout form of an eCommerce site or on a comment form. In my last article I talked about WordPress hooks. In this scenario we will need to find the right hook to use that allows us to run additional code at that hook.

When you think you found the right code on StackOverflow, WordPress Stack Exchange, the WordPress support forums or somewhere else on the Internet, do you know where to put it, how to test it and how to evaluate if it is secure?

Can I Put This Code In My Theme’s functions.php ?

Any change you make to WordPress itself or a plugin or theme will be lost when you update the plugin or theme or WordPress. This is why we have hooks and child themes. Child themes allow you to customize a theme without modifying it, and hooks let you modify the behaviour of all parts of WordPress without actually modifying the code.

So, when you’re looking at some PHP code you think may help, you really have only two options: placing it in your child theme’s functions.php or creating a plugin to hold it. A lot of people place code in functions.php. This works, but it is not the best idea.

The problem with using your theme for custom code, is that themes change. In fact a great troubleshooting step is to change your theme. This is why putting your custom code in plugin makes the most sense. It allows you to switch themes, and keep your custom code. Also, by creating lots of small plugins that you can easily turn on and off as needed or to aid in troubleshooting.

Creating a WordPress plugin is easy. Just add a file to your site’s plugin directory and start it with a valid plugin header. Here is an example:

<?php 
/*
Plugin Name: My Custom Code
*/

That’s pretty easy, right? Now each bit of custom code can have its own home independent of your theme.

Congratulations You Are A Plugin Developer!

Now that you know how to make a plugin, you can start making your own. This is awesome for you. Not only does it make testing and evolving sites easier, but it also means you more easily share code between sites. Put your plugins in Github repositories so you can easily install them on different sites you are working on. Also, you can share what you have done with others.

A lot of time I hear people asking for solutions to problems “without a plugin.” This is an interesting way of phrasing a question. It makes it seem like adding a plugin is a bad thing. I think what they mean is how to do something without having to use a plugin that is designed to work on any site.

The more abstract code is, the more it has to handle options and different ways it can be used, the less efficient it will be. There is no hard and fast rules for evaluating this, but it is a question that I often ask: if I take my time to make something totally custom, will it be that more performant and more functional enough to justify just using an existing plugin? The answer is almost always “no.”

But, using off the shelf plugins does mean I’m regularly adding a bunch of small plugins that use a few hooks to make a plugin or theme I’m using work exactly the way I or my clients need it to.

How To Evaluate WordPress Code For Security

There are no hard and fast rules for knowing if code is secure or not. But there are definitely things that you should look out for. For example, both PHP and JavaScript have functions called “eval” that allow you to execute other code. There are plenty of valid reasons to use these functions, but you should be suspicious when you see them used.

Another function to look out for is the php function base64_decode. This function has valid uses, but is often used to mask malicious code. If you see it in use in a plugin, theme or code snippet, be suspicious.

JavaScript has the ability to cause a page to navigate to another page or open another page automatically. This is really useful, but is also used to redirect site visitors to a phishing scam, or other bad site. If you see window.location or window.open or similar in JavaScript code, make sure you think about where it may be taking you and how it is called.

A few weeks ago a post was shared in a popular WordPress Facebook group that showed how to use WordPress’ admin-ajax API in a completely insecure way. Yes the post mentioned that, but the code examples were super insecure. It was a strong reminder that often times in order to simplify a tutorial, educational writers skip on security. Skipping on security for your site or your client’s site is never acceptable.

Learning to evaluate code for security is not something that is easy to learn. First, you must learn how to write secure code, which is something that will benefit you enormously. A great place to start is the WordPress plugin developer’s handbook section on security and the security section of 10up’s engineering best practices. Both are great resources to keep bookmarked.

How Do I Test Custom WordPress Code?

Before you run any code on a live site, you need to make sure it works and has no unintended consequences. This is why having a local development environment — a WordPress site running on your computer — is so important. If you mess up your local environment no one sees it and it is easy to fix.

Programs like DesktopServer make this really easy to do. If your host offers a staging environment, which it should, testing there is not as easy and quick as testing on a local site, but is a good second test before going live. Just remember a staging site is no substitute for local development environment.

A Testing Workflow

Before I end this article, I want to give you a brief walk through of a testing workflow. You should start by making a copy of your site on your computer. There are a lot of ways to do this. The easiest way is to use the free plugin WordPress Duplicator to make an export file which you can import into DesktopServer. You might also consider BackupBuddy which helps with both pulling live sites into a local environment and deploying your changes.

How ever you create your local WordPress development environment, make sure that in your wp-config, you have debug mode enabled fully. That means making sure that the WP_DEBUG, WP_DEBUG_DISPLAY, and WP_DEBUG_LOG constants are set to true:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', true );
define( 'WP_DEBUG_LOG', true );

By default WordPress suppresses all PHP errors, notices and warnings. This is a good thing on a live site, but on a testing site you want all of that to be shown so you can fix the issues fixing them.

As an aside, the so-called “WordPress White Screen of Death” is caused by a PHP fatal error that you can’t see because you have suppressed it. In those scenarios, add these same constants to your wp-config and you should see an error instead. It’s not a fix, but it’s a good first step.

Now that you have your local development environment working and some custom code to test, don’t add the code right away. First, check that you’re not already getting any errors. Often times turning on WP_DEBUG reveals a lot of issues that were hidden. You want to know if after you add custom code that any errors, warnings or notices you see are the fault of your custom code, or were preexisting.

Don’t forget that PHP is not the only language that could be having issues. There is also JavaScript. Most browsers have a JavaScript console and a network inspector. Make sure you have those open — there are cross browser/ OS instructions on how to do so here — and are on the lookout for JavaScript console errors, and error codes in the network inspector as you test your site.

Now browse through a few posts of each post type, and try all of your important forms — contact forms, checkout forms, comment forms — and see if you can make any errors. Record each one and if you can deduce from the file path given for the error what theme or plugin is causing it, reach out to their support. Also, copy those errors into a Google search and see what you get.

Once you are satisfied with the “baseline” you have established by fixing our deciding to live with any issues you have found, its time for that custom code. Add it into a custom plugin and activate that plugin. Now you can repeat exactly the process I walked through before making the change.

This time you are looking to see that the change took effect, and that it did not add new errors. There is nothing more frustrating than fixing one thing to find out that it broke something else but hopefully by checking it locally, you can fix it before it breaks your live site.

Once you are happy with the change in your local site you should push the change to your staging site to repeat this process. Having all of your changes in a custom plugin makes this easy, as you can just move that one plugin. Some people will do this via sFTP, but that gets messy quickly. The best way to do it would be to track your custom plugin’s development in a Git repository and then use either the Github plugin updater or WPPusher to move the plugin to your staging site and when ready to your live site.

How ever you move your custom code to your staging site, make sure to run through the same tests to ensure the change works and doesn’t break anything when it’s on a live server. Your staging site should have the debug constants set as on your local site.

When you are comfortable to move your changes to the live site, you probably don’t want to display PHP errors on the live site, but you still want to make sure no errors happen. This is where debug logging comes into play. On your live site, change your debug constants to look like this:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', true );

Now, because WP_DEBUG_DISPLAY is false, no errors will be shown on the screen. The WP_DEBUG_LOG constant is still true, so any errors will be written to the log. As you test your site, check the file debug.log in your site’s content directory. Any PHP errors, warnings or notices will be logged there. Just make sure to delete the log and turn all of those constants back to false when you are done.

Congrats, you just learned a good testing workflow. It is a process that you should be using not only for evaluating custom code, but also for plugin or theme updates and adding new plugins to your site.

Be Helped and Be Helpful

I hope this article has helped you understand what code to look for, and how to evaluate and test it when you are customizing a WordPress site. The WordPress community is so supportive, but don’t forget that giving is circular. You should always try and give in some way as much as you take others gifts.

Be sure to help others and share what you have learned. When people are helping you, be kind, be clear about what you are trying to do, why you’re doing it, what you expected to happen and what happened instead.

I love WordPress because it gives me an unending set of challenges to work with. Yes, it’s frustrating, but in the end I find the puzzles rewarding. I hope you feel the same way and that you’ve learned something in this article that will help you be less frustrated and better equipped to solve WordPress problems.