From 744cfd50fb153d42cad9b978a1acd3b49b23725b Mon Sep 17 00:00:00 2001
From: Elijah Horton <fieryprophet@yahoo.com>
Date: Thu, 19 Jun 2014 11:54:38 -0400
Subject: [PATCH] - Updated documentation

---
 CHANGELOG.md                                  |   1 +
 MANUAL.html                                   | 131 ++++++++++++-
 README.md                                     |   2 +-
 src/Error.php                                 |   2 +-
 src/PHPSandbox.php                            | 172 +-----------------
 src/SandboxWhitelistVisitor.php               |   2 +-
 src/SandboxedString.php                       |   2 +-
 src/ValidatorVisitor.php                      |   2 +-
 src/WhitelistVisitor.php                      |   2 +-
 .../Tests/Config/DefaultConfigTest.php        |   7 +
 10 files changed, 150 insertions(+), 173 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 32d6d96..2cac5c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
 - Added flags to enable/disable validation checks for every type (for example, this will help in situations where someone wants to enable all functions but not blacklist a fake function name to remove the function whitelist.) Disabling a validation check also ignores any custom validation check for that type!
 - Fixed issue with toolkit giving incorrect error and exception messages
 - Added ability for sandbox to overwrite static type hints that are redefined to other class names (NOTE: All statically referenced class/interface/trait names are treated as classes by the parser and the sandbox, therefore they must be redefined via define_class())
