Developers: Updates for civix and cv

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 as phpunit or codecept.
• 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 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 or 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 civix sub-commands use cv to access your local CiviCRM instance. The cv improvements initiated by Andrew and Erich also improve civix.
• 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 of info.xml. Use the new sub-commands civix info:get and civix info:set.
• Extension versions are domain-independent: The civix upgrader 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 (executeSqlFile(...) or sql/auto_install.sql) and Smarty-based SQL templates (executeSqlTemplate(...) or 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 civilint or Drupal 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.

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 and civix have built-in help screens to list sub-commands and arguments.
• Only tested with Linux/OS X: Both cv and civix 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 the civibuild configurations like drupal-clean and wp-demo. If you'd like to improve support other configurations, please open a pull-request on Github.