{"id":29150174,"url":"https://github.com/humanmade/orphan-command","last_synced_at":"2025-06-30T23:09:46.093Z","repository":{"id":56987054,"uuid":"328009280","full_name":"humanmade/orphan-command","owner":"humanmade","description":"WP-CLI command to list and delete orphan WordPress entities and metadata.","archived":false,"fork":false,"pushed_at":"2024-12-04T17:15:32.000Z","size":68,"stargazers_count":41,"open_issues_count":1,"forks_count":7,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-06-30T16:14:53.347Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/humanmade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-08T20:49:56.000Z","updated_at":"2025-04-13T04:06:52.000Z","dependencies_parsed_at":"2024-12-04T17:34:09.992Z","dependency_job_id":null,"html_url":"https://github.com/humanmade/orphan-command","commit_stats":{"total_commits":11,"total_committers":1,"mean_commits":11.0,"dds":0.0,"last_synced_commit":"9ca9183782ebb2d2890d8b182fc7be00b3d9ae88"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/humanmade/orphan-command","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2Forphan-command","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2Forphan-command/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2Forphan-command/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2Forphan-command/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/humanmade","download_url":"https://codeload.github.com/humanmade/orphan-command/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanmade%2Forphan-command/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262864258,"owners_count":23376461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-30T23:09:45.034Z","updated_at":"2025-06-30T23:09:46.050Z","avatar_url":"https://github.com/humanmade.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Orphan Command\n\n\u003e WP-CLI command to list and delete orphan WordPress entities and metadata.\n\n----\n\n## Introduction\n\nWordPress offers dedicated APIs that are to be used for CRUD operations on the various core data structures.\nFor 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.\nGreat!\n\nHowever, people do not always do what is right—on purpose, or by accident.\nThe 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).\nThis might make sense when you want to reduce a large production or staging database export, and therefore delete (random) posts etc.\nOr maybe someone only did a partial database import, or partial migration.\nOver time, you might end up with a database that is full of orphaned entries.\nComment metadata for comments that no longer exist, comments for non-existing posts, or revisions of posts that don't exist anymore.\n\nOrphan Command provides a new WP-CLI command, `wp orphan`, that lets you easily spot orphans, and even delete them, if you want.\n\n## Table of Contents\n\n* [Installation](#installation)\n  * [Composer](#composer)\n  * [Manual](#manual)\n* [Requirements](#requirements)\n  * [PHP](#php)\n  * [WordPress](#wordpress)\n  * [WP-CLI](#wp-cli)\n* [Commands](#commands)\n  * [`wp orphan blog meta`](#wp-orphan-blog-meta)\n  * [`wp orphan comment`](#wp-orphan-comment)\n  * [`wp orphan comment meta`](#wp-orphan-comment-meta)\n  * [`wp orphan post`](#wp-orphan-post)\n  * [`wp orphan post meta`](#wp-orphan-post-meta)\n  * [`wp orphan revision`](#wp-orphan-revision)\n  * [`wp orphan term meta`](#wp-orphan-term-meta)\n  * [`wp orphan user meta`](#wp-orphan-user-meta)\n  * [Run all commands](#run-all-commands)\n* [Extending Orphan Command](#extending-orphan-command)\n* [Frequently Asked Questions](#frequently-asked-questions)\n\n## Installation\n\n### Composer\n\nInstall with [Composer](https://getcomposer.org):\n\n```shell\ncomposer require humanmade/orphan-command\n```\n\nBy default, Orphan Command will be installed as WP-CLI package.\nHowever, it **can** also be installed as WordPress plugin, for example, by using [a custom install path](https://github.com/composer/installers#custom-install-paths).\n\n### Manual\n\nIn case you're not managing your entire site via Composer, you can also clone this repository into your site's plugins directory.\n\n```shell\ncd /path/to/plugins\n\ngit clone git@github.com:humanmade/orphan-command.git\n```\n\nThen, install and set up PHP auto-loading:\n\n```shell\ncd orphan-command\n\ncomposer install --prefer-dist --no-dev\n```\n\nFinally, go to your site's Plugins page, and activate Orphan Command.\n\n## Requirements\n\n### PHP\n\nOrphan Command **requires PHP 7.2 or higher**.\n\n### WordPress\n\nOrphan Command **requires WordPress 3.3 or higher**.\n\n### WP-CLI\n\nOrphan Command **requires WP-CLI 2.5 or higher**.\n\n## Commands\n\nIn general, all commands support the following three **actions**:\n\n* **`delete`**: Delete all orphans of the respective entity type.\n* **`list`**: List all orphans of the respective entity type.\n* **`query`**: Print the MySQL query to list all orphans of the respective entity type.\n\nBy default, the output of `list` is a comma-separated list of IDs.\nThis can be changed by using the `--format` option, which supports the following values:\n\n* **`count`**: The number of orphans.\n* **`csv`**: Orphan IDs to be exported into a CSV file.\n  * Sample usage: `wp orphan post list --format=csv \u003e orphan-posts.csv`\n* **`ids`**: Orphan IDs as a single comma-separated string.\n* **`json`**: Orphan IDs to be exported into a JSON file.\n\t* Sample usage: `wp orphan post list --format=json \u003e orphan-posts.json`\n* **`table`**: Orphan IDs printed as a table (with a single column only).\n* **`yaml`**: Orphan IDs to be exported into a YAML file.\n\t* Sample usage: `wp orphan post list --format=yaml \u003e orphan-posts.yaml`\n\nSome commands support additional options that are explained in the following sections.\n\n### `wp orphan blog meta`\n\nThe `wp orphan blog meta` command lets you list and delete all **blog metadata** referencing **blogs** that don't exist anymore.\n\n**List all orphan blog metadata:**\n\n```shell\nwp orphan blog meta list\n```\n\n**Delete all orphan blog metadata:**\n\n```shell\nwp orphan blog meta delete\n```\n\n### `wp orphan comment`\n\nThe `wp orphan comment` command lets you list and delete all **comments** referencing **posts** that don't exist anymore.\n\nIn addition to `--format`, the `wp orphan comment` command also supports the following options:\n\n* **`--type`**: Comma-separated list of comment type slugs.\n  * Sample usage: `--type=comment` or `--type=comment,reaction`\n\n**List all orphan comments of any comment type:**\n\n```shell\nwp orphan comment list\n```\n\n**List all orphan reactions:**\n\n```shell\nwp orphan comment list --type=reaction\n```\n\n**Delete all orphan comments of any comment type:**\n\n```shell\nwp orphan comment delete\n```\n\n**Delete all orphan default comments only:**\n\n```shell\nwp orphan comment delete --type=comment\n```\n\n**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.\nThis is **not** what this command does, though.\nThe main reason is that a comment referencing a non-existing post will usually not be exposed to site visitors.\n\nA future version of Orphan Command might allow to also list/delete comments referencing non-existing parent comments.\n\n### `wp orphan comment meta`\n\nThe `wp orphan comment meta` command lets you list and delete all **comment metadata** referencing **comments** that don't exist anymore.\n\n**List all orphan comment metadata:**\n\n```shell\nwp orphan comment meta list\n```\n\n**Delete all orphan comment metadata:**\n\n```shell\nwp orphan comment meta delete\n```\n\n### `wp orphan post`\n\nThe `wp orphan post` command lets you list and delete all **posts** referencing parent **posts** that don't exist anymore.\n\nIn addition to `--format`, the `wp orphan post` command also supports the following options:\n\n* **`--type`**: Comma-separated list of post type slugs.\n\t* Sample usage: `--type=post` or `--type=post,page`\n\n**List all orphan posts of any post type:**\n\n```shell\nwp orphan post list\n```\n\n**List all orphan pages:**\n\n```shell\nwp orphan post list --type=page\n```\n\n**Delete all orphan posts of any post type:**\n\n```shell\nwp orphan post delete\n```\n\n**Delete all orphan default posts only:**\n\n```shell\nwp orphan post delete --type=post\n```\n\n### `wp orphan post meta`\n\nThe `wp orphan post meta` command lets you list and delete all **post metadata** referencing **posts** that don't exist anymore.\n\n**List all orphan post metadata:**\n\n```shell\nwp orphan post meta list\n```\n\n**Delete all orphan post metadata:**\n\n```shell\nwp orphan post meta delete\n```\n\n### `wp orphan revision`\n\nThe `wp orphan revision` command lets you list and delete all **revisions** referencing original **posts** that don't exist anymore.\n\nRevisions are one of the Custom Post Types included in WordPress.\nSince 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.\n\n**List all orphan revisions:**\n\n```shell\nwp orphan revision list\n```\n\n**Delete all orphan revisions:**\n\n```shell\nwp orphan revision delete\n```\n\n### `wp orphan term meta`\n\nThe `wp orphan term meta` command lets you list and delete all **term metadata** referencing **terms** that don't exist anymore.\n\n**List all orphan term metadata:**\n\n```shell\nwp orphan term meta list\n```\n\n**Delete all orphan term metadata:**\n\n```shell\nwp orphan term meta delete\n```\n\n### `wp orphan user meta`\n\nThe `wp orphan user meta` command lets you list and delete all **user metadata** referencing **users** that don't exist anymore.\n\n**List all orphan user metadata:**\n\n```shell\nwp orphan user meta list\n```\n\n**Delete all orphan user metadata:**\n\n```shell\nwp orphan user meta delete\n```\n\n### Run all commands\n\n```shell\nwp core is-installed --network \u0026\u0026 wp orphan blog meta list\nwp orphan comment list\nwp orphan post list\nwp orphan post meta list\nwp orphan revision list\nwp orphan term meta list\nwp orphan user meta list\n```\n\n## Extending Orphan Command\n\nIf 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.\n\nAll relevant class methods are marked `protected` or `public`, so you can redefine or decorate any behavior.\nFor example, the `Orphan_Post_Command` class enhances the `get_query` method to inject the post type passed to the command, if any.\n\n## Frequently Asked Questions\n\n\u003e **What about terms?**\n\nFor terms, there is no clear definition of orphans.\nAn orphan term could be defined in one of several ways:\n\n* 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.)\n* 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`).\n* 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`).\n* 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.)\n\nTo some extent, this is similar to comments.\nHowever, there it is more of an interpretation issue, which is why Orphan Command, by default, defines orphan comments as comments referencing non-existing posts.\n\nA future version of Orphan Command might allow to also list/delete orphan terms.\n\n\u003e **What about site/network metadata or options?**\n\nThe terminology in WordPress around blog metadata and options, network options, and site metadata and options is quite confusing!\n\nSome facts:\n\n* Orphan Command supports blog meta.\n* Options live in dedicated tables on a per-site basis, which means there cannot be any orphan options.\n* 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.\n* A future version of Orphan Command might allow to also list/delete site metadata.\n\n\u003e **What about use case XYZ?**\n\nYes, there are most certainly several possible use cases around orphan data and metadata missing.\nHowever, this is on purpose.\n\nWhile 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.\n\nOrphan Command provides easy access to tasks that a lot of people might want to perform a lot of times; not more.\n\nThat said, you should be able to use existing WP-CLI commands such as `wp \u003centity\u003e list|delete` or `wp db query` to accomplish any of the above examples quite easily.\n\n## License\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanmade%2Forphan-command","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumanmade%2Forphan-command","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanmade%2Forphan-command/lists"}