wp-cli / embed-command

Inspects oEmbed providers, clears embed cache, and more.

WP-CLI

WP-CLI is the command-line interface for WordPress. You can update plugins, configure multisite installations and much more, without using a web browser.

Ongoing maintenance is made possible by:

The current stable release is version 2.10.0. For announcements, follow @wpcli on Twitter or sign up for email updates. Check out the roadmap for an overview of what's planned for upcoming releases.

Quick links: Using | Installing | Support | Extending | Contributing | Credits

Using

WP-CLI provides a command-line interface for many actions you might perform in the WordPress admin. For instance, wp plugin install --activate (doc) lets you install and activate a WordPress plugin:

$ wp plugin install user-switching --activate
Installing User Switching (1.0.9)
Downloading installation package from https://downloads.wordpress.org/plugin/user-switching.1.0.9.zip...
Unpacking the package...
Installing the plugin...
Plugin installed successfully.
Activating 'user-switching'...
Plugin 'user-switching' activated.
Success: Installed 1 of 1 plugins.

WP-CLI also includes commands for many things you can't do in the WordPress admin. For example, wp transient delete --all (doc) lets you delete one or all transients:

$ wp transient delete --all
Success: 34 transients deleted from the database.

For a more complete introduction to using WP-CLI, read the Quick Start guide. Or, catch up with shell friends to learn about helpful command line utilities.

Already feel comfortable with the basics? Jump into the complete list of commands for detailed information on managing themes and plugins, importing and exporting data, performing database search-replace operations and more.

Installing

Downloading the Phar file is our recommended installation method for most users. Should you need, see also our documentation on alternative installation methods (Composer, Homebrew, Docker).

Before installing WP-CLI, please make sure your environment meets the minimum requirements:

• UNIX-like environment (OS X, Linux, FreeBSD, Cygwin); limited support in Windows environment
• PHP 5.6 or later
• WordPress 3.7 or later. Versions older than the latest WordPress release may have degraded functionality

Once you've verified requirements, download the wp-cli.phar file using wget or curl:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Next, check the Phar file to verify that it's working:

php wp-cli.phar --info

To use WP-CLI from the command line by typing wp, make the file executable and move it to somewhere in your PATH. For example:

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

If WP-CLI was installed successfully, you should see something like this when you run wp --info:

$ wp --info
OS:     Linux 5.10.60.1-microsoft-standard-WSL2 #1 SMP Wed Aug 25 23:20:18 UTC 2021 x86_64
Shell:  /usr/bin/zsh
PHP binary:     /usr/bin/php8.1
PHP version:    8.1.0
php.ini used:   /etc/php/8.1/cli/php.ini
MySQL binary:   /usr/bin/mysql
MySQL version:  mysql  Ver 8.0.27-0ubuntu0.20.04.1 for Linux on x86_64 ((Ubuntu))
SQL modes:
WP-CLI root dir:        /home/wp-cli/
WP-CLI vendor dir:      /home/wp-cli/vendor
WP_CLI phar path:
WP-CLI packages dir:    /home/wp-cli/.wp-cli/packages/
WP-CLI global config:
WP-CLI project config:  /home/wp-cli/wp-cli.yml
WP-CLI version: 2.10.0

Updating

You can update WP-CLI with wp cli update (doc), or by repeating the installation steps.

If WP-CLI is owned by root or another system user, you'll need to run sudo wp cli update.

Want to live life on the edge? Run wp cli update --nightly to use the latest nightly build of WP-CLI. The nightly build is more or less stable enough for you to use in your development environment, and always includes the latest and greatest WP-CLI features.

Tab completions

WP-CLI also comes with a tab completion script for Bash and ZSH. Just download wp-completion.bash and source it from ~/.bash_profile:

source /FULL/PATH/TO/wp-completion.bash

Don't forget to run source ~/.bash_profile afterwards.

If using zsh for your shell, you may need to load and start bashcompinit before sourcing. Put the following in your .zshrc:

