Version 1.5.0 released

It’s release day again!

We’re excited to bring you WP-CLI v1.5.0, with a total of 279 merged pull requests since v1.4.1 in November 2017.

This release was led by the tireless Martin Burke (@gitlost), who made sure no bug went unsquashed and no edge case untested.

New committer

  • Pascal (@swissspidy) lives in Zurich, Switzerland. Amongst other contributions, he’s been doing the hard work on the embed family of commands.

Plugin checksum verification

WP-CLI can now verify the integrity of your installed plugins through the new plugin verify-checksums command (in addition to the already existing core verify-checksums command). [#15], [#26]

# Verify the files of all installed plugins against their official checksums.
$ wp plugin verify-checksums --all
| plugin_name | file          | message                 |
| gutenberg   | backdoor.php  | File was added          |
| gutenberg   | gutenberg.php | Checksum does not match |
Error: Only verified 1 of 2 plugins (1 failed).

Note: This is a first iteration on this functionality, and it still comes with a few limitations:

  • It only works for plugins that are hosted in the official plugin repository.
  • It only works for recent versions of these plugins, as we haven’t yet rolled out code on the backend to retroactively generate the checksums for older versions.

Please keep these limitations in mind when you plan on using this new command.

As we will further iterate on this project to allow verification of all free themes from the themes repository, and later hopefully also third-party plugins/themes, we welcome any and all feedback to the current implementation.

WordPress config file manipulations

Managing your wp-config.php file just got a whole lot easier! Not only did we improve the config get and included both a config has and a filterable config list command… No, we finally bring you full WordPress Config file manipulation with the new config set and config delete commands. [#42], [#44]

# Get the table_prefix as defined in wp-config.php file.
$ wp config get table_prefix

# Check whether the DB_PASSWORD constant exists in the wp-config.php file.
$ wp config has DB_PASSWORD
(return exit code)

# List only database user and password from wp-config.php file.
$ wp config list DB_USER DB_PASSWORD --strict
| key         | value | type     |
| DB_USER     | root  | constant |
| DB_PASSWORD | root  | constant |

Big thanks to @fjarrett for the awesome work on the wp-cli/wp-config-transformer package that powers the changes to wp-config.php.

oEmbed management

The new embed command allows you to inspect and manipulate the oEmbed object, for instance you can clear the cached values for a particular post with

$ wp embed cache clear 123
Success: Cleared oEmbed cache.

or reset the cached values with

$ wp embed cache trigger 123
Success: Caching triggered!

You can find out what the embed HTML is for a URL with fetch:

$ wp embed fetch

or look at exactly what the provider is returning by using the --raw option:

$ wp embed fetch --raw
{"height":295,"thumbnail_height":360,"provider_name":"YouTube","provider_url":"https:\/\/\/","author_name":"RickAstleyVEVO","width":525,"version":"1.0","thumbnail_width":480,"author_url":"https:\/\/\/user\/RickAstleyVEVO","html":"<iframe width=\"525\" height=\"295\" src=\"https:\/\/\/embed\/dQw4w9WgXcQ?feature=oembed\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen><\/iframe>","title":"Rick Astley - Never Gonna Give You Up","thumbnail_url":"https:\/\/\/vi\/dQw4w9WgXcQ\/hqdefault.jpg","type":"video"}

And lots more!

Array argument support (post meta for now)

The --meta_input option of the post create and post update commands now accepts JSON-formatted arrays, so you can add or update your post and its meta in one go:

$ wp post create --post_title='Title' --post_content='Content.' --meta_input='{"key1":"value1","key2":"value2"}
Success: Created post 123.

A great time saver, as you’d previously have to run three separate commands to get the same result.

This rather innocuous change means we can finally accept associative arrays as parameter arguments, through the use of this JSON syntax. The --meta_input parameter is probably just the first of many more to come. Let us know if you can think of other potential use cases for this syntax.

Everything else in v1.5.0

Backward Compatibility breaks

Please note that a framework change [#4624] alters the behavior of table filter arguments to the db search, db tables and search-replace commands.

The table filter arguments now:

  • Respect registered wpdb tables when given a table filter and not given the --all-tables-with-prefix or the --all-tables option.
  • Do not ignore the --scope option when given the --network option.
  • Tables are always returned in sorted order.

Also note that option list no longer shows transients by default [#127].

New and notable

  • user reset-password: Resets a user’s password [#119].
  • Command descriptions now follow the WordPress norm and use the third person singular, thanks DrewAPicture !

Command improvements

  • cli info:
    • Displays OS & shell information [#4604], [#4610].
  • core download:
    • Skips cache also when ZIP URL is 'http://' to nightly build [#44].
  • core update:
    • Ignores SSL trigger_error in WP get_core_checksums() [#48].
    • Strips wp-content/ using ZipArchive to always allow --skip-content [#59].
  • core verify-checksums
    • Warns when files prefixed with wp- are included in WordPress root [#28].
  • db *:
    • Uses new after_wp_config_load hook for early invocation of db commands [#57].
  • db check/cli/create/drop/export/import/optimize/query/repair/reset:
    • Adds --dbuser and --dbpass options to all the heightened privilege commands, and extra arguments option to check, optimize and repair [#75].
  • db search:
    • NOTE: See Backward Compatibility breaks above on treatment of table filter arguments [#4624].
  • db size:
    • Ensures default value of --size_format=<format> argument is always bytes [#69].
    • Includes support for TB and GB database size formats [#81].
  • db tables:
    • NOTE: See Backward Compatibility breaks above on treatment of table filter arguments [#4624].
  • export:
    • Adds --with_attachments option to force including attachments when --post__in has been specified. [#16].
  • media image-size:
    • Adds size ratio to output [#58], [#59].
  • media regenerate:
    • Does not throw PHP warning if no sizes metadata [#61].
  • option get:
    • Display error message if option doesn’t exist [#126].
  • option list:
    • Defaults to not showing transients [#127].
  • package *:
    • Caters for mixed-case package names [#49], [#50].
    • Adds GITHUB_TOKEN and COMPOSER_AUTH handling [#47].
  • package browse/list:
    • Catches exception if browsing/listing packages and Composer can’t access a repository [#60].
  • package install/uninstall:
    • Reverts composer.json on memory limit error [#64].
  • package install:
    • Retrieves package name from correct branch [#65].
  • plugin install:
    • Uses the Github project name as the plugin directory for Github archive URLs [#81]
  • post create/update:
    • Adds the ability to add multiple metadata by passing JSON-formatted arrays to --meta_input [#133], [#138].
  • post create:
    • Accepts category slugs in --post_category and checks if incorrect ids or slugs given [#129].
  • post delete:
    • Corrects delete message [#124].
  • post generate:
    • Adds support for generating a specific post_title [#94].
  • scaffold block:
    • Scaffolds a basic Gutenberg block for a plugin or theme [#96].
    • Adds inline documentation based on the Gutenberg Handbook, generates style.css, supports latest supportsHtml API, WordPress Coding Standards fixes [#107].
    • Updates PHP template to latest recommended method [#111].
  • scaffold child-theme:
    • Generates WordPress Coding Standards compliant code [#117].
  • scaffold plugin:
    • Adds a default task to scaffolded Gruntfile.js [#87].
    • Generates WordPress Coding Standards compliant code [#120].
  • scaffold plugin-tests:
    • Uses Composer to determine which PHPUnit version to install, instead of keying off Travis environment variable [#75].
    • Adds XML declaration to phpunit.xml.dist [#78].
    • Uses updated error message in bootstrap.php [#90].
    • Removes Composer vendor directory from Travis CI cache [#99].
  • scaffold post-type:
    • Trims dashicon- from dashicon argument to prevent duplicated string [#70].
    • Refreshes scaffolded post type labels [#84].
    • Generates WordPress Coding Standards compliant code [#110].
  • scaffold taxonomy:
    • Adds term_updated_messages to scaffolded taxonomies [#82].
    • Generates WordPress Coding Standards compliant code [#112].
  • scaffold theme-tests:
    • Adds theme_root filter to tests/bootstrap.php to make sure theme’s functions.php gets loaded [#116].
  • search-replace:
    • NOTE: See Backward Compatibility breaks above on treatment of table filter arguments [#4624].
    • Adds --skip-tables=<tables> argument to exclude specific tables [#48].
    • Disables report tables without index when using --report-change-only [#54].
    • General improvements to reporting, including disabling table display when no tables to output [#57].
    • Fixes not quoting non-integer primary keys [#59], [#63].
  • user remove-caps:
    • Errors if the cap doesn’t exist or is inherited from a role [#125].

Framework enhancements

  • Improves warning when can’t create cache directory [#4456].
  • Allows method @when to override class @when [#4458].
  • Pulls links from help texts into footnotes [#4465].
  • Implements command namespaces [#4470].
  • Generates get_site_url() without set_url_scheme() [#4473].
  • Introduces new after_wp_config_load hook (used to invoke wp db * early) [#4488].
  • Gets the hostname automatically with vagrant ssh-config [#4495].
  • Indicates other WP installs in db when install isn’t found [#4476].
  • Permits use of php7.1-mysql in Debian build [#4511].
  • Supports 'longdesc' as command argument when registering a command [#4513], [#4636].
  • Improves Extractor error messages [#4510].
  • Runs wp cache flush and wp search-replace on multisite even when site isn’t found [#4527].
  • Fixes prompting on Windows git/cygwin bash [#4547].
  • Doesn’t show 'sitecategories' table unless global terms are enabled [#4552].
  • Ensures late-registered registered commands appear in usage [#4564].
  • Improves Windows compatibility on invoking a proc and using [#4572], [#4595].
  • Uses a softer PHP requirement in RPM build [#4571].
  • Only provides dictionary-based suggestions if they produce valid options [#4590].
  • Adds interval argument to make_progress_bar() [#4603].
  • Adds Utils\esc_like() polyfill of wpdb version [#4612].
  • Deals correctly with wildcards in wp_get_table_names() (see Backward Compatibility breaks above) [#4624].
  • Adds shell array parsing helper [#4623], [#4635].
  • Checks for readability of WordPress core files [#4626].
  • Adds some more suggestions for mistyped arguments [#4577].

Contributors to this release (39 total)
ahmadawais, BhargavBhandari90, danielbachhuber, davidbhayes, DrewAPicture, drzrafecotechie, emgk, eriktorsner, fjarrett, gitlost, grantpalin, gziolo, inetbiz, kirtangajjar, LC43, lukecav, marcochiesi, marksabbath, miya0001, mm-pagely, neonardo1, ntwb, ocean90, playmonorkialashaki, runofthemill, ryotsun, sagarprajapati, schlessera, Shelob9, ssnepenthe, swissspidy, szepeviktor, terriann, thrijith, vbaranovskiy-plesk, vigilanteweb, websupporter

#cli, #release, #v1-5-0

How should we embark upon new feature development?

Update July 11th:  We’re having a follow-up discussion in Slack (#cli channel) next Tuesday, July 18th at 16:00 UTC (9 am PT, 12 pm ET). Our goal is to get to the point where we have a rough sense of the path forward.

The WP-CLI package index is a directory of user-maintained commands. For a long while now, submissions have been put on hold. I’d like to unblock new feature development, but we first need to address the conundrum before us.

Originally, the package index was created as space for developers to share custom WP-CLI commands. A developer would write a new command, submit it to the index, and the command would be displayed on the website for others to discover. The command would also become installable through wp package install.

However, the package index suffered from the same problems that plague the WordPress plugin directory:

  • After a while, submitted packages are no longer actively maintained. Eventually, they become abandoned. Maintaining packages is commonly a solo-author activity when it needs to be a multi-author activity to be sustainable.
  • Over time, different implementations are submitted of the same feature. I actually ended up pausing acceptance of new packages when four of five submissions were near duplicates of existing packages.

Just like WordPress, the end-user experience is the priority for the WP-CLI project. It’s a bad user experience to have to choose from multiple poorly-maintained implementations of the same feature. It’s a much better user experience to have one high-quality, well-documented solution to a specific problem.

Not only that, but we’d much rather focus contributor effort towards maintaining common packages, rather than have spread amongst a number of one-off individual implementations. The maintenance burden of the command ecosystem is much easier to manage when somewhat centralized, than spread amongst numerous small projects.

Given what we know at the moment, our priorities are the following:

  • Provide an outstanding user experience.
  • Have a streamlined pipeline for adding needed functionality.
  • Be able to maintain and adopt packages to keep them available for the community.
  • Keep maintenance effort in check.
  • Encourage contributions in many forms.

What we want to avoid is any of the following:

  • Outdated / abandoned packages being endorsed to users.
  • Duplicated functionality causing confusion.
  • Maintainers being a bottleneck.

We were fortunate enough to be able to discuss this problem during the WordPress Community Summit. Brainstorming with other community members, we were able to identify three possible approaches so far:

A. No package index, but community-driven feature development.

Ideas are collected within the wp-cli/ideas repository or a similar tool. The ones that get the most traction or votes get included in the roadmap to build as new official packages.

Observations from the discussion:

  • Solves problems noted above by having WP-CLI be the sole source of endorsed packages.
  • Not practically feasible in terms of team effort.
  • Too slow to make progress and act on requirements.

B. Submission proposal that is coupled to precise quality and maintenance requirements.

To get included in the package index, you need not only ensure high quality but also commit to regular maintenance.

Observations from the discussion:

  • Adds strict procedures and requirements to the current package index.
  • Could include the provision that abandoning a package will cause it to be adopted by the WP-CLI project itself.
  • Growing team effort that will become problematic over time.

C. Two-tiered system with both an “official” index and a “community” index.

The “official” index is controlled and endorsed by the WP-CLI team, while the free-for-all “community” index will include a notice that use of these packages is at everyone’s own risk.

Observations from the discussion:

  • Completely open directory is valuable for innovation.
  • Submissions could default to the “community” index, and packages then need to submit a proposal to get “promoted” to the “official” one if they meet the requirements.
  • Adds cognitive overhead by having two sources of packages, with potentially two different mechanisms of installation.

None of these three approaches is a perfect fit for our priorities above, they just provide differing sets of benefits and drawbacks. In addition, we are quite sure there are other models out there that can potentially be adapted to meet our needs.

This is where we are hoping for valuable input from the community. There are some specific decisions we need to make:

  • What process should we follow for new feature development?
  • Is it possible to adapt the existing package index to help us achieve our priorities?
  • If yes, what form should it take?
  • If no, is there another mechanism might we employ?
  • What should we do with the pending submitted packages?

Have some perspective to share or process to suggest? Know of other projects that we can model our approach on? We’d appreciate your comment on this post, especially if it also includes pros, cons, expected maintenance burden effort, etc.

Please keep in mind that we may make a decision you don’t agree with. Our decision will be biased to reflect the priorities of the project.

We greatly welcome your input to the decision-making process, though, particularly to the degree that it’s respectful, introduces perspective we may not have considered, and represents a great deal of thought and consideration.