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

Hello Dolly is included as a quick example of how a basic WordPress plugin is set up. The plugin itself just displays a random line from the song Hello Dolly in the upper right of the admin dashboard.

Akismet is a plugin that helps to stop spam comments by checking incomming comments against the database at Akismet.com. This plugin and service greatly reduces the number of spam comments that make it onto the frontend of your website. The Akismet service is free (or name your own price) for personal use.

/wp-content/themes

Any WordPress themes you install on your WordPress site will be located in this directory. By default, WordPress comes with a few standard themes all named after the year they were released (e.g. Twenty Sixteen, Twenty Seventeen, etc).

/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. Some plugins will also create a subdirectory in the uploads directory to various files used or managed by the plugin.

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

It is a good idea to check for the mu-plugins folder on any existing site you start working on. See what if there are any plugins in there and what they do. So many times we have been debugging an issue and wondering why something unexpected was happening even though we had disabled all of the active plugins, only to find out that there was an overlooked mu-plugin responsible for the issue.

add_option( string $option, mixed $value = ', string $deprecated = ', string|bool $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.²

• $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 yes. If you are sure you are going to need this option on every page load, you can leave the value as the default yes. If you are only going to need to lookup the option on specific pages, then it’s usually better to set autoload to no.

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.

Example 2-1 demonstrates some of the basic functions for interacting with 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(
                 '@alphaweb',
                 '@pmproplugin'
         )
);
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] => @alphaweb
    [4] => @pmproplugin
)
*/
?>

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

<?php
// insert user
$userdata = array(
    'user_login'    => 'brian',
	'user_pass'     => 'KO03gT7@n*',
	'user_nicename' => 'Brian',
	'user_url'      => 'https://alphaweb.com/',
	'user_email'    => 'brian@alphaweb.com',
	'display_name'  => 'Brian',
	'nickname'      => 'Brian',
	'first_name'    => 'Brian',
	'last_name'     => 'Messenlehner',
	'description'   => 'This is a WordPress 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 - change user name fields 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
*/
?>
-------------------------------------------

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.

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.

<?php
// get brian's id
$brian_id = get_user_by( 'login', 'brian' )->ID;

// add user meta - unique is set to true.
add_user_meta( $brian_id, 'bwawwp_wife', 'Married to the game', 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 - 3rd parameter is a unique value
add_user_meta( $brian_id, 'bwawwp_kid', 'Dalya' );
add_user_meta( $brian_id, 'bwawwp_kid', 'Brian' );
add_user_meta( $brian_id, 'bwawwp_kid', 'Nina' );
add_user_meta( $brian_id, 'bwawwp_kid', 'Cam' );

// 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: Married to the game
Brian's kids:
Array
(
    [0] => Dalya
    [1] => Brian Jr
    [2] => Nina
    [3] => Cam
)
Jason's wife:
Array
(
    [0] => Kimberly Ann Coleman
)
Jason's kids:
Array
(
    [0] => Isaac
    [1] => Marin
)
*/
?>
-------------------------------------------

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.

<?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"
*/
?>
----

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.

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.

<?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';
 $students[] = 'cam';

	// 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";i:6;s:5:"cam";}
        )

    [bwawwp_student] => Array
        (
            [0] => dalya
            [1] => ashleigh
            [2] => lola
            [3] => isaac
            [4] => marin
            [5] => brian
            [6] => nina
	[7] => cam
        )
)
oldest student: dalya
*/
?>

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 = '' )

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.

<?php
// insert post
$args = array(
 'post_title'   => 'What should I do tonight?',
 'post_content' => 'Think of something 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[] = 'ICE CREAM!!!!';
$comments[] = 'Taco Bell';
$comments[] = 'Get a good night sleep';

//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'] = 'Read this entire book';
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' => ‘',
	);
	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 . ' & build some apps!',
	);
		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 - What should I do tonight?
comments:
Array
(
    [0] => ICE CREAM!!!!
    [1] => Taco Bell
    [2] => Get a good night sleep
)
comment count: 5
new comment count: 1
best comment: Read this entire book & build some apps!
*/
?>

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 = '')

Update comment meta for a 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. 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.

<?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, 2018, 4:16 pm";i:1;s:9:"127.0.0.1";}
        )

)
*/
?>

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 )

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

