admin/config_php: Add more config values

To make the config values more visible rather
than having to find them in their location
in the Mahara source code.

source/administration/config_php.rst

@@ -8,6 +8,9 @@ Config.php variables
 
 Some site options cannot be set in the administration area but need to be updated directly on the server in the ``config.php`` file. In this section, you see the settings that are possible and why you might want to include them in your ``config.php`` file for your site.
 
+.. note::
+   Some of the config parameters have an equivalent setting in the *Administration* area. If you set a value explicitely in your ``config.php`` file, it overwrites any value entered in the administration, and the field becomes unavailable for editing.
+
 The ``config.php`` file sits in the ``/htdocs`` directory of your site. If you want to view all possible variables and their default values, you can find them in ``/htdocs/lib/config-defaults.php``. You can overwrite any default values by placing the variable in your ``config.php`` file.
 
 Anatomy of a config variable
@@ -32,9 +35,9 @@ A configuration variable needs to be written in the correct syntax in order to f
 .. note::
    If you want to change the default behaviour of a variable in your instance of Mahara, copy it from the ``config-defaults.php`` file into your ``config.php`` file so it won't get overwritten when you update the codebase. The ``config.php`` file is never changed by an update or upgrade of Mahara.
 
-  .. index::
-    single: config.php; Developer mode
-    single: config.php variables; developermode
+.. index::
+  single: config.php; Developer mode
+  single: config.php variables; developermode
 
 .. _config_variable_developermode:
 
@@ -51,6 +54,142 @@ When you enable developer mode, the following two changes are made automatically
 .. note::
    ``developermode=true`` is less powerful than the :ref:`productionmode=false <config_variable_productionmode>`.
 
