- You want to add a cool new feature to your WordPress site so you look up a tutorial on how to make it happen.
- The tutorial gives you a chunk of code and tells you to paste it inside functions.php.
- You do that.
- Your site breaks. Maybe you get a scary error message, or just an empty white page.
I’m going to help you avoid the white screen of death.
I guess I should start this by saying that I can’t guarantee you won’t break your site. But my goal in this post is to help you understand what’s going on in functions.php so you can better navigate around the code and have a smaller chance of breaking your site!
So let’s talk a bit about how the functions.php file works.
functions.php is for PHP code
Most (if not all) of the functions.php file is in a language called PHP. That means:
- This is not the place to put custom CSS code.
- This is not the place for HTML (unless you know what you’re doing!).
This file is for PHP snippets and functions.
These functions change the behaviour and functionality of your site. So let’s look at some of the files that make up a WordPress theme:
- style.css — Contains CSS code. This file changes the appearance of your site, including fonts, colours, spacing, and layouts.
- Template Files (like index.php, archive.php, single.php, etc.) — Contain HTML and bits of PHP. These files insert content into your pages. They’re responsible for inserting the post titles in the right place, the post content in the right place, etc. Template files make text and HTML appear on your site.
- functions.php — Adds features and functionality to your site. For example: creating new widget areas, adding support for featured images, adding extra settings to the Customizer, etc.
PHP code goes inside PHP tags
All of the PHP in the file needs to be inside PHP tags. Those look like this:
<?php // PHP code can go in here! ?>
This immediately tells us one important thing: if you want to insert code at the top of the file, it needs to be after the opening <?php tag.
Note that the closing PHP tag is optional at the end of the file. So if you don’t see ?> at the bottom of the file, that’s okay. It’s optional.
An example chunk of code
Here’s an example of something you might find in functions.php:
/**
* Register widget area.
*
* @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
*/
function _s_widgets_init() {
register_sidebar( array(
'name' => esc_html__( 'Sidebar', '_s' ),
'id' => 'sidebar-1',
'description' => esc_html__( 'Add widgets here.', '_s' ),
'before_widget' => '<section id="%1$s" class="widget %2$s">',
'after_widget' => '</section>',
'before_title' => '<h2 class="widget-title">',
'after_title' => '</h2>',
) );
}
add_action( 'widgets_init', '_s_widgets_init' );
This particular piece of code is for creating a new widget area (sidebar). Let’s dissect it a little:
/** * Register widget area. * * @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar */
This is a comment. It doesn’t do anything—it’s just for explaining what the code does. Comments are a bit like footnotes.
- Don’t insert code in the middle of a comment—it won’t work. No code inside a comment gets executed.
- Don’t delete anything at the beginning or end of a comment. If you remove the slash at the beginning, the comment will break, and that will break your whole functions.php file. Same if you accidentally remove the slash from the end.
function _s_widgets_init() {
// 'register_sidebar' code stuff was in here
}
This is the declaration of a new function. A function is basically a piece of code that does something. That’s vague, I know.
- Unless you know what you’re doing, don’t mess with existing functions.
- Don’t try to place your code inside an existing function (again, unless you know what you’re doing).
- Make sure you wait until a function is ‘over’ before you insert your code. Look for the closing curly brace:
}. That designates the end of a function.
Where to place your code
It’s a good idea to find a nice empty space. Don’t aim for the middle of your functions.php file, since you’re more likely to accidentally interfere with another piece of code there. Instead, I recommend heading straight to the end of functions.php.
- Insert your code at the bottom of the file, after all other code. Add a few empty lines between the last bit of code on the site and your new snippet.
- If there’s a closing PHP tag like thsi:
?>then place your code before that. Leave the>tag on the line below your code. - If there’s no closing PHP tag, then that’s okay. You don’t need to add one.
Examples:
Let’s say you want to add this code to your functions.php file:
add_filter( 'widget_text', 'do_shortcode' );
Here are some different examples (some wrong, some right):
WRONG
/**
* Register widget area.
*
* @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
*/
function _s_widgets_init() {
register_sidebar( array(
add_filter( 'widget_text', 'do_shortcode' );
'name' => esc_html__( 'Sidebar', '_s' ),
'id' => 'sidebar-1',
'description' => esc_html__( 'Add widgets here.', '_s' ),
'before_widget' => '<section id="%1$s" class="widget %2$s">',
'after_widget' => '</section>',
'before_title' => '<h2 class="widget-title">',
'after_title' => '</h2>',
) );
}
add_action( 'widgets_init', '_s_widgets_init' );
Can you see where I inserted the snippet? Smack dab in the middle of a function! This would break the whole function and cause big errors on your site.
CORRECT
/**
* Register widget area.
*
* @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
*/
function _s_widgets_init() {
register_sidebar( array(
'name' => esc_html__( 'Sidebar', '_s' ),
'id' => 'sidebar-1',
'description' => esc_html__( 'Add widgets here.', '_s' ),
'before_widget' => '<section id="%1$s" class="widget %2$s">',
'after_widget' => '</section>',
'before_title' => '<h2 class="widget-title">',
'after_title' => '</h2>',
) );
}
add_action( 'widgets_init', '_s_widgets_init' );
add_filter( 'widget_text', 'do_shortcode' );
This time I found the end of the function and then inserted my code. Technically this would be okay too:
/**
* Register widget area.
*
* @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
*/
function _s_widgets_init() {
register_sidebar( array(
'name' => esc_html__( 'Sidebar', '_s' ),
'id' => 'sidebar-1',
'description' => esc_html__( 'Add widgets here.', '_s' ),
'before_widget' => '<section id="%1$s" class="widget %2$s">',
'after_widget' => '</section>',
'before_title' => '<h2 class="widget-title">',
'after_title' => '</h2>',
) );
}
add_filter( 'widget_text', 'do_shortcode' );
add_action( 'widgets_init', '_s_widgets_init' );
It’s a little less organized, but the important thing is that your code is outside of the curly braces and isn’t interfering with other functions.
WRONG
?> add_filter( 'widget_text', 'do_shortcode' );
Here, I placed the snippet at the end of the file, but after the ?> tag. PHP code needs to be inside PHP tags, so this would cause errors.
CORRECT
add_filter( 'widget_text', 'do_shortcode' ); ?>
Again, our snippet is placed at at the end of the file, but this time it’s before the ?> tag. This means it’s being placed inside “PHP mode”, which is what we want!
Watch out for curly quotes!
I’ve come across people who have added the correct code to their site, but it still broke. The problem was that their perfectly valid code had curly quotes in it instead of plain quotes. Here’s the difference (it’s subtle!):
- Curly Quote (double | single): “ ‘
- Plain Quote (double | single): " '
Curly quotes are not valid code characters. Sometimes if you copy code from a tutorial website, the quotes may have been accidentally converted into curly quotes inside the blog post. Always double check the code you’re pasting in before you add it to your site.
WRONG
add_filter( ‘widget_text’, ‘do_shortcode’ );
CORRECT
add_filter( 'widget_text', 'do_shortcode' );
Remind yourself what your code does
When putting something into functions.php, you should leave a note to yourself to remind you what that code was for. So if you look at it two weeks from now, you’ll still remember what it does.
You can leave notes in the form of comments. There are a few different kinds:
Single line comments
You’ll most commonly see single line comments with two slashes in front.
// Enables shortcodes in widgets. add_filter( 'widget_text', 'do_shortcode' );
Simply prefix your text with two slashes. That will turn that one line into a comment, allowing you to insert plain text. But remember, it works for one line only so this is NOT correct:
WRONG
// Enables shortcodes in widgets. This lets me add shortcodes in text widgets. add_filter( 'widget_text', 'do_shortcode' );
In that incorrect example, we tried adding more text on a second line, but we didn’t include the two slashes again. Text that isn’t inside a comment is now just being inserted in “PHP mode”, which will break our site, since it isn’t recognized as being valid PHP.
Multi line comments
If you want to create a comment that spans multiple lines, you can do it like this:
/* Comment starts here and keeps going... ...until we close it */
- Begin the comment with
/* - End the comment with
*/
Don’t forget to actually end it, otherwise the comment will keep going on and on forever and will probably break your site.
WRONG
/* Enables shortcodes in widgets. This lets me add shortcodes in text widgets. add_filter( 'widget_text', 'do_shortcode' );
This is incorrect because we’ve forgotten to end the comment!
CORRECT
/* Enables shortcodes in widgets. This lets me add shortcodes in text widgets.*/ add_filter( 'widget_text', 'do_shortcode' );
We’ve ended the comment correctly.
Always take a backup before changing your functions.php file
You don’t need to do an entire site backup—just copy or download the functions.php file, save it on your computer, then make your changes separately. That way you always have the original file to revert back to if you mess something up!
Use FTP — not Appearance > Editor!
You should also use FTP for making your site changes—don’t use the built-in editor (Appearance > Editor). It’s super easy to undo mistakes via FTP, but if you do make a mistake while editing in Appearance > Editor, you’ll get the white screen of death and then you’ll have to figure out FTP in order to fix it!
I’m more and more these days beginning to be less intimidated by the PHP codes. I often edit functions.php to fix any little quirks I run in to, and yep like you said, definitely using FTP should incase a hiccup occurs.
I wish you published this a couple of weeks ago. I messed with my PHP and killed my blog. fortunately the help-desk from my hosting company was awesome and fixed it on the same day 🙂
I wish I read this before
Thanks for this,
How do you access the PHP editing place?
I click on Dashboard, then go to appearance and then there is no ‘editing’ option?
I’m running the Adelle theme for my blog and am hosting it on WordPress.
Would really appreciate your help!
Hi Mahriya,
I’m sorry but you can’t do this on the free WordPress.com platform. Your site needs to be self-hosted.
Thanks for replying. I’ll have to consider getting my own domain, it’s been on my mind for a while…
Keep in mind that getting your own domain doesn’t mean self hosted. You have to get your own domain AND completely move off the WordPress.com platform. It’s more complicated than just buying a custom domain from WordPress.com.
Hmm, so would I still be able to use WordPress to upload content to my blog, if I were to do this, or am i missing the point?
Thanks for the advice!
You still use the WordPress software, but instead of hosting your site for free on WordPress.com (Automattic’s servers), you have to rent server space from a hosting company, install the WordPress software there, then migrate your blog over.
See this: https://www.nosegraze.com/walkthrough-moving-wordpress-com-self-hosted/
Google led me to your article, exactly what I needed, thank you!
https://docs.woocommerce.com/document/woocommerce_breadcrumb/
…shows code at the end of the article in which they initiate a second <?php section. Wondering if we should try that to get it to work since it's not working otherwise.
Thanks a lot…I tried so many time adding some hook to my function file but didn’t work.. Just notice it caused by the curly note as mention in this article..
Thanks Ashley.
Hi Ashley,
I tried to add this line of code to my functions.php file
It is supposed to invoke WordPress antispambot feature to protect email addresses from email scrapers. I added it right at the end of the file after all the other code. But it broke my site, so what did I do wrong?
There was no ?> at the end of the page, but I noted that you said this was optional so it shouldn’t have mattered.
But I am wondering if I should have just used the content without the at the end i.e. if I had just used this antispambot(‘protectmy@email.com’) would that have worked?
Thanks
This article is awesome! Just had a minor issue with php for not closing the file properly. I’m gonna save this page and come back to it as it’s so informative! Well displayed and described.
Very well done. 🙂
Thank you, thank you, thank you, thank you. I needed the code I added to my function.php so I didn’t want to remove it. I was desperate to figure out why I was getting the white screen of death. You are a LIFESAVER! It was such a simple fix!
You’re very welcome! 🙂
This is great! I added code that ended up not working…instead it added just the line of code to the top of my homepage. I had saved my original file and so just reverted my functions code back to the way it was before, but my site is still showing that line of code at the very top. Is there any way to fix this?
Thanks for this you explained something I have been struggling to get my head round for ages ! 🙂
I am having problem updating my site wordpress theme. It returns error – Update Failed: The package could not
be installed. PCLZIP_ERR_MISSING_FILE (-4): Missing archive file ‘tmp/filename.tmp’
When I turned on debuggin, each time I tried accessing the theme in wordpress I get the below warnings/errors. Can you help with interpreting and resolving these?
disabled for security reasons in /home/oha/public_html/wp-includes/functions.php on line 4782
Warning: fread() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4785
Warning: fclose() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4788
Warning: fopen() has been disabled for security reasons in /home/oha/public_html/wp-includes/functions.php on line 4782
Warning: fread() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4785
Warning: fclose() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4788
Warning: fopen() has been disabled for security reasons in /home/oha/public_html/wp-includes/functions.php on line 4782
Warning: fread() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4785
Warning: fclose() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4788
Warning: fopen() has been disabled for security reasons in /home/oha/public_html/wp-includes/functions.php on line 4782
Warning: fread() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4785
Warning: fclose() expects parameter 1 to be resource, null given in /home/oha/public_html/wp-includes/functions.php on line 4788
Warning: Cannot modify header information – headers already sent by (output started at /home/oha/public_html/wp-includes/functions.php:4782) in /home/oha/public_html/wp-includes/option.php on line 828
Warning: Cannot modify header information – headers already sent by (output started at /home/oha/public_html/wp-includes/functions.php:4782) in /home/oha/public_html/wp-includes/option.php on line 829
Thank you.
I want to show content from a specific page in sidebar and use it: $column_post = get_post(‘ID post’);
$thumbnail = wp_get_attachment_image_src(get_post_thumbnail_id($column_post->ID), ‘twentyseventeen-featured-image’);
How can I done within IT
Outside loop work, but I can not insert the contents of the page in sidebar.
php $column_post = get_post(‘149’);
echo $column_post->post_content
A very good guide that is easy to understand. I was able to edit my theme with the first try. Thanks Ashely
Ashley, just saying thanks for this. I’ve never edited the php before, and I was freaking out. But I followed all your advice and it worked out perfectly. No white screen of death.
I’m not complaining about what you know, but your instructions are just all the rest I have ever seen. The most important is always, and I mean always left out. The question is: where does a person get to the functions.php file to begin with? I just don’t understand why no one ever gives that information. Without it, people that do not know the answer has to give up or pay someone else to place the snippet in for them.
Thank you. Clear and concise!
I’ve pasted code snippets into my functions.php file so many times. I just sort of test things and figure things out that I need to figure out. But it was so nice to read your post and clear up some confusions I had on the subject of php. Really nice. I’ve always been afraid of putting it in the wrong place, and I never knew what the RIGHT place was. And the snippet I JUST added worked perfectly. Thank you.
Thank you so much Ashley. Awesome article!!!!
The curly quote vs plain quote part saved my life 🙂 I appreciate.
The entire article is super, very clear and it makes functions.php so easy to understand.
Thank you Ashley!!!!!
This article is quite impressive as you give some fine details in a clear and straightforward way. I also want to add some function in php, but as i’m a total novice and knowing the fact it can breakdown my whole site, i fear to add function in php. can you tell me please from where should I start learning it for making some basic modifications? I’m scared with this ghost PHP.
After struggling most of the day, I read this and was able to understand everything much better. Thank you. This really helped me a lot!
Nicole
Heya,
Nice article, thanks a lot.
I’m having a very strange issue with my functions.php
Everything works, but if I change something inside code that already exists (for example change 114 to 134 in a line of code), my site semi-breaks.
The mini-cart doesn’t function and shipping methods keep spinning over and over.
When I save a post in the backend, I get a white screen, but the changes are still saves (if I go back and reload the page, they’re there).
Any ideas?
after editing mine, it refused to work again, i am using sahifa theme
hello i accidentally put some code and now i cant open my wordpress what should i do?
Thank you so much for these tips!!! Just getting into wordpress. Was helping on simple things and my friend updated to latest version of wordpress and all sorts of things went wrong. Mainly his blog page won’t load any posts or properly at all. It was like it defaulted to a really old version of his page. He’s sure I did it and asking me to fix, but I’m sure it’s a coding issue which is far beyond me. I’m also pretty sure it happened from updating wordpress version. Any suggestions? TY!!!
Thanks Ashley
Now I can edit my theme without worry.
Can you suggest me another method besides FTP?
VERY NICE AND SIMPLE.
Please I need help on solving this error message “column unique values limit exceeded”. I am using Gravity Form Chain select Plugin. trying to use your explanation above.
https://docs.gravityforms.com/gform_chainedselects_column_unique_values_limit/
the above url shows how to resolve it but am new to php.
Thanks
Thank you!!!!! Very helpful.
This was SUCH a helpful tutorial! Working with my themes tech support, they told me to add some code to my functions.pho file but just said “at the bottom” and neglected to say “but before the ?>”.
So we had some issues…
But now we’re good to go! Thank you!
This is a God sent article. You probably knew that someone like me would be helpless. Now that I read your article, I will proceed no further looking for a solution but to get the Job done. Thanks very much.
Thank you very much
Very good article its work
Thanks California girl! I was wondering why I couldn’t edit it in WordPress. FTP clients should be OK. By the way, I fell in love also and wrote about it on my music blog. Check it out! http://soundsirius.blog
Thank for the great info about editing functions.php!
If I add a code snippet to the end of my functions.php file – before the closing php tag ?>, will I have to re-enter the code snippet if my theme updates with a new version of functions.php?
Would creating a child theme and placing the functions.php – which includes the original functions.php content together with my code snippet properly inserted work?
Please let me know…
Yes you will lose any modifications you make if/when your theme is updated. A child theme protects against that. Note that if you do create a child theme, you should NOT copy the parent theme’s functions.php file into the child theme’s functions.php file. That will result in the parent theme functions being loaded twice, which is a problem. Your child theme’s functions.php file should only contain your custom snippets.
Thank you so much Ashley!
Could I just copy the theme style.css file and use it as-is in the directory of my child theme? without bothering about @import – which use of is now discouraged, and other modern ways of dealing with more than 1 css theme file?