Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!


About bcworkz

My username is derived from one of my old businesses, Butler Creek Works.

I was once new to WordPress and server side scripts not too long ago, but fairly experienced in client side programming, and I pick up computer skills fairly quickly, so I probably knew more than most users at that point. I should probably learn more about formatting wiki pages though.

When searching for information in the Codex, I come on information that appears outdated, I hope to contribute to updating things like this when ever my knowledge is adequate. I also see minor errors, like spelling, or grammar, which should be corrected for the Codex to be more professional and authoritative.

One of my peeves about the Codex in it's recent state was there was little mention of Child Themes in many of the articles about customizing WordPress. When I first started my own site, I made a bunch of changes to the twentyeleven theme before I stumbled onto the Child Theme page. Realizing the superiority of this method, I had to go back and diff out and transfer all my changes to my new Child Theme, then finally restoring the original twentyeleven from backup.

9 Nov '11 - I've gone back and salted a bunch of references to Child Themes in the Codex, so hopefully no one makes my mistake again.

Since my lowly introduction, I've learned a huge amount about the inner workings of WordPress and now share my knowledge with others on the WordPress Hacks Forum. I still tweak the Codex here and there when I can, and have several ideas for articles to add to the knowledge base.

Codex Bookmarks

My browser bookmarks are cluttered enough, so I keep WP related links here that I find useful for reference.


I use this area as my personal sandbox to draft content I plan to contribute to the Codex that is a bit too involved to just edit on the fly in the Codex page's edit box.


Just trying out some of the suggestions in the Codex Style Guide.

get_the_content(); //auto <pre> shortcut by starting single code line with a space

What about multiple lines of code with space?

if ( current_user_can('edit_posts'))
    set_user_meta( 1, 'my_meta', 'example string value');

nowiki tags on links such as http://make.wordpress.org/docs/handbook/references/formatting/ prevent auto linkifying:


