To start developing your own themes or plugins for WordPress, and to edit the code of those you are already using today, knowing how to write functions in PHP is basic.
If you just copy and paste the code snippets you find on the Internet, you may experience very frustrating situations: the code does not work as you want, your web features are broken, or even you are compromising the security of your installation.
And worst-case scenario, you don’t know why these things happen! Specially if you don’t understand the code snippet you’re copying and pasting. This is something you should always avoid. And to fix it, we have no choice but to learn.
To help you improve your WordPress skills, here is a small tutorial to learn how to write PHP functions and execute them on your WordPress. I will try to explain everything as simple as possible. Let’s do it!
Instructions For Writing a Function in WordPress
To be able to execute a function in WordPress the first thing you have to do is write it. Let’s see how we do it.
What do We Need?
To write a PHP function in your WordPress you don’t need anything extra. Unless you have limited permissions or your user has a non-administrator role, you can edit the functions.php file of your theme directly from WordPress. Go to the Appearance menu, then to Theme Editor, and there you can edit this file.
Be careful! Putting code in the functions.php file might not be the best option. In fact, it can be a total disaster if the code you put there has errors, since you will suffer a white screen and your website will stop working until you fix it. Remember that it is usually much better to put your code in a plugin.
Instead, use a code editor and a WordPress staging installation. For the local installation of WordPress you can use Local by Flywheel, which is quite simple to use. If you are more experienced you can try using Lando, but you don’t need to worry about complex things right now.
As for the code editor, you can use any text editor (without text formatting) or something more professional like Atom or VisualStudio Code. By the way, I now use the latter and I am delighted.
Finally, if you do not use a local WordPress installation and want to edit your server’s PHP files, you will need an FTP client to access them.
Nelio Content
I’m so happy about Nelio Content that I will sound like a payed advocate… but here’s why you’ll love it: it works as promised, its auto-scheduling feature is top-notch, Nelio’s value for money is unmatched, and the support team feels like your own.
Panozk
Document Your Code
Creating documentation in your code is something that, whether you like it or not, you must do. Not only for those who will read your code someday, but for yourself. I’m sure in the future you’ll forget what you did and will thank when you find out there is documentation in your old code to review.
In order to write documentation for a function I recommend that you use the PHPDoc or DocBlock standard, as indicated here.
Imagine you want to send an email every time a post is published in your WordPress. In that case, you should write a comment like the following:
Note that comments are defined within special characters /**/. If you use a code editor, it will probably help you when completing the asterisks in each line break.
In the previous comment, we first define in a short sentence the intent of our function: what it will do. Then, we can use a longer description explaining in more detail what the function does.
On the other hand, notice you can write comments in your own language (it does not need to be in English). However, if the comments and everything else are written in English, if you then upload the code to a public repository and other programmers see it, they’ll be able to understand your code and even contribute to it.
The Header of The Function
Once we have the basic documentation of the function, we can go on and write its header. That is, the name of the function next to its parameters (if any) and the brackets that define its scope.
For our example, we can do the following:
Notice that we first use the function keyword to indicate that we are going to write a function. Then comes the name of the specific function we are writing. To choose the name of the function, we must try to make this name indicative of what the function will do. In our case, notify when a post is published. Hence we have notify_on_post_published.
As we are not going to use namespaces yet, we have to make sure the function name is unique. Therefore, we add the custom prefix nelio_ (but you can and should use your own). I recommend you always use the same prefix in all your functions, so it will also help you quickly identify the ones you have developed.
After the name comes the list of parameters surrounded by parentheses. In this function, we have the $ID of a post and a $post object with the data of the post that’s been published. These parameters will then be used in the body of the function.
Finally, we define the body of the function between curly brackets: { and }. Although it is not mandatory, we also usually add a closing comment after the final curly bracket }, as you can see on line 13. This helps us identify that this specific curly bracket is the end of a function (which can come very handy in longer and more complex functions).
The Body of The Function
The body of the function is the set of instructions that “get the job done.” Let’s look at the body of our function, where we prepare the email and send it:
Note that the instructions end with the semicolon symbol in PHP. There are three blocks of instructions, each with an initial comment explaining what is done there.
In the first block we put in the $message variable the content of the email. In this content we also have the content of the post, which is obtained through $post->post_content.
In the second block we prepare the subject of the email and put it in the variable $subject. In the subject we also put the title of the post, which we get from $post->post_title.
Finally, we use the WordPress function wp_mail that is used to send an email. This function is called using parentheses and passing the parameters that we need. As the documentation indicates, we first pass the recipient’s email, then the subject, and then the message. We do this by first passing a text string with the email and then the two variables that we have been preparing in the previous instructions.
Notice how we have also documented the parameters that our function receives within the DocBlock (lines 8 and 9), so that anyone can understand that one parameter is the identifier of the post and the other is an object of type WP_Post with the post data.
Instructions to Execute a Function in WordPress
Even though we have been able to write a fairly successful function, the truth is that it will never be executed unless we do something else. Let’s see now how to run our code.
Connecting The Function With WordPress
For our function to run, we have to connect it with a WordPress hook. Hooks are actions or filters that WordPress executes when certain events occur. You can hook to them so that when WordPress runs a certain action or filter, it also runs your function.
Since our function has to send an email when a post is published, we need a WordPress hook that runs when a post is published. And there’s one, of course! WordPress has a publish_post hook we can use for this task. Read more about it here.
To connect to this hook we do the following:
As you can see, the code is the same as before but now on line 25 we have added the add_action function that is responsible for connecting our nelio_notify_on_post_published function with the hook publish_post.
We always use add_action or add_filter to connect with hooks of any kind (actions or filters). Here you have more details about WordPress hooks.
The last two parameters of add_action indicate the priority of execution of our function (the default value is 10) and the number of parameters to be passed to the connected function. In the case of the hook publish_post, two parameters are passed.
And that’s it. If we do this and go to the post editor and publish a new post, we will send an email to the address indicated in our function. I encourage you to give it a try and even create your own function, as practice.
Knowing How to Code Functions is Key to Becoming a WordPress Developer
Understanding how functions work in WordPress is essential to make the leap to real development with WordPress. Filters and actions are the most important tool that WordPress provides to extend the functionality of the platform.
If you have followed all the steps we have explained here and have understood everything, surely you have increased your WordPress skills. You still have a long way to go, but surely everything will be easier now.
There are thousands of options to make a living with WordPress without writing a single line of code. Do you think it is worth learning to develop in WordPress? I think so! Remember that you can leave me a comment down below with your opinion about it.
Featured image by Patryk Grądys on Unsplash.
Leave a Reply