+- Updated documentation
 
 ##05/06/2014
 - Corrected defined alias case-sensitivity issue (see: issue #10)
diff --git a/MANUAL.html b/MANUAL.html
index 6111d54..a74bd04 100644
--- a/MANUAL.html
+++ b/MANUAL.html
@@ -34,7 +34,7 @@ <h3>1 - About PHPSandbox &amp; PHPSandbox Toolkit</h3>
                 </a>
                 <br/>
                 <h1 style="margin: 0;">
-                    PHPSandbox Toolkit 1.3.6
+                    PHPSandbox Toolkit 1.3.7
                 </h1>
                 <br/>
                 <strong>Developed by: </strong> <a href="http://www.fieryprophet.com" target="_blank">Elijah Horton</a>
@@ -120,6 +120,135 @@ <h3>Options</h3>
             <pre>$sandbox->set_option('allow_functions', false);</pre>
             <h4>Option Descriptions</h4>
             <ul>
+                <li>
+                    <strong>Validate Functions: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate functions within the sandboxed code. If this flag is
+                    disabled then all function validation, including custom function validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Variables: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate variables within the sandboxed code. If this flag is
+                    disabled then all variable validation, including custom variable validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Globals: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate globals within the sandboxed code. If this flag is
+                    disabled then all global validation, including custom global validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Superglobals: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate superglobals within the sandboxed code. If this flag is
+                    disabled then all superglobal validation, including custom superglobal validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Constants: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate constants within the sandboxed code. If this flag is
+                    disabled then all constant validation, including custom constant validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Magic Constants: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate magic constants within the sandboxed code. If this flag is
+                    disabled then all magic constant validation, including custom magic constant validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Namespaces: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate namespaces within the sandboxed code. If this flag is
+                    disabled then all namespace validation, including custom namespace validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Aliases (aka Use): </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate aliases within the sandboxed code. If this flag is
+                    disabled then all alias validation, including custom alias validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Classes: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate classes within the sandboxed code. If this flag is
+                    disabled then all class validation, including custom class validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Interfaces: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate interfaces within the sandboxed code. If this flag is
+                    disabled then all interface validation, including custom interface validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Traits: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate traits within the sandboxed code. If this flag is
+                    disabled then all trait validation, including custom trait validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Keywords: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate keywords within the sandboxed code. If this flag is
+                    disabled then all keyword validation, including custom keyword validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Operators: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate operators within the sandboxed code. If this flag is
+                    disabled then all operator validation, including custom operator validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Primitives: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate primitives within the sandboxed code. If this flag is
+                    disabled then all primitive validation, including custom primitive validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Validate Types: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will validate types within the sandboxed code. If this flag is
+                    disabled then all type validation, including custom type validation, will be ignored.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Error Level: </strong> &mdash; Default Value: <em>null</em>
+                    <br/>
+                    If this option is set then sandbox will set the error level to this value before executing the sandboxed code.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Restore Error Level: </strong> &mdash; Default Value: <em>true</em>
+                    <br/>
+                    If this flag is set the sandbox will restore the error level after the sandboxed code has executed.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Convert Errors: </strong> &mdash; Default Value: <em>false</em>
+                    <br/>
+                    If this flag is set the sandbox will convert errors to exceptions during execution of the sandboxed code.
+                    <hr/>
+                </li>
+                <li>
+                    <strong>Capture Output: </strong> &mdash; Default Value: <em>false</em>
+                    <br/>
+                    If this flag is set the sandbox will return all output generated by the executed code.
+                    <hr/>
+                </li>
                 <li>
                     <strong>Auto Whitelist Trusted Code: </strong> &mdash; Default Value: <em>true</em>
                     <br/>
diff --git a/README.md b/README.md
index a432697..dcdc406 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ It also utilizes [FunctionParser](https://github.com/jeremeamia/FunctionParser)
 
 **Online API Documentation:** [http://fieryprophet.com/phpsandbox-docs/](http://fieryprophet.com/phpsandbox-docs/)
 
-[![Build Status](https://travis-ci.org/fieryprophet/php-sandbox.png?branch=master)](https://travis-ci.org/fieryprophet/php-sandbox) [![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/fieryprophet/php-sandbox/badges/quality-score.png?s=4f2d82525b9e2c6bae18e26cf643ca3fd09333fc)](https://scrutinizer-ci.com/g/fieryprophet/php-sandbox/) [![Code Coverage](https://scrutinizer-ci.com/g/fieryprophet/php-sandbox/badges/coverage.png?s=d6cef7d18a66d2ac39b76410b76c89fa15d84b8c)](https://scrutinizer-ci.com/g/fieryprophet/php-sandbox/) [![Latest Stable Version](https://poser.pugx.org/fieryprophet/php-sandbox/v/stable.png)](https://packagist.org/packages/fieryprophet/php-sandbox) [![Total Downloads](https://poser.pugx.org/fieryprophet/php-sandbox/downloads.png)](https://packagist.org/packages/fieryprophet/php-sandbox) [![Latest Unstable Version](https://poser.pugx.org/fieryprophet/php-sandbox/v/unstable.png)](https://packagist.org/packages/fieryprophet/php-sandbox) [![License](https://poser.pugx.org/fieryprophet/php-sandbox/license.png)](https://packagist.org/packages/fieryprophet/php-sandbox)
+[![Build Status](https://travis-ci.org/fieryprophet/php-sandbox.png?branch=master)](https://travis-ci.org/fieryprophet/php-sandbox) [![Latest Stable Version](https://poser.pugx.org/fieryprophet/php-sandbox/v/stable.png)](https://packagist.org/packages/fieryprophet/php-sandbox) [![Total Downloads](https://poser.pugx.org/fieryprophet/php-sandbox/downloads.png)](https://packagist.org/packages/fieryprophet/php-sandbox) [![Latest Unstable Version](https://poser.pugx.org/fieryprophet/php-sandbox/v/unstable.png)](https://packagist.org/packages/fieryprophet/php-sandbox) [![License](https://poser.pugx.org/fieryprophet/php-sandbox/license.png)](https://packagist.org/packages/fieryprophet/php-sandbox)
 
 ##Features:
 
diff --git a/src/Error.php b/src/Error.php
index a5496bd..399de63 100644
--- a/src/Error.php
+++ b/src/Error.php
@@ -11,7 +11,7 @@
      * @namespace PHPSandbox
      *
      * @author  Elijah Horton <fieryprophet@yahoo.com>
-     * @version 1.3.6
+     * @version 1.3.7
      */
     class Error extends \Exception {
         /* START ERROR CODES */
diff --git a/src/PHPSandbox.php b/src/PHPSandbox.php
index c98baa4..b86f392 100644
--- a/src/PHPSandbox.php
+++ b/src/PHPSandbox.php
@@ -14,7 +14,7 @@
      * @namespace PHPSandbox
      *
      * @author  Elijah Horton <fieryprophet@yahoo.com>
-     * @version 1.3.6
+     * @version 1.3.7
      */
     class PHPSandbox implements \IteratorAggregate {
         /**
@@ -772,155 +772,59 @@ public function set_option($option, $value = null){
             }
             $option = strtolower($option); //normalize option names
             switch($option){
-                case 'validate_functions':
-                    $this->validate_functions = $value ? true : false;
+                case 'error_level':
+                    $this->error_level = is_numeric($value) ? intval($value) : null;
                     break;
+                case 'validate_functions':
                 case 'validate_variables':
-                    $this->validate_variables = $value ? true : false;
-                    break;
                 case 'validate_globals':
-                    $this->validate_globals = $value ? true : false;
-                    break;
                 case 'validate_superglobals':
-                    $this->validate_superglobals = $value ? true : false;
-                    break;
                 case 'validate_constants':
-                    $this->validate_constants = $value ? true : false;
-                    break;
                 case 'validate_magic_constants':
-                    $this->validate_magic_constants = $value ? true : false;
-                    break;
                 case 'validate_namespaces':
-                    $this->validate_namespaces = $value ? true : false;
-                    break;
                 case 'validate_aliases':
-                    $this->validate_aliases = $value ? true : false;
-                    break;
                 case 'validate_classes':
-                    $this->validate_classes = $value ? true : false;
-                    break;
                 case 'validate_interfaces':
-                    $this->validate_interfaces = $value ? true : false;
-                    break;
                 case 'validate_traits':
-                    $this->validate_traits = $value ? true : false;
-                    break;
                 case 'validate_keywords':
-                    $this->validate_keywords = $value ? true : false;
-                    break;
                 case 'validate_operators':
-                    $this->validate_operators = $value ? true : false;
-                    break;
                 case 'validate_primitives':
-                    $this->validate_primitives = $value ? true : false;
-                    break;
                 case 'validate_types':
-                    $this->validate_types = $value ? true : false;
-                    break;
-                case 'error_level':
-                    $this->error_level = is_numeric($value) ? intval($value) : null;
-                    break;
                 case 'restore_error_level':
-                    $this->restore_error_level = $value ? true : false;
-                    break;
                 case 'convert_errors':
-                    $this->convert_errors = $value ? true : false;
-                    break;
                 case 'capture_output':
-                    $this->capture_output = $value ? true : false;
-                    break;
                 case 'auto_whitelist_trusted_code':
-                    $this->auto_whitelist_trusted_code = $value ? true : false;
-                    break;
                 case 'auto_whitelist_functions':
-                    $this->auto_whitelist_functions = $value ? true : false;
-                    break;
                 case 'auto_whitelist_constants':
-                    $this->auto_whitelist_constants = $value ? true : false;
-                    break;
                 case 'auto_whitelist_globals':
-                    $this->auto_whitelist_globals = $value ? true : false;
-                    break;
                 case 'auto_whitelist_classes':
-                    $this->auto_whitelist_classes = $value ? true : false;
-                    break;
                 case 'auto_whitelist_interfaces':
-                    $this->auto_whitelist_interfaces = $value ? true : false;
-                    break;
                 case 'auto_whitelist_traits':
-                    $this->auto_whitelist_traits = $value ? true : false;
-                    break;
                 case 'auto_define_vars':
-                    $this->auto_define_vars = $value ? true : false;
-                    break;
                 case 'overwrite_defined_funcs':
-                    $this->overwrite_defined_funcs = $value ? true : false;
-                    break;
                 case 'overwrite_sandboxed_string_funcs':
-                    $this->overwrite_sandboxed_string_funcs = $value ? true : false;
-                    break;
                 case 'overwrite_func_get_args':
-                    $this->overwrite_func_get_args = $value ? true : false;
-                    break;
                 case 'overwrite_superglobals':
-                    $this->overwrite_superglobals = $value ? true : false;
-                    break;
                 case 'allow_functions':
-                    $this->allow_functions = $value ? true : false;
-                    break;
                 case 'allow_closures':
-                    $this->allow_closures = $value ? true : false;
-                    break;
                 case 'allow_variables':
-                    $this->allow_variables = $value ? true : false;
-                    break;
                 case 'allow_static_variables':
-                    $this->allow_static_variables = $value ? true : false;
-                    break;
                 case 'allow_objects':
-                    $this->allow_objects = $value ? true : false;
-                    break;
                 case 'allow_constants':
-                    $this->allow_constants = $value ? true : false;
-                    break;
                 case 'allow_globals':
-                    $this->allow_globals = $value ? true : false;
-                    break;
                 case 'allow_namespaces':
-                    $this->allow_namespaces = $value ? true : false;
-                    break;
                 case 'allow_aliases':
-                    $this->allow_aliases = $value ? true : false;
-                    break;
                 case 'allow_classes':
-                    $this->allow_classes = $value ? true : false;
-                    break;
                 case 'allow_interfaces':
-                    $this->allow_interfaces = $value ? true : false;
-                    break;
                 case 'allow_traits':
-                    $this->allow_traits = $value ? true : false;
-                    break;
                 case 'allow_generators':
-                    $this->allow_generators = $value ? true : false;
-                    break;
                 case 'allow_escaping':
-                    $this->allow_escaping = $value ? true : false;
-                    break;
                 case 'allow_casting':
-                    $this->allow_casting = $value ? true : false;
-                    break;
                 case 'allow_error_suppressing':
-                    $this->allow_error_suppressing = $value ? true : false;
-                    break;
                 case 'allow_references':
-                    $this->allow_references = $value ? true : false;
-                    break;
                 case 'allow_backticks':
-                    $this->allow_backticks = $value ? true : false;
-                    break;
                 case 'allow_halting':
-                    $this->allow_halting = $value ? true : false;
+                    $this->{$option} = !!$value;
                     break;
             }
             return $this;
@@ -975,120 +879,56 @@ public function get_option($option){
             $option = strtolower($option);  //normalize option names
             switch($option){
                 case 'validate_functions':
-                    return $this->validate_functions;
-                    break;
                 case 'validate_variables':
-                    return $this->validate_variables;
-                    break;
                 case 'validate_globals':
-                    return $this->validate_globals;
-                    break;
                 case 'validate_superglobals':
-                    return $this->validate_superglobals;
-                    break;
                 case 'validate_constants':
-                    return $this->validate_constants;
-                    break;
                 case 'validate_magic_constants':
-                    return $this->validate_magic_constants;
-                    break;
                 case 'validate_namespaces':
-                    return $this->validate_namespaces;
-                    break;
                 case 'validate_aliases':
-                    return $this->validate_aliases;
-                    break;
                 case 'validate_classes':
-                    return $this->validate_classes;
-                    break;
                 case 'validate_interfaces':
-                    return $this->validate_interfaces;
-                    break;
                 case 'validate_traits':
-                    return $this->validate_traits;
-                    break;
                 case 'validate_keywords':
-                    return $this->validate_keywords;
-                    break;
                 case 'validate_operators':
-                    return $this->validate_operators;
-                    break;
                 case 'validate_primitives':
-                    return $this->validate_primitives;
-                    break;
                 case 'validate_types':
-                    return $this->validate_types;
-                    break;
                 case 'error_level':
-                    return $this->error_level;
                 case 'restore_error_level':
-                    return $this->restore_error_level;
                 case 'convert_errors':
-                    return $this->convert_errors;
                 case 'capture_output':
-                    return $this->capture_output;
                 case 'auto_whitelist_trusted_code':
-                    return $this->auto_whitelist_trusted_code;
                 case 'auto_whitelist_functions':
-                    return $this->auto_whitelist_functions;
                 case 'auto_whitelist_constants':
-                    return $this->auto_whitelist_constants;
                 case 'auto_whitelist_globals':
-                    return $this->auto_whitelist_globals;
                 case 'auto_whitelist_classes':
-                    return $this->auto_whitelist_classes;
                 case 'auto_whitelist_interfaces':
-                    return $this->auto_whitelist_interfaces;
                 case 'auto_whitelist_traits':
-                    return $this->auto_whitelist_traits;
                 case 'auto_define_vars':
-                    return $this->auto_define_vars;
                 case 'overwrite_defined_funcs':
-                    return $this->overwrite_defined_funcs;
                 case 'overwrite_sandboxed_string_funcs':
-                    return $this->overwrite_sandboxed_string_funcs;
                 case 'overwrite_func_get_args':
-                    return $this->overwrite_func_get_args;
                 case 'overwrite_superglobals':
-                    return $this->overwrite_superglobals;
                 case 'allow_functions':
-                    return $this->allow_functions;
                 case 'allow_closures':
-                    return $this->allow_closures;
                 case 'allow_variables':
-                    return $this->allow_variables;
                 case 'allow_static_variables':
-                    return $this->allow_static_variables;
                 case 'allow_objects':
-                    return $this->allow_objects;
                 case 'allow_constants':
-                    return $this->allow_constants;
                 case 'allow_globals':
-                    return $this->allow_globals;
                 case 'allow_namespaces':
-                    return $this->allow_namespaces;
                 case 'allow_aliases':
-                    return $this->allow_aliases;
                 case 'allow_classes':
-                    return $this->allow_classes;
                 case 'allow_interfaces':
-                    return $this->allow_interfaces;
                 case 'allow_traits':
-                    return $this->allow_traits;
                 case 'allow_generators':
-                    return $this->allow_generators;
                 case 'allow_escaping':
-                    return $this->allow_escaping;
                 case 'allow_casting':
-                    return $this->allow_casting;
                 case 'allow_error_suppressing':
-                    return $this->allow_error_suppressing;
                 case 'allow_references':
-                    return $this->allow_references;
                 case 'allow_backticks':
-                    return $this->allow_backticks;
                 case 'allow_halting':
-                    return $this->allow_halting;
+                    return $this->{$option};
             }
             return null;
         }
diff --git a/src/SandboxWhitelistVisitor.php b/src/SandboxWhitelistVisitor.php
index 195e940..93af748 100644
--- a/src/SandboxWhitelistVisitor.php
+++ b/src/SandboxWhitelistVisitor.php
@@ -13,7 +13,7 @@
      * @namespace PHPSandbox
      *
      * @author  Elijah Horton <fieryprophet@yahoo.com>
-     * @version 1.3.6
+     * @version 1.3.7
      */
     class SandboxWhitelistVisitor extends \PHPParser_NodeVisitorAbstract {
         /** The PHPSandbox instance to check against
diff --git a/src/SandboxedString.php b/src/SandboxedString.php
index b98fca8..09fe184 100644
--- a/src/SandboxedString.php
+++ b/src/SandboxedString.php
@@ -11,7 +11,7 @@
      * @namespace PHPSandbox
      *
      * @author  Elijah Horton <fieryprophet@yahoo.com>
-     * @version 1.3.6
+     * @version 1.3.7
      */
     class SandboxedString implements \ArrayAccess, \IteratorAggregate {
         /**
diff --git a/src/ValidatorVisitor.php b/src/ValidatorVisitor.php
index 937ea10..be682f4 100644
--- a/src/ValidatorVisitor.php
+++ b/src/ValidatorVisitor.php
@@ -13,7 +13,7 @@
      * @namespace PHPSandbox
      *
      * @author  Elijah Horton <fieryprophet@yahoo.com>
-     * @version 1.3.6
+     * @version 1.3.7
      */
     class ValidatorVisitor extends \PHPParser_NodeVisitorAbstract {
         /** The PHPSandbox instance to check against
diff --git a/src/WhitelistVisitor.php b/src/WhitelistVisitor.php
index 41464ef..76beb1a 100644
--- a/src/WhitelistVisitor.php
+++ b/src/WhitelistVisitor.php
@@ -13,7 +13,7 @@
      * @namespace PHPSandbox
      *
      * @author  Elijah Horton <fieryprophet@yahoo.com>
-     * @version 1.3.6
+     * @version 1.3.7
      */
     class WhitelistVisitor extends \PHPParser_NodeVisitorAbstract {
         /** The PHPSandbox instance to check against
diff --git a/tests/PHPSandbox/Tests/Config/DefaultConfigTest.php b/tests/PHPSandbox/Tests/Config/DefaultConfigTest.php
index 4def360..ea3dc72 100644
--- a/tests/PHPSandbox/Tests/Config/DefaultConfigTest.php
+++ b/tests/PHPSandbox/Tests/Config/DefaultConfigTest.php
@@ -18,6 +18,13 @@ public function setUp(){
             $this->sandbox = new PHPSandbox;
         }
 
+        public function testSettingAndUnsettingOptions(){
+            $this->sandbox->set_option('error_level', 1);
+            $this->assertEquals(1, $this->sandbox->get_option('error_level'));
+            $this->sandbox->set_option('error_level', null);
+            $this->assertEquals(null, $this->sandbox->get_option('error_level'));
+        }
+
         /**
          * Test whether sandbox returns expected value
          */