get_term_meta( $term_id, $key = '', $single = false )

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

• $term_id—A required integer of a term 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 term 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 term 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_term_meta( $term_id, $meta_key, $meta_value, $prev_value = '' )

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

• $term_id—A required integer of a term 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.

add_term_meta($term_id, $meta_key, $meta_value, $unique = false)

Inserts brand-new term meta into the wp_termmeta table. Again, it is preferred to use update_term_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 term, you should use this function and set the $unique parameter to true:

• $term_id—A required integer of a term 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_term_meta($term_id, $meta_key, $meta_value = '')

Deletes term metadata for a provided term 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:

• $term_id—A required integer of a term 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 term_id and meta_key.

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

get_object_taxonomies( $object, $output = names )

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() )

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 )

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.

$wpdb

The $wpdb class is used to interact with the database directly. Once globalized, you can use $wpdb in custom functionality to select, update, insert, and delete database records. If you are new to WordPress and aren’t familiar with all of the functions to push and pull from the database, $wpdb is going to be your best friend.

Queries using $wpdb are also useful when you need to manage custom tables required by your app or perform a complicated query (perhaps joining many tables) faster than the core WordPress functions would run on their own. Please don’t assume that the built-in WordPress functions for querying the database are slow. Unless you know exactly what you are doing, you’ll want to use the built-in functions for getting posts, users, and metadata. The WordPress core is smart about optimizing queries and caching the results from these calls, which will work well across all of the plugins you are running. However, in certain situations, you can shave a bit of time by rolling your own query. A few examples like this are covered in [Link to Come].

Using custom DB tables

In SchoolPress, we store the relationship of student submissions to assignments in a custom table. This keeps the core WordPress tables a bit cleaner² and allows us to easily query for things like “select all of Isaac’s assignments.”

To add our table to the database, we need to write up the SQL for the CREATE TABLE command and query it against the WordPress database. You can use either the $wpdb->query() method or the dbDelta() function in the WordPress core.

There are a few things we need to do to keep track of our custom tables. We want to store a db_version for our app plugin so we know what version of the database schema we are working with in case it updates between versions. We can also check the version so we only run the setup SQL once for each version. Another common practice is to store your custom table name as a property of $wpdb to make querying it a bit easier later.

Example 3-1 shows a little bit of our database setup function for the SchoolPress app:

<?php
// setup the database for the SchoolPress app
function sp_setupDB() {
	global $wpdb;

	// shortcuts for SchoolPress DB tables
	$wpdb->schoolpress_assignment_submissions = $wpdb->prefix .
		'schoolpress_assignment_submissions';

	$db_version = get_option( 'sp_db_version', 0 );

	// create tables on new installs
	if ( empty( $db_version ) ) {
		global $wpdb;

		$sqlQuery = "
		CREATE TABLE '" . $wpdb->schoolpress_assignment_submissions . "' (
		  `assignment_id` bigint(11) unsigned NOT NULL,
		  `submission_id` bigint(11) unsigned NOT NULL,
		UNIQUE KEY `assignment_submission` (`assignment_id`,`submission_id`),
		UNIQUE KEY `submission_assignment` (`submission_id`,`assignment_id`)
		)
		";

		require_once ABSPATH . 'wp-admin/includes/upgrade.php';
		dbDelta( $sqlQuery );

		$db_version = '1.0';
		update_option( 'sp_db_version', '1.0' );
	}
}
add_action( 'init', 'sp_dbSetup', 0 );
?>
-------------------------------------------

The sp_dbSetup() function is run early in init (priority 0) so the table shortcuts are available to any other code you have running. You can’t always assume a wp_ prefix, so the $wpdb->prefix property is used to get the database prefix for the WordPress install.

A DB version for the SchoolPress app is stored in the WordPress options table. We get the value out of options, and if it is empty, we run code to create our custom tables. The CREATE TABLE SQL statement here is pretty standard. You should always try to run these commands directly on the MySQL database before pasting them into your plugin code to make sure they work.

We use the dbDelta() function to create the database table. This function will create a new table if it doesn’t exist. Or if a table with the same name already exists, it will figure out the correct ALTER TABLE query to get the old table to match the new schema.

