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: Introduction
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:
eval(`cv php:boot`);
Overall, 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 asphpunit
orcodecept
. - Evaluate PHP snippet (
cv php:eval [snippet]
akacv ev [snippet]
): Evaluate a small snippet of PHP code within your CiviCRM instance. - Execute PHP script file (
cv php:script [file]
akacv 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 drush
, wp-cli
, or 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:
cv
should now work better with vanilla Joomla environments. Special thanks to Andrew Hunt for fixing and testing this. - Verbose boot: If
cv
doesn't boot correctly in your environment, pass-vvv
to 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
grunt
orprotractor
, then you may occasionally need access to CiviCRM paths, URLs, databases, or demo users. Instead of hardcoding these details, you can use the librarycivicrm-cv
(https://github.com/civicrm/cv-nodejs) to get programmatic access.
civix: Recent improvements
- Joomla support and verbose boot: Some
civix
sub-commands usecv
to access your local CiviCRM instance. Thecv
improvements initiated by Andrew and Erich also improvecivix
. - Manipulate "info.xml": If your extension has a custom build process, then your build scripts might need to access the
version
,releaseDate
, or other properties ofinfo.xml
. Use the new sub-commandscivix info:get
andcivix info:set
. - Extension versions are domain-independent: The
civix
upgrader traditionally stored a version number incivicrm_setting
. However, this did not work well in multi-domain configurations. The upgrader now tracks the version incivicrm_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 (
executeSqlFile(...)
orsql/auto_install.sql
) and Smarty-based SQL templates (executeSqlTemplate(...)
orsql/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
civilint
or Drupalcoder
. 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.
General notes
- 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
cv
andcivix
have built-in help screens to list sub-commands and arguments. - Only tested with Linux/OS X: Both
cv
andcivix
are 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
civibuild
configurations: 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.cv
is only tested with thecivibuild
configurations likedrupal-clean
andwp-demo
. If you'd like to improve support other configurations, please open a pull-request on Github.
Comments
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.