Building Web Apps with WordPress (2014)

Chapter 2. WordPress Basics

WordPress was first developed in 2003 and was created primarily as blogging software. By the release of version 3.5, the image of Wordpress had changed from blogging software to a versatile CMS (content management system) and the word “blog” was actually removed from the description of the software and in most places in the source code. Today, it has evolved to become the largest platform on the web and is used on about 20% of all the websites on the Internet.

There are a couple of reasons WordPress has gained so much popularity over the years. The first is that WordPress is open source software and has an entire community of people who are invested in improving it and continually contributing new code to extend its functionality. WordPress users, developers, and designers are always thinking of new creative ways to use WordPress and creating plugins for these new features, which are then made available to the community.

Another reason WordPress has been so successful is the fact that it is an extremely flexible CMS and can be used to power all different types of websites. Developers are constantly exploring innovative new ways to use the software, including using it to build web applications, which is the focus of this book.

NOTE

We are going to assume that you already know how to use WordPress, and have already installed the latest version somewhere. If this is your first time using WordPress, you should check out the book WordPress for Dummies. Not saying you’re a dummy or anything, but everyone has to start somewhere.

WordPress Directory Structure

Let’s take a quick top-level look at the folders and files that are included within a typical WordPress install.

Root Directory

In the root directory, there are a few core WordPress files. Unless you are digging around in the core WordPress code looking for hooks to use or certain functionality, the only file you may need to ever alter is wp-config.php. You should never, ever, ever, ever^[5^] alter any other core WordPress files. Hacking core is a bad idea because you won’t be able to upgrade WordPress when a new version becomes available without overriding your changes. The only directory you should need to interact with is wp-content because it contains your plugins, themes, and uploaded files.

Any time you find yourself wanting to hack a core WordPress file, think again. There is probably a hook you could use to accomplish the same goal. If there isn’t a hook available to do what you need, add one and try to get it added to core. The core WordPress developers are very responsive about adding in new hooks and filters.

/wp-admin

This directory contains core directories and files for managing the WordPress admin interface. Another key file in this directory is admin-ajax.php, which all AJAX requests should be run through. AJAX is covered in Chapter 9.

/wp-includes

This directory contains core directories and files for various WordPress functionality.

/wp-content

This directory contains subdirectories for the plugins and themes you have installed on your site and any media files you upload to your site. If you create a plugin that needs to store dynamic files of its own, it is a best practice to place them somewhere in the wp-content folder so they are included in a content backup.

The following directories are subdirectories of the wp-content directory.

/wp-content/plugins

Any WordPress plugin you install on your WordPress site will be located in this directory. By default, WordPress comes with the Hello Dolly and Akismet plugins.

/wp-content/themes

Any WordPress themes you install on your WordPress site will be located in this directory. By default, WordPress comes with the Twenty Eleven, Twenty Twelve, Twenty Thirteen, and Twenty Fourteen themes.

/wp-content/uploads

Once you start uploading any photos or files to your media library, you will start seeing this directory being populated with those uploaded files. All uploaded media is stored in the uploads directory.

/wp-content/mu-plugins

In WordPress, you can force the use of any plugin by creating a mu-plugins directory inside of the wp-content directory. This directory does not exist unless you create it. The “mu” stands for “must use,” and any plugin you put in the mu-plugins folder will automatically run without needing to be manually activated on the admin plugins page. In fact, you won’t even see any must use plugins listed there.

Must use plugins are especially useful on multisite installs of WordPress so you can use plugins that your individual network site admins won’t be able to deactivate.

WordPress Database Structure

WordPress runs on top of a MySQL database and creates its own tables to store data and content. Below is the database schema created by a default install of WordPress. We have also included some basic information on built-in WordPress functions for interacting with these tables. If you can grasp the database (DB) schema and get comfortable with the list functions in this chapter, you can push and pull any data into and out of WordPress.

NOTE

The following table names use the default prefix of wp_. This prefix can be changed during the WordPress installation, and so the exact table names of your WordPress install may vary.

wp_options

The wp_options table stores any sitewide data for you. This table stores the name, description, and admin email that you entered when running a typical install. This table will also come prepopulated with a few records that store the various default settings within WordPress. Table 2-1shows the database structure for the wp_options table.

Table 2-1. DB schema for wp_options table

Functions Found in /wp-includes/option.php

The following functions can all be found in /wp-includes/option.php:

add_option( $option, $value = ', $deprecated = ', $autoload = yes )

First checks if an option_name exists before inserting a new row:

§ $option—A required string of the option_name you would like to add.

§ $value—An optional mixed variable of the option_value you would like to add. If the variable passed is an array or object, the value will be serialized before storing in the database.

§ $deprecated—This parameter was deprecated in version 2.3 and is not used anymore.^[6^]

§ $autoload—An optional Boolean used to distinguish whether to load the option into cache when WordPress starts up. Set to yes or no. The default value is no. This can save you a DB query if you are sure you are going to need this option on every page load.

update_option( $option, $newvalue )

Updates an existing option but will also add it if it doesn’t already exist:

§ $option—A required string of the option_name you would like to update/add.

§ $newvalue—An optional mixed variable of the option_value you would like to update/add.

get_option( $option, $default = false )

Retrieves the option_value for a provided option_name:

§ $option—A required string of the option_name you would like to get.

§ $default—An optional mixed variable you would like to return if the option_name you provided doesn’t exist in the table. By default, this parameter is false.

delete_option( $option )

Deletes an existing option from the database permanently:

§ $option—A required string of the option_name you would like to delete.

NOTE

Most of the code examples in this book are not fully functional code. They are basic theoretical examples of how to use the functions we are talking about. You can follow along with most of the code examples if you like in a custom plugin or your theme’s functions.php file.

Example 2-1 demonstrates some of the basic functions for interacting with the wp_options table.

Example 2-1. Adding, updating, getting, and deleting records in the wp_options table

<?php

// add option

