Skip to content
Snippets Groups Projects
Commit 7e7237b6 authored by homotechsual's avatar homotechsual
Browse files

Refactor, Lint and L10n 

This commit refactors this page in line with coding standards and linting output and documents the l10n directory.
parent 8ea966c7
No related branches found
No related tags found
1 merge request!752Refactor, Lint and L10n
Hide whitespace changes
Inline Side-by-side
docs/framework/filesystem.md
+ 66
− 67
View file @ 7e7237b6
......@@ -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;
```
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment