From 953cf65223e9d061133950c2780f313afb5b5dd4 Mon Sep 17 00:00:00 2001
From: Matias Griese <matias@trilbymedia.com>
Date: Tue, 13 Apr 2021 12:40:08 +0300
Subject: [PATCH] Added some documentation #3297

---
 system/defines.php | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/system/defines.php b/system/defines.php
index 6551da7fc4..63eab18c8e 100644
--- a/system/defines.php
+++ b/system/defines.php
@@ -1,4 +1,5 @@
 <?php
+
 /**
  * @package    Grav\Core
  *
@@ -22,41 +23,50 @@
     define('DS', '/');
 }
 
-// Directories and Paths
+// Absolute path to Grav root. This is where Grav is installed into.
 if (!defined('GRAV_ROOT')) {
     $path = rtrim(str_replace(DIRECTORY_SEPARATOR, DS, getenv('GRAV_ROOT') ?: getcwd()), DS);
     define('GRAV_ROOT', $path);
 }
+// Absolute path to Grav webroot. This is the path where your site is located in.
 if (!defined('GRAV_WEBROOT')) {
     $path = rtrim(getenv('GRAV_WEBROOT') ?: GRAV_ROOT, DS);
     define('GRAV_WEBROOT', $path);
 }
+// Relative path to user folder. This path needs to be located under GRAV_WEBROOT.
 if (!defined('GRAV_USER_PATH')) {
     $path = rtrim(getenv('GRAV_USER_PATH') ?: 'user', DS);
     define('GRAV_USER_PATH', $path);
 }
+// Absolute or relative path to system folder. Defaults to GRAV_ROOT/system
+// If system folder is outside of webroot, see https://github.com/getgrav/grav/issues/3297#issuecomment-810294972
 if (!defined('GRAV_SYSTEM_PATH')) {
     $path = rtrim(getenv('GRAV_SYSTEM_PATH') ?: 'system', DS);
     define('GRAV_SYSTEM_PATH', $path);
 }
+// Absolute or relative path to cache folder. Defaults to GRAV_ROOT/cache
 if (!defined('GRAV_CACHE_PATH')) {
     $path = rtrim(getenv('GRAV_CACHE_PATH') ?: 'cache', DS);
     define('GRAV_CACHE_PATH', $path);
 }
+// Absolute or relative path to logs folder. Defaults to GRAV_ROOT/logs
 if (!defined('GRAV_LOG_PATH')) {
     $path = rtrim(getenv('GRAV_LOG_PATH') ?: 'logs', DS);
     define('GRAV_LOG_PATH', $path);
 }
+// Absolute or relative path to tmp folder. Defaults to GRAV_ROOT/tmp
 if (!defined('GRAV_TMP_PATH')) {
     $path = rtrim(getenv('GRAV_TMP_PATH') ?: 'tmp', DS);
     define('GRAV_TMP_PATH', $path);
 }
+// Absolute or relative path to backup folder. Defaults to GRAV_ROOT/backup
 if (!defined('GRAV_BACKUP_PATH')) {
     $path = rtrim(getenv('GRAV_BACKUP_PATH') ?: 'backup', DS);
     define('GRAV_BACKUP_PATH', $path);
 }
 unset($path);
 
+// INTERNAL: Do not use!
 define('USER_DIR', GRAV_WEBROOT . '/' . GRAV_USER_PATH . '/');
 define('CACHE_DIR', (!str_starts_with(GRAV_CACHE_PATH, '/') ? GRAV_ROOT . '/' : '') . GRAV_CACHE_PATH . '/');