$twitters = array( '@bwawwp', '@bmess', '@jason_coleman' );

add_option( 'bwawwp_twitter_accounts', $twitters );

// get option

$bwawwp_twitter_accounts = get_option( 'bwawwp_twitter_accounts' );

echo '<pre>';

print_r( $bwawwp_twitter_accounts );

echo '</pre>';

// update option

$twitters = array_merge(

$twitters,

array(

'@webdevstudios',

'@strangerstudios'

)

);

update_option( 'bwawwp_twitter_accounts', $twitters );

// get option

$bwawwp_twitter_accounts = get_option( 'bwawwp_twitter_accounts' );

echo '<pre>';

print_r( $bwawwp_twitter_accounts );

echo '</pre>';

// delete option

delete_option( 'bwawwp_twitter_accounts' );

/*

The output from the above example should look something like this:

Array

(

[0] => @bwawwp

[1] => @bmess

[2] => @jason_coleman

)

Array

(

[0] => @bwawwp

[1] => @bmess

[2] => @jason_coleman

[3] => @webdevstudios

[4] => @strangerstudios

)

*/

?>

wp_users

When you log in to WordPress with your username and password, you are referencing data stored in this table. All users and their default data are stored in the wp_users table. Table 2-2 shows the database structure for the wp_users table.

Table 2-2. DB schema for wp_users table

Functions Found in /wp-includes/…

The following functions are found in /wp-includes/pluggable.php and /wp-includes/user.php:

wp_insert_user( $userdata )

Inserts a new user into the database. This function can also be used to update a user if the user ID is passed in with the $user_data. $userdata is a required array of field names and values. The accepted fields are:

§ ID—An integer that will be used for updating an existing user.

§ user_pass—A string that contains the plain-text password for the user.

§ user_login—A string that contains the user’s username for logging in.

§ user_nicename—A string that contains a URL-friendly name for the user. The default is the user’s username.

§ user_url—A string containing the URL for the user’s website.

§ user_email—A string containing the user’s email address.

§ display_name—A string that will be shown on the site. Defaults to the user’s username. It is likely that you will want to change this, for appearance.

§ nickname—The user’s nickname. Defaults to the user’s username.

§ first_name—The user’s first name.

§ last_name—The user’s last name.

§ description—A string containing content about the user.

§ rich_editing—A string for whether to enable the rich editor. False if not empty.

§ user_registered—The date the user registered. Format is Y-m-d H:i:s.

§ role—A string used to set the user’s role.

§ jabber—User’s Jabber account.

§ aim—User’s AOL IM account.

§ yim—User’s Yahoo IM account.

wp_create_user( $username, $password, $email )

This function utilizes the prior function wp_insert_user() and makes it easier to add a new user based on the required columns:

§ $username—A required string of the username/login of a new user.

§ $password—A required string of the password of a new user.

§ $email—A required string of the email address of a new user.

wp_update_user( $userdata )

This function can be used to update any of the fields in the wp_users and wp_usermeta (covered next) tables tied to a specific user. Note that if a user’s password is updated, all of his cookies will the cleared, logging him out of WordPress:

§ $userdata—A required array of field names and values. The ID and at least one other field is required. These fields are the same ones accepted in the wp_insert_post() function.

get_user_by( $field, $value )

This function returns the WP_User object on success and false if it fails. The WordPress User class is found in /wp-includes/capabilities.php and basically queries the wp_user table like so:

SELECT * FROM wp_users WHERE $field = $value;

The WP_User class also caches the results so it is not querying the database every time it is used. The class also figures out the roles and capabilities of a specific user, which we will go over in more detail in Chapter 6:

§ $field—A required string of the field you would like to query the user data by. This string can only be id, slug, email, or login.

§ $value—A required integer or string of the value for a given id, slug, email or login.

get_userdata( $userid )

This function actually utilizes the previous function get_user_by() and returns the same WP_User object:

§ $userid—A required integer of the user ID of the user you would like to get data for.

wp_delete_user( $id, $reassign = novalue )

You guessed it: this function deletes a user and can also reassign any of their posts or links to another user:

§ $id—A required integer of the ID of the user you would like to delete.

§ $reassign—An optional integer of the ID you would like to reassign any post or links from the deleted user to. Example 2-2 demonstrates some of the basic functions for interacting with the wp_users table.

Example 2-2. Working with the wp_users table

<?php

// insert user

$userdata = array(

'user_login' => 'brian',

'user_pass' => 'KO03gT7@n*',

'user_nicename' => 'Brian',

'user_url' => 'http://webdevstudios.com/',

'user_email' => 'brian@schoolpress.me',

'display_name' => 'Brian',

'nickname' => 'Brian',

'first_name' => 'Brian',

'last_name' => 'Messenlehner',

'description' => 'This is a SchoolPress Administrator account.',

'role' => 'administrator'

);

wp_insert_user( $userdata );

// create users

wp_create_user( 'jason', 'YR529G%*v@', 'jason@schoolpress.me' );

// get user by login

$user = get_user_by( 'login', 'brian' );

echo 'email: ' . $user->user_email . ' / ID: ' . $user->ID . '<br>';

echo 'Hi: ' . $user->first_name . ' ' . $user->last_name . '<br>';

// get user by email

$user = get_user_by( 'email', 'jason@schoolpress.me' );

echo 'username: ' . $user->user_login . ' / ID: ' . $user->ID . '<br>';

// update user - add first and last name to brian and change role to admin

$userdata = array(

'ID' => $user->ID,

'first_name' => 'Jason',

'last_name' => 'Coleman',

'user_url' => 'http://strangerstudios.com/',

'role' => 'administrator'

);

wp_update_user( $userdata );

// get userdata for brian

$user = get_userdata( $user->ID );

echo 'Hi: ' . $user->first_name . ' ' . $user->last_name . '<br>';

// delete user - delete the original admin and set their posts to our new admin

// wp_delete_user( 1, $user->ID );

