From 7e7237b6a5b62d7022ad34a23803adf0ddb666a7 Mon Sep 17 00:00:00 2001
From: Mikey O'Toole <mikey@mjco.uk>
Date: Tue, 28 Jan 2020 12:20:26 +0000
Subject: [PATCH] Refactor, Lint and L10n
This commit refactors this page in line with coding standards and linting output and documents the l10n directory.
---
docs/framework/filesystem.md | 133 +++++++++++++++++------------------
1 file changed, 66 insertions(+), 67 deletions(-)
diff --git a/docs/framework/filesystem.md b/docs/framework/filesystem.md
index 786318dc..902e61c4 100644
--- a/docs/framework/filesystem.md
+++ b/docs/framework/filesystem.md
@@ -19,16 +19,16 @@ the [civicrm-drupal](https://github.com/civicrm/civicrm-drupal/),
contain the code connecting CiviCRM to the CMS along with some CMS-specific
features.
-### Drupal and Backdrop
+### Codebase: Drupal and Backdrop
The CiviCRM module is typically found in the `sites/all/modules/civicrm`
directory. As with any Drupal module, it is possible to put CiviCRM in
several alternative folders, such as:
- * `sites/example.com/modules/civicrm`
- * `sites/default/modules/civicrm`
- * `sites/all/modules/civicrm` (most common)
- * `modules/civicrm`
+* `sites/example.com/modules/civicrm`
+* `sites/default/modules/civicrm`
+* `sites/all/modules/civicrm` (most common)
+* `modules/civicrm`
Within the `civicrm` folder, there will be a
[`drupal/`](https://github.com/civicrm/civicrm-drupal/) or
@@ -36,12 +36,12 @@ Within the `civicrm` folder, there will be a
contains the `civicrm.module` along with the role sync modules, blocks, and
drush and views integration.
-### Joomla
+### Codebase: Joomla
CiviCRM's codebase exists in *two* places within Joomla:
- - A front-end component at `components/com_civicrm`
- - A back-end component at `administrator/components/com_civicrm`
+* A front-end component at `components/com_civicrm`
+* A back-end component at `administrator/components/com_civicrm`
The back-end component contains the common CiviCRM code, in
`administrator/components/com_civicrm/civicrm`. The
@@ -49,30 +49,30 @@ The back-end component contains the common CiviCRM code, in
a `site` directory for the front-end files and an `admin` directory for the
back-end files.
-### WordPress
+### Codebase: WordPress
The CiviCRM plugin is found in `wp-content/plugins/civicrm`. This corresponds
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
+### Tip: Programatically using [civicrm.root]
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'
+``` sh
+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
+``` php
echo Civi::paths()->getPath("[civicrm.root]/.");
echo Civi::paths()->getPath("[civicrm.root]/README.md");
echo Civi::paths()->getUrl("[civicrm.root]/.");
@@ -84,21 +84,21 @@ echo Civi::paths()->getUrl("[civicrm.root]/README.md");
The CiviCRM codebase includes some third-party libraries. These are pulled
into three folders:
- * __`vendor`__ is collection of PHP libraries which are automatically downloaded
- by [`composer`](http://getcomposer.org/) based on the `composer.json` configuration.
- * __`bower_components`__ is a collection of JS/CSS libraries which are automatically
- downloaded by [`bower`](https://bower.io/) based on the `bower.json` configuration.
- * __`packages`__ is a manually curated collection of library files.
- It's maintained in [`civicrm-packages.git`](https://github.com/civicrm/civicrm-packages/).
+* `vendor`__ is collection of PHP libraries which are automatically downloaded
+ by [`composer`](http://getcomposer.org/) based on the `composer.json` configuration.
+* `bower_components`__ is a collection of JS/CSS libraries which are automatically
+ downloaded by [`bower`](https://bower.io/) based on the `bower.json` configuration.
+* `packages`__ is a manually curated collection of library files.
+ It's maintained in [`civicrm-packages.git`](https://github.com/civicrm/civicrm-packages/).
!!! note "When adding a new dependency to core, use `composer.json` or `bower.json`."
-### Tip: Programmatic lookup
+### Tip: Programmatically using Civi::paths()
Traditionally, one would use the root folder of `civicrm-core` to determine the path
or URL of a library, as in:
-```php
+``` php
global $civicrm_root;
echo "$civircm_root/packages/IDS/default_filter.xml";
```
@@ -110,7 +110,7 @@ future.
In CiviCRM v4.7.21+, one should use `Civi::paths()` to lookup the path or
URL for a library:
-```php
+``` php
echo Civi::paths()->getPath('[civicrm.vendor]/dompdf/dompdf/README.md');
echo Civi::paths()->getUrl('[civicrm.vendor]/dompdf/dompdf/README.md');
@@ -124,13 +124,13 @@ echo Civi::paths()->getUrl('[civicrm.packages]/IDS/default_filter.xml');
Additionally, to register JS/CSS resources in `Civi::resources()`, you can use
a shorthand with the path variables, as in:
-```php
+``` php
echo Civi::resources()->addScriptFile('civicrm.bower', 'jquery/dist/jquery.min.js');
```
-## Local data files
+## Local Data Files
-CiviCRM also needs directories for storing volatile data files, such as
+CiviCRM also needs directories for storing volatile data files, such as
logs, caches, and uploads. These directories are located outside
the main codebase, in a location that can be safely preserved during
upgrades.
@@ -142,18 +142,18 @@ CiviCRM provides two main file storage helpers:
The actual path is chosen to align with the conventions of each CMS and typically [civicrm.private] will refer to the same directory as [civicrm.files] while providing the ability to manage paths in a more granular fashion should the need arise.
-### Drupal and Backdrop
+### Local Data Files: Drupal and Backdrop
CiviCRM stores its files in a folder named `civicrm` within the Drupal
`files` directory. This is commonly `sites/default/files/civicrm`, though
it could be `files/civicrm`, `sites/example.org/files/civicrm`, or another
folder determined by the system administrator.
-### Joomla
+### Local Data Files: Joomla
The CiviCRM local files are within the `media/civicrm` directory.
-### WordPress
+### Local Data Files: WordPress
Newly-installed CiviCRM sites on WordPress have their local files at
`wp-content/uploads/civicrm`. Many older sites use the previous default:
@@ -161,21 +161,20 @@ Newly-installed CiviCRM sites on WordPress have their local files at
### Tip: Sub-directories
-The `[civicrm.files]` and `[civicrm.private]` are CiviCRM's base directories for files storage, each will contain several sub-directories.
+The `[civicrm.files]` and `[civicrm.private]` are CiviCRM's base directories for files storage, each will contain several sub-directories.
These sub-directories will include:
-
-| Code Name | Typical Path | Recommended Access Level | Comments
-| -------------------- | ------------------------------------ | ----------------------------------------------- |-----------------------------------------------------------------
-| `configAndLogDir` | `[civicrm.log]` defaults to `[civicrm.private]/ConfigAndLog` | Prohibit all web access | Stores log files. Writes and reads should be infrequent, unless there are errors/warnings.
-| `customFileUploadDir` | `[civicrm.files]/custom` | Prohibit all web access | Stores sensitive uploads (such as custom-field attachments). Writes and reads vary widely (depending on use-case/config).
-| `extensionsDir` | `[civicrm.files]/ext` | Allow file reads but prohibit directory listing | Stores downloaded extensions. Writes should be infrequent. Reads are very frequent. In hardened systems, this may be readonly or disabled.
-| `imageUploadDir` | `[civicrm.files]/persist/contribute` | Allow file reads but prohibit directory listing | Stores uploaded or autogenerated media (images/css/etc). Writes and reads vary widely (depending on use-case/config).
-| `templateCompileDir` | `[civicrm.compile]` defaults to `[civicrm.private]/templates_c`| Prohibit all web access | Stores autogenerated PHP files. Writes should be infrequent. Reads are very frequent.
-| `uploadDir` | `[civicrm.files]/upload` | Prohibit all web access | Temporary files. Writes and reads vary widely (depending on use-case/config).
+| Code Name | Typical Path | Recommended Access Level | Comments |
+| --------------------- | -------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `configAndLogDir` | `[civicrm.log]` defaults to `[civicrm.private]/ConfigAndLog` | Prohibit all web access | Stores log files. Writes and reads should be infrequent, unless there are errors/warnings. |
+| `customFileUploadDir` | `[civicrm.files]/custom` | Prohibit all web access | Stores sensitive uploads (such as custom-field attachments). Writes and reads vary widely (depending on use-case/config). |
+| `extensionsDir` | `[civicrm.files]/ext` | Allow file reads but prohibit directory listing | Stores downloaded extensions. Writes should be infrequent. Reads are very frequent. In hardened systems, this may be readonly or disabled. |
+| `imageUploadDir` | `[civicrm.files]/persist/contribute` | Allow file reads but prohibit directory listing | Stores uploaded or autogenerated media (images/css/etc). Writes and reads vary widely (depending on use-case/config). |
+| `l10nDir` | `[civicrm.l10n]` defaults to `[civicrm.private]/l10n` | Prohibit all web access | Stores CiviCRM's localisation files. Writes should be infrequent (generally on Update or Extension Install). Reads are very frequent. |
+| `templateCompileDir` | `[civicrm.compile]` defaults to `[civicrm.private]/templates_c`| Prohibit all web access | Stores autogenerated PHP files. Writes should be infrequent. Reads are very frequent. |
+| `uploadDir` | `[civicrm.files]/upload` | Prohibit all web access | Temporary files. Writes and reads vary widely (depending on use-case/config). |
!!! tip "Advanced filesystem and web server configurations"
-
Each folder has different requirements (with respect to permissions,
read-write frequency, etc). Most Apache-based web servers respect the `.htaccess`
and `index.html` files, and these are configured automatically.
@@ -186,28 +185,29 @@ These sub-directories will include:
For the time being,`CIVICRM_TEMPLATE_COMPILEDIR` can be set in `civicrm.settings.php` and file paths will work as before. Alternatively, one may remove `CIVICRM_TEMPLATE_COMPILEDIR` and instead, set all paths using `$civicrm_paths`. With the following examples, the reasons for this setup should be more intuitive.
-#### Example 1: Minimalist: all public and private data go to the same folder, sites/default/files/civicrm.
+#### Example 1: Minimalist: all public and private data go to the same folder, sites/default/files/civicrm
-```
+``` php
$civicrm_paths['civicrm.files']['path'] = '/srv/example.com/htdocs/sites/default/files/civicrm';
$civicrm_paths['civicrm.private']['path'] = '/srv/example.com/htdocs/sites/default/files/civicrm';
```
-The constant `CIVICRM_TEMPLATE_COMPILEDIR` is never consulted. Updating `civicrm.files` changes only public data folders. Updating `civicrm.private` changes only private data folders (e.g. `templateCompileDir` and `ConfigAndLogDir`).
+The constant `CIVICRM_TEMPLATE_COMPILEDIR` is never consulted. Updating `civicrm.files` changes only public data folders. Updating `civicrm.private` changes only private data folders (e.g. `templateCompileDir` and `ConfigAndLogDir`).
-#### Example 2: The public and private data are stored in separate places, akin to Drupal's public and private folders.
+#### Example 2: The public and private data are stored in separate places, akin to Drupal's public and private folders
-```
+``` php
$civicrm_paths['civicrm.files']['path'] = '/srv/example.com/htdocs/sites/default/files/civicrm');
$civicrm_paths['civicrm.private']['path'] = '/srv/example.com/private/civicrm');
```
-#### Example 3: Try to follow Linux FHS and override most default paths.
+#### Example 3: Try to follow Linux FHS and override most default paths
-```
+``` php
$civicrm_paths['civicrm.files']['path'] = '/var/www/sites/default/files/civicrm');
$civicrm_paths['civicrm.private']['path'] = '/var/lib/civicrm');
$civicrm_paths['civicrm.log']['path'] = '/var/log/civicrm');
+$civicrm_paths['civicrm.l10n']['path'] = '/var/lib/civicrm/l10n');
$civicrm_paths['civicrm.compile']['path'] = '/var/run/civicrm-compile');
$civicrm_paths['civicrm.root']['path'] = '/usr/share/php/civicrm-core');
$civicrm_paths['civicrm.root']['url'] = 'https://example.com/civicrm-core'); // with httpd path alias
@@ -215,18 +215,18 @@ $civicrm_paths['cms.root']['path'] = '/usr/share/php/drupal-core');
$civicrm_paths['cms.root']['url'] = 'https://example.com/'); // with httpd path alias
```
-### Tip: Programmatic lookup
+### Tip: Programmatically using [civicrm.files]
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'
+``` sh
+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()`:
@@ -242,15 +242,15 @@ 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
+``` sh
+cv path -c configAndLogDir
+cv path -c templateCompileDir
+cv path -c templateCompileDir/en_US
```
Or in PHP:
-```
+``` php
echo CRM_Core_Config::singleton()->configAndLogDir;
echo CRM_Core_Config::singleton()->templateCompileDir;
echo CRM_Core_Config::singleton()->templateCompileDir . '/en_US';
@@ -273,8 +273,8 @@ In Backdrop, the `civicrm.settings.php` is often located in the site root.
There are two instances of `civicrm.settings.php` in Joomla, within each of the
components:
- - front-end at `components/com_civicrm/civicrm.settings.php`
- - back-end at `administrator/components/com_civicrm/civicrm.settings.php`
+* front-end at `components/com_civicrm/civicrm.settings.php`
+* back-end at `administrator/components/com_civicrm/civicrm.settings.php`
The files are *nearly* identical. The one difference is that the front-end file
has the site's normal base URL, while the back-end file has `/administrator/` on
@@ -290,19 +290,18 @@ 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
+### Tip: Programmatically using CIVICRM_SETTINGS_PATH
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;'
+``` sh
+cv ev 'echo CIVICRM_SETTINGS_PATH;'
```
Or in PHP:
-```php
+``` php
echo CIVICRM_SETTINGS_PATH;
```
--
GitLab