diff --git a/docs/basics/filesystem.md b/docs/basics/filesystem.md index 37658b7a7cad365bf6d78ee0741f51f6636148cd..3222cc0d9826ec59517f2fe4ae81f48112e32705 100644 --- a/docs/basics/filesystem.md +++ b/docs/basics/filesystem.md @@ -56,6 +56,29 @@ to the [civicrm-wordpress](https://github.com/civicrm/civicrm-wordpress/) repository, containing the plugin file as well as WP-CLI integration. The common CiviCRM codebase is found at `wp-content/plugins/civicrm/civicrm`. +### Tip: Programmatic lookup + +If you are writing an extension or integration that needs to reference the +codebase of an existing installation, use a command to lookup the correct +value. In `bash`, call the [`cv`](https://github.com/civicrm/cv) +command-line tool: + +``` +$ cv path -d '[civicrm.root]' +$ cv path -d '[civicrm.root]/README.md' +$ cv url -d '[civicrm.root]' +$ cv url -d '[civicrm.root]/README.md' +``` + +Or in PHP, use `Civi::paths()`: + +```php +echo Civi::paths()->getPath("[civicrm.root]/."); +echo Civi::paths()->getPath("[civicrm.root]/README.md"); +echo Civi::paths()->getUrl("[civicrm.root]/."); +echo Civi::paths()->getUrl("[civicrm.root]/README.md"); +``` + ## Local data files CiviCRM also needs a files directory for storing a variety of site-specific @@ -80,6 +103,47 @@ Newly-installed CiviCRM sites on WordPress have their local files at `wp-content/uploads/civicrm`. Many older sites use the previous default: `wp-content/plugins/files/civicrm`. +### Tip: Programmatic lookup + +If you are writing an extension or integration that needs to reference the +data files of an existing installation, use a command to lookup the correct +value. In `bash`, call the [`cv`](https://github.com/civicrm/cv) +command-line tool: + +``` +$ cv path -d'[civicrm.files]' +$ cv path -d'[civicrm.files]/upload' +$ cv url -d'[civicrm.files]' +$ cv url -d'[civicrm.files]/upload' +``` + +Or in PHP, use `Civi::paths()`: + +```php +echo Civi::paths()->getPath("[civicrm.files]/."); +echo Civi::paths()->getPath("[civicrm.files]/upload"); +echo Civi::paths()->getUrl("[civicrm.files]/."); +echo Civi::paths()->getUrl("[civicrm.files]/upload"); +``` + +Additionally, some items -- such as the log folder or cache folder -- are +configurable. The most correct way to find these is to read a config +variable. In `bash`: + +``` +$ cv path -c configAndLogDir +$ cv path -c templateCompileDir +$ cv path -c templateCompileDir/en_US +``` + +Or in PHP: + +``` +echo CRM_Core_Config::singleton()->configAndLogDir; +echo CRM_Core_Config::singleton()->templateCompileDir; +echo CRM_Core_Config::singleton()->templateCompileDir . '/en_US'; +``` + ## Settings file CiviCRM's database connection, base URL, site key, CMS, and file paths are defined in `civicrm.settings.php`. @@ -113,3 +177,20 @@ put the settings file within the CiviCRM plugin folder at dangerous when upgrading: it is important in this case to keep the `civicrm` folder until the upgrade is complete and the site is verified to be working properly. + + +### Tip: Programmatic lookup + +If you are writing an extension or integration that needs to reference the +settings of an existing installation, use the constant +`CIVICRM_SETTINGS_PATH` to locate `civicrm.settings.php`. In `bash`: + +``` +$ cv ev 'echo CIVICRM_SETTINGS_PATH;' +``` + +Or in PHP: + +```php +echo CIVICRM_SETTINGS_PATH; +```