+.. index::
+ single: config.php; Permissions
+ single: config.php variables; directorypermissions
+
+.. _config_variable_directorypermissions:
+
+directorypermissions: Permissions to use in dataroot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->directorypermissions = 0700;`` (default)
+
+You can set what permissions are used for files and directories in the Mahara dataroot. The default allows only the web server user to read the data. If you are on shared hosting and might want to download the contents of your dataroot later, e.g. for backup purposes, set this to 0755. Otherwise, leave it as is.
+
+.. index::
+ single: config.php; Share the same dataroot with another Mahara
+ single: config.php variables; insecuredataroot
+
+.. _config_variable_insecuredataroot:
+
+insecuredataroot: Share the same dataroot with another Mahara
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->insecuredataroot = false;`` (default) or ``$cfg->insecuredataroot = true;``
+
+You can enforce checking that files that are served have come from dataroot. You would only want to turn this on if you were running more than one Mahara against the same dataroot. If you are doing that, make sure you create separate dataroots for each installation, but symlink the artefact directory from all of them to one of them, and turn on "insecuredataroot" on all the ones for which you created symlinks.
+
+.. index::
+ single: config.php; System email address
+ single: config.php variables; noreplyaddress
+
+.. _config_variable_noreplyaddress:
+
+noreplyaddress: System email address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->noreplyaddress = 'noreply@yourdomainhere';``
+
+Set the system mail address. Notifications are sent from this address (except for a few emails when a person doesn't yet have an account). You can also set it in *Administration → Configure site → Site options → Email settings*.
+
+Typically, the noreply address is one that is not monitored as people are not supposed to reply to it.
+
+.. index::
+ single: config.php; Destination for log information
+ single: config.php variables; log targets
+
+.. _config_variable_log_targets:
+
+log targets: Destination for log information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typical production environment:
+
+| ``$cfg->log_dbg_targets     = LOG_TARGET_ERRORLOG;``
+| ``$cfg->log_info_targets    = LOG_TARGET_ERRORLOG;``
+| ``$cfg->log_warn_targets    = LOG_TARGET_ERRORLOG;``
+
+Typical non-production environment:
+
+| ``$cfg->log_dbg_targets     = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;``
+| ``$cfg->log_info_targets    = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;``
+| ``$cfg->log_warn_targets    = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;``
+| ``$cfg->log_environ_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;``
+
+There are 4 different types of log messages that you can log to an error log and / or display on screen:
+
+* **dbg**: Debugging messages
+* **info**: Informational messages
+* **warn**: Warning messages
+* **environ**: Environment errors
+
+You can log the different messages to different destinations:
+
+* **LOG_TARGET_SCREEN**: Display error messages on the screen. This is useful during testing and when debugging, but should not be used on a live site.
+* **LOG_TARGET_ADMIN**: Show error messages on the screen, but only when you are in the *Administration* area.
+* **LOG_TARGET_ERRORLOG**: Send log information to the error log as specified in your Apache configuration. It is recommended to use this setting for all log levels no matter the other targets that you specified.
+* **LOG_TARGET_FILE**: This allows you to specify a file to which messages will be logged. It's best to pick a path in dataroot, but note that log files tend to get very large over time. So it's advisable to implement some kind of logrotate if you want to leave this on all the time. The other option is to just turn this option on when you are getting a specific error or want to see the logging, and know that you're not going to let the log file get large.
+
+You can combine the targets with bitwise operations, e.g. ``LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG``.
+
+.. index::
+ single: config.php; File containing error messages
+ single: config.php variables; log_file
+
+.. _config_variable_log_file:
+
+log_file: File containing error messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->log_file = '/path/to/dataroot/error.log';``
+
+If you use LOG_TARGET_FILE, this is the file to which errors will be logged. By default, it will write to the file ``error.log`` under the dataroot. If you change this in config.php, make sure you use a folder which is writable by the web server.
+
+.. index::
+ single: config.php; Log backtraces
+ single: config.php variables; log_backtrace_levels
+
+.. _config_variable_log_backtrace_levels:
+
+log_backtrace_levels: Log backtraces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For example: ``$cfg->log_backtrace_levels = LOG_LEVEL_WARN | LOG_LEVEL_ENVIRON;`` (default)
+
+The log levels that will generate backtraces. Useful for development, but probably only warnings are useful on a live site.
+
+.. index::
+ single: config.php; Log backtraces
+ single: config.php variables; log_backtrace_print_args
+
+.. _config_variable_log_backtrace_print_args:
+
+log_backtrace_print_args: Log backtraces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->log_backtrace_print_args = null;`` (default)
+
+Print the values of function and method arguments when printing a backtrace. This can be useful for debugging, but it is a security risk because function parameters may include sensitive data such as passwords and private keys. Though arguments whose names suggest that they contain passwords, will still be blanked out even if this feature is enabled.
+
+A ``null`` value here tells Mahara to hide argument values when ``$cfg->productionmode`` is enabled, and to show them otherwise. A ``true`` or ``false`` tells Mahara to always show or hide argument values in backtraces regardless of the value of ``$cfg->productionmode``.
+
+.. index::
+ single: config.php; Error reporting
+ single: config.php variables; error_reporting
+
+.. _config_variable_error_reporting:
+
+error_reporting: Error reporting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->error_reporting = E_ALL & ~E_STRICT;`` (default)
+
+This parameter indicates what level of errors to print to the Mahara logs. It gets passed directly to the PHP function ``error_reporting()``.
+
+.. note::
+  There are some limitations in this method because it doesn't get called until several scripts have already been compiled: ``init.php, config.php, config-defaults.php, errors.php``, and the file directly invoked in the URL. So, compile-time errors in those files, which includes most strict errors, will be unaffected by this setting.
+
 .. index::
   single: config.php; Open Badges displayer sources
   single: config.php variables; openbadgedisplayer_source
@@ -172,6 +311,34 @@ renamecopies: Rename copied pages and collections
 
 The site administrator can decide to add "Copy of..." for copied pages and collections. If ``$cfg->renamecopies = true;``, copies of new pages and collections will have "Copy of" prepended to their titles. The default setting is ``$cfg->renamecopies = false;``.
 
+.. index::
+   single: config.php; Send all emails to one address)
+   single: config.php variables; sendemail
+
+.. _config_variable_sendemail:
+
+sendemail: Send all emails to one address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->sendemail = true;`` or ``$cfg->sendemail = false;``
+
+Decide whether you want to send emails from your instance of Mahara. If set to false, Mahara will not send any emails. This is useful when setting up a non-production instance of Mahara with real data where you don't want to accidentally send email to users from this particular Mahara instance.
+
+.. index::
+   single: config.php; Send all emails to one address)
+   single: config.php variables; sendallemailto
+
+.. _config_variable_sendallemailto:
+
+sendallemailto: Send all emails to one address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$cfg->sendallemailto = 'you@yourdomain';``
+
+You can use this setting to have all emails from this instance of Mahara sent to one particular email address instead of their real recipients. Leave ``$cfg->sendemail = true;`` if you want to use this setting.
+
+This setting is handy for test instances when you want to replicate an issue or test a new feature with real data, but do not want the users to receive notifications accidentally.
+
 .. index::
    single: config.php; Hide login sideblock (showloginsideblock)
    single: config.php variables; showloginsideblock