/*

The output from the above example should look something like this:

email: brian@schoolpress.me / ID: 2

Hi: Brian Messenlehner

username: jason / ID: 3

Hi: Jason Coleman

*/

?>

wp_usermeta

Sometimes you may want to store additional data along with a user. WordPress provides an easy way to do this without having to add additional columns to the users table. You can store as much user metadata as you need to in the wp_usermeta table. Each record is associated to a user ID in the wp_user table by the user_id field. Table 2-3 shows the database structure for the wp_usermeta table.

Table 2-3. DB schema for wp_usermeta table

get_user_meta( $user_id, $key = '', $single = false )

Gets a user’s meta value for a specified key:

§ $user_id—A required integer of a user ID.

§ $key—An optional string of the meta key of the value you would like to return. If blank then all metadata for the given user will be returned.

§ $single—A Boolean of whether to return a single value or not. The default is false and the value will be returned as an array.

There can be more than one meta key for the same user ID with different values. If you set $single to true, you will get the first key’s value; if you set it to false, you will get an array of the values of each record with the same key.

update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' )

This function will update user metadata but will also insert metadata if the passed-in key doesn’t already exist:

§ $user_id—A required integer of a user ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to store. If this meta key already exists, it will update the current row’s meta value, if not it will insert a new row.

§ $meta_value—A required mixed value of an integer, string, array, or object. Arrays and objects will automatically be serialized.

§ $prev_value—An optional mixed value of the current metadata value. If a match is found, it will replace the previous/current value with the new value you specified. If left blank, the new meta value will replace the first instance of the matching key. If you have five rows of metadata with the same key and you don’t specify which row to update with this value, it will update the first row and remove the other four.

NOTE

This function relies on the update_metadata() function located in /wp-includes/meta.php. Check it out!

add_user_meta($user_id, $meta_key, $meta_value, $unique = false)

Yup, this function will insert brand-new user meta into the wp_usermeta table. We don’t use this function often anymore because we can just use update_user_meta() to insert new rows as well as update them. If you want to ensure that a given meta key is only ever used once per user, you should use this function and set the $unique parameter to true:

§ $user_id—A required integer of a user ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to store.

§ $meta_value—A required mixed value of an integer, string, array, or object.

§ $unique—An optional Boolean, which when set to true will make sure the meta key can only ever be added once for a given ID.

delete_user_meta($user_id, $meta_key, $meta_value = '')

Deletes user metadata for a provided user ID and matching key. You can also specify a matching meta value if you only want to delete that value and not other metadata rows with the same meta key:

§ $user_id—A required integer of a user ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to delete.

§ $meta_value—An optional mixed value of the meta value. If you have more than one record with the same meta key, you can specify which one to delete by matching the meta value. It defaults to nothing, which will delete all meta rows with a matching user_id and meta_key.

Example 2-3 demonstrates some of the basic functions for interacting with the wp_username table.

Example 2-3. Working with the wp_username table

<?php

// get brian's id

$brian_id = get_user_by( 'login', 'brian' )->ID;

// add user meta - unique is set to true. no polygamy! only

one wife at a time.

add_user_meta( $brian_id, 'bwawwp_wife', 'Robin Jade Morales Messenlehner', true);

// get user meta - returning a single value

$brians_wife = get_user_meta( $brian_id, 'bwawwp_wife', true);

echo "Brian's wife: " . $brians_wife . "<br>";

// add user meta - no 3rd parameter/unique. can have as many kids

as wife will let me.

add_user_meta( $brian_id, 'bwawwp_kid', 'Dalya' );

add_user_meta( $brian_id, 'bwawwp_kid', 'Brian' );

add_user_meta( $brian_id, 'bwawwp_kid', 'Nina' );

// update user meta - this will update brian to brian jr.

update_user_meta( $brian_id, 'bwawwp_kid', 'Brian Jr', 'Brian' );

// get user meta - returning an array

$brians_kids = get_user_meta( $brian_id, 'bwawwp_kid' );

echo "Brian's kids:";

echo '<pre>';

print_r($brians_kids);

echo '</pre>';

// delete brian's user meta

delete_user_meta( $brian_id, 'bwawwp_wife' );

delete_user_meta( $brian_id, 'bwawwp_kid' );

// get jason's id

$jason_id = get_user_by( 'login', 'jason' )->ID;

// update user meta - this will create meta if the key doesn't exist for the user.

update_user_meta( $jason_id, 'bwawwp_wife', 'Kimberly Ann Coleman' );

// get user meta - returning an array

$jasons_wife = get_user_meta( $jason_id, 'bwawwp_wife' );

echo "Jason's wife:";

echo '<pre>';

print_r($jasons_wife);

echo '</pre>';

// add user meta - storing as an array

add_user_meta( $jason_id, 'bwawwp_kid', array( 'Isaac', 'Marin' ) );

// get user meta - returning a single value which happens to be an array.

$jasons_kids = get_user_meta( $jason_id, 'bwawwp_kid', true );

echo "Jason's kids:";

echo '<pre>';

print_r($jasons_kids);

echo '</pre>';

// delete jason's user meta

delete_user_meta( $jason_id, 'bwawwp_wife' );

delete_user_meta( $jason_id, 'bwawwp_kid' );

/*

The output from the above example should look something like this:

Brian's wife: Robin Jade Morales Messenlehner

Brian's kids:

Array

(

[0] => Dalya

[1] => Brian Jr

[2] => Nina

)

Jason's wife:

Array

(

[0] => Kimberly Ann Coleman

)

Jason's kids:

Array

(

[0] => Isaac

[1] => Marin

)

*/

?>

wp_posts

Ah, the meat of WordPress. The wp_posts table is where most of your post data is stored. By default, WordPress comes with posts and pages. Both of these are technically posts and are stored in this table. The post_type field is what distinguishes what type of post a post is, whether it is a post, a page, a menu item, a revision, or any custom post type that you may later create (custom post types are covered more in Chapter 5). Table 2-4 shows the database structure for the wp_posts table.

