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

The Akismet plugin helps stop spam comments by checking incoming comments against the database at https://akismet.com. This plugin and service greatly reduce 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 for the year they were released (Twenty Seventeen, Twenty Nineteen, etc.).

/wp-content/uploads

Once you start uploading any photos or files to your media library, you will see 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 to see whether it contains any plugins, and if so, to determine 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 whether 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, deprecated in version 2.3, is no longer used.²

$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 look up the option on specific pages, 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 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. Accepted fields are as follows:

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.

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 )

Use this function to update any field 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 their cookies will be cleared, logging them 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 to avoid 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 by which you would like to query the user data. 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 for which you would like to get data.

wp_delete_user( $id, $reassign = ‘novalue’ )

You guessed it: this function delete 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'    => '[email protected]',
	'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@', '[email protected]' );

// 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', '[email protected]' );
echo 'username: ' . $user->user_login . ' / ID: ' . $user->ID . '<br>';

// update user-change username 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: [email protected] / 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 used only 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 that, 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 want to delete only 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' );
add_user_meta( $brian_id, 'bwawwp_kid', 'Aksel' );

// 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
    [4] => Aksel
)
Jason's wife:
Array
(
    [0] => Kimberly Ann Coleman
)
Jason's kids:
Array
(
    [0] => Isaac
    [1] => Marin
)
*/
?>

wp_insert_post( $postarr, $wp_error = false )

This function 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 in which the array 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 )

This function 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’ )

This function gets 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 )

This function 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 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 updates post metadata, but it also inserts 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 inserts brand-new post meta into the wp_postmeta table. This function is used less these days 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 ensure that a given meta key is used only 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 object.

$unique

An optional Boolean that, when set to true, will ensure that the meta key can be added only once for a given ID.

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

This function deletes post metadata for a provided post ID and matching key. You can also specify a matching meta value if you want to delete only 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 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.

In Example 2-5, we 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 )

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

$comment

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

$output

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

get_comments( $args = '' )

This function retrieves a list of comments for specific posts or a single post. It calls the WP_Comment_Query class, which we 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 in which 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, and user_id.

order

A string of how to order the selected orderby 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 to which a comment is attached.

post_author

An integer of the post author ID to which a comment is attached.

post_name

A string of the post name to which a comment is attached.

post_parent

An integer of the post parent ID to which a comment is attached.

post_status

A string of the post status to which a comment is attached.

post_type

A string of the post type to which a comment is attached.

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 on which you can search a comment. Searches the following fields: comment_author, comment_author_email, comment_author_url, comment_author_IP, and comment_content.

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 )

This function 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 )

This function 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 )

This function deletes a comment. By default, it will trash the comment unless you specify 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 )

This function gets 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 )

This function adds 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 = '' )

This function updates 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 = '' )

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

This function 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:

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.

order

ASC or DESC. The default is ASC.

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 of whether they are being used by a post or not.

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.

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.

include

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

number

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

offset

The number by which to offset the terms query.

fields

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

slug

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

hierarchical

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

search

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

name_like

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

pad_counts

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

get

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

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.

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.

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

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

This function 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 to which the term will be added.

$args

An optional array or string of term arguments to be inserted/updated. Available arguments are as follows:

alias_of

An optional string of the slug of which the term will be an alias.

description

An optional string that describes the term.

parent

An optional integer of the parent term ID of which this term will be a child.

slug

An optional string of the slug of the term.

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

This function 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 with which the term is associated.

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

This function deletes a term from the database. If the term is a parent of other terms, 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 with which the term is associated.

$args

An optional array to overwrite term field values.

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

This function 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, all metadata for the given term will be returned.

$single

A Boolean for whether to return a single value. The default is false; thus, 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 updates 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 )

This function 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 used only 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 that, when set to true, will make sure the meta key can be added only once for a given ID.

delete_term_meta( $term_id, $meta_key, $meta_value = '' )

This function deletes term metadata for a provided term ID and matching key. You can also specify a matching meta value if you want to delete only 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 are returned. There are a lot, and we cover all of them in Chapter 5.

$output

An optional string of either names or objects. The default is names, which returns a list of taxonomy names.

$operator

An optional string of either and or or. The default is and, meaning all the arguments passed in must match. If set to or, any 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 any way you see fit. We’ll 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) to which this taxonomy will be tied.

$args

An optional array or string of arguments. There are a lot of these, and we cover all of them in Chapter 5.

get_object_taxonomies( $object, $output = ‘names’ )

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

$object

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

$output

An optional string of either names or objects. The default is names, which returns a list of taxonomy names.

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

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

$object_ids

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

$taxonomies

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

$args

An optional array or string of arguments that change how the data is returned. Here are the arguments you can change:

orderby

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

order

Defaults to ASC; also accepts DESC.

fields

Defaults to all; also accepts ids, names, slugs, and all_with_object_id. This argument dictates what values are returned.

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

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

$object_id

A required integer of the object ID (post ID) to which to relate your terms.

$terms

A required array, integer, or string of the terms you want to add to an object (post).

$taxonomy

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

$append

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