civicrm / cv-lib
Bootstrap library for CiviCRM CLI tools
Requires
- php: >=7.3.0
- ext-json: *
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 incv
). -
Civi\Cv\Bootstrap
supports the legacy boot protocol. In this protocol, we search forcivicrm.settings.php
and start CiviCRM. Finally, we usecivicrm-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 incv
).
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:
BootTrait
defines certain CLI options (--level
,--user
,--hostname
, etc).BootTrait
automatically decides betweenBootstrap.php
andCmsBootstrap.php
.BootTrait
passes CLI options through toBootstrap.php
orCmsBootstrap.php
.