Table 2-4. DB schema for wp_posts table

Functions found in /wp-includes/post.php

The following functions are found in /wp-includes/post.php.

wp_insert_post($postarr, $wp_error = false)

Inserts a new post with provided post data:

§ $postarr—An array or object of post data. Arrays are expected to be escaped; objects are not.

§ $wp_error—An optional Boolean that will allow for a WP_Error if returned false.

The defaults for the parameter $postarr are:

§ post_status—Default is draft.

§ post_type—Default is post.

§ post_author—Default is current user ID ($user_ID). The ID of the user who added the post.

§ ping_status—Default is the value in the default_ping_status option. Whether the attachment can accept pings.

§ post_parent—Default is 0. Set this for the post it belongs to, if any.

§ menu_order—Default is 0. The order it is displayed.

§ to_ping—Whether to ping.

§ pinged—Default is empty string.

§ post_password—Default is empty string. The password to access the attachment.

§ guid—Global unique ID for referencing the attachment.

§ post_content_filtered—Post content filtered.

§ post_excerpt—Post excerpt.

wp_update_post( $postarr = array(), $wp_error = false )

Updates a post with provided post data.

§ $postarr—A required array or object of post data. Arrays are expected to be escaped, objects are not.

§ $wp_error—An optional Boolean that will allow for a WP_Error if returned false.

get_post( $post = null, $output = OBJECT, $filter = raw )

Get post data from a provided post ID or a post object:

§ $post—An optional integer or object of the post ID or post object you want to retrieve. The default is the current post you are on inside of the post loop, which is covered later in this chapter.

§ $output—An optional string of the output format. The default value is OBJECT (WP_Post object) and the other values can be ARRAY_A (associative array) or ARRAY_N (numeric array).

§ $filter—An optional string of how the context should be sanitized on output. The default value is raw, but other values can be edit, db, display, attribute, or js. Sanitization is covered in Chapter 8.

get_posts($args = null)

Returns a list of posts from matching criteria. This function uses the WP_Query class, which you will see examples of throughout the book: $args is an optional array of post arguments. The defaults are:

§ numberposts—Default is 5. Total number of posts to retrieve. –1 is all.

§ offset—Default is 0. Number of posts to pass over.

§ category—What category to pull the posts from.

§ orderby—Default is post_date. How to order the posts.

§ order—Default is DESC. The order to retrieve the posts.

§ include—A list of post IDs to include

§ exclude—A list of post IDs to exclude

§ meta_key—Any metadata key

§ meta_value—Any metadata value. Must also use meta_key.

§ post_type—Default is post. Can be page, or attachment, or the slug for any custom CPT. The string any will return posts from all post types.

§ post_parent—The parent ID of the post.

§ post_status—Default is publish. Post status to retrieve.

wp_delete_post( $postid = 0, $force_delete = false )

This function will trash any post or permanently delete it if $force_delete is set to true:

§ $postid—A required integer of the post ID you would like to trash or delete.

§ $force_delete—An optional Boolean that if set to true will delete the post; if left blank, it will default to false and will move the post to a deleted status.

Example 2-4 demonstrates some of the basic functions for interacting with the wp_posts table.

Example 2-4. Working with the wp_posts table

<?php

// insert post - set post status to draft

$args = array(

'post_title' => 'Building Web Apps with WordPress',

'post_excerpt' => 'WordPress as an Application Framework',

'post_content' => 'WordPress is the key to successful cost effective

web solutions in most situations. Build almost anything on top of the

WordPress platform. DO IT NOW!!!!',

'post_status' => 'draft',

'post_type' => 'post',

'post_author' => 1,

'menu_order' => 0

);

$post_id = wp_insert_post( $args );

echo 'post ID: ' . $post_id . '<br>';

// update post - change post status to publish

$args = array(

'ID' => $post_id,

'post_status' => 'publish'

);

wp_update_post( $args );

// get post - return post data as an object

$post = get_post( $post_id );

echo 'Object Title: ' . $post->post_title . '<br>';

// get post - return post data as an array

$post = get_post( $post_id, ARRAY_A );

echo 'Array Title: ' . $post['post_title'] . '<br>';

// delete post - skip the trash and permanently delete it

wp_delete_post( $post_id, true );

// get posts - return 100 posts

$posts = get_posts( array( 'numberposts' => '100') );

// loop all posts and display the ID & title

foreach ( $posts as $post ) {

echo $post->ID . ': ' .$post->post_title . '<br>';

}

/*

The output from the above example should look something like this:

post ID: 589

Object Title: Building Web Apps with WordPress

Array Title: Building Web Apps with WordPress

"A list of post IDs and Titles from your install"

*/

?>

wp_postmeta

Sometimes you may want to store additional data along with a post. WordPress provides an easy way to do this without having to add additional fields to the posts table. You can store as much post metadata as you need to in the wp_postmeta table. Each record is associated to a post through the post_id field. When editing any post in the backend of WordPress, you can add/update/delete metadata or Custom Fields via the UI. Table 2-5 shows the database structure for the wp_postmeta table.

NOTE

Metadata keys that start with an underscore are hidden from the Custom Fields UI on the edit post page. This is useful to hide certain meta fields that you don’t want end users editing directly.

Table 2-5. DB schema for wp_postmeta table

Functions Found in /wp-includes/post.php

The following functions are found in /wp-includes/post.php.

get_post_meta($post_id, $key = '', $single = false)

Get post metadata for a given post:

§ $post_id—A required integer of the post ID, for which you would like to retrieve post meta.

§ $key—Optional string of the meta key name for which you would like to retrieve post meta. The default is to return metadata for all of the meta keys for a particular post.

§ $single—A Boolean of whether to return a single value or not. The default is false, and the value will be returned as an array.

There can be more than one meta key for the same post ID with different values. If you set $single to true, you will get the first key’s value; if it is set to false, you will get an array of the values of each record with the same key.

