From 6c7dea9874da246c7f70f986e666836c841d9124 Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Thu, 9 Mar 2023 17:26:05 -0800 Subject: [PATCH 1/3] (NFC) BootTrait --- src/Util/BootTrait.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/Util/BootTrait.php b/src/Util/BootTrait.php index 057df539..1ccea370 100644 --- a/src/Util/BootTrait.php +++ b/src/Util/BootTrait.php @@ -238,11 +238,12 @@ protected function setupErrorHandling(OutputInterface $output) { } /** + * @param \Symfony\Component\Console\Input\InputInterface $input * @param \Symfony\Component\Console\Output\OutputInterface $output * @return array */ protected function createBootParams(InputInterface $input, OutputInterface $output) { - $boot_params = [] ; + $boot_params = []; if ($output->isDebug()) { $boot_params['output'] = $output; } From 0df471017d58c16ccef0bf2f6a629dd3ad13818e Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Tue, 7 Mar 2023 18:28:43 -0800 Subject: [PATCH 2/3] Let admin choose default boot proto. Respect both CIVIRM_BOOT and CIVICRM_SETTINGS. This is preparation for v0.4. The ultimate aim is to flip the default boot behavior (`full/Bootstrap` <=> `cms-full/CmsBootstrap`); but this is a big change. This patch is about allowing admins fine-tune the transition. * In v0.3, the default is `full/Bootstrap`. * In v0.4, it will be `cms-full/CmsBootstrap`. * If you're on v0.3 and want to get ahead (*start using `CmsBootstrap` by default; now*), then you can explicitly set `CIVICRM_BOOT=Auto://` * If you're on v0.4 and want to stay behind (*stay on `Bootstrap` by default*), then you can explicitly set `CIVICRM_SETTING=Auto` These env-vars already exist, but they're not consistently respected. You sometimes need to manually set `--level=full` or `--level=cms-full`. This patch allows you switch without needing to manually pass `--level=X` with each call. --- src/Util/BootTrait.php | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/Util/BootTrait.php b/src/Util/BootTrait.php index 1ccea370..11885b43 100644 --- a/src/Util/BootTrait.php +++ b/src/Util/BootTrait.php @@ -33,7 +33,19 @@ public function boot(InputInterface $input, OutputInterface $output) { } if ($input->getOption('level') === 'full|cms-full') { - $input->setOption('level', getenv('CIVICRM_BOOT') ? 'cms-full' : 'full'); + if (getenv('CIVICRM_UF') === 'UnitTests') { + $input->setOption('level', 'full'); + } + elseif (getenv('CIVICRM_BOOT')) { + $input->setOption('level', 'cms-full'); + } + elseif (getenv('CIVICRM_SETTINGS')) { + $input->setOption('level', 'full'); + } + else { + $input->setOption('level', 'full'); + // TODO (when tests pass, for v0.4): $input->setOption('level', 'cms-full'); + } } if (getenv('CIVICRM_UF') === 'UnitTests' && preg_match('/^cms-/', $input->getOption('level'))) { From e423c9a55123f05c1677fc117007276e04525ba6 Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Tue, 7 Mar 2023 19:08:33 -0800 Subject: [PATCH 3/3] README.md - Add "Bootstrap" section --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 41 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 53cd8db4..263ddce4 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,9 @@ The `cv` command is a utility for interacting with a CiviCRM installation. It pe Requirements ============ -A local CiviCRM installation. - -PHP v5.6+. - -Support may vary depending on the host environment (CMS type, file-structure, symlinks, etc). - * *Tested heavily*: Drupal 7/8 single-site, WordPress single-site, UnitTests - * *Tested lightly*: Drupal 9 single-site, Backdrop single-site, WordPress (alternate content root) - * *Untested*: Drupal 7 multi-site, WordPress multi-site, Joomla, Drupal 6; any heavy symlinking - * *Tip*: If you use an untested or incompatible host environment, then you may see the error `Failed to locate civicrm.settings.php`. See [StackExchange](http://civicrm.stackexchange.com/questions/12732/civix-reports-failed-to-locate-civicrm-settings-php) to discuss work-arounds. +* PHP v7.3+. +* A local CiviCRM installation. +* Systems with special file-layouts may need to [configure bootstrap](#bootstrap). Download ======== @@ -142,6 +136,44 @@ Example: NodeJS See https://github.com/civicrm/cv-nodejs +Bootstrap +========= + +`cv` must find and bootstrap the local instance of CiviCRM, Drupal, WordPress, or similar. This may work a few ways: + +* __Automatic__: By default, `cv` checks the current directory and each parent directory for evidence of well-known environment (such as Drupal or WordPress). + + The automatic search is designed to work with a default site-layout -- as seen in a typical "zip" or "tar" file + from `drupal.org`, `wordpress.org`, or similar. Some deployments add more advanced options -- such as + configuring "multi-site", adding bespoke "symlinks", or moving the `wp-admin` folder. For advanced layouts, you + may need to set an environment variable. + +* __`CIVICRM_BOOT`__: To enable the _standard boot protocol_, set this environment variable. Specify the CMS type and base-directory. Examples: + + ```bash + export CIVICRM_BOOT="Drupal://var/www/public" + export CIVICRM_BOOT="Drupal8://admin@/var/www/public" + export CIVICRM_BOOT="WordPress:/$HOME/sites/my-wp-site/web/" + export CIVICRM_BOOT="Auto://." + ``` + + (Note: In the standard protocol, `cv` loads a CMS first and then asks it to bootstrap CiviCRM. This is more representative of + a typical HTTP page-view, and it is compatible with commands like `core:install`. However, it has not been used for as long.) + +* __`CIVICRM_SETTINGS`__: To enable the _legacy boot protocol_, set this environment variable. Specify the `civicrm.settings.php` location. Examples: + + ```bash + export CIVICRM_SETTINGS="/var/www/sites/default/files/civicrm.settings.php" + export CIVICRM_SETTINGS="Auto" + ``` + + (Note: In the legacy protocol, `cv` loads CiviCRM and then asks CiviCRM to boostrap the CMS. However, it is + less representative of a typical HTTP page-view, and it is incompatible with commands like `core:install`. You might use it + for headless testing or as fallback/work-around if any bugs are discovered in the standard protocol.) + +> ___NOTE___: In absence of a configuration variable, the __Automatic__ mode will behave like `CIVICRM_SETTINGS="Auto"` (in v0.3.x). + This is tentatively planned to change in v0.4.x, where it will behave like `CIVICRM_BOOT="Auto://."` + Build =====