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