How to Edit Your Theme’s Functions.php File Without Killing Your Site

  • 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!

Photo of Ashley
I'm a 26 year old California girl living in England (I fell in love with a Brit!). I like to inject a little #girlpower into the WordPress development community by teaching women how to be coding badasses. more »

Don't miss my next post!

Sign up to get my blog posts sent directly to your inbox (plus exclusive store discounts!).

You might like these

Leave a Reply

(Enter your URL then click here to include a link to one of your blog posts.)

36 comments

  1. 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!

    1. Hi Mahriya,

      I’m sorry but you can’t do this on the free WordPress.com platform. Your site needs to be self-hosted.

        1. 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.

          1. 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!

  2. 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.

  3. 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

  4. 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.

  5. 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!

  6. 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?

  7. 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.

  8. 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

  9. 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.

  10. 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.

  11. 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.

    1. 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!!!!!

  12. 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.

  13. 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

  14. 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?

  15. 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!!!

Recent Posts

    Random Posts