civicrm/cv-lib

Bootstrap library for CiviCRM CLI tools

v0.3.48 2023-07-13 12:37 UTC

Requires

• php: >=7.3.0
• ext-json: *

MIT

• Tim Otten

README

cv-lib is a subpackage provided by cv. It defines the essential core of cv -- locating and booting CiviCRM.

The canonical home for developing this code is in civicrm/cv. It will be periodically published to the read-only mirror civicrm/cv-lib to facilitate usage by other projects.

Installation

composer require civicrm/cv-lib

Primary API

The library provides a handful of supported classes:

• Civi\Cv\CmsBootstrap supports the standard boot protocol. In this protocol, we search for a recognized UF/CMS, start that, and then start CiviCRM. The advantage of this protocol is that it is more representative of a typical HTTP-request. (Events and add-ons supported by UF/CMS and CRM will tend to work more normally.)

  Basic usage:

  Civi\Cv\CmsBootstrap::singleton()->bootCms()->bootCivi();

  Or you can pass in options:

  $options = [...];
  Civi\Cv\CmsBootstrap::singleton()
    ->addOptions($options)
    ->bootCms()
    ->bootCivi();

  End-users may fine-tune the behavior by setting CIVICRM_BOOT (as documented in cv).

• Civi\Cv\Bootstrap supports the legacy boot protocol. In this protocol, we search for civicrm.settings.php and start CiviCRM. Finally, we use civicrm-core API's to start the associated UF/CMS.

  Basic usage:

  $options = [...];
  \Civi\Cv\Bootstrap::singleton()->boot($options);
  \CRM_Core_Config::singleton();
  \CRM_Utils_System::loadBootStrap([], FALSE);

  End-users may fine-tune the behavior by setting CIVICRM_SETTING (as documented in cv).

Both bootstrap mechanisms accept an optional set of hints and overrides.

For example, by default, cv-lib will print errors to STDERR, but you can override the handling of messages:

// Disable all output
$options['log'] = new \Psr\Log\NullLogger();

// Enable verbose logging to STDOUT/STDERR
$options['log'] = new \Civi\Cv\Log\StderrLogger('Bootstrap', TRUE);

// Use bridge between psr/log and symfony/console
$options['log'] = new \Symfony\Component\Console\Logger\ConsoleLogger($output);

// Use the console logger from cv cli. (Requires symfony/console. Looks a bit prettier.)
public function execute(InputInterface $input, OutputInterface $output) {
  ...
  $options['output'] = $output;
  ...
}

For more info about $options, see the docblocks.

Experimental API

Other classes are included, but their contracts are subject to change.

A particularly interesting one is BootTrait. This requires symfony/console, and it is used by most cv subcommands to achieve common behaviors:

1. BootTrait defines certain CLI options (--level, --user, --hostname, etc).
2. BootTrait automatically decides between Bootstrap.php and CmsBootstrap.php.
3. BootTrait passes CLI options through to Bootstrap.php or CmsBootstrap.php.