WP-CLI command to list and delete orphan WordPress entities and metadata.
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.
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.
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 git@github.com: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.
Orphan Command requires PHP 7.2 or higher.
Orphan Command requires WordPress 3.3 or higher.
Orphan Command requires WP-CLI 2.5 or higher.
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
- Sample usage:
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
- Sample usage:
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
- Sample usage:
Some commands support additional options that are explained in the following sections.
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
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
- Sample usage:
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.
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
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
- Sample usage:
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
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
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
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
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
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.
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 thewp_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 inwp_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 inwp_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.
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.