wp_localize_script Explanation

A long time ago a WordPress programmer wanted to use a PHP value in their JavaScript.

No problem they said, I’ll add this in my PHP theme code.

Using a PHP Value in JavaScript – version 1

<?php
    $my_php_value = 'Hello World';
    echo '<script>';
        echo 'alert( "' . $myPHPValue . '" );';
    echo '</script>';
?>

This results in the following being part of the markup on the webpage.

<script>alert( "Hello World" );</script>

That’s great they said but I want don’t want to put my JavaScript on the page, I want it in a separate file.

No problem they said, I’ll put the PHP value into a JavaScript variable.

Using a PHP Value in JavaScript – version 2

<?php
    $my_php_value = 'Hello World';
    echo '<script>';
        echo 'var phpValueToDisplay = "' . $myPHPValue . '";';
    echo '</script>';
?>

This results in the following being part of the markup on the webpage.

<script>var phpValueToDisplay = "Hello World";</script>

And in their display-php-value.js file they add code to use this variable.

alert( phpValueToDisplay );

Using a PHP Value in JavaScript – version 3 (wp_localize_script)

Hey, we’ve been doing this trick a lot where use a PHP value in JavaScript, we should write a function to make this easier. One of the things this is good for is handling translations (a.k.a. localization), let’s make that part of the name. Unfortunately this name has led to some confusion, perhaps make_php_value_available_in_javascript() would have been a better function name 😀.

<?php
$my_php_value = 'Hello Everybody';

wp_localize_script(
        // The "handle" of the JS file we enqueue.
        'fe-display-php-value',

        // A name we makeup to avoid our PHP values colliding with others.
        'feWPLocalizeScriptDemo', 

         // A key/value array of values to pass from PHP to JavaScript.
         array( 'phpValueToDisplay' => $my_php_value )
    );
?>

The code above results in something like the following

<script type='text/javascript'>
var feWPLocalizeScriptDemo = {"phpValueToDisplay":"Hello Everybody"};
</script>

Now in our display-php-value.js we can display the PHP value with something like

alert( feWPLocalizeScriptDemo.phpValueToDisplay );

Why Use wp_localize_script()

At this point you may be saying, I’m going to use version 1 or version 2 because it is easier and clearer to me. I know that feeling and have written code like that in the past. Over time I’ve seen the benefits of wp_localize_script(), specifically:

Escaping

In our custom code versions 1 and 2, we don’t include any escaping, which can cause problems. Imagine $myPHPValue is a string that includes the " character (this will mess up the quotes around our JavaScript value. While we can add escaping functions ourselves in our custom code, we don’t have to with wp_localize_script() because escaping is built-in.

Only when needed

In our custom code, the JavaScript with our values will be included on every page. When using wp_localize_script(), the first parameter is the “handle” of the JavaScript file. Our JavaScript where the values are assigned only appears on a page when this JavaScript file is loaded.

Handling Multiple Values

The key/value array of values to pass from PHP to JavaScript that is the third parameter of wp_localize_script() can handle lots of values easily. When doing our custom code, multiple values isn’t as tidy. (Right now, you may only be passing one value but if you need multiple values in the future, future you will thank you for using wp_localize_script())

Clarity

When future developers look at this code (including when future me looks at this code), using the standard technique of wp_localize_script() helps make clear what is going on, rather than analyzing our custom code.

Future friendly

I would be surprised if web browsers changed in such a way that the underlying mechanism of wp_localize_script() needed to change, but if this did occur I anticipate WordPress would address this in a backwards compatible way.

Demo Plugin

I’ve created a minimal wp_localize_script() plugin, which is available on GitHub.

Official Documentation

WordPress Codex wp_localize_script()

Photo Credit

tableatny on flickr

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.