update_post_meta($post_id, $meta_key, $meta_value, $prev_value = '')

This function will update post metadata but will also insert metadata if the passed-in key doesn’t already exist:

§ $post_id—A required integer of a post ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to store. If this meta key already exists, it will update the current row’s meta value; if not, it will insert a new row.

§ $meta_value—A required mixed value of an integer, string, array, or object. Arrays and objects will automatically be serialized.

§ $prev_value—An optional mixed value of the current metadata value. If a match is found, it will replace the previous/current value with the new value you specified. If left blank, the new meta value will replace the first instance of the matching key. If you have five rows of metadata with the same key and you don’t specify which row to update with this value, it will update the first row and remove the other four.

NOTE

This function relies on the update_metadata() function located in /wp-includes/meta.php. Check it out!

add_post_meta($post_id, $meta_key, $meta_value, $unique = false)

This function will insert brand-new post meta into the wp_postmeta table. We don’t use this function so often anymore because we can just use the previous function we talked about, update_post_meta(), to insert new rows as well as update them. If you want to insure that a given meta key is only ever used once per post, you should use this function and set the $unique parameter to true:

§ $user_id—A required integer of a post ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to store.

§ $meta_value—A required mixed value of an integer, string, array, or an object.

§ $unique—An optional Boolean that when set to true will make sure the meta key can only ever be added once for a given ID.

delete_post_meta($post_id, $meta_key, $meta_value = '')

Deletes post metadata for a provided post ID and matching key. You can also specify a matching meta value if you only want to delete that value and not other metadata rows with the same meta key:

§ $post_id - A required integer of a post ID.

§ $meta_key - A required string of the

§ $meta_value - An optional mixed value of the meta value. If you have more than one record with the same meta key, you can specify which one to delete by matching this value. It defaults to nothing, which will delete all meta rows with a matching post_id and meta_key.

In Example 2-5 we will get the last post and add, update, and delete various post meta.

Example 2-5. Working with post metadata

<?php

// get posts - return the latest post

$posts = get_posts( array( 'numberposts' => '1', 'orderby' =>

'post_date', 'order' => 'DESC' ) );

foreach ( $posts as $post ) {

$post_id = $post->ID;

// update post meta - public metadata

$content = 'You SHOULD see this custom field when editing your latest post.';

update_post_meta( $post_id, 'bwawwp_displayed_field', $content );

// update post meta - hidden metadata

$content = str_replace( 'SHOULD', 'SHOULD NOT', $content );

update_post_meta( $post_id, '_bwawwp_hidden_field', $content );

// array of student logins

$students[] = 'dalya';

$students[] = 'ashleigh';

$students[] = 'lola';

$students[] = 'isaac';

$students[] = 'marin';

$students[] = 'brian';

$students[] = 'nina';

// add post meta - one key with array as value, array will be serialized

// automatically

add_post_meta( $post_id, 'bwawwp_students', $students, true );

// loop students and add post meta record for each student

foreach ( $students as $student ) {

add_post_meta( $post_id, 'bwawwp_student', $student );

}

// get post meta - get all meta keys

$all_meta = get_post_meta( $post_id );

echo '<pre>';

print_r( $all_meta );

echo '</pre>';

// get post meta - get 1st instance of key

$student = get_post_meta( $post_id, 'bwawwp_student', true );

echo 'oldest student: ' . $student;

// delete post meta

delete_post_meta( $post_id, 'bwawwp_student' );

}

/*

The output from the above example should look something like this:

Array

(

[_bwawwp_hidden_field] => Array

(

[0] => You SHOULD NOT see this custom field when editing your latest post.

)

[bwawwp_displayed_field] => Array

(

[0] => You SHOULD see this custom field when editing your latest post.

)

[bwawwp_students] => Array

(

[0] => a:7:{i:0;s:5:"dalya";i:1;s:8:"ashleigh";i:2;s:4:"lola";i:3;s:5:

"isaac";i:4;s:5:"marin";i:5;s:5:"brian";i:6;s:4:"nina";}

)

[bwawwp_student] => Array

(

[0] => dalya

[1] => ashleigh

[2] => lola

[3] => isaac

[4] => marin

[5] => brian

[6] => nina

)

)

oldest student: dalya

*/

?>

wp_comments

Comments can be left against any post. The wp_comments table stores individual comments for any post and default associated data. Table 2-6 shows the database structure for the wp_comments table.

Table 2-6. DB schema for wp_comments table

Functions Found in /wp-includes/comment.php

The following functions are found in /wp-includes/comment.php.

get_comment( $comment, $output = OBJECT )

Returns comment data from a comment ID or comment object. If the comment is empty, then the global comment variable will be used if set:

§ $comment—An optional integer, string, or object of a comment ID or object.

§ $output—An optional string that defines what format the output should be in. Possible values are OBJECT, ARRAY_A, and ARRAY_N.

get_comments( $args = '' )

This function retrieves a list of comments for specific posts or a single post. It calls the WP_Comment_Query class, which we will cover in the next chapter. $args are an optional array or string of arguments to query comments. The default arguments are:

§ author_email—A string of a comment author’s email address.

§ ID—An integer of the ID of a comment.

§ karma—An integer of a comment’s karma, which can be used by plugins for rating.

§ number—An integer of the number of comments to return. Default is all comments.

§ offset—An integer of the number of comments to pass over. Default is 0.

§ orderby—A string of the field to order the comment by. Allowed values are: comment_agent, comment_approved, comment_author, comment_author_email, comment_author_IP, comment_author_url, comment_content, comment_date, comment_date_gmt,comment_ID, comment_karma, comment_parent, comment_post_ID, comment_type, user_id.

§ order—A string of how to order the selected order by argument. Defaults to DESC and also accepts ASC.

§ parent—An integer of a comment’s parent comment ID.

§ post_id—An integer of the post ID a comment is attached to.

§ post_author—An integer of the post author ID a comment is attached to.

