Basic PHP Syntax for custom_functions.php

The custom_functions.php file is used less often for customization in Thesis than the custom.css file, but it is viewed with fear all out of proportion to how much it is employed. That’s because PHP errors in the custom_functions.php file can stop your site cold with a cryptic error message, whereas an error in custom.css will just make the selector do nothing.

The parts of the PHP language used by Thesis is limited, so there’s not so much to learn as with the CSS in the custom.css file. And the requirements and syntax used by PHP are simpler than CSS, but they are very, very strict and unforgiving. In a large portion of cases, a PHP error is caused by a simple syntax mistake rather than genuinely bad code.

This guide shows you the basics of PHP syntax as it applies to Thesis and the custom_functions.php file, and points out the most common mistakes people make. It is intended to help you prevent mistakes as well as to help you track down and correct PHP syntax errors that can cause your site to come to a screeching halt. It is not intended to be a complete tutorial, which would take many pages. A good online PHP tutorial is available on the w3schools.com site. The tutorial is useful not only for learning what you need to know about PHP, but as a reference as well.

The basic PHP scripting block

A block of PHP code can be written in as short a unit as a part of one line, or it can be many lines long. Whatever its size, it always requires a “<?php” to open PHP and make it active and “?>” to close it. Here are examples of PHP code blocks:

<?php SOME PHP CODE HERE ?>

<?php
	SOME PHP CODE HERE
	SOME MORE PHP CODE HERE
?>

You will sometimes see PHP code with a “<?” at the beginning of the code block instead of “<?php”. This is called shorthand, and is not available on all servers. For maximum compatibility, you should use the standard form “<?php” rather than the shorthand.

PHP functions and PHP statements in custom_functions.php require PHP to be open to work

Since Thesis makes limited use of the PHP language, almost all of the customizations you will ever do in custom_functions.php will involve PHP functions or PHP statements. These both require that PHP be open and active for them to work. You do this by making sure that the function or statement is preceded by a “<?php” in the code above it. Note that the custom_functions.php file actually begins with a “<?php”.

One of the most common errors in custom_functions.php is for PHP not to be active when required. But don’t riddle your code with “<?php” everywhere — that will produce errors, too. All it takes is one “<?php” to make PHP active. A good practice is to exit every function with PHP open.

If you have an error, the first thing to look for is that there is a “<?php” activating PHP somewhere above the new PHP code you have written.

A typical Thesis PHP statement

Probably the most common PHP statements in custom_functions.php are detaching or attaching a function to a Thesis hook. The following example has statements that move the Thesis navigation menu from above the header to below it.

The statements in the example have two important PHP syntax characteristics. Each PHP statement ends with a semicolon (;). This tells PHP to process that line. If you leave the semicolon out, either you will get an error message or nothing will happen. Note also that PHP typically uses single quotation marks (‘), unlike HTML which uses double quotation marks (“). Mixed up or unbalanced single and double quotation marks are frequent causes of custom_functions.php errors.

Remember that PHP statements require a “<?php” in the code above it to work and not cause errors:

<?php
remove_action('thesis_hook_before_header', 'thesis_nav_menu');
add_action('thesis_hook_after_header', 'thesis_nav_menu');

The basic PHP function

You sometimes will be cutting-and-pasting functions or building your own functions in custom_functions.php. Functions all have the same basic format and syntax. Remember that they require a “<?php” in the code above it to be recognized by PHP and not cause an error message.

Functions are actually quite simple. They begin with the word “function,” which is followed by the function name, then an opening and closing parenthesis “()” and finally an opening curly bracket “{“. After its contents, the function is then closed by a closing curly bracket “}”. For example:

<?php
function FUNCTION-NAME() {
	CONTENTS OF FUNCTION
}

A common error is to forget to close the function with a closing curly bracket “}”. It may not even cause an error message, but the function definitely will not work.

PHP comments in custom_functions.php

It is good coding practice to label the parts of your code with comments. Besides helping you remember what a block of code does after time has passed, it helps others read your code more easily. Comment marks are also useful to temporarily disable a block of code.

There are two ways to put comments into PHP: one method for single lines, and another for multiple lines. Single-line comments are preceded by two right slashes “//”. Multiple-line comments are preceded by “/*” and ended with “*/”. Either of these kinds of comments can be used for single lines and may be placed at the end of a line of code.

I always use the multiple-line comment style for everything for the simple reason that it’s also the commenting syntax required for the CSS in the custom.css file: One less thing to remember, one fewer source of errors!

Following is an illustration of both styles of comments, along with a block of PHP code that has been commented out by enclosing it within a “/*” and a “*/”:

// This is a single line comment

/* This is a multiple line comment
continued onto a second line. */

/* The multiple line comment syntax can be used for everything. */

/* A block of code commented out */
/*function bad_code() {
	ERROR-PRODUCING CODE
}*/

I hope this short guide will help you format your PHP well, and track down errors when your custom_functions.php file gives you trouble. Remember that your comments are always welcome, and that you can email me directly by clicking on the “Contact” button at the top of the page.

©2009 Michael L Nichols. All rights reserved.

Related Articles

• New Articles for Newbies: Basic Syntax for custom.css and custom_functions.php! (6)
• Tutorial: Customizing Just Your Front Page, Pages or Posts Using Conditional Tags (1)
• Important New Article! Tutorial: Customizing Just Your Front Page, Pages or Posts Using Conditional Tags (2)
• Basic CSS Syntax for custom.css (3)
• Toolbox Essentials – Tutorial: Browser Detection to Execute IE Hacks (1)

Tagged as: custom_functions.php, Customization, PHP, Syntax