Welcome to WP-CLIWP-CLIWP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/https://make.wordpress.org/cli/!
WP-CLI is the official command line tool for interacting with and managing your WordPress sites.
WP-CLIWP-CLIWP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/https://make.wordpress.org/cli/ follows a pull request workflow for changes to its code (and documentation). Whether you want to fix a bug or implement a new feature, the process is pretty much the same:
Search existing issues; if you can’t find anything related to what you want to work on, open a new issue in the appropriate repository so that you can get some initial feedback.
Opening an issue before submitting a pull request helps us provide architectural and implementation guidance before you spend too much time on the code.
Fork the repository you’d like to modify, either the framework or one of the command packages.
See Setting Up for more details on configuring the codebase for development.
Create a branch for each issue you’d like to address. Commit your changes.
Push the code changes from your local clone to your fork.
Open a pull request. It doesn’t matter if the code isn’t perfect. The idea is to get it reviewed early and iterate on it.
Respond to code review feedback in a timely manner, recognizing development is a collaborative process.
Once your pull request has passed code review, it will be merged into the default branch and be in the pipeline for the next release.
When submitting a pull request, there are several expectations to keep in mind.
Tests are required
Most of the time, we’ll ask that functional or unit tests be added to cover the change. If it’s a new feature, the pull request needs tests. If it’s fixing a bug, the pull request needs tests.
See the documentation below for more information on writing and running tests.
Follow WordPress Coding StandardsWordPress Coding StandardsThe Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook.
May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards.
While not yet strictly enforced, the WP-CLI project generally follows the WordPress Coding Standards. We may ask you to clean up your pull request if it deviates too much.
Please refrain from unnecessary code churn
Code refactoring should not be done just because we can. With a years-old codebase, there’s an infinite number of best practice, readability, or consistency improvements that could be made. However, engaging on any of them has non-obvious costs: our time and attention, making GitGitGit is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. history more difficult to review, etc. Any code changes should have clear and obvious value.
Contributions are atomic
To make it far easier to merge your code, each pull request should only contain one conceptual change. Keeping contributions atomic keeps the pull request discussion focused on one topic and makes it possible to approve changes on a case-by-case basis.
If you submit a pull request with multiple conceptual changes, we’ll ask you to resubmit as separate pull requests.
Make regular progress on your contribution
Through our code review process, we’ll work with you to make sure your pull request is ready for merge. But if changes are needed and we haven’t heard from you in two weeks, we’ll consider the pull request abandoned. Someone else may pick it up and make the changes required. Or it may be closed.
If you need to step away for any reason, make a comment on the pull request or the related issue so we can pick things up or put things on hold when needed.
If you haven’t submitted a pull request before, you’ll want to install WP-CLI for local development. Depending on whether you want to work on a particular command/package or on the entire project as a whole, the process is slightly different.
Install Composer and hub if you don’t already have them.
Clone the git repository of the command/package you want to work on to your local machine. As an example for working on the wp core command: hub clone wp-cli/core-command
Change into the cloned directory and fork WP-CLI: cd core-command.
Install all Composer dependencies: composer install
Verify WP-CLI was installed properly: vendor/bin/wp --info
Within this package, you should preferably use vendor/bin/wp to run the command. Just using wp should work as well, but by doing that you might run the command through a different version of the framework and thus getting an unexpected result.
Install Composer and hub if you don’t already have them.
Clone the WP-CLI git repository to your local machine: git clone git@github.com:wp-cli/wp-cli.git ~/wp-cli
Change into the cloned directory and fork WP-CLI: cd ~/wp-cli. If you are going to work on the coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. framework itself, run hub fork here to create a pushable repository on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/.
Install all Composer dependencies: composer install --prefer-source
Alias the wp command to your new WP-CLI install: alias wp='~/wp-cli/bin/wp'
Verify WP-CLI was installed properly: wp --info
Commands bundled with WP-CLI (e.g. wp scaffold plugin) will be editable from the vendor/wp-cli directory (e.g. vendor/wp-cli/scaffold-command). The --prefer-source flag when installing WP-CLI ensures each command is installed as a Git clone, making it easier to commit to.
Commands available for standalone installation (e.g. wp dist-archive) can be installed from source (e.g. wp package install git@github.com:wp-cli/dist-archive-command.git). Run wp package path <package-name> to find the appropriate directory to edit.
Importantly, you’ll need to fork each repository in order to have an origin to push to. Run hub fork to fork a repository from the command-line:
$ cd vendor/wp-cli/scaffold-command
$ hub fork
Updating danielbachhuber
From https://github.com/wp-cli/scaffold-command
* [new branch] master -> danielbachhuber/master
new remote: danielbachhuber
$ git remote -v
danielbachhuber git@github.com:danielbachhuber/scaffold-command.git (fetch)
danielbachhuber git@github.com:danielbachhuber/scaffold-command.git (push)
Once you’ve done so, you’ll have a fork in your GitHub account and new remote you can push to. If you didn’t install hub, you’ll need to fork the target repo through the web UIUIUI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. and manually add your fork as a remote.
The sniffers ensure that the code adheres to a given code style, to avoid unneeded discussions about less relevant details like spacing or alignments.
They also check for known sources of bugs and PHPPHPPHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. compatibility problems.
To run the sniffssniffA module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food.:
composer phpcs
To fix the errors and warnings that can be automatically fixed:
WP-CLI uses Behat as its functional test suite. Stability between releases is an important contact WP-CLI makes with its users. Functional tests are different than unit tests in that they execute the entire WP-CLI command, and ensure they always work as expected.
Every repository has a features/ directory with one or more YAML-formatted *.feature files. Here’s an example of what you might see:
Feature: Manage WordPress options
Scenario: Read an individual option
Given a WP install
When I run `wp option get home`
Then STDOUT should be:
"""
https://example.com
"""
In this example:
Feature: documents the scope of the file.
Scenario: describes a specific test.
Given provides the initial environment for the test.
When causes an event to occur.
Then asserts what’s expected after the event is complete.
In a slightly more human-friendly form:
I have a WordPress installation. When I run wp option get home, then the output from the command should be ‘https://example.org’.
Essentially, WP-CLI’s functional test suite lets you describe how a command should work, and then run that description as a functional test.
Notably, Behat is simply the framework for writing these tests. We’ve written our own custom Given, When, and Then step definitions (example, example).
Before running the functional tests, you’ll need a MySQLMySQLMySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com/. (or MariaDB) user called wp_cli_test with the password password1 that has full privileges on the MySQL database wp_cli_test.
To override these credentials you can make use of the database credentials constants of wp-cli-tests
If your user has the correct permissions, the database can also be set up by running composer prepare-tests. This will create the database and the user and configure the necessary privileges. Note that this operation is not needed for every test run, it only needs to be run the first time for the initial setup.
Note: If you are using MySQL >= 8.0, you may experience inconsistencies with WP-CLI successfully connecting to the database. MySQL 8.0 changed the default authentication pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party and some clients (such as PHP) do not yet support this change. More information can be found on this blog post.
This will run all the tests that the package is set up to use, based on the presence of the respective configuration files.
Each repository is configured to run all of its active tests on every code push. The wp-cli/automated-tests repository runs all tests for all repositories on a regular basis.