§ post_name—A string of the post name a comment is attached to.

§ post_parent—An integer of the post parent ID a comment is attached to.

§ post_status—A string of the post status a comment is attached to.

§ post_type—A string of the post type a comment is attached to.

§ status—A string of the status of a comment. Optional values are hold, approve, spam, or trash.

§ type—A string of the type of a comment. Optional values are '', pingback, or trackback.

§ user_id—An integer of the user ID of a comment.

§ search—A string of search terms to search a comment on. Searches the comment_author, comment_author_email, comment_author_url, comment_author_IP, and comment_content fields.

§ count—A Boolean that will make the query return a count or results. The default value is false.

§ meta_key—The comment meta key of comment meta to search on.

§ meta_value—The comment meta value of comment meta to search on; meta_key is required.

wp_insert_comment( $commentdata )

Inserts a comment into the database:

§ $commentdata—A required array of comment fields and values to be inserted. Available fields to be inserted are comment_post_ID, comment_author, comment_author_email, comment_author_url, comment_author_IP, comment_date, comment_date_gmt,comment_content, comment_karma, comment_approved, comment_agent, comment_type, comment_parent, and user_id.

wp_update_comment( $commentarr )

Updates comment data and filters to make sure all required fields are valid before updating in the database:

§ $commentarr - An optional array of arguments containing comment fields and values to be updated. These are the same field arguments just listed for the wp_insert_comment() function.

wp_delete_comment( $comment_id, $force_delete = false )

Deletes a comment. By default, it will trash the comment unless specified to permanently delete:

§ $comment_id - A required integer of the comment ID to trash/delete.

§ $force_delete - An optional Boolean that if set to true will permanently delete a comment. Example 2-6 demonstrates some of the basic functions for interacting with the wp_comments table.

Example 2-6 demonstrates managing comment data attached to a post.

Example 2-6. Working with the wp_comments table

<?php

// insert post

$args = array(

'post_title' => '5 year anniversary on 9/10/16',

'post_content' => 'Think of somthing cool to do and make a comment about it!',

'post_status' => 'publish'

);

$post_id = wp_insert_post( $args );

echo 'post ID: ' . $post_id . ' - ' . $args['post_title'] . '<br>';

// make comments array

$comments[] = 'Take a trip to South Jersey';

$comments[] = 'Dinner at Taco Bell';

$comments[] = 'Make a baby';

//loop comments array

foreach ( $comments as $key => $comment ) {

// insert comments

$commentdata = array(

'comment_post_ID' => $post_id,

'comment_content' => $comments[$key],

);

$comment_ids[] = wp_insert_comment( $commentdata );

}

echo 'comments:<pre>';

print_r( $comments );

echo '</pre>';

// update comment

$commentarr['comment_ID'] = $comment_ids[0];

$commentarr['comment_content'] = 'Take a trip to Paris, France';

wp_update_comment( $commentarr );

// insert comment - sub comment from parent id

$commentdata = array(

'comment_post_ID' => $post_id,

'comment_parent' => $comment_ids[0],

'comment_content' => 'That is a pretty good idea...',

);

wp_insert_comment( $commentdata );

// get comments - search taco bell

$comments = get_comments( 'search=Taco Bell&number=1' );

foreach ( $comments as $comment ) {

// insert comment - sub comment of taco bell comment id

$commentdata = array(

'comment_post_ID' => $post_id,

'comment_parent' => $comment->comment_ID,

'comment_content' => 'Do you want to get smacked up?',

);

wp_insert_comment( $commentdata );

}

// get comment - count of comments for this post

$comment_count = get_comments( 'post_id= ' . $post_id . '&count=true' );

echo 'comment count: ' . $comment_count . '<br>';

// get comments - get all comments for this post

$comments = get_comments( 'post_id=' .$post_id );

foreach ( $comments as $comment ) {

// update 1st comment

if ( $comment_ids[0] == $comment->comment_ID ) {

$commentarr = array(

'comment_ID' => $comment->comment_ID,

'comment_content' => $comment->comment_content . ' & make a baby!',

);

wp_update_comment( $commentarr );

// delete all other comments

}else {

// delete comment

wp_delete_comment( $comment->comment_ID, true );

}

}

// get comment - new comment count

$comment_count = get_comments( 'post_id= ' . $post_id . '&count=true' );

echo 'new comment count: ' . $comment_count . '<br>';

// get comment - get best comment

$comment = get_comment( $comment_ids[0] );

echo 'best comment: ' . $comment->comment_content;

/*

The output from the above example should look something like this:

post ID: 91011 - 5 year anniversary on 9/10/16

comments:

Array

(

[0] => Take a trip to South Jersey

[1] => Dinner at Taco Bell

[2] => Make a baby

)

comment count: 5

new comment count: 1

best comment: Take a trip to Paris, France & make a baby!

*/

?>

wp_commentsmeta

Just like the wp_usermeta and wp_postmeta table, this table stores any custom, additional data tied to a comment by the comment_id fields. Table 2-7 shows the database structure for the wp_commentsmeta table.

Table 2-7. DB schema for wp_commentsmeta table

Functions Found in /wp-includes/comment.php

The following functions are found in /wp-includes/comment.php.

get_comment_meta($comment_id, $key = '', $single = false)

Get comment meta for a given comment ID:

§ $comment_id—A required integer of the comment ID for which you would like to retrieve comment meta.

§ $key—Optional string of the meta key name for which you would like to retrieve comment meta. The default is to return metadata for all of the meta keys for a particular post.

§ $single—A Boolean of whether to return a single value or not. The default is false, and the value will be returned as an array.

add_comment_meta($comment_id, $meta_key, $meta_value, $unique = false)

Add comment meta for given comment ID:

§ $comment_id—A required integer of a comment ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to store.

§ $meta_value—A required mixed value of an integer, string, array, or object.

§ $unique—An optional Boolean that when set to true will make sure the meta key can only ever be added once for a given ID.

