WP-CLI is the official command line tool for interacting with and managing your WordPress sites.
Want to help make it better? Check out our Contributing guide for an introduction, or “good first issues” for your first pull request.
“Contributing to WP-CLI” was the second of two discussions we held at the Community Summit. For notes from the first, see details embedded in the feature development post.
We began the conversation by giving an overview to the current contribution process. Notably:
From the introduction, the conversation turned more free-form. In no particular order, some highlights:
Thanks to everyone who participated!
Want to submit your first pull request to WP-CLI? We’ve identified a few good first issues for you to get your feet wet:
tee in “Save command output” section of Shell friendstee is a useful utility if you want to capture and display output from a command. For this issue, you’ll get to explore how tee works, and share your learnings in the WP-CLI documentation.wp core multisite-install is to modify wp-config.php to include the multisite constants. It would be helpful to have a --skip-config flag to support skipping this behavior.wp config getwp config get is a new command that shows you globals and constants defined in wp-config.php. It would be helpful if it also showed you files included from wp-config.php so, for instance, you could see which environment-specific configuration file was being included.--all flag for wp post term delete--all flag to do so.Read through the contributing guide for details on how to get started, or join us in the #cli channel with any questions you might have.
This week’s WP-CLI office hours had been a special “feature development and the package index” edition, as was announced in the previous post: How should we embark upon new feature development?
Here’s a link to the chat log. The attendees were: @danielbachhuber, @dave_navarro, @grapplerulrich, @miyauchi, @modernnerd, @nerrad, @schlessera.
We started with a quick recap of what the different approaches were that we already presented in the previous post:
Most of the discussion that immediately followed revolved around approach C, and what the best technical implementation of such a system would be.
It is clear that this involves a lot of work on the infrastructure that supports these different tiers. Some existing package indexes/managers were mentioned as a comparison: npm/packagist in terms of being a similar CLI tool, but also rpm as a package system that allows arbitrary repositories to be added as a package source.
When I told the group that we were considering going with approach A for now, while targeting some form of C as a longer-term goal, people seemed to agree in principle. The discussion that followed then made it rather clear that we are discussing two distinct problems and trying to find a solution for both at the same time:
This lead the group to reason about these two problems separately, and ultimately allowed us to formulate the following plan:
vendor/package will default to the corresponding GitHub repository.wp-cli GitHub organization.We will now start work on investigating this specific approach. Expect several issues to pop up on GitHub related to this.
This also means that the actual feature development will now be handled as was described for approach A. Ideas are collected within the wp-cli/ideas repository. The ones that get the most traction get included in the roadmap to build as new official packages, which means they will be part of the wp-cli GitHub organization. We will more clearly define our policies surrounding this process and include them in the contributor’s documentation.
We are still very grateful about any feedback we can get about this important aspect of WP-CLI, so don’t hesitate to share your thoughts in the comments below!
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:
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:
What we want to avoid is any of the following:
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:
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:
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:
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:
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.
On Thursday, June 15th, WordCamp Europe 2017 in Paris had the very first Contributor Day where WP-CLI was officially represented as a separate team that people could contribute to.
On the official WordCampe Europe 2017 website, you can find the organization information that was sent to the attendees.
To get a sense of the event, you can visit the Contributor Day album by Olivier Gobet on Flicker.
Over the course of the day, there were a dozen contributors joining the team to work on WP-CLI. Considering that the command line is not a mainstream topic in the WordPress world and that the team has only recently been officially added, we can consider this a success in itself.
After a small introductory round, it was clear that all of the contributors had prior experience with WP-CLI, either making regular use of it or even having already done development against it. This meant that we could skip the basic introduction and immediately dive into a more technical analysis of how the tool and its packages are architected.
We then split the team into two groups, depending on what the individual contributors preferred to work on: one group focussing on commands, and the other group focussing on the framework itself. The main difference between these two is the skill set needed: for the commands, the development closely mimics regular WordPress development, whereas for the framework, WordPress has not been loaded yet and the development is closer to pure PHP console development.
Once we’ve split up the teams, we went through the Good First Issues page, and everyone was quickly able to find something to work on. This was a definite success, as I’ve often attended Contributor Days where some people were lost during the entire day, not really knowing where to focus their efforts on.
The fact that the code is managed through git and GitHub was well received by the contributors, as it made issue discovery easier and allowed for faster feedback cycles.
What made everything run smoothly as well was the fact that the contributors to join this team were mostly of above average technical proficiency. This meant that technical issues that were encountered were quickly taken care of, with people helping each other out, and there has even been an impromptu introductory session to test-driven development (TDD) by one of the contributors as well.
We are still facing some issues with the contributor onboarding process, mostly around documentation and testing.
One problem we faced was the fact that it is not obvious for most contributors that they need to create a test database first before being able to run the functional tests. Documentation could be clearer on this step, and we might even provide a hint in the console when the tests are being run without access to a database.
Another source of confusion was that there are different conventions (workflows, file names, …) of how to proceed depending on whether you want to work on a command, or the framework itself. This should all be streamlined so that every single wp-cli package will have the exact same requirements and support the same workflows.
Big thanks to the organizing team of WordCamp Europe in Paris for the additional efforts they went through in order to find a space for our brand-new team! Although we hadn’t been included in the original planning (when they didn’t yet know about the WP-CLI team), we had a flawless experience and felt welcome as an integral part of the WordPress project.
Happy release day!
After 325 merged pull requests, we’re excited to bring you WP-CLI v1.2.0, chock full of enhancements, bug fixes… and a bootstrap refactor.
But first…
Coming soon to a laptop near you:
Thanks to Chris Wallace and the crew at Lift UX for their work, as well as everyone who responded to my pings about feedback.
We’ve split up the project!
The main wp-cli/wp-cli repository now only contains the framework itself. All of the bundled commands can be found in separate repositories. For instance, the wp cache * series of commands are now located at github.com/wp-cli/cache-command.
This abstraction provides a few benefits:
For those using WP-CLI via Composer, you can contribute improvements to packages as you’d normally contribute to Composer dependencies. Use composer install --prefer-source to install dependencies as Git clones.
For those using WP-CLI via Phar downloadable, you can contribute improvements by installing the package (which will override the bundled version). For instance, with the cache command, this is:
$ wp package install git@github.com:wp-cli/cache-command.git
$ cd $(wp package path wp-cli/cache-command)
Check out #3728 for the original history. For a better understanding of the underlying infrastructure, read Alain’s posts about the new bootstrapping mechanism, managing command dependencies and dependency resolution mechanisms.
The investments in package abstraction and the bootstrap process are a part of our larger effort to improve the contribution workflow.
Ultimately, we’d like to make contributing to the project:
For new contributors, we now have a Good First Issues page:
For committers, we now have the beginnings of a customized dashboard:
Work on the contribution workflow is an on-going process. We’ve barely scratched the surface.
Expect to see lots efforts on some of the key areas that make up the contributor experience:
Join the conversation during our weekly office hours, Tuesday, April 25 at 16:00 UTC, or at WordCamp Europe.
Want to sanity check your wp-config.php? Use wp config get list constants and globals defined in wp-config.php [#9]
$ wp config get --fields=key,value
+--------------------+-----------------+
| key | value |
+--------------------+-----------------+
| table_prefix | wp_ |
Don’t want to remember where wp-config.php is on your filesystem? Use wp config path to get the path to wp-config.php [#7]
# Edit wp-config.php in your editor.
$ vim $(wp config path)
Curious how much your database weighs? Run wp db size to get the size of the database and its tables [#16]
$ wp db size --tables
+-----------------------+--------+
| Name | Size |
+-----------------------+--------+
| wp_users | 64 KB |
| wp_usermeta | 48 KB |
| wp_posts | 4 MB |
| wp_comments | 2 MB |
| wp_links | 32 KB |
| wp_options | 1 MB |
| wp_postmeta | 8 MB |
| wp_terms | 416 KB |
| wp_term_taxonomy | 336 KB |
| wp_term_relationships | 736 KB |
| wp_termmeta | 48 KB |
| wp_commentmeta | 2 MB |
+-----------------------+--------+
Command improvements
wp core install:
wp cron event run:
$args are passed with --due-now [#11].wp db *:
/usr/bin/env mysql instead of mysql when calling MySQL executable [#14].wp db (drop|reset):
wp db drop and wp db reset commands [#12].wp db export:
--exclude_tables=<tables> option when exporting a database [#20].wp db import:
wp language core install:
--activate flag even when language is already installed [#3851].wp language core (install|uninstall)
wp media import:
wp media regenerate:
wp menu location assign:
wp package *:
get_composer_json_path() under Windows [#11].wp plugin install:
wp plugin update:
wp (plugin|theme) update:
--exclude=<name> argument to exclude plugins or themes from updating [#16].wp post term *:
wp rewrite *:
--skip-plugins or --skip-themes, because rewrites may be missing [#3917].wp scaffold (child-theme|_s):
.editorconfig based on WordPress coding standards [#3902].wp scaffold plugin-tests
wp server:
wp user create:
wp user import-csv:
Framework enhancements
before_add_command:<parent command> lets you check runtime requirements before adding a commandafter_add_command:<parent command> lets you depend on a specific parent command before triggering a given functionality [#4033]RUN_DIR deletion, safely, to ensure Behat doesn’t hang on cleanup [#4112].@require-wp tags when WP_VERSION isn’t ‘latest’ or ‘nightly’ to ensure full test suite is run in these contexts [#4055].Contributors to this release (43 total): 1naveengiri, aaemnnosttv, afragen, balbuf, behzod, carl-alberto, CodeProKid, danielbachhuber, davgothic, diablodale, diggy, dnmvisser, fjarrett, flaskboy, geekoun, gitlost, hason, JayWood, jeremyfrady, ka7, kcarwilemiller, lichtscheu, mbovel, MiteshShah, miya0001, Nikschavan, ntwb, petenelson, rahul3883, raquelmsmith, Rarst, ryanshoover, schlessera, Sidsector9, SosyalAlkolik, ssnepenthe, Steveorevo, tfrommen, tillkruss, timdream, trepmal, wp-make-coffee, zacksheppard
The upcoming 1.2.0 release of WP-CLI will include a refactored bootstrapping flow that provides a more flexible way of loading the framework itself and setting everything up. This refactoring is needed to allow for some of the expected functionality to work in conjunction with bundled commands being provided through external packages and the general use of autoloading (Issue #3850 | Pull Request #3872).
In general terms, bootstrapping code is code that is not part of the actual logic meant to solve the problem, but rather code that is needed to prepare the environment so that the actual logic is able to run.
This usually means locating files and folders, setting constants, reading configuration, etc…
The current stable release has all bundled commands be part of the wp-cli/wp-cli repository as a big monolithic package. This has several drawbacks, like having a huge testsuite be run for every single change to the framework (and waiting for 2 hours on feedback from the tests), and coupling the update frequency of these commands to the framework itself (making a quick hotfix to one single command difficult).
To get around these problems, we’ve extracted all of the commands into separate repositories that exist on their own, come with their own testsuites and have their own release cycles. To be able to profit from these decoupled release cycles, though, you need to be able to update a bundled command independently of the framework. This means that the act of loading the framework needs to be strictly separate to the act of loading the bundled commands.
The new bootstrapping mechanism separates the procedural list of load operations into a set of isolated steps for which the order can be freely defined.
After defining some constants to locate the needed files, WP-CLI will load the bootstrap component and call the WP_CLI\bootstrap() function (source).
This function defines a list of bootstrapping steps that will then be loaded and processed in the provided order (source).
The list of bootstrapping steps is a basic array of fully qualified class names (source). Each of the classes implements the WP_CLI\Bootstrap\BootstrapStep interface, meaning that it provides a process( BootstrapState $state ) method (source).
When the process( BootstrapState $state ) method of a WP_CLI\Bootstrap\BootstrapStep object is being called, that object will execute its tasks to take care of its responsibilities and then return the (potentially modified) $state.
Each step works in isolation, so that they can be added/removed/rearranged as needed.
The current code does not allow for the list of steps to be modified from outside code yet, while we collect data and feedback about this new mechanism. However, if we feel confident about the reliability and usefulness, we might open up the array of steps for modification with a later release. If you feel you have a valid use case for such modifications to the bootstrapping process, please let us know!
The WP_CLI\Bootstrap\BootstrapState object that is being passed from one step to the next is a very basic key-value store. It currently only knows about one key, BootstrapState::IS_PROTECTED_COMMAND, which is used to skip certain steps when dealing with protected commands (source).
The only protected command right now is wp cli info (source). This protection means that loading of external command packages and --required files is skipped, so that the command can not be overridden. In this way, you can always be sure that the wp cli info command is indeed the one provided by the framework.
The current implementation uses a custom Composer plugin to split the Composer autoloader provided by the wp-cli/wp-cli package into two separate autoloaders (source). This is needed to allow autoloaders from external command packages to take precedence over the bundled commands. Otherwise, you would not be able to update bundled commands through the built-in package manager.
This is only a workaround to get around the fact that the “WP-CLI Framework” would actually need to be a separate repository from the “bundled WP-CLI”. If the repositories themselves should be split at a later date, this custom Composer plugin will not be needed and removed again. So don’t rely on this plugin or the functionality it provides to be available.
A combination of changes we are currently working on – putting all commands into external packages as well as making the WP-CLI bootstrapping process more flexible – made it obvious that we need to deal with command dependencies in one way or another. As an example, the scaffold package command depends on the scaffold command to be already registered. Both are provided through external packages, though. If they are loaded in the wrong order, adding the scaffold package command will not work as expected.
Therefore, the current nightly includes a new mechanism for dealing with these command dependencies. This is achieved through a pair of new hooks:
before_add_command:<command>
The main purpose of this hook is to allow you to check runtime requirements at the moment the command would be added.
The callback you provide will have a WP_CLI\Dispatcher\CommandAddition object be provided as the first argument. This object has a method abort( $reason ) that you can use to prevent the command from being added. The reason that you provide is not yet being used, but the plan is to display this reason in the help screen so that users have feedback about why certain commands are unavailable.
Usage example:
WP_CLI::add_hook( 'before_add_command:db', function ( $addition ) {
if ( ! $this->database_is_available() ) {
$addition->abort(
'The db command needs a working connection to the database.'
);
}
} );
after_add_command:<command>
This hook is used to have one command depend on a different command being loaded first. The main use case is when you add a new sub-command to a parent command located in a different package. As you cannot simply depend on loading order, you can wrap the addition of this sub-command in the after_add_command:<command> hook.
Usage example:
WP_CLI::add_hook( 'after_add_command:scaffold', function () {
WP_CLI::add_command( 'scaffold package', 'WP_CLI\ScaffoldPackageCommand' );
} );
These two hooks allow commands to be built in a more robust way and open up new possibilities for the future.
One of the goals we currently discuss is to have the help screen display unavailable commands together with the reason why the command has been disabled. This provides valuable feedback to the user and might even point to the next action for resolving the issue.
Also, getting rid of some of the run-time errors that let WP-CLI fail without even showing a help screen can potentially be defused through these hooks as well. A simple requirements check before adding a command can then display a warning, and avoid adding the command that would throw an error.
WP-CLI welcomes its second maintainer, thanks to the support of our 2017 sponsors.
First, I’d like to formally welcome Alain Schlesser as WP-CLI’s newest co-maintainer. If you’ve been following the project over the last month, you may have noticed him diving deep into WP-CLI’s internals. We’re excited about the infrastructural improvements coming in the next release, and the new features they’ll enable.
Alain is new to the WordPress community, and brings years of experience developing for other platforms, from hobby game development to large enterprise projects in a government environment.
I’m wildly excited about the opportunity to join Daniel and work on WP-CLI. This project represents a special facet of the WordPress ecosystem and comes with a unique set of requirements and challenges. I can’t wait to explore the possibilities!
— Alain
With Alain joining the project as a co-maintainer, the WP-CLI project is restoring capacity to meet current demands (e.g. support), and ramping up on new feature development and evangelization. We’ve already improved the build time by 33%!
Come say hello to Alain at our new office hours every Tuesday. Office hours start tomorrow, Tuesday, April 4 at 16:00 UTC
Maintaining an open source project requires a substantial, ongoing commitment of time and energy. WP-CLI is a dependable tool loved by thousands because it’s actively maintained, which is made possible by the generosity of its sponsors.
Aaron Jorbin, Anant Shrivastava, Andy Fragen, Austin Ginder, Barry van Someren, Ben Meredith, Ben Welch-Bolen, Bill Christensen, Birgit Pauli-Haack, Bjørn Johansen, Boone Gorges, Carl Hancock, Chuck Reynolds, Craig Martin, Daniel Hüsken, David Herrera, David McDonald, Doruk Fisek, Drew Linsalata, Dwayne McDaniel, Erik Joling, Full Name, Hidetaka Okamoto, Hugh McGuire, Ian Johnson, Jared Atchison, Jason Conroy, Javi, Javier Arnáez, Jeremiah J Terhark, Joel Gaeddert, John Speed, Jonathan Bossenger, Jonathan Daggerhart, Joost de Valk, Joshua Koenig, Kevin Cristiano, Knight Tan, Matt Gross, Matthew Lawrence, Mike Garrett, Miya0001, Ned Zimmerman, Nicholas Duncan, Nick Cernis, Patrick Garman, Per Søderlind, Pippin Williamson, Rachel Baker, Rahul Bansal, Ralf Hortt, required gmbh, Richard Aber, Rick Wiggins, Robert Mathews, Rocket Lift In., Ross Wintle, Ryan Sullivan, Sean Hayes, Simon Blackbourn, Steph Gray, Tadpole Collective, Tanner, Thiana Kitrilakis, Thorsten Ott, Vlad Olaru, WP Bullet, Yash Chandra
Excited to experiment with a couple new WP-CLI commands? wp doctor and wp profile are now available for everyone to install.
wp doctor lets you diagnose problems within WordPress by running a series of checks for symptoms. It includes an API for defining your own diagnosis, as well as writing custom checks.
$ wp @daniel doctor check --all Running checks 100% [============================================================================================] 0:02 / 0:09 +----------------------------+---------+--------------------------------------------------------------------+ | name | status | message | +----------------------------+---------+--------------------------------------------------------------------+ | core-verify-checksums | success | WordPress verifies against its checksums. | | file-eval | success | All 'php' files passed check for 'eval\(.*base64_decode\(.*'. | | autoload-options-size | success | Autoloaded options size (16.25kb) is less than threshold (900kb). | | constant-savequeries-falsy | success | Constant 'SAVEQUERIES' is undefined. | | constant-wp-debug-falsy | success | Constant 'WP_DEBUG' is defined falsy. | | core-update | success | WordPress is at the latest version. | | cron-count | success | Total number of cron jobs is within normal operating expectations. | | cron-duplicates | success | All cron job counts are within normal operating expectations. | | option-blog-public | success | Site is public as expected. | | plugin-active-count | success | Number of active plugins (2) is less than threshold (80). | | plugin-deactivated | success | Less than 40 percent of plugins are deactivated. | | plugin-update | success | Plugins are up to date. | | theme-update | warning | 1 theme has an update available. | +----------------------------+---------+--------------------------------------------------------------------+
wp profile quickly identifies what’s slow with WordPress, by giving you visibility into key I/O indicators.
$ wp @daniel profile stage --fields=stage,time,cache_ratio +------------+---------+-------------+ | stage | time | cache_ratio | +------------+---------+-------------+ | bootstrap | 0.2643s | 80% | | main_query | 0.0186s | 85.71% | | template | 0.0489s | 93.71% | +------------+---------+-------------+ | total (3) | 0.3318s | 86.47% | +------------+---------+-------------+
Both packages are in early stages of development — feedback welcome!
