Orphan Command

WP-CLI command to list and delete orphan WordPress entities and metadata.

---

Introduction

WordPress offers dedicated APIs that are to be used for CRUD operations on the various core data structures. For example, when you delete a comment via wp_delete_comment( $comment_id, true ), WordPress takes care that all metadata for that comment gets automatically deleted as well. Great!

However, people do not always do what is right—on purpose, or by accident. The reason for that could be that someone deleted entities and/or metadata directly in the DB (instead of using the respective WordPress API to handle that data). This might make sense when you want to reduce a large production or staging database export, and therefore delete (random) posts etc. Or maybe someone only did a partial database import, or partial migration. Over time, you might end up with a database that is full of orphaned entries. Comment metadata for comments that no longer exist, comments for non-existing posts, or revisions of posts that don't exist anymore.

Orphan Command provides a new WP-CLI command, wp orphan, that lets you easily spot orphans, and even delete them, if you want.

Table of Contents

• Installation
  • Composer
  • Manual
• Requirements
  • PHP
  • WordPress
  • WP-CLI
• Commands
  • wp orphan blog meta
  • wp orphan comment
  • wp orphan comment meta
  • wp orphan post
  • wp orphan post meta
  • wp orphan revision
  • wp orphan term meta
  • wp orphan user meta
• Extending Orphan Command
• Frequently Asked Questions

Installation

Composer

Install with Composer:

composer require humanmade/orphan-command

By default, Orphan Command will be installed as WP-CLI package. However, it can also be installed as WordPress plugin, for example, by using a custom install path.

Manual

In case you're not managing your entire site via Composer, you can also clone this repository into your site's plugins directory.

cd /path/to/plugins

git clone [email protected]:humanmade/orphan-command.git

Then, install and set up PHP auto-loading:

cd orphan-command

composer install --prefer-dist --no-dev

Finally, go to your site's Plugins page, and activate Orphan Command.

Requirements

PHP

Orphan Command requires PHP 7.2 or higher.

WordPress

Orphan Command requires WordPress 3.3 or higher.

WP-CLI

Orphan Command requires WP-CLI 2.5 or higher.

Commands

In general, all commands support the following three actions:

• delete: Delete all orphans of the respective entity type.
• list: List all orphans of the respective entity type.
• query: Print the MySQL query to list all orphans of the respective entity type.

By default, the output of list is a comma-separated list of IDs. This can be changed by using the --format option, which supports the following values:

• count: The number of orphans.
• csv: Orphan IDs to be exported into a CSV file.
  • Sample usage: wp orphan post list --format=csv > orphan-posts.csv
• ids: Orphan IDs as a single comma-separated string.
• json: Orphan IDs to be exported into a JSON file.
  • Sample usage: wp orphan post list --format=json > orphan-posts.json
• table: Orphan IDs printed as a table (with a single column only).
• yaml: Orphan IDs to be exported into a YAML file.
  • Sample usage: wp orphan post list --format=yaml > orphan-posts.yaml

Some commands support additional options that are explained in the following sections.

wp orphan blog meta

The wp orphan blog meta command lets you list and delete all blog metadata referencing blogs that don't exist anymore.

List all orphan blog metadata:

wp orphan blog meta list

Delete all orphan blog metadata:

wp orphan blog meta delete

wp orphan comment

The wp orphan comment command lets you list and delete all comments referencing posts that don't exist anymore.

In addition to --format, the wp orphan comment command also supports the following options:

• --type: Comma-separated list of comment type slugs.
  • Sample usage: --type=comment or --type=comment,reaction

List all orphan comments of any comment type:

wp orphan comment list

List all orphan reactions:

wp orphan comment list --type=reaction

Delete all orphan comments of any comment type:

wp orphan comment delete

Delete all orphan default comments only:

wp orphan comment delete --type=comment

Note: Since comments can be nested (i.e., a comment can have a parent comment), an orphan comment could also be a comment referencing another comment that does not exist anymore. This is not what this command does, though. The main reason is that a comment referencing a non-existing post will usually not be exposed to site visitors.

A future version of Orphan Command might allow to also list/delete comments referencing non-existing parent comments.

wp orphan comment meta