update_comment_meta($comment_id, $meta_key, $meta_value, $prev_value = '')

§ $comment_id—A required integer of a comment ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to store. If this meta key already exists, it will update the current row’s meta value; if not, it will insert a new row.

§ $meta_value—A required mixed value of an integer, string, array, or object. Arrays and objects will automatically be serialized.

§ $prev_value—An optional mixed value of the current metadata value. If a match is found, it will replace the previous/current value with the new value you specified. If left blank, the new meta value will replace the first instance of the matching key. If you have five rows of metadata with the same key and you don’t specify which row to update with this value, it will update the first row and remove the other four.

delete_comment_meta($comment_id, $meta_key, $meta_value = '')

Deletes comment metadata for a provided comment ID and matching key. You can also specify a matching meta value if you only want to delete that value and not other metadata rows with the same meta key:

§ $comment_id—A required integer of a comment ID.

§ $meta_key—A required string of the meta key name for the meta value you would like to delete.

§ $meta_value—An optional mixed value of the meta value. If you have more than one record with the same meta key, you can specify which one to delete by matching this value. It defaults to nothing, which will delete all meta rows with a matching post_id and meta_key.

Example 2-7 demonstrates some of the basic functions for interacting with the wp_commentsmeta table.

Example 2-7. Working with the wp_commentsmeta table

<?php

// get comments - last comment ID

$comments = get_comments( 'number=1' );

foreach ( $comments as $comment ) {

$comment_id = $comment->comment_ID;

// add comment meta - meta for view date & IP address

$viewed = array( date( "m.d.y" ), $_SERVER["REMOTE_ADDR"] );

$comment_meta_id = add_comment_meta( $comment_id, 'bwawwp_view_date',

$viewed, true );

echo 'comment meta id: ' . $comment_meta_id;

// update comment meta - change date format to format like

// October 23, 2020, 12:00 am instead of 10.23.20

$viewed = array( date( "F j, Y, g:i a" ), $_SERVER["REMOTE_ADDR"] );

update_comment_meta( $comment_id, 'bwawwp_view_date', $viewed );

// get comment meta - all keys

$comment_meta = get_comment_meta( $comment_id );

echo '<pre>';

print_r( $comment_meta );

echo '</pre>';

// delete comment meta

delete_comment_meta( $comment_id, 'bwawwp_view_date' );

}

/*

The output from the above example should look something like this:

comment meta id: 16

Array

(

[bwawwp_view_date] => Array

(

[0] => a:2:{i:0;s:24:"August 11, 2013, 4:16 pm";i:1;s:9:"127.0.0.1";}

)

)

*/

?>

wp_links

This table stores any links, URLs, or bookmarks you create. Since WordPress version 3.5, the links/blogroll manager UI has been hidden, so if you do a fresh install and don’t see it, don’t freak out. You can still use the links/blogroll manager if you choose by installing Andrew Nacin’s link manager plugin. If you are upgrading WordPress from a version prior to 3.5, you will still be able to access the UI. Why was this removed, you might ask? If Andrew pulled it out of core, you can bet he had a good reason for it. Once you read about custom post types in Chapter 5, you should be enlightened. Because this feature is on it’s way out, we aren’t going to go over some of the basic helper functions used to interact with this table. Table 2-8 shows the database structure for the wp_links table.

Table 2-8. DB schema for wp_links table

NOTE

Bookmark functions can be found in /wp-includes/bookmark.php.

wp_terms

The wp_terms table stores each category name or term name that you create. Each record is tied to its taxonomy in the wp_term_taxonomy table by the term_id. So you’re familiar with post categories and tags? Well, each category or tag is stored in this table, and technically they are both taxonomies. Every term that is stored in the name column is a taxonomy term. We will be covering taxonomies in much more detail in Chapter 5, so if you don’t fully grasp what a taxonomy is, you will soon. Table 2-9 shows the database structure for the wp_terms table.

Table 2-9. DB schema for wp_terms table

Functions Found in /wp-includes/taxonomy.php

The following functions are found in /wp-includes/taxonomy.php.

get_terms( $taxonomies, $args = '' )

Gets the terms of a specific taxonomy or an array of taxonomies:

§ $taxonomies—A required string or array of a taxonomy or list of taxonomies.

§ $args—An optional string or array of arguments. Available arguments are:

1. orderby—Default is name. Can be name, count, term_group, slug, or nothing, which will use term_id. Passing a custom value other than these will cause the terms to be ordered on that custom value.

2. order—ASC or DESC. The default is ASC.

3. hide_empty—The default value is true, which will only return terms that are attached to a post. If set to false, you can return all terms regardless, if they are being used by a post or not.

4. exclude—An array or comma-separated or space-delimited string of term IDs to exclude from the query results. If include is being used, exclude will be ignored.

5. exclude_tree—An array or comma-separated or space-delimited string of term IDs to exclude from the query results, including any child terms. If include is being used, exclude_tree will be ignored.

6. include—An array or comma-separated or space-delimited string of term IDs to include in the query results.

7. number—The number of terms for the query to return. The default is all.

8. offset—The number by which to offset the terms query.

9. fields—You can specify if you want to return term IDs or names. The default is all, which returns an array of term objects.

10.slug—A string that will return any terms that have a matching slug.

11.hierarchical—Includes all child terms if they are attached to posts. The default is true, so to not return terms hierarchically, set this to false.

12.search—A string that will return any terms whose names match the value provided. The search is case-insensitive.

13.name_like—A string that will return any terms whose names begin with the value provided. Like the search, this is case-insensitive.

14.pad_counts—If set to true, the query results will include the count of each term’s children.

15.get—If set to all, returns terms regardless of ancestry or whether the terms are empty.

16.child_of—When set to a term ID, the query results will contain all descendants of the provided term ID. The default is 0, which returns everything.

17.parent—When set to a term ID, the query results will contain the direct children of the provided term ID. The default is an empty string.