To use dbDelta(), you must be sure to include the wp-admin/includes/upgrade.php file since that file is only loaded when needed. Then pass dbDelta() the SQL for a CREATE TABLE query. Your SQL must be in a specific format a little more strict than the general MySQL format.

1. You must put each field on its own line in your SQL statement.

2. You must have two spaces between the words PRIMARY KEY and the definition of your primary key.

3. You must use the keyword KEY rather than its synonym INDEX, and you must include at least one KEY.

4. You must not use any apostrophes or backticks around field names.

Escaping in DB queries

It should be noted that values passed into the query() method are not escaped automatically. Therefore, you will always need to escape untrusted input when using the query() method directly.

There are two main ways of escaping values used in your SQL queries: you can wrap your variables in the esc_sql() function (see Example 3-2) or you can use the $wpdb->prepare() method to build your query.

global $wpdb;
$user_query = $_REQUEST[‘uq’];

$sqlQuery = “SELECT user_login FROM $wpdb->users WHERE
user_login LIKE ‘%” . esc_sql($user_query) . “%’ OR
user_email LIKE ‘%” . esc_sql($user_query) . “%’ OR
display_name LIKE ‘%” . esc_sql($user_query) . “%’
”;
$user_logins = $wpdb->get_col($sqlQuery);

if(!empty($user_logins))
{
	echo “<ul>”;
foreach($user_logins as $user_login)
	{
		echo “<li>$user_login</li>”;
}
echo “</ul>”;
}

Alternatively, you could create the query using the prepare() method, which functions similarly to the sprintf() and printf() functions in PHP. Using prepare is preferred whenever possible because it does a better job of escaping data and also helps to avoid issues around misplaced single quotes.

The prepare method of the $wpdb class located in wp-includes/wp-db.php accepts two or more parameters:

• $query—A string of your custom SQL statement with placeholders for each dynamic value.

• $args—One or more additional parameters to be used to replace the placeholders in your SQL statement.

The following directives can be used in the SQL statement string:

• %d (integer)

• %f (float)

• %s (string)

• %% (literal percentage sign–-no argument needed)

The directives %d, %f, and %s should be left unquoted in the SQL statement, and each placeholder used needs to have a corresponding argument passed in for it. Literals (%) as part of the query must be properly written as %%:

$sqlQuery = $wpdb->prepare(“SELECT user_login FROM $wpdb->users WHERE
user_login LIKE %%%s%% OR
user_email LIKE %%%s%% OR
display_name LIKE %%%s%%”, $user_query, $user_query, $user_query);
$user_logins = $wpdb->get_col($sqlQuery);

Holy percent sign, Batman! The % is used in SQL as a wildcard in SELECT statements when using the LIKE keyword. So if you searched for user_login LIKE %coleman%, it would return users with user logins like “jcoleman” and “jasoncoleman” and “coleman1982.” To keep these literal % signs in place with the prepare() method, we need to double them up to %%, which is translated into just one % in the final query.

The other % in there is used with %s, which is the placeholder where our $user_query parameter is going to be swapped in after being escaped.

You may have noticed we used the $wpdb->get_col() method in the previous code segment. WordPress offers many useful methods on the $wpdb object to SELECTs, INSERTs, and other common queries in MySQL.

SELECT queries with $wpdb

The WordPress $wpdb object has a few useful methods for selecting arrays, objects, rows, columns, or even single values out of the MySQL database using SQL queries.

$wpdb→get_results($query, $output_type) will run your query and return the last_results array, including all of the rows from your SQL query in the output type specified. By default, the result will be a “numerically indexed array of row objects.” Here’s the full list of output types from the WordPress Codex:

OBJECT

Result will be output as a numerically indexed array of row objects.

OBJECT_K

Result will be output as an associative array of row objects, using the first column’s values as keys (duplicates will be discarded).

ARRAY_A

Result will be output as an numerically indexed array of associative arrays, using column names as keys.

ARRAY_N

Result will be output as a numerically indexed array of numerically indexed arrays.

The following code helps show how to use the array returned by $wpdb->get_results() when using the OBJECT output type:

