Merge pull request #652 from herbdool/issue-651

Add help for new paths

docs/framework/filesystem.md

@@ -130,13 +130,17 @@ echo Civi::resources()->addScriptFile('civicrm.bower', 'jquery/dist/jquery.min.j
 
 ## Local data files
 
-CiviCRM also needs a directory for storing volatile data files, such as 
-logs, caches, and uploads.  This directory is located outside
-the main codebase -- in a location that can be safely preserved during
+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.
 
-This folder is generically referred to as `[civicrm.files]`, but the actual
-path is chosen to align with each CMS's conventions.
+CiviCRM provides two main file storage helpers:
+
+* `[civicrm.files]` - Intended to store files which can safely live within the files directory of your CMS, within your webroot.
+* `[civicrm.private]` - Intended to store files which could be stored outside of your webroot for enhanced security.
+
+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
 
@@ -157,17 +161,17 @@ Newly-installed CiviCRM sites on WordPress have their local files at
 
 ### Tip: Sub-directories
 
-The `[civicrm.files]` is a base which contains several sub-directories.
-These folders include:
+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.files]/ConfigAndLog`       | Prohibit all web access                         | Stores log files. Writes and reads should be infrequent, unless there are errors/warnings.
+| `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.files]/templates_c`        | Prohibit all web access                         | Stores autogenerated PHP files. Writes should be infrequent. 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"
@@ -178,6 +182,39 @@ These folders include:
     However, some web-servers don't support these, so CiviCRM's
     status-check shows warnings if it detects unexpected configuration.
 
+### Configuration options for paths
+
+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.
+
+```
+$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`).
+
+
+#### Example 2: The public and private data are stored in separate places, akin to Drupal's public and private folders.
+
+```
+$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.
+
+```
+$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.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
+$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
 
 If you are writing an extension or integration that needs to reference the