The wp orphan comment meta command lets you list and delete all comment metadata referencing comments that don't exist anymore.

List all orphan comment metadata:

wp orphan comment meta list

Delete all orphan comment metadata:

wp orphan comment meta delete

wp orphan post

The wp orphan post command lets you list and delete all posts referencing parent posts that don't exist anymore.

In addition to --format, the wp orphan post command also supports the following options:

• --type: Comma-separated list of post type slugs.
  • Sample usage: --type=post or --type=post,page

List all orphan posts of any post type:

wp orphan post list

List all orphan pages:

wp orphan post list --type=page

Delete all orphan posts of any post type:

wp orphan post delete

Delete all orphan default posts only:

wp orphan post delete --type=post

wp orphan post meta

The wp orphan post meta command lets you list and delete all post metadata referencing posts that don't exist anymore.

List all orphan post metadata:

wp orphan post meta list

Delete all orphan post metadata:

wp orphan post meta delete

wp orphan revision

The wp orphan revision command lets you list and delete all revisions referencing original posts that don't exist anymore.

Revisions are one of the Custom Post Types included in WordPress. Since they are somewhat special in that a revision with a non-existing original (parent) post is of no use whatsoever, and since there is a dedicated API for revisions (e.g., wp_delete_post_revision), Orphan Command provides a custom command for managing revisions.

List all orphan revisions:

wp orphan revision list

Delete all orphan revisions:

wp orphan revision delete

wp orphan term meta

The wp orphan term meta command lets you list and delete all term metadata referencing terms that don't exist anymore.

List all orphan term metadata:

wp orphan term meta list

Delete all orphan term metadata:

wp orphan term meta delete

wp orphan user meta

The wp orphan user meta command lets you list and delete all user metadata referencing users that don't exist anymore.

List all orphan user metadata:

wp orphan user meta list

Delete all orphan user metadata:

wp orphan user meta delete

Extending Orphan Command

If you want to customize or extend the functionality of Orphan Command, you can either extend any of the actual command classes, or you could write your own based on either the Orphan_Command or Orphan_Meta_Command class included in Orphan Command.

All relevant class methods are marked protected or public, so you can redefine or decorate any behavior. For example, the Orphan_Post_Command class enhances the get_query method to inject the post type passed to the command, if any.

Frequently Asked Questions

What about terms?

For terms, there is no clear definition of orphans. An orphan term could be defined in one of several ways:

• An entry in the wp_terms table that is not referenced at all in the wp_term_taxonomy table. (This is most likely not what you want, most of the time.)
• An entry in the wp_term_taxonomy table referencing a non-existing term (i.e., wp_term_taxonomy.term_id does not exist in wp_terms.term_id).
• An entry in the wp_term_taxonomy table referencing a non-existing parent term (i.e., wp_term_taxonomy.parent does not exist in wp_terms.term_id).
• An entry in the wp_term_relationships table referencing a non-existing object. (This would either require the taxonomy, or the object type to then use all registered taxonomies.)

To some extent, this is similar to comments. However, there it is more of an interpretation issue, which is why Orphan Command, by default, defines orphan comments as comments referencing non-existing posts.

A future version of Orphan Command might allow to also list/delete orphan terms.

What about site/network metadata or options?

The terminology in WordPress around blog metadata and options, network options, and site metadata and options is quite confusing!

Some facts:

• Orphan Command supports blog meta.
• Options live in dedicated tables on a per-site basis, which means there cannot be any orphan options.
• While it makes sense to manage site (i.e., network) metadata, Orphan Command currently does not allow for this. The main reason really is to prevent people from accidentally deleting the wrong data.
• A future version of Orphan Command might allow to also list/delete site metadata.

What about use case XYZ?

Yes, there are most certainly several possible use cases around orphan data and metadata missing. However, this is on purpose.

While it may be a good idea to list all users of a specific role that are not added to any site, or to delete all orphan posts with a specific status, this would be out of scope.

Orphan Command provides easy access to tasks that a lot of people might want to perform a lot of times; not more.

That said, you should be able to use existing WP-CLI commands such as wp <entity> list|delete or wp db query to accomplish any of the above examples quite easily.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.