<?php
global $wpdb;
$sqlQuery = "SELECT * FROM $wpdb->posts
	WHERE post_type = 'assignment'
	AND post_status = 'publish' LIMIT 10";
$assignments = $wpdb->get_results( $sqlQuery );

// rows are stored in an array, use foreach to loop through them
foreach ( $assignments as $assignment ) {
// each item is an object with property names equal to the SQL column names?>
<h3><?php echo $assignment->post_title;?></h3>
<?php echo apply_filters( "the_content", $assignment->post_content );?>
<?php
}
?>

$wpdb→get_col($query, $collumn_offset = 0) will return an array of the values in the first column of the MySQL results. The $collumn_offset parameter can be used to grab other columns from the results (0 is the first, 1 is the second, and so on).

This function is most commonly used to grab IDs from a database table to be used in another function call or DB query:

<?php
global $wpdb;
$sqlQuery = "SELECT ID FROM $wpdb->posts
	WHERE post_type = 'assignment'
	AND post_status = 'publish'
	LIMIT 10";
// getting IDs
$assignment_ids = $wpdb->get_col( $sqlQuery );

// result is an array, loop through them
foreach ( $assignment_ids as $assignment_id ) {
	// we have the id, we can use get_post to get more data
	$assignment = get_post( $assignment_id );
	?>
	<h3><?php echo $assignment->post_title;?></h3>
	<?php echo apply_filters( "the_content", $assignment->post_content );?>
	<?php
}
?>

Note that we’re putting that global $wpdb; line in most of our examples here to reinforce the point that you need to make sure that $wpdb is in scope before calling one of its methods. In practice, this line is usually at the top of the function or file you are working within.

$wpdb→get_row($query, $output_type, $row_offset) is used to get just one row from a result. Instead of getting an array of results, you will just get the first object (or array if the $output_type is specified) from the result set.

You can use the $row_offset parameter to grab a different row from the results (0 is the first, 1 is the second, and so on).

<?php
// processing new submissions for assignments
global $wpdb, $current_user;

// create submission
$assignment_id = intval( $_REQUEST['assignment_id'] );
$submission_id = wp_insert_post(
	array(
		'post_type'    => 'submission',
		'post_author'  => $current_user->ID,
		'post_title'   => sanitize_title( $_REQUEST['title'] ),
		'post_content' => sanitize_text_field( $_POST['submission'] )
	)
);

// connect the submission to the assignment
$wpdb->insert(
  $wpdb->schoolpress_assignment_submissions,
  array( "assignment_id"=>$assignment_id, "submission_id"=>$submission_id ),
  array( '%d', '%d' )
);

/*
	This insert call will generate a SQL query like:
	INSERT INTO
	'wp_schoolpress_assignment_submissions'

	('assignment_id','submission_id' VALUES (101,10)
*/
?>

<?php
global $wpdb;
// just update the status
$wpdb->update(
	'ecommerce_orders',   //table name
	array( 'status' => 'paid' ),  //data fields
	array( 'id' => $order_id )  //where fields
);

// update more data about the order
$wpdb->update(
	'ecommerce_orders',   //table name
	array( 'status' => 'pending',  //data fields
		'subtotal' => '100.00',
		'tax' => '6.00',
		'total' => '106.00'
	),
	array( 'id' => $order_id )  //where fields
);
?>

<?php
//welcome the logged-in user
global $current_user;
if ( !empty( $current_user->ID ) ) {
	echo 'Howdy, ' . $current_user->display_name;
}
?>

Database tables

Unlike a lot of WordPress plugins, BuddyPress creates its own database tables in MySQL. If the original BuddyPress developers were to rewrite the plugin from scratch today, they would probably store activities and notifications as custom posts instead of using custom tables. However, custom post types weren’t implemented when the original version of BuddyPress was released and it would take a lot of effort to change that architecture now. The custom tables that store groups and friend relationships between users are much easier to understand and faster to query against that if these kinds of things were stored as some combination of posts, user meta, and taxonomies.

For smaller distributed plugins, it makes sense to avoid custom tables whenever possible because it means there is less overhead for users of the plugin to worry about. However, for plugins specific to your app or plugins that include as much functionality as BuddyPress, custom tables can help to speed up or better organize your data. We’ve included the schema for each BuddyPress table here (Table 3-3 through Table 3-18) as an example of how you might go about structuring custom tables for your own apps and also to help you understand how BuddyPress data is stored in case you would like to query for that information directly.

