Make the 'debug' configuration option more fine-grained.

Some things, like logging of SAML messages or backtraces, are controlled with the 'debug' configuration option. However, it might be possible that we don't want one while we want the other, but that's impossible with just one option.

This commit allows us to configure debugging options independently, but groupping all of them together. This is particularly useful if we want to log backtraces to debug errors, for example, but we don't want to log SAML messages to keep the privacy of the users. This also allows us to get rid of the 'debug.validatexml' configuration option, and group it with other debug options.

This changes are backwards-compatible. Old and new configurations will work at the same time.

config-templates/config.php

@@ -145,16 +145,42 @@ $config = array(
      ************************/
 
     /*
-     * If you enable this option SimpleSAMLphp will log the following to the log file:
+     * The 'debug' option allows you to control how SimpleSAMLphp behaves in certain
+     * situations where further action may be taken
      *
-     * - All SAML messages sent and received.
-     * - Encrypted and decrypted SAML messages.
-     * - Backtraces on errors.
+     * It can be left unset, in which case, debugging is switched off for all actions.
+     * If set, it MUST be an array containing the actions that you want to enable, or
+     * alternatively a hashed array where the keys are the actions and their
+     * corresponding values are booleans enabling or disabling each particular action.
      *
-     * Note: The messages are logged with the DEBUG log level, so you also need to set
-     * the 'logging.level' option to LOG_DEBUG.
+     * SimpleSAMLphp provides some pre-defined actiones, though modules could add new
+     * actions here. Refer to the documentation of every module to learn if they
+     * allow you to set any more debugging actions.
+     *
+     * The pre-defined actions are:
+     *
+     * - 'saml': this action controls the logging of SAML messages exchanged with other
+     * entities. When enabled ('saml' is present in this option, or set to true), all
+     * SAML messages will be logged, including plaintext versions of encrypted
+     * messages.
+     *
+     * - 'backtraces': this action controls the logging of error backtraces. If you
+     * want to log backtraces so that you can debug any possible errors happening in
+     * SimpleSAMLphp, enable this action (add it to the array or set it to true).
+     *
+     * - 'validatexml': this action allows you to validate SAML documents against all
+     * the relevant XML schemas. SAML 1.1 messages or SAML metadata parsed with
+     * the XML to SimpleSAMLphp metadata converter or the metaedit module will
+     * validate the SAML documents if this option is enabled.
+     *
+     * If you want to disable debugging completely, unset this option or set it to an
+     * empty array.
      */
-    'debug' => false,
+    'debug' => array(
+        'saml' => false,
+        'backtraces' => true,
+        'validatexml' => false,
+    ),
 
     /*
      * When 'showerrors' is enabled, all error messages and stack traces will be output
@@ -174,12 +200,6 @@ $config = array(
      *   'errors.show_function' => array('sspmod_example_Error_Show', 'show'),
      */
 
-    /*
-     * This option allows you to enable validation of XML data against its
-     * schemas. A warning will be written to the log if validation fails.
-     */
-    'debug.validatexml' => false,
-
 
 
     /**************************

lib/SimpleSAML/Error/Exception.php

@@ -198,7 +198,14 @@ class SimpleSAML_Error_Exception extends Exception
      */
     protected function logBacktrace($level = \SimpleSAML\Logger::DEBUG)
     {
-        if (!SimpleSAML_Configuration::getInstance()->getBoolean('debug', false)) {
+        // see if debugging is enabled for backtraces
+        $debug = SimpleSAML_Configuration::getInstance()->getArrayize('debug', array('backtraces' => false));
+
+        if (!(in_array('backtraces', $debug, true) // implicitly enabled
+              || (array_key_exists('backtraces', $debug) && $debug['backtraces'] === true) // explicitly set
+              // TODO: deprecate the old style and remove it in 2.0
+              || (array_key_exists(0, $debug) && $debug[0] === true) // old style 'debug' configuration option
+        )) {
             return;
         }
 

lib/SimpleSAML/Utils/XML.php

@@ -14,7 +14,7 @@ class XML
 
     /**
      * This function performs some sanity checks on XML documents, and optionally validates them against their schema
-     * if the 'debug.validatexml' option is enabled. A warning will be printed to the log if validation fails.
+     * if the 'validatexml' debugging option is enabled. A warning will be printed to the log if validation fails.
      *
      * @param string $message The SAML document we want to check.
      * @param string $type The type of document. Can be one of:
@@ -41,8 +41,16 @@ class XML
             throw new \SimpleSAML_Error_Exception('XML contained a doctype declaration.');
         }
 
-        $enabled = \SimpleSAML_Configuration::getInstance()->getBoolean('debug.validatexml', null);
-        if (!$enabled) {
+        // see if debugging is enabled for XML validation
+        $debug = \SimpleSAML_Configuration::getInstance()->getArrayize('debug', array('validatexml' => false));
+        $enabled = \SimpleSAML_Configuration::getInstance()->getBoolean('debug.validatexml', false);
+
+        if (!(in_array('validatexml', $debug, true) // implicitly enabled
+              || (array_key_exists('validatexml', $debug) && $debug['validatexml'] === true) // explicitly enabled
+              // TODO: deprecate this option and remove it in 2.0
+              || $enabled // old 'debug.validatexml' configuration option
+        )) {
+            // XML validation is disabled
             return;
         }
 
@@ -84,9 +92,15 @@ class XML
             throw new \InvalidArgumentException('Invalid input parameters.');
         }
 
-        $globalConfig = \SimpleSAML_Configuration::getInstance();
-        if (!$globalConfig->getBoolean('debug', false)) {
-            // message debug disabled
+        // see if debugging is enabled for SAML messages
+        $debug = \SimpleSAML_Configuration::getInstance()->getArrayize('debug', array('saml' => false));
+
+        if (!(in_array('saml', $debug, true) // implicitly enabled
+              || (array_key_exists('saml', $debug) && $debug['saml'] === true) // explicitly enabled
+              // TODO: deprecate the old style and remove it in 2.0
+              || (array_key_exists(0, $debug) && $debug[0] === true) // old style 'debug'
+        )) {
+            // debugging messages is disabled
             return;
         }