autoload bashcompinit
bashcompinit
source /FULL/PATH/TO/wp-completion.bash

Support

WP-CLI's maintainers and contributors have limited availability to address general support questions. The current version of WP-CLI is the only officially supported version.

When looking for support, please first search for your question in these venues:

• Common issues and their fixes
• WP-CLI handbook
• Open or closed issues in the WP-CLI GitHub organization
• Threads tagged 'WP-CLI' in the WordPress.org support forum
• Questions tagged 'WP-CLI' in the WordPress StackExchange

If you didn't find an answer in one of the venues above, you can:

• Join the #cli channel in the WordPress.org Slack to chat with whomever might be available at the time. This option is best for quick questions.
• Post a new thread in the WordPress.org support forum and tag it 'WP-CLI' so it's seen by the community.

GitHub issues are meant for tracking enhancements to and bugs of existing commands, not general support. Before submitting a bug report, please review our best practices to help ensure your issue is addressed in a timely manner.

Please do not ask support questions on Twitter. Twitter isn't an acceptable venue for support because: 1) it's hard to hold conversations in under 280 characters, and 2) Twitter isn't a place where someone with your same question can search for an answer in a prior conversation.

Remember, libre != gratis; the open source license grants you the freedom to use and modify, but not commitments of other people's time. Please be respectful, and set your expectations accordingly.

Extending

A command is the atomic unit of WP-CLI functionality. wp plugin install (doc) is one command. wp plugin activate (doc) is another.

WP-CLI supports registering any callable class, function, or closure as a command. It reads usage details from the callback's PHPdoc. WP_CLI::add_command() (doc) is used for both internal and third-party command registration.

/**
 * Delete an option from the database.
 *
 * Returns an error if the option didn't exist.
 *
 * ## OPTIONS
 *
 * <key>
 * : Key for the option.
 *
 * ## EXAMPLES
 *
 *     $ wp option delete my_option
 *     Success: Deleted 'my_option' option.
 */
$delete_option_cmd = function( $args ) {
	list( $key ) = $args;

	if ( ! delete_option( $key ) ) {
		WP_CLI::error( "Could not delete '$key' option. Does it exist?" );
	} else {
		WP_CLI::success( "Deleted '$key' option." );
	}
};
WP_CLI::add_command( 'option delete', $delete_option_cmd );

WP-CLI comes with dozens of commands. It's easier than it looks to create a custom WP-CLI command. Read the commands cookbook to learn more. Browse the internal API docs to discover a variety of helpful functions you can use in your custom WP-CLI command.

Contributing

We appreciate you taking the initiative to contribute to WP-CLI. It’s because of you, and the community around you, that WP-CLI is such a great project.

Contributing isn’t limited to just code. We encourage you to contribute in the way that best fits your abilities, by writing tutorials, giving a demo at your local meetup, helping other users with their support questions, or revising our documentation.

Read through our contributing guidelines in the handbook for a thorough introduction to how you can get involved. Following these guidelines helps to communicate that you respect the time of other contributors on the project. In turn, they’ll do their best to reciprocate that respect when working with you, across timezones and around the world.

Leadership

WP-CLI has one project maintainer: schlessera.

On occasion, we grant write access to contributors who have demonstrated, over a period of time, that they are capable and invested in moving the project forward.

Read the governance document in the handbook for more operational details about the project.

Credits

Besides the libraries defined in composer.json, we have used code or ideas from the following projects:

• Drush for... a lot of things
• wpshell for wp shell
• Regenerate Thumbnails for wp media regenerate
• Search-Replace-DB for wp search-replace
• WordPress-CLI-Exporter for wp export
• WordPress-CLI-Importer for wp import
• wordpress-plugin-tests for wp scaffold plugin-tests

embed-command's Issues

Support --all for `wp embed cache clear`

Feature Request

• Yes, I reviewed the contribution guidelines.