18.cache_domain—Enables a unique cache key to be produced when this query is stored in object cache.

get_term( $term, $taxonomy, $output = OBJECT, $filter = raw )

Get all term data for any given term:

§ $term—A required integer or object of the term to return.

§ $taxonomy—A required string of the taxonomy of the term to return.

§ $output—An optional string of the output format. The default value is OBJECT, and the other values can be ARRAY_A (associative array) or ARRAY_N (numeric array).

§ $filter—An optional string of how the context should be sanitized on output. The default value is raw.

wp_insert_term( $term, $taxonomy, $args = array() )

Adds a new term to the database:

§ $term—A required string of the term to add or update.

§ $taxonomy—A required string of the taxonomy the term will be added to.

§ $args—An optional array or string of term arguments to be inserted/updated. Available arguments are:

1. alias_of—An optional string of the slug that the term will be an alias of.

2. description—An optional string that describes the term.

3. parent—An optional integer of the parent term ID that this term will be a child of.

4. slug—An optional string of the slug of the term.

wp_update_term( $term_id, $taxonomy, $args = array() )

Updates an existing term in the database:

§ $term_id—A required integer of the term ID of the term you want to update.

§ $taxonomy—A required string of the taxonomy the term is associated with.

§ $args—An optional array or string of term arguments to be updated. These are the same arguments used in wp_insert_term().

wp_delete_term( $term, $taxonomy, $args = array() )

Deletes a term from the database. If the term is a parent of other terms, then the children will be updated to that term’s parent:

§ $term—A required integer of the term ID of the term you want to delete.

§ $taxonomy—A required string of the taxonomy the term is associated with.

§ $args—An optional array to overwrite term field values.

wp_term_taxonomy

The wp_term_taxonomy table stores each taxonomy type you are using. WordPress has two taxonomy types built in, category and post_tag, but you can also register your own taxonomies. When a new term gets added in the wp_terms table, it is associated with its taxonomy in this table, along with that taxonomy term ID, description, parent, and count. Table 2-10 shows the structure for the wp_term_taxonomy table.

Table 2-10. DB schema for wp_term_taxonomy table

/wp-includes/taxonomy.php

The following functions are found in /wp-includes/taxonomy.php.

get_taxonomies( $args = array(), $output = names, $operator = and )

This function returns a list of registered taxonomy objects or a list of taxonomy names:

§ $args—An optional array of arguments to query what taxonomy objects get returned. There are a lot, and we will cover all of them in Chapter 5.

§ $output—An optional string of either names or objects. The default is names, which will return a list of taxonomy names.

§ $operator—An optional string of either and or or. The default is and, which means that all of the arguments passed in must match. If set to or, any of the arguments passed in can match.

get_taxonomy( $taxonomy )

This function will first check that the parameter string given is a taxonomy object; and if it is, it will return it:

§ $taxonomy—A required string of the name of the taxonomy object to return.

register_taxonomy( $taxonomy, $object_type, $args = array() )

This function creates or updates a taxonomy object. Registering custom taxonomies can really extend WordPress because you can categorize your posts anyway you see fit. We are going to go over registering taxonomies in much more detail in Chapter 5:

§ $taxonomy - A required string of the name of the taxonomy.

§ $object_type - A required array or string of the object types (post types like post and page) that this taxonomy will be tied to.

§ $args - An optional array or string of arguments. There are a lot, and we will cover all of them in Chapter 5.

wp_term_relationships

The wp_term_relationships table relates a taxonomy term to a post. Every time you assign a category or tag to a post, it’s being linked to that post in this table. Table 2-11 shows the structure for the wp_term_relationships table.

Table 2-11. DB schema for wp_term_relationships table

get_object_taxonomies( $object, $output = names )

This function returns all taxonomies associated with a post type or post object:

§ $object—A required array, string, or object of the name(s) of the post type(s) or post object(s).

§ $output—An optional string of either names or objects. The default is names, which will return a list of taxonomy names.

wp_get_object_terms( $object_ids, $taxonomies, $args = array() )

This function returns terms associated with a supplied post object ID or IDs and a supplied taxonomy.

§ $object_ids—A required string or array of object IDs for the object terms you would like to return. Passing in a post ID would return terms associated with that post ID.

§ $taxonomies—A required string or array of the taxonomy names from which you want to return terms. Passing in the taxonomy post_tag would return terms of the post_tag taxonomy.

§ $args—An optional array or string of arguments that change how the data is returned. The arguments that can be changed are:

1. orderby—Defaults to name; also accepts count, slug, term_group, term_order, and none.

2. order—Defaults to ASC; also accepts DESC.

3. fields—Defaults to all; also accepts ids, names, slugs, and all_with_object_id. This argument will dictate what values will be returned.

wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false )

This function adds taxonomy terms to a provided object ID and taxonomy. It has the ability to overwrite all terms or to append new terms to existing terms. If a term passed into this function doesn’t already exist, it will be created and then related to the provided object ID and taxonomy:

§ $object_id—A required integer of the object ID (post ID) to relate your terms to.

§ $terms—A required array, integer, or string of the terms you would like to add to an object (post).

§ $taxonomy—A required array or string of the taxonomy or taxonomies you want to relate your terms to.

§ $append—An optional Boolean that defaults to false that will replace any existing terms related to an object ID with the new terms you provided. If set to true, your new terms will be appended to the existing terms.

CAUTION

Discussion is underway to remove the wp_terms table from WordPress in a future release. The name and slug columns of wp_terms will be moved into the wp_terms_taxonomy table, and a MySQL view will be created called wp_terms that can be queried against, preserving backward compatibility for your custom queries.

Extending WordPress

If you are looking to write your own functionality or customize the data returned by WordPress, you might find the following core concepts in the next chapter very helpful. We will cover more of the various built-in functions and methods used to interact with WordPress data throughout the book. Chapter 3 covers the WordPress Plugin API, including some of the key features of WordPress that make extending it easy, powerful, and consistent!