Live Links Example

 * [[#|My Life Stories]]
 * [[#|My Family]]
 * [[#Sandbox|Sharing]]
 * [[#Sandbox|Facts and Fiction]]

Failure of Emailed Passwords

The last 1/3 of this section is outdated and needs to be fixed. No mention of the hooks to alter the From: data exists. This is an important tool for solving this issue. It also indicates the admin email is used as default, but now it is wordpress@yourwpdomain.com. Also looks like the following section on quicktags is completely obsolete and should be deleted entirely.

E-mailed passwords are not being received - Copied to Codex

Description: When users try to register with your blog or change their passwords by entering their username and/or email, WordPress indicates that their password has been emailed to them, but it is never received.

Reason and Solutions: WordPress uses the standard PHP mail() function, which uses sendmail. No account information is needed. This is not generally a problem if you are using a hosting service, but if you are using your own box and do not have an SMTP server, the mail will never send. If you are using a *NIX box, you should have either postfix or sendmail on your machine; you will just need to set them up (search the Internet for how-to's). If you do not want to go through setting up a complete mail server on your *NIX box you may find ssmtp useful -- it provides "A secure, effective and simple way of getting mail off a system to your mail hub". On a Windows machine, try a sendmail emulator like Glob SendMail.

More help can be found on this thread of the WordPress Support Forums. For a plugin based alternative, you could try Configure SMTP: "Configure SMTP mailing in WordPress, including support for sending e-mail via SSL/TLS (such as GMail)."

Windows Host Server Specific: With the Configure SMTP plugin you can work around the issue of e-mails not being received. Alternately, check your "Relay" settings on the SMTP Virtual Server. Grant access to . Then in your php.ini file, set the SMTP setting to the same IP address. Also set smtp_port to 25.

Ensure Proper Return Address is Used: By default, the WordPress mailer fills in the From: field with wordpress@yourdomain.com and the From: name as WordPress.

This is fine if this is a valid e-mail address. For example, if your real e-mail is wordpress@yourdomain.com, your host should pass the email on for delivery. It will probably send your mail as long as yourdomain.com is setup to send and receive mail, even if wordpress is not a valid mail box. But if you set you real email as the From: address and it's something like wpgod@gmail.com, the mail may not send because gmail.com is not a domain handled by the mail server.

When using the plugin Configure SMTP the same applies, and there is an option to hard code the From: address. You can also use 'wp_mail_*' filters to change the From: address and name used. It's strongly suggested you do this because people involved with several blogs may get email from all of those blogs, and each of them likely is From: WordPress. Make your blog stand out as different!

function cdx_from_email() {
	return "wpgod@yourdomain.com";
add_filter( 'wp_mail_from', 'cdx_from_email' );
function cdx_from_name() {
	return "WPGod";
add_filter( 'wp_mail_from_name', 'cdx_from_name' );

Use the above code by adding it to your theme or child theme functions.php file.

Treated as Spam: Your email message may have been routed to a spam folder or even worse, simply discarded as malicious. There are a couple measures you can use to convince recipient's mail servers that your message is legitimate and should be delivered as addressed.

SPF: (Sender Policy Framework) This is the most common anti-spam measure used. If you are on a hosted system, there is a good chance your host has set this up for the mail server you are using. Have Wordpress email you and check the message headers for evidence that the message passed the SPF check. You can get a message sent by following the Forgot Password link on the login page. To keep your old password, do not follow the link in the message. If your system email failed the SPF check, you can set up the credentials if you have access to your DNS records and your mail server's domain belongs to you. Check the return path of the email your system sent. If the mail server listed there has your domain name, you can set up SPF credentials. There are several how-tos on the Internet.

DKIM: (Domain Key Identified Mail) This system is also used. You can use both SPF and DKIM in the same message. Again, just as with SPF, you can check if your receiving mailserver verified your host's domain key by examining the mail header. There is a fair chance no signature key was provided, indicating your host chose to not use this protocol. Also as with SPF, if you can edit your DNS records and the mail server belongs to your domain, you can set up DKIM credentials yourself. Some how-tos exist if you search the Internet.

To get WordPress to send the proper DKIM keys, hook the 'phpmailer_init' action. You are passed the $phpmailer object. Set the necessary properties and return the object. See the class source code for more information. It's on wp-includes/class-phpmailer.php .

Local Development Environment

There are a few articles on the 'net on setting this up, but there's no obvious mention in the Codex about how important this is. We need an overview of the steps with links to the various articles. May need to tie up some loose ends, like accessing the local development server over a LAN, since will not work. It's not even clear where to put references to this new page so that it is seen, but not starting to look a bit like link spam, as there's no obvious entry point for new developers.

Local Development Environment - DRAFT

Coming Soon

Verifying Trackbacks and Pingbacks

The 'backs sections are vague on how to actually make trackbacks work and the fact that pingbacks are completely automatic.

This Codex sub-section should perhaps be retitled 'Using Pingbacks and Trackbacks'?

Verifying the 'backs - Copied to Codex

To enable trackbacks and pingbacks, in the Disscussion Settings of your Administration Panels, select these items under 'Default article settings':

Attempt to notify any blogs linked to from the article.

Allow link notifications from other blogs (pingbacks and trackbacks.)

Selecting one option and not the other would not be very neighborly ;)

Once enabled, trackbacks and pingbacks from other sites will appear in your Administration Panels just like other comments, but on your post pages, they will appear according to your theme's design.

Once enabled, pingbacks are sent automatically when you publish your post, you don't have to do anything. To send trackbacks, you will need to find the trackback URL somewhere on the post page you are linking to. If you can't find one, try to determine if the site supports pingbacks. If it does, you should not send trackbacks as well. Copy/paste the trackback URL into the Send Trackbacks field on your Add New Post screen. If you don't see this field, go to the screen options and select the Send Trackbacks option. Note that selecting this does not send trackbacks, it only displays the field called Send Trackbacks. When you publish your post, trackbacks will be sent to the URLs you pasted into the field. This field will also show the status of trackbacks and pingbacks on your Edit Post screen.

If there is someone that wants to send a trackback to your WordPress blog because their blogging software does not support pingbacks, your trackback URL they should insert into their post edit panel is your blog post's permalink with "trackback/" appended to the end. If their software supports pingbacks, they do not need to do anything, the process is automatic.

Error Display and Logging

Things are rather vague on Configure Error Logging in Editing wp-config.php on how the PHP directives and WordPress error constants do or do not interact. There's also a security issue with the debug.log located in a publicly accessible directory.

Configure Error Logging - Copied to Codex

Retitle sub section as above. Under current Configure Error Log at top add:

Configuring error logging can be a bit tricky. First of all, default PHP error log and display settings are set in the php.ini file, which you may or may not have access to. If you do, they should be set to the desired settings for live PHP pages served to the public. It's strongly recommended that no error messages are displayed to the public and instead routed to an error log. Further more, error logs should not be located in the publicly accessible portion of your server. Sample recommended php.ini error settings:

error_reporting = 4339
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /home/example.com/logs/php_error.log
log_errors_max_len = 1024
ignore_repeated_errors = On
ignore_repeated_source = Off
html_errors = Off

About Error Reporting 4339

This is a custom value that only logs issues that affect the functioning of your site, and ignores things like notices that may not even be errors. See Error Constants for the meaning of each binary position for 1000011110011, which is the binary number equal to 4339. The far left 1 means report any E_RECOVERABLE_ERROR. The next 0 means do not report E_STRICT, (which is thrown when sloppy but functional coding is used) and so on. Feel free to determine your own custom error reporting number to use in place of 4339.

Obviously, you will want different settings for your development environment. If your staging copy is on the same server, or you don't have access to php.ini, you will need to override the default settings at run time. It's a matter of personal preference whether you prefer errors to go to a log file, or you prefer to be notified immediately of any error, or perhaps both. Here's an example that reports all errors immediately that you could insert into your wp-config.php file:

@ini_set('error_reporting', E_ALL );
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', false);
define('WP_DEBUG_DISPLAY', true);

the start of current entry

Because wp-config.php is loaded for every page... blah blah

... and at end add:

Confusing the issue is that WordPress has 3 constants that look like they could do the same thing. First off, remember that if WP_DEBUG is false, it and the other two WordPress DEBUG constants do not do anything. The PHP directives, whatever they are, will prevail. Second, even if WP_DEBUG is true, the other constants only do something if they too are set to true. If they are set to false, the PHP directives remain unchanged. For example, if your php.ini file has the directive display_errors = On, but you have the statement define('WP_DEBUG_DISPLAY', false); in your wp-config.php file, errors will still be displayed on screen even though you tried to prevent it by setting WP_DEBUG_DISPLAY to false because that is the php configured behavior. This is why it's very important to set the PHP directives to what you need in case any of the related WP constants are set to false. To be safe, explicitly set/define both types. More detailed descriptions of the WP constants is available at Debugging in WordPress.

For your public, production WordPress installation, you might consider placing the following in your wp-config.php file, even though it may be partly redundant:

@ini_set('error_reporting', 4339 ); //only log errors you will want to know about
define('WP_DEBUG', false);
define('WP_DEBUG_LOG', false);
define('WP_DEBUG_DISPLAY', false);

The default debug log file is /wp-content/debug.log. Placing error logs in publicly accessible locations is a security risk. Ideally, your log files should be placed above you site's public root directory. If you can't do this, at the very least, set the log file permissions to 600 and add this entry to the .htaccess file in the root directory of your WP installation:

<Files debug.log>
   Order allow,deny
   Deny from all

This prevents anyone from accessing the file via HTTP. You can always view the log file by retrieving it from your server via FTP.

Overriding Continue reading-> for Excerpts

The whole customizing read more section is largely oriented to someone creating their own template. It's less useful to child theme users as the suggested changes to the parent theme would need to be reapplied any time the theme is updated. A different strategy is needed for child theme users, particularly if the parent is twentyeleven. It will require a hook for both the_content and the _excerpt to address all possible combinations of user input and theme post styles. This page needs significant reorganization, or perhaps instead, a separate page oriented to child theme users.

Will add sub section to this subsection of Customizing the Read More page. When using child theme of twentyeleven template, can't set the more link with excerpts with just the shown code. Need to remove the parent theme's filters trying to customize the same thing. But we can't remove the filters directly because the parent's function.php has not been loaded yet. Need to hook the action 'after_setup_theme' and remove filters at that time.

Overriding Continue Reading-> - Copy Moved

Copy moved to relevant Codex section

What does WordPress do to validate e-mail addresses provided by comment authors?

I looked through the code WordPress uses to validate e-mail addresses and saw that all it does is check that it's properly formed and uses only permitted characters. A way to do a more stringent behind the scenes e-mail validation would be a useful function, but I couldn't find anything in the Codex. After doing some research, I wrote some code to check for the existence of a mail exchanger within the address' domain. This question could go on the FAQ Working with Wordpress page, under spam and comments. But then it's not so much about spam as verifying email addresses. It also goes beyond just a quick mod, it's sort of basic plugin material. I am now thinking I should host this myself and just provide a link on the Combating Comment Spam under the External Resources. Need to find some email address related content for another possible link location.

I also have a sizeable list of disposable email domains and a basic binary search function to quickly find any matches that may be useful. Another possible anti-spam measure is disallowing an excessive number of dots in the mailbox name. Also disallowing extremely short or long names.

E-Mail Validation DRAFT

WordPress checks to see that the address provided is a properly formed address. WordPress does nothing to determine if the address would actually work. There are other measures administrators can do to verify if an e-mail address actually works.

Most people have experienced the challenge and reply e-mail exchange where the commenter is sent a message within which is a link they must follow to validate that their e-mail address actually works. There are a few Plugins that provide this sort of validation. While this method provides accurate validation, it takes away the immediacy of posting a timely comment, and can further frustrate users if there are delays in message transmission.

A behind the scenes method that requires no action by the commenter has a few benefits. One way to get an indication of the validity of an e-mail address is to use the PHP function checkdnsrr() to check if a domain record exists showing a mail exchanger on that domain. This method is less than 100% reliable, as it does nothing to verify if there is a valid mailbox within that domain.

Extending the WordPress e-mail check function to include this verification is fairly simple. You could create a very basic Plugin and insert the following code:

// extend e-mail check to include checking DNS for a valid domain with mail exchanger
// returns false if check fails
function check_email_domain($valid, $email, $type) {
	if ( !$type && $valid ) {
		// address has passed all other checks, let's do ours
		list($userName, $mailDomain) = explode("@", $email);	//extract domain
		if (checkdnsrr($mailDomain, "MX")) {
			// this is a valid email domain, return the e-mail address
			$pass = $email;
		} else {
			// this email domain doesn't exist, return false
			$pass = false;
	//  else $type has value or $valid is false, address has failed a previous test,
	//  just pass it on
	} else {
		$pass = $valid;
	return $pass;
add_filter('is_email', 'check_email_domain', 10, 3);

Creating plugins can be very easy, the above code actually has most of the work done for you.

A more thorough behind the scenes method is to query a domain's SMTP server to verify if the username is associated with a valid mailbox. Even this is not 100% accurate, as some domains will return a valid mailbox answer to any query whether the mailbox really exists or not. Furthermore, if you run this sort of query often enough, it will get your domain blacklisted for 'namespace mining behavior.' Another way !@#* spammers have ruined things for all of us!

How do I prevent comment flooding?

I drafted a major update to the following very outdated section from FAQ Working with WordPress. I spent a fair bit of time trying to get the code provided in the old version to work before I realized there was no need to do anything at all. This was my working copy to be sure all the formatting and links worked. I suppose I could delete it now that I've updated the actual page.

Comment Flooding - Copy Moved

Moved to relevant Codex page.

FAQ Caution Box

Warning Box for FAQs that direct users to alter core files. I didn't know where to find a text box example, so used a table cell, which does not work too well because there is no padding. There's probably a way to fix that, but I'm too tired to figure it out.

Well, DUH! I didn't know we can use inline CSS here! I know how to do that!

Caution Box - Old version

Superceded by CSS version

Caution Box with Inline CSS - Moved

Moved to relevant Codex pages