cv (https://github.com/civicrm/cv) and
civix (https://github.com/totten/civix) are Unix/CLI tools for developers.
cv provides access to your Civi site on the command line, and
civix generates skeletal code for new extensions. We've had a few recent updates to each of these tools, so I wanted to introduce
cv more formally and then recap some of recent improvements for each tool.
cv originated as part of the Testapalooza project which broadened support for automated tests in CiviCRM -- testing of CiviCRM extensions or external integration modules; testing with PHPUnit or Behat or Codeception; testing for headless scenarios or end-to-end scenarios; ad nauseum. In all of these cases, we start with some existing PHP tool (such as
phpunit) and mix-in Civi+CMS.
For example, if you have
cv installed, then your other PHP programs can start CiviCRM with one line:
cv enables you to run PHP code in Civi using four different flows:
- Generate boot code (
cv php:boot): Generate PHP code for booting your CiviCRM instance. You can use this code inside another script, such as
- Evaluate PHP snippet (
cv php:eval [snippet]aka
cv ev [snippet]): Evaluate a small snippet of PHP code within your CiviCRM instance.
- Execute PHP script file (
cv php:script [file]aka
cv scr [file]): Execute any PHP script file within your CiviCRM instance.
- Interactive command line (REPL) (
cv cli): Open an interactive prompt where you can enter several PHP statements. (This is based on the incredible Psysh tool.)
It also includes a few sub-commands which can be useful for writing tests:
- Call APIv3 (
cv api): Execute an API call. Inputs and outputs may be encoded as JSON.
- Lookup a URL (
cv url): Lookup the URL for any Civi page, with suitable adjustments to match the current CMS and domain.
- Export configuration (
cv vars:show): Export data about the DSN, URL, and demo users.
cv is similar to
joomla-console in that it provides CLI access to a CiviCRM installation. However, it differs in that:
- You don't need to know which CMS is being used.
- The sub-commands are focused on Civi features (such as APIv3 and extensions).
cv: Recent improvements
- Extension management: To administer CiviCRM extensions (e.g. downloading, enabling, disabling, uninstalling), use the new sub-commands like
cv dl [extension-name]. See PR #4 for more complete details.
- Joomla support:
cvshould now work better with vanilla Joomla environments. Special thanks to Andrew Hunt for fixing and testing this.
- Verbose boot: If
cvdoesn't boot correctly in your environment, pass
-vvvto display more verbose information. Special thanks to Erich Schulz for initiating this.
- NodeJS library: If you develop enhancements for CiviCRM using NodeJS tools such as
protractor, then you may occasionally need access to CiviCRM paths, URLs, databases, or demo users. Instead of hardcoding these details, you can use the library
civicrm-cv(https://github.com/civicrm/cv-nodejs) to get programmatic access.
civix: Recent improvements
- Joomla support and verbose boot: Some
cvto access your local CiviCRM instance. The
cvimprovements initiated by Andrew and Erich also improve
- Manipulate "info.xml": If your extension has a custom build process, then your build scripts might need to access the
releaseDate, or other properties of
info.xml. Use the new sub-commands
- Extension versions are domain-independent: The
civixupgrader traditionally stored a version number in
civicrm_setting. However, this did not work well in multi-domain configurations. The upgrader now tracks the version in
civicrm_extension. Special thanks to Frank Gomez for initiating this.
- Smarty for SQL Upgrades: In CiviCRM core, SQL upgrades are processed via Smarty. This allows them to adjust dynamically and to handle multilingual schema. The civix upgrader now supports both static SQL files (
sql/auto_install.sql) and Smarty-based SQL templates (
sql/auto_install.mysql.tpl). Special thanks to Sunil Pawar for initiating this improvement.
- Multiple cleanups: Several templates have been updated to improve docs and code-style. These are non-functional changes and don't impact existing extensions -- but for new extensions, the code should validate better in
coder. Special thanks to Coleman Watts for initiating these changes.
Note: If you'd like to upgrade an existing extension with newer templates from
civix, see UPGRADE.md.
- Downloading: If you use buildkit, run civi-download-tools to get the latest releases. Otherwise, see download instructions at https://github.com/civicrm/cv and https://github.com/totten/civix.
- Built-in help: Both
civixhave built-in help screens to list sub-commands and arguments.
- Only tested with Linux/OS X: Both
civixare command-line PHP tools. They are distributed as platform-independent executables (PHAR), but they are only tested in certain builds of Linux and OS X. They may or may not work well on Windows -- in either case, trying them on Windows will require more skills/experience with Windows PHP CLI. If you'd like to improve Windows support, please open a pull-request on Github.
- Only tested with basic
civibuildconfigurations: CiviCRM can be deployed with many system configurations using techniques like symlinks, multiple URLs, dynamic database credentials, and so on. However, these techniques often impact the bootstrap process, and we cannot test every possible configuration.
cvis only tested with the
wp-demo. If you'd like to improve support other configurations, please open a pull-request on Github.
Great work, @totten. So happy to see well-thought, robust, generalized tools like this in the CiviCRM space. "Right tool for the right job" is a lot easier when there are better tools in the box.