Components

After activating BuddyPress, head on over to the Components panel in Settings → BuddyPress or /wp-admin/options-general.php?page=bp-components to set up what components you would like to use. See Figure 3-3 for an illustration of the panel.

You will see the following components:

Extended Profiles

Just like any typical social network, BuddyPress has member profiles. A member can join and have complete control of her own profile. Out of the box, all members are listed in a members directory; once you click on a member, you will be taken to her profile page.

Account Settings

Members can update their email address, change their password, and even manage the email notifications they will receive when other members interact with them.

Friend Connections

Members can add each other as friends. When one member requests to be friends with another, the other member will receive a friend request. Think Facebook friends.

Private Messaging

Members can send private messages to each other and view all of their messages in one place, like an inbox for your social network. Members can reply, mark as read, delete, and perform other actions with messages you might expect with any large social network.

Activity Streams

Members can post activity updates to their profiles and groups, leave comments on other members’ or groups’ activity, and favorite any activity post. Sounds kind of like Facebook, right? BuddyPress has an @mention feature that is kind of like when someone mentions you on Twitter. @mentions are automatically linked to the mentioned member’s profile page, and if that member doesn’t have his notifications turned off, he will receive an email about it. Activity also comes standard with RSS feeds.

User Groups

A very powerful component of BuddyPress, groups can be created organically (or not) by network members. Each group is listed on a Groups listing page, and clicking on that group’s avatar brings you to that group’s profile page. The group profile is set up very similar to the member profile page, but with group-specific subpages like group activity, members, admin settings, and invite friends. Groups can be public, private, or hidden and members can be promoted to group admins or group moderators.

Site Tracking

Any new posts and comments on your site will create BuddyPress activity posts. If you are running BuddyPress on a WordPress multisite network, any posts and comments created on any site in your network will also create BuddyPress activity posts.

All of these core BuddyPress components can be extended with BuddyPress plugins. It can be a little confusing if you are new to all of this, but you can install additional plugins specific to BuddyPress or build your own. There are approximately 485 WordPress plugins that extend or integrate with BuddyPress in one way or another.

Figure 3-3. BuddyPress components

Pages

Once you have decided which core components you want to use, go to the Pages tab at Settings → BuddyPress → Pages (shown in Figure 3-4). BuddyPress maps the components it is using to new or existing pages. By default, BuddyPress will try to make a new page for each component. If you wanted to call members “Students” instead of “Members,” you could create a regular WordPress page called “Students” and map the members component to this new page. The same goes for other BuddyPress components. You will notice two pages that need to be created for member registration, Register and Activate. You will need to map both of these to pages if you wish to have open registration on your social network.

Figure 3-4. BuddyPress pages

Settings

In the Settings panel (Settings → BuddyPress → Settings) or /wp-admin/admin.php?page=bp-settings, you can configure some additional BuddyPress settings:

Toolbar

By default, BuddyPress shows the WordPress admin bar with a Login and Register link for non-logged-in users. If you would like to turn this off, you can do so here.

Account Deletion

You can decide if you want to allow registered users to be able to delete their accounts.

Avatar Uploads

Allow registered members to upload avatars.

Profile Syncing

Enable BuddyPress to WordPress profile syncing.

Group Creation

Allow your registered members to create their own groups. Site admins can still create groups if this setting is turned off.

Blog & Forum Comments

Allow activity stream commenting on blog and forum posts.

Profile fields

Located at Users → Profile Fields or /wp-admin/users.php?page=bp-profile-setup, this BuddyPress feature allows you to create any number of profile field groups and profile fields for your members. You can collect data such as location, date of birth, likes, dislikes, favorite color, and/or whatever you want. This feature is very flexible in allowing you to organize your profile fields into different profile groups, all of which will be made available on any member’s frontend profile page.

When adding any new profile field, you are provided with a slick UI for deciding to make your new field required or not, what type of form element it should be, what the default visibility is, and whether you want your members to be able to decide if they can change the visibility for the field. This form is shown in Figure 3-5.

Figure 3-5. BuddyPress profile fields