Describe your use case and the problem you are facing

There's currently no way of completely clearing the oembed cache. This is for example useful after one has added a oembed_dataparse filter to modify the HTML.

Describe the solution you'd like

I'd propose adding an cache clear-all command.

The quick and dirty version is to run DELETE FROM wp_posts WHERE post_type = 'oembed_cache' and DELETE FROM wp_postmeta WHERE meta_key LIKE '_oembed_%'.

Move command over to new v2 structure

The following changes need to be made to move the command over to the v2 structure:

• Make sure the correct framework is required:

  composer require wp-cli/wp-cli:^2
  

• Require the testing framework as a dev dependency:

  composer require --dev wp-cli/wp-cli-tests:^0
  

• Use the .travis.yml file from wp-cli/wp-cli:

  wget https://raw.githubusercontent.com/wp-cli/wp-cli/master/.travis.yml
  

• Add the default script configuration to Composer file:

    "scripts": {
        "lint": "run-linter-tests",
        "phpcs": "run-phpcs-tests",
        "phpunit": "run-php-unit-tests",
        "behat": "run-behat-tests",
        "prepare-tests": "install-package-tests",
        "test": [
            "@lint",
            "@phpcs",
            "@phpunit",
            "@behat"
        ]
    },
  

• Remove scaffolded binary files:

  git rm bin/install-package-tests.sh
  git rm bin/test.sh
  

