Location: PHPKode > scripts > DbProxy > dbproxy/assets/ParamsProxy.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>ParamsProxy Module -- Documentation</title>
</head>
<body>
<p><strong>Important Note</strong>: This class requires John Heinstein's <code>DOMIT! v. 1.01</code> library. It is recommended that you use supplied version whenever applicable.</p>
<h1>ParamsProxy</h1>
<h2>Description</h2>
<p>
  Takes an XML file as input, parses it, and sets parsed values to a given class instance, provided the class has appropriate public setter methods.
</p>
<h2>Features list</h2>
<ul>
  <li> Effectively separates <em>logic</em> from <em>setup</em>.</li>
  <li> Allows users with no PHP knowledge to perform setup of a PHP standalone module.</li>
  <li> Built with security in mind:
    <ul>
      <li> <strong>built-in protection against putting the XML file under the <em>Documents Root </em>folder.</strong>*<br />
        If user was allowed to place the XML file under the Documents Root folder, a person who knew the exact XML path could load it in a browser, which could lead to security issues;</li>
      <li> <strong>built-in protection against putting the XML file under the <em>Includes Path</em> folder.</strong><br />
        If user was allowed to place the XML file under the Includes Path folder, in shared hosting scenario, poor host setup could allow a different user to load the XML file without the need to know the file's exact path, merely guessing its name;</li>
      <li> <strong>cannot be used for setting arbitrary values to the <em>global scope</em></strong>.<br />
        The module requires a class instance to operate on;</li>
      <li><strong> cannot be used for altering arbitrary class values</strong>.<br />
        The class to be configured must provide appropriate public setter methods for the module to execute;</li>
      <li><strong> built-in protection against “hijacking” data in the configuration file</strong>.<br />
        The XML configuration file is redundantly bound to the class to be configured, both at module's core level and at XML file's level. If this wasn't the case, in a poorly designed multi-user portal scenario, where some users were granted PHP execution rights, a malicious user could trick the module into “configuring” some class of his own, thus accessing data in configuration files.</li>
    </ul>
  </li>
  <li><strong>Easy setup</strong>.<br />
    The module itself only requires a single parameter to be setup, that being the OS specific, absolute path on disk to the configuration folder.</li>
</ul>
<p>* the module cannot be used in shared hosting scenarios that do not provide users with a folder that is inaccessible from the web. This limitation is assumed.</p>
<h2>How it works</h2>
<p>The module is a Singleton (a single instance of the module's class is created per script lifetime).</p>
<p>Upon instantiation, the module looks for the<strong> [module class file path]/[module class file<br />
  name]_config.xml</strong> file and parses it for the value of the <em>configuration folder</em> parameter. If the value<br />
  of the <em>configuration folder </em>parameter fails to comply with any of the security constraints, fatal<br />
  errors are produced, forcing the developer to adjust the path properly.</p>
<p>Note: Possibly exposing the configuration folder parameter value does not essentially<br />
  involve a security issue, since the path of the configuration folder itself is not accessible<br />
  from the web anyway. If you want, you can prevent your web server from serving this file<br />
  using htaccess rules:</p>
<pre># protect the intrinsic configuration file
&lt;files <strong>[module class file path]/[module class file name]_config.xml</strong>&gt;
	order allow,deny
	deny from all
&lt;/files&gt;
</pre>
<h2>API</h2>
<p>The module provides a single public method, <code>configure(instance)</code>. Upon calling this method, the module will lookup, load and parse the XML file at <strong>[configuration folder path] / [<code>instance</code>'s class name]/config.xml</strong>.</p>
<p>Upon success, the values gathered from the XML file are set to the <code><strong>instance</strong></code><strong>'s class</strong> by calling appropriate setter methods. Upon failure fatal errors are produced, forcing the developer to investigate and fix the issues.</p>
<p>Setter names are to be deduced from parameter names, as set in the XML file. For example, given</p>
<pre>&lt;param&gt;
	&lt;name&gt;sessionLifetime&lt;/name&gt;
	&lt;value&gt;3600&lt;/value&gt;
&lt;/param&gt;
</pre>
<p>the module will attempt to call <em><code>instance</code></em> -&gt; <code>setSessionLifetime(3600)</code>; any failure beyond this point is handled by PHP – i.e., a fatal error will be produced if <code><strong>instance</strong></code><strong>'s class</strong> does not implement a <code>setSessionLifetime($seconds)</code> public method.</p>
<h2>XML format</h2>
<pre>&lt;config for=”myClassName”&gt;

    &lt;param&gt;
        &lt;name&gt;param1&lt;/name&gt;
        &lt;!-- Type can be one of: string, number, boolean, array, null,
           auto.
           If omitted, type defaults to “auto”, which is able to
           recognize automatically strings, numbers, booleans and
           the null value.
           The array type must be set explicitly.
           If type has been explicitly set to “null”, the &lt;value&gt;
           node can be omitted (or will be ignored anyway). --&gt;
        &lt;type&gt;string&lt;/type&gt;
        &lt;value&gt;Lorem ipsum dolor.&lt;/value&gt;
    &lt;/param&gt;

    &lt;param&gt;
        &lt;name&gt;myOtherParam1&lt;/name&gt;
        &lt;type&gt;string&lt;/type&gt;
        &lt;!-- The &lt;value&gt; node describing a “type” that is not “array”
           won't complain about unknown children nodes, but will
           silently discard them, only retaining their text
           inner content.
           This behaviour may change in future versions and one
           should not relay upon it.
           CDATA sections must be used in order to preserve HTML
           tags. --&gt;
        &lt;value&gt;
            &lt;![CDATA[
               &lt;p class=”demo”&gt;
                    &lt;strong&gt;HTML&lt;/strong&gt; text can be used as well!
               &lt;/p&gt;
            ]]&gt;
        &lt;/value&gt;
    &lt;/param&gt;

    &lt;param&gt;
        &lt;name&gt;param2&lt;/name&gt;
        &lt;type&gt;number&lt;/type&gt;
        &lt;value&gt;41.99&lt;/value&gt;
    &lt;/param&gt;

    &lt;param&gt;
        &lt;name&gt;param3&lt;/name&gt;
        &lt;type&gt;boolean&lt;/type&gt;
        &lt;value&gt;false&lt;/value&gt;
    &lt;/param&gt;

    &lt;param&gt;
        &lt;name&gt;param4&lt;/param&gt;
        &lt;type&gt;array&lt;/type&gt;
        &lt;!-- The array type requires an &lt;item&gt; node for each of its
           items. The &lt;item&gt; node provides two optional properties,
           “key” and “type”.
           The “key” property can be numeric or not.
           Note: only “pure” numeric strings (i.e., /^\d*$/)
           will be parsed into their integer counterparts.
           Note: all PHP array rules apply.
           The “type” property works similarly to the &lt;type&gt; node
           described earlier, with one notable exception: the value
           of the “type” property cannot be “array”.
           Note: if the value of the “type” property is
           “null”, the parent &lt;item&gt; node can omit its
           value (or will be ignored anyway). --&gt;
        &lt;value&gt;
            &lt;item&gt;apple&lt;/item&gt;
            &lt;item&gt;orange&lt;/item&gt;
            &lt;item&gt;banana&lt;/item&gt;
            &lt;item key=”5”&gt;pineapple&lt;/item&gt;
            &lt;item key=”myFavorite”&gt;grapes&lt;/item&gt;
            &lt;item key=42 type=”null” /&gt;
        &lt;/value&gt;
    &lt;/param&gt;

&lt;/config&gt;</pre>
</body>
</html>
Return current item: DbProxy