• Remove scaffolded Behat setup:

  git rm features/bootstrap/*
  git rm features/extra/*
  git rm features/steps/*
  

• Remove scaffolded Behat tags util script:

  git rm utils/behat-tags.php
  

• Add command packages that are needed for Behat tests as --dev dependencies.
  The following commands are already available, anything else needs to be explicitly required:
  • cli *
  • config *
  • core *
  • eval
  • eval-file
  • help
• Update all dependencies:

  composer update
  

• Optional - Add PHPCS rule set to enable CS & compatibility sniffing:

  wget https://raw.githubusercontent.com/wp-cli/wp-cli/master/phpcs.xml.dist
  

• Run and adapt tests to make sure they all pass:

  composer test
  

Set WP version requirement for find command

wp embed cache find requires WordPress 4.9 because \WP_Embed::find_oembed_post_id() was introduced then.

However, wp embed cache currently requires WordPress 2.9:

embed-command/embed-command.php

Lines 41 to 47 in 41714b8

	WP_CLI::add_command( 'embed cache', '\WP_CLI\Embeds\Cache_Command', array(
	'before_invoke' => function () {
	if ( \WP_CLI\Utils\wp_version_compare( '2.9', '<' ) ) {
	WP_CLI::error( 'Requires WordPress 2.9 or greater.' );
	}
	},
	) );

Note: wp embed cache clear works with WordPress 2.9 as \WP_Embed::delete_oembed_caches() was already present.

Adopt and enforce new `WP_CLI_CS` standard

We have a new PHPCS standard for WP-CLI called WPCliCS (props @jrfnl). It is part of the wp-cli/wp-cli-tests package starting with version v2.1.0.

To adopt & enforce this new standard, the following actions need to be taken for this repository:

• Create a PR that adds a custom ruleset phpcs.xml.dist to the repository

  • Add phpcs.xml.dist file
  • Adapt .distignore to ignore phpcs.xml.dist & phpunit.xml.dist
  • Adapt .gitignore to ignore phpunit.xml, phpcs.xml & .phpcs.xml
  • Require version ^2.1 of the wp-cli/wp-cli-tests as a dev dependency

• Make any required changes to the code that fail the checks from the above ruleset in separate PRs

• Merge thre ruleset once all required changes have been processed and merged

A sample PR for a simple repository can be seen here: https://github.com/wp-cli/maintenance-mode-command/pull/3/files

Related wp-cli/wp-cli#5179

Add tests for cache command

Include oEmbed endpoints introduced by plugins to the `wp embed provider list`

Feature Request

• Yes, I reviewed the contribution guidelines.

Describe your use case and the problem you are facing

Hello,
I noticed the wp embed provider list only contains default WP providers. It would be great if it listed providers added to WP via plugins through wp_oembed_add_provider on the init hook. I tested a few plugins beyond my own and none when added seem to list their providers. Some I tested;
https://en-ca.wordpress.org/plugins/sendtonews-oembed/
https://en-ca.wordpress.org/plugins/jotform-oembed/
https://en-ca.wordpress.org/plugins/github-embed/

In addition to that the wp embed fetch <url> won't work for any oembed URLs of these custom providers.

Describe the solution you'd like

I would love the wp embed functions to cover custom oembed providers installed via plugins to the users WordPress install.

Thank you

Add tests for handler command

See #1.

Add cache command

It would be nice if we could:

• Delete the oembed_cache post for a given URL (+ width / height)
  (\WP_Embed::find_oembed_post_id())
• Delete the oEmbed cache for a given post ID (\WP_Embed::delete_oembed_caches())
• Trigger oEmbed cache for a given post ID (\WP_Embed::cache_oembed())

Add tests for provider command

Perform a final review of the package before tagging the initial release

Before this package lands in WP-CLI as a bundled command, it'd be helpful to do a final review for implementation details (e.g. do we like all argument naming, etc.)

Test broken for `--force-regex` flag

The tests are currently failing for the List oEmbed providers scenario when it tries to test the effects of the --force-regex flag.

It took me a bit of research to understand what's happening. Here's my current understanding:

• oEmbed provider formats can be provided as proper regexes, or in a simplified format that uses an asterisk as a wildcard.
• The --force-regex flag turns the simplified format in a proper regex.
• The test assumed that Core comes with some simplified formats by default. Therefore, to test whether the --force-regex had an effect, it simplifies the logic by just testing whether the result with the flag is different from the result without the flag.
• Now, Core currently only ships with proper regex formats by default, no simplified ones.
• This makes the test fail, as there's nothing to convert, and hence the result with or without the flag is exactly the same.

This means that the test needs to be changed to verify this in a different way. I think the easiest is to filter the list of providers before retrieving them, injecting a simplified format in there and comparing before & after application of the --force-regex flag. If we inject one ourselves, we can even test against the exact regex to be generated.

Automatically rerun failed scenarios

The following changes need to be made:

1. In the .travis.yml file, the - composer behat line in the script: section needs to be changed into the following:

- composer behat || composer behat-rerun

2. In the composer-json file, the requirement on wp-cli/wp-cli-tests needs to be adapted to require at least v2.0.7:

"wp-cli/wp-cli-tests": "^2.0.7"

3. In the composer-json file, the "scripts" section needs to be extended. Immediately after the line "behat": "run-behat-tests",, the following line needs to be inserted:

"behat-rerun": "rerun-behat-tests",

---

Here's an example of how this should look like:

Enable Travis builds for this repo

Error when no cache is found

The current behavior of wp embed cache clear is to output a line and return when no cache is found:

if ( empty( $post_metas ) ) {
	WP_CLI::line( sprintf( 'No metadata available for post with ID %d!', $post_id ) );
	return;
}

However, this is inconsistent with the rest of WP-CLI:

local ➜  wordpress-develop git:(master) wp option delete foo
Error: Could not delete 'foo' option. Does it exist?
local ➜  wordpress-develop git:(master) wp cache delete foo
Error: The object was not deleted.

The correct behavior should be to error when no cache is found.

Add command to list embed handlers

Custom embed handlers can be added using wp_embed_register_handler().

It would be nice if there was a way to list all of them. By default WordPress adds 3 custom handlers already, see wp_maybe_load_embeds().

Add tests for fetch command

Consider renaming `embed provider get` to `embed provider match`

I think the matter makes more sense, and follows wp rewrite list --match=<path>

Are you amenable to the change?