PHP Labware source code viewer / Internal utilities | 19 Apr, 2024
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Language" content="en" />
<meta name="description" content="Sourceer code / file / directory browser / viewer - sourceer_README.txt - presented with rTxt2htm, a PHP Labware utility" />
<meta name="keywords" content="Sourceer, readme, help, documentation, usage, configuration, code, file, directory browser, viewer, PHP, Labware, sourceer_README.txt, rTxt2htm, PHP Labware, SVN alternative, CVS alternative, PHP documentation, PHPDoc alternative, Trac alternative, Doxygen alternative, sourceer_README.txt, rTxt2htm, PHP Labware" />
<style type="text/css" media="all">
<!--/*--><![CDATA[/*><!--*/
a {text-decoration:none; color: blue;}
a:hover {color: red;}
a:visited {color: blue;}
body {margin: 0; padding: 0;}
body, div, html, p {font-family: Georgia, 'Times new roman', Times;}
code.code {font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
div.comment {padding: 5px; color: #999999; font-size: 80%;}
div.comment a {color: #6699cc;}
div#body {width: 70%; margin: 5px; padding: 5px;} /* holds non-toc content */
div#toc {position: fixed; top: 5px; left: 73%; z-index: 2; margin-top: 5px; margin-left: 5px; border: 1px solid gray; padding: 5px; background-color: #ededed; width: 23%; overflow: auto; max-height:94%; font-size: 90%;} /* holds content table (toc) */
div#top {font-size: 14px; margin: 5px; padding: 5px;} /* holds all content */
div.monospace {overflow: auto; font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
div.sub-section {padding-left: 15px;}
div.sub-sub-section {padding-left: 30px;}
h1 {font-size: 22px; margin-top: 5px; margin-bottom: 5px;}
h2 {font-size: 20px; float: left; margin-top: 15px; margin-bottom: 5px;}
h3 {font-size: 18px; float: left; margin-top: 15px; margin-bottom: 5px;}
h4 {font-size: 16px; float: left; margin-top: 15px; margin-bottom: 5px;}
hr {margin-top: 15px; margin-bottom: 5px;}
input, textarea {font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
p.subtle {color: gray; padding: 0; padding-top: 10px; margin: 0;}
p.subtle a, p.subtle a:visited {color: #6699cc;}
span.item-no {color: black;}
span.subtle {color: gray; margin: 0; padding:0;}
span.subtle a, span.subtle a:visited {color: #6699cc;}
span.term {font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
span.toc-item {color: black;}
span.totop {float: right; margin-top: 15px; margin-bottom: 5px;}
span.totop a, span.totop a:visited {color: #6699cc;}
@media screen { /* fixes for old IE */
* html, * html body {overflow-y: auto!important; height: 100%; margin: 0; padding: 0;}
* html div#body {height: 100%; overflow-y: auto; position: relative;}
* html div#toc {position: absolute;}
}
/*]]>*/-->
</style>
<title>Sourceer documentation | Sourceer code / file / directory browser / viewer</title>
</head>
<body>
<div id="top">
<h1><a id="peak" name="peak"></a>Sourceer documentation</h1>
<div id="toc"><span class="toc-item"><a href="#s1"><span class="item-no">1</span>  About</a></span><br />
<span class="toc-item"><a href="#s2"><span class="item-no">2</span>  Usage</a></span><br />
  <span class="toc-item"><a href="#s2.1"><span class="item-no">2.1</span>  Basic</a></span><br />
  <span class="toc-item"><a href="#s2.2"><span class="item-no">2.2</span>  Advanced</a></span><br />
    <span class="toc-item"><a href="#s2.2.1"><span class="item-no">2.2.1</span>  Authentication and security</a></span><br />
    <span class="toc-item"><a href="#s2.2.2"><span class="item-no">2.2.2</span>  Parameters</a></span><br />
    <span class="toc-item"><a href="#s2.2.3"><span class="item-no">2.2.3</span>  Returned values</a></span><br />
    <span class="toc-item"><a href="#s2.2.4"><span class="item-no">2.2.4</span>  Layout and style</a></span><br />
    <span class="toc-item"><a href="#s2.2.5"><span class="item-no">2.2.5</span>  Non-Sourceer file security</a></span><br />
<span class="toc-item"><a href="#s3"><span class="item-no">3</span>  Other</a></span><br />
  <span class="toc-item"><a href="#s3.1"><span class="item-no">3.1</span>  Upgrade</a></span><br />
  <span class="toc-item"><a href="#s3.2"><span class="item-no">3.2</span>  Change-log</a></span><br />
  <span class="toc-item"><a href="#s3.3"><span class="item-no">3.3</span>  Support</a></span><br />
  <span class="toc-item"><a href="#s3.4"><span class="item-no">3.4</span>  Known issues</a></span><br />
  <span class="toc-item"><a href="#s3.5"><span class="item-no">3.5</span>  Donate</a></span></div><!-- ended div toc -->
<div id="body">
<br />
<div class="comment">sourceer_README.txt<br />
Sourceer 1.3.2, 5 July 2022<br />
Source code viewer<br />
Copyright Santosh Patnaik<br />
GPL v3 license<br />
A PHP Labware internal utility - <a href="https://bioinformatics.org/phplabware/internal_utilities">https://bioinformatics.org/phplabware/internal_utilities</a> </div>
<br />
Download latest version from <a href="https://bioinformatics.org/phplabware/downloads/sourceer.zip">https://bioinformatics.org/phplabware/downloads/sourceer.zip</a><br />
<div class="section"><h2>
<a name="s1" id="s1"></a><span class="item-no">1</span>  About
</h2><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Sourceer is a highly configurable, single-file PHP software for web-based browsing of directory contents, with options to view source code of specified file-types or download them. File-sizes and last-modification dates are indicated if so optioned. Directory contents are listed alphabetically, with files grouped by file-types, but can be sorted by size or age. Source code display, by default, uses PHP's syntax highlighting function. However, other means such as the server-side, PHP-based <span class="term">Geshi</span>, or the client-side, Javascript-based <span class="term">dpSyntaxHighlighter</span> scripts can easily be used.<br />
<br />
Among other things, Sourceer is useful for presenting contents of software projects (a much simple alternative to <span class="term">Trac</span>, <span class="term">PHPDoc</span>, <span class="term">Doxygen</span>, SVN/CVS systems, etc.). Sourceer was developed at PHP Labware (<a href="https://bioinformatics.org/phplabware">https://bioinformatics.org/phplabware</a>) for this purpose. Sourceer's original code was based on Stuart Montgomery's <span class="term">DirPHP</span> v1.0 code.<br />
<br />
Easy integrability and high customizability set Sourceer apart from other such software.<br />
</div>
<div class="section"><h2>
<a name="s2" id="s2"></a><span class="item-no">2</span>  Usage
</h2><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<div class="sub-section"><h3>
<a name="s2.1" id="s2.1"></a><span class="item-no">2.1</span>  Basic
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Sourceer works with <strong>PHP versions 5 and above</strong>. Put <span class="term">sourceer.php</span> in the directory that is to be browsed. Change parameter values at top if desired -- see <a href="#s2.2.2">section 2.2.2</a>. Change layout and style if desired -- see <a href="#s2.2.4">section 2.2.4</a>. Also see <a href="#s2.2.1">section 2.2.1</a> for authentication setup, and <a href="#s2.2.5">section 2.2.5</a> for file-security measures.<br />
</div>
<div class="sub-section"><h3>
<a name="s2.2" id="s2.2"></a><span class="item-no">2.2</span>  Advanced
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
For formatting of source code (<strong>syntax highlighting</strong>, etc.) using <span class="term">Geshi</span>, etc., instead of Sourceer (which uses PHP's <span class="term">highlight_string</span> function) set the <span class="term">hiliter</span> parameter of <span class="term">$cfg</span> to the name of your custom PHP function to use. The function is passed the raw file source and some other parameters by Sourceer, and it is expected to return the formatted code along with optional CSS, Javascript or HTML footer content to Sourceer. Refer to the description for <span class="term">hiliter</span> in <a href="#s2.2.2">section 2.2.2</a>.<br />
<br />
An example of such <em>external</em> highlighting using <a href="http://mihai.bazon.net/projects/javascript-syntax-highlighting-engine">this</a> Javascript-based syntax highlighter:<br />
<br />
<code class="code">    ...</code>
<br />
<code class="code">    $cfg['hiliter'] = 'myHl';</code>
<br />
<code class="code">    ...</code>
<br />
<code class="code">    function myHl($in, $type, $path, $enc){</code>
<br />
<br />
<code class="code">     // Let Sourceer handle .txt file-type.</code>
<br />
<code class="code">     // Also we want only .css and .js handled this way.</code>
<br />
<br />
<code class="code">     if($type == 'txt' or ($type != 'css' and $type != 'js)){</code>
<br />
<code class="code">      return 0;</code>
<br />
<code class="code">     }</code>
<br />
<br />
<code class="code">     // Long code is too resource-intensive to syntax-highlight.</code>
<br />
<code class="code">     // Just return as plain-formatted, preserving white-spaces.</code>
<br />
<br />
<code class="code">     if(isset($in[30000])){</code>
<br />
<code class="code">      return array(str_replace(array('<br />', '<br>', '&nbsp;', "\n ", '  '), array("\n<br />\n", "\n<br>\n", ' ', "\n&nbsp;", ' &nbsp;'), "\n". nl2br(htmlspecialchars($in, ENT_COMPAT, $enc))));</code>
<br />
<code class="code">     }</code>
<br />
<br />
<code class="code">     // Return array with formatted code, style and script declarations, etc.</code>
<br />
<br />
<code class="code">     return array(</code>
<br />
<br />
<code class="code">      // Formatted code</code>
<br />
<br />
<code class="code">      0 => '<pre name="code" class="'. $type. '">'. htmlspecialchars($in, ENT_COMPAT, $enc). '</pre>',</code>
<br />
<br />
<code class="code">      // Additional CSS style declaration for HTML head</code>
<br />
<br />
<code class="code">      1 => '<link rel="stylesheet" type="text/css" href="style.css" />',</code>
<br />
<br />
<code class="code">      // Additional Javascript declaration for HTML head</code>
<br />
<br />
<code class="code">      2 => '<script type="text/javascript" src="hl-all.js"></script>',</code>
<br />
<br />
<code class="code">      // Additional HTML declaration for HTML foot</code>
<br />
<br />
<code class="code">      3 => '<script type="text/javascript">DlHighlight.HELPERS.highlightByName("code", "pre");</script>'</code>
<br />
<br />
<code class="code">     );</code>
<br />
<code class="code">    }</code>
<br />
<br />
<br />
You can copy the <span class="term">Sourceer</span> class and use it like using <span class="term">sourceer.php</span>. Also, the <span class="term">sourceer.php</span> file itself can be included in another script. Output of <span class="term">sourceer.php</span> can be obtained by including the file -- <span class="term">include("path/to/sourceer.php")</span> -- and then using such two lines of code either in the parent script or in <span class="term">sourceer.php</span> itself:<br />
<br />
<code class="code">    $var = new Sourceer($sec_dirs, $sec_files, $src_filetypes, $cfg, $presrc);</code>
<br />
<code class="code">    $var->work();</code>
<br />
<br />
<br />
For displaying the Sourceer output <em>later</em>, use output buffering functions. E.g.:<br />
<br />
<code class="code">    $sourceer = new Sourceer($a, $b, $c, $d);</code>
<br />
<code class="code">    ob_start();</code>
<br />
<code class="code">    $sourceer->work();</code>
<br />
<code class="code">    $sourceer_out = ob_get_contents;</code>
<br />
<code class="code">    ob_end_clean();</code>
<br />
<code class="code">    ...</code>
<br />
<code class="code">    echo $sourceer_out;</code>
<br />
<br />
<br />
The arguments <span class="term">$sec_dirs</span>, <span class="term">$sec_files</span>, <span class="term">$src_filetypes</span>, and <span class="term">$cfg</span> should be in the form of arrays (the arrays themselves can be empty; one or more elements of the <span class="term">$cfg</span> array may not be defined -- see note on <span class="term">parameter values</span> below).<br />
<br />
<br />
All code in sourceer.php that is between the <span class="term"><?php</span> and the class definition can be removed, and one can use the Sourceer class code like so in the parent script:<br />
<br />
<code class="code">    $out = new Sourceer(array(), array('.htaccess'), array('php'), array('root'=>'../pics/nat', 'head'=>'<table id="S">', 'foot'=>'</table>'), 0);</code>
<br />
<code class="code">    $out->work();</code>
<br />
<br />
<br />
$cfg parameters can also be passed using <span class="term">set_cfg()</span> once the Sourceer object is created. Thus, e.g.,<br />
<br />
<code class="code">    $out = new Sourceer(array(), array('.htaccess'), array('php'), array('root'=>'../pics/nat', 'head'=>'<table id="S">', 'foot'=>'</table>'), 0);</code>
<br />
<code class="code">    $sourceer->set_cfg('dl', 0);</code>
<br />
<code class="code">    $out->work();</code>
<br />
<div class="sub-sub-section"><h4>
<a name="s2.2.1" id="s2.2.1"></a><span class="item-no">2.2.1</span>  Authentication and security
</h4><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
There is only one user level for Sourceer. That is, all parameters are applied similarly to all. However, access can be allowed to only those providing the correct password, or, optionally, those at a permitted IP address. See <a href="#s2.2.2">section 2.2.2</a> for more.<br />
<br />
To secure (hide or limit access to) certain files/directories, set the appropriate parameters (<a href="#s2.2.2">section 2.2.2</a>).<br />
<br />
Sourceer filters the URL query string (<span class="term">$_GET</span>) values for filenames, so one cannot attempt to move up-root using strings like <span class="term">/..</span> or <span class="term">//</span>. If up-root traversal is permitted (<a href="#s2.2.2">section 2.2.2</a>), then one may use the string <span class="term">/..</span> in the <span class="term">Sl</span> parameter of the query string.<br />
<br />
Also see <a href="#s2.2.5">section 2.2.5</a>.<br />
</div>
<div class="sub-sub-section"><h4>
<a name="s2.2.2" id="s2.2.2"></a><span class="item-no">2.2.2</span>  Parameters
</h4><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Valid PHP code can be used for the parameter values.<br />
<br />
<strong>$src_filetypes</strong><br />
<br />
Specifies file-types (extensions) whose source code is viewable. Such files are optionally downloadable as well. It is an array of key-value pairs where the keys are lower-cased extension names and the values are file-types, like <span class="term">array("php"=>"php", "php4"=>"php", "htaccess"=>"txt", "txt"=>"txt", "js"=>"js")</span>. Thus, as per this example, an <span class="term">.htaccess</span> file and a <span class="term">hello.txt</span> file both have the <span class="term">txt</span> file-type (but different file-extensions -- <span class="term">.htaccess</span> and <span class="term">.txt</span>). An empty key <span class="term">""</span> can be used to refer to files that have no extension (<span class="term">""=>"txt"</span>).<br />
<br />
Note that other file-types (e.g., <span class="term">jpg</span>) are <em>downloadable</em> as well (but not through Sourceer/PHP) as links shown for such files can be clicked on for the browser to receive.<br />
<br />
<strong>$sec_files</strong><br />
<br />
Specifies <em>secured</em> files that, depending on <span class="term">$cfg</span>, may not be listed or looked into. Elements are paths to such files relative to the root (<span class="term">$cfg["root"]</span>) directory. E.g., <span class="term">array("./.htaccess", "../.htaccess", "./pics/.HTACCESS")</span>.<br />
<br />
You can use PHP PCRE-compatible regular expressions to indicate many filenames in a simpler way. To do so, put this in the array: <span class="term">array("x", "y", ...)</span> where <span class="term">x</span>, <span class="term">y</span>, etc., are the expression patterns with delimiters. E.g., <span class="term">array("./.htaccess", "../.htaccess", "./pics/.HTACCESS", array("!\.htaccess$!i", "!\.ini$!i"))</span>. The expression patterns should be PHP/PCRE-compatible and should use the exclamation mark (<span class="term">!</span>) as the delimiter.<br />
<br />
To secure the <span class="term">sourceer.php</span> file itself, either set the root directory below <span class="term">sourceer.php</span> and turn off up-root browsing (see <span class="term">$cfg</span> below), or put the relative path to <span class="term">sourceer.php</span> in <span class="term">$sec_files</span>.<br />
<br />
<strong>$sec_dir</strong><br />
<br />
Similar to <span class="term">$sec_files</span> but for directories<br />
<br />
   Consider this file structure:<br />
<br />
<div class="monospace"><br />
      __________dir___www___pics___.HTACCESS<br />
      |         |     |<br />
      |___x.ini |     |___.htaccess<br />
                |     |<br />
                |     |___sourceer.php<br />
                |<br />
                |___.htaccess<br />
</div>
<br />
   Here, sourceer.php is in <span class="term">dir/www/</span> and if the <span class="term">$cfg</span> <span class="term">root</span> parameter (more below) is set to <span class="term">.</span>, then the effective root is <span class="term">www</span>. With the <span class="term">$sec_files</span> set to <span class="term">array("./.htaccess", "../.htaccess", "./pics/.HTACCESS", array("!\.htaccess$!i", "!\.ini$!i"))</span>, <span class="term">www/.htaccess</span> and <span class="term">www/pics/.HTACCESS</span> are both secured. Even if there is no <span class="term">./../.htaccess</span> in the array, the file <span class="term">dir/.htaccess</span> is secure, like all files in <span class="term">dir/</span> if the <span class="term">up_root</span> parameter is set to <span class="term">0</span>.<br />
<br />
   However, if <span class="term">up_root</span> is <span class="term">1</span>, then unlike other files in <span class="term">dir/</span>, the <span class="term">.htaccess</span> file gets secured. With <span class="term">$sec_dirs</span> set to <span class="term">array("./pics")</span>, or to <span class="term">array(array("\pics$\"))</span>, <span class="term">www/pics/</span> is secured.<br />
<br />
   The file <span class="term">x.ini</span> at <span class="term">./../..</span> can be secured by having <span class="term">up_root</span> set to <span class="term">0</span> (most restrictive), or the element <span class="term">array("`(^|\.)/../..(/|$)`")</span> in <span class="term">$sec_dirs</span> (less restrictive), or the element <span class="term">./../../x.ini</span> in <span class="term">$sec_files</span> (least restrictive). There are obviously many other possibilities with different levels of restrictiveness.<br />
<br />
<strong>$cfg</strong><br />
<br />
Specifies settings. It is an array with none, one or more of following elements with user-settable values. When the elements are not specified, Sourceer uses certain default values.<br />
<br />
   <span class="term">auth</span> - <span class="term">1</span> if a password is needed unless the user's IP address is in the <span class="term">ok_ips</span> array. The MD5 hash of the password prefixed with <span class="term">sourceer</span> is specified in <span class="term">hash</span>. Default: <span class="term">0</span><br />
<br />
   <span class="term">base</span> - base URL. E.g., <span class="term">http://domain.com/sourceer.php</span>, <span class="term">sourceer.php</span>, <span class="term">https://localhost</span>, etc. It can have a query string. E.g., <span class="term">http://domain.com/index.php?page=codes&guest=1</span> (note the <span class="term">&</span> is not <span class="term">&amp;</span> -- don't use entities). Default: code to auto-determine correct URL<br />
<br />
   <span class="term">charset</span> - character encoding, for HTML rendering purposes only. Probably best if set to encoding used the server's filesystem. Default: <span class="term">utf-8</span><br />
<br />
   <span class="term">compress</span> - gzip-compress output to reduce bandwidth. Sourceer will auto-check other parameters (e.g., if browser accepts compressed content). To turn off, set to <span class="term">0</span>. Default: <span class="term">1</span><br />
<br />
   <span class="term">css</span> - style declarations. If not set, or set to <span class="term">0</span>, default is used. If set as an array, like <span class="term">array("div.p {color: red;}")</span>, will get appended to default CSS. Default: (complete declarations)<br />
<br />
   <span class="term">cookie</span> - cookie name to use; needed when using password for authentication; used for auto-login for password-authentication if the user revisits within an hour. Default: <span class="term">sourceer</span><br />
<br />
   <span class="term">date_type</span> - specifies the date format; should be compatible with PHP's <span class="term">date()</span> function (like <span class="term">m-d-y</span>). Default: <span class="term">m/d/y</span><br />
<br />
   <span class="term">dl</span> - <span class="term">1</span> if <span class="term">$src_filetypes</span> files can be downloaded. Default: <span class="term">1</span><br />
<br />
   <span class="term">file_info</span> - <span class="term">0</span> if file-sizes and modification times are not to be shown. Default: <span class="term">1</span><br />
<br />
   <span class="term">foot</span> - HTML string to append to the output. Can be empty, <span class="term"></body></html></span>, etc. If not set, or set to <span class="term">0</span>, default is used. If set as an array, like <span class="term">array("<p>Home</p>")</span>, will get prepended to default foot. Default: <span class="term"></div></body></html></span><br />
<br />
   <span class="term">hash</span> - see <span class="term">auth</span>. Default: MD5 hash of <span class="term">sourceerpass</span> (i.e., default password is <span class="term">pass</span>)<br />
<br />
   <span class="term">head</span> - HTML string to prepend to the output. Can be empty, full-blown HTML like <span class="term"><html>...</head><body></span>, etc. If not set, or set to <span class="term">0</span>, default is used. If set otherwise, the string <span class="term">_Sourceer_dynamic_title_</span> can be used in the text, and Sourceer will replace it with a dynamically generated, page context-specific short title (useful for the HTML <span class="term">title</span> element). If set as an array, like <span class="term">array("<p>Home</p>")</span>, will get appended to default head. Default: (with HTML doctype, CSS declarations, etc.)<br />
<br />
   <span class="term">hiliter</span> - name of a custom highlighting function to use for syntax-highlighting of source codes. The function must be defined somewhere. If not, or if <span class="term">hiliter</span> is set to <span class="term">0</span>, syntax-highlighting for PHP code will be done using PHP's highlighting function.; other types of code will be formatted for view but will not be syntax-highlighted. The <span class="term">hiliter</span> function will be passed four arguments (in this order): the raw source code, the file-type, the file-path and the character-encoding being used on the web-page that will display the code. The function is expected to return an array with four non-keyed elements (in this order): the formatted code (with HTML, if any), any CSS declarations (or <span class="term">style</span> elements) to add to the web-page displaying the code, any Javascript code for a similar purpose, and any text/HTML to prepend to the footer of the web-page (can be HTML code, plain text, Javascript code, etc.). Default: <span class="term">0</span>.<br />
<br />
   <span class="term">js</span> - like for <span class="term">CSS</span> above.<br />
<br />
   <span class="term">lang</span> - language; RFC3066 specified-values such as <span class="term">en</span> for English; used for HTML language specification only (not user interface) Default: <span class="term">en</span><br />
<br />
   <span class="term">ok_ips</span> - see <span class="term">auth</span>. Default: <span class="term">array()</span><br />
<br />
   <span class="term">query_plus</span> - string to append to URLs. E.g., if sourceer.php is used at URL <span class="term">domain.com/wiki.php?page=home</span>, you may want to set it to <span class="term">page=home</span>. Don't use entities. Thus, e.g., <span class="term">page=home&category=<main></span> and not <span class="term">page=home&amp;category=&lt;main&gt;</span>. Default: ''<br />
<br />
   <span class="term">root</span> - root directory for browsing. Use <span class="term">.</span> if same as <span class="term">sourceer.php</span> (or the parent script when <span class="term">sourceer.php</span> is included), or <span class="term">./..</span> for the directory above it. Or, e.g., <span class="term">./../../dir2</span> where <span class="term">dir2</span> is an <span class="term">uncle</span> directory. Don't use trailing or leading slashes, double slashes or backslashes. Default: <span class="term">.</span><br />
<br />
   <span class="term">sec_check_off</span> - <span class="term">1</span> to turn off checking if files/directories are secured (to be hidden). Default: <span class="term">0</span><br />
<br />
   <span class="term">sec_dir_into</span> - <span class="term">1</span> if <span class="term">$secure_dirs</span> can be looked into. Default: <span class="term">0</span><br />
<br />
   <span class="term">sec_dir_list</span> - <span class="term">1</span> if <span class="term">$secure_dirs</span> are to be shown listed in directory content lists. Default: <span class="term">0</span><br />
<br />
   <span class="term">sec_file_dl</span> - <span class="term">1</span> if <span class="term">$sec_files</span> can be downloaded. Default: <span class="term">0</span><br />
<br />
   <span class="term">sec_file_list</span> - <span class="term">1</span> if '$sec_file's can be listed (shown). Default: <span class="term">0</span><br />
<br />
   <span class="term">sec_file_src</span> - 1 if source code of <span class="term">$sec_files</span> can be viewed. Default: <span class="term">0</span><br />
<br />
   <span class="term">src</span> - <span class="term">1</span> to turn on source code viewing of <span class="term">$src_filetypes</span> files. Default: <span class="term">1</span><br />
<br />
   <span class="term">timeout</span> - time limit for script to execute (when sending downloads, any time-limit is always ignored). Default: <span class="term">300</span><br />
<br />
   <span class="term">title</span> - a title for the Sourceer pages. HTML entities may or may not be used. Default: <span class="term">Sourceer file and code viewer</span><br />
<br />
   <span class="term">up_root</span>  - <span class="term">1</span> allows move to higher levels than <span class="term">root</span> using <span class="term">/..</span> in the <span class="term">Sl</span> parameter in the query string of the URL (e.g. <span class="term">sourceer.php?Sl=../../dir3&Sd=file3</span>). Irrespective of the setting, specifying files to download/source-view using <span class="term">..</span> is not allowed. Runs of <span class="term">/</span>, like <span class="term">//</span> and <span class="term">///</span>, are always reduced to <span class="term">/</span>. Default: <span class="term">0</span><br />
</div>
<div class="sub-sub-section"><h4>
<a name="s2.2.3" id="s2.2.3"></a><span class="item-no">2.2.3</span>  Returned values
</h4><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
This can be helpful when integrating Sourceer in other systems. The <span class="term">$sourceer->work()</span> call returns an associative array containing one or more of these items with values that are raw text (do not have character entities, and may be empty):<br />
<br />
   <span class="term">error</span> - a brief description of any error; e.g., if a specified directory is absent<br />
<br />
   <span class="term">filepath</span> - filepath, relative to Sourceer's root (<span class="term">$cfg["root"]</span>), of directory being viewed or of file being accessed, or false. For directory, there will be a trailing slash (<span class="term">/</span>).<br />
<br />
   <span class="term">task</span> - task that was performed; possible values, that also indicate progress:<br />
<br />
   - <em>browse</em> - a directory view request processed<br />
   - <em>download</em> - a download request processed<br />
   - <em>instantiate</em> - Sourceer object created<br />
   - <em>login</em> - a password-based login request processed<br />
   - <em>pathchecks</em> - requested filepaths processed<br />
   - <em>source</em> - a source code view request processed<br />
<br />
   <span class="term">title</span> - a short title; useful for use in HTML head section, etc.<br />
<br />
   <span class="term">css</span>, <span class="term">foot</span> and <span class="term">js</span> - may be available when source-code is being viewed or a directory is being listed. These may be useful for use in, e.g., inside external HTML templates.<br />
</div>
<div class="sub-sub-section"><h4>
<a name="s2.2.4" id="s2.2.4"></a><span class="item-no">2.2.4</span>  Layout and style
</h4><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
The default Sourceer code produces standalone HTML as output (with HTML head, title, etc., elements). To have a different layout and/or styling (e.g., when including Sourceer inside another web-page), set proper values for the <span class="term">css</span>, <span class="term">js</span>, <span class="term">foot</span> and/or <span class="term">head</span> elements of <span class="term">$cfg</span>.<br />
<br />
If you set <span class="term">$cfg</span> <span class="term">head</span> to not use Sourceer's default <span class="term">head</span>, the <span class="term">$cfg</span> <span class="term">css</span> becomes meaningless. Then, do keep in mind that CSS declarations for HTML elements in the Sourceer output (like <span class="term">Sfile1</span> and <span class="term">Scode</span>) are not lost from the HTML page that has the Sourceer output.<br />
</div>
<div class="sub-sub-section"><h4>
<a name="s2.2.5" id="s2.2.5"></a><span class="item-no">2.2.5</span>  Non-Sourceer file security
</h4><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
As mentioned above, Sourceer has provisions to secure specific files/directories from being accessed through Sourceer. However, in many cases (depending on the root location), a user may be able to access such content by simply browsing to their location by typing URLs in a browser's address bar. Depending on the file-type, this can also lead to the execution of a file (e.g., a PHP or a Perl file).<br />
<br />
Sourceer administrators should therefore appropriately configure the web server (e.g., by editing the <span class="term">httpd.conf</span> file or by placing the right <span class="term">htaccess</span> files in case of Apache servers). E.g., the following content in an <span class="term">htaccess</span> placed in the root directory (that also holds <span class="term">sourceer.php</span>) will disable unwanted execution of PHP files:<br />
<br />
<code class="code">    <FilesMatch "(?<!sourceer)\.php$"></code>
<br />
<code class="code">     Order deny,allow</code>
<br />
<code class="code">     Deny from all</code>
<br />
<code class="code">    </FilesMatch></code>
<br />
</div>
</div>
</div>
<div class="section"><h2>
<a name="s3" id="s3"></a><span class="item-no">3</span>  Other
</h2><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<div class="sub-section"><h3>
<a name="s3.1" id="s3.1"></a><span class="item-no">3.1</span>  Upgrade
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
From v1.2 to v1.3<br />
<br />
  Just replace code. Note that you have to use the <span class="term">$cfg["hiliter"]</span> parameter for highlighting source code using an external application like <span class="term">Geshi</span>.<br />
<br />
From v1.1 to v1.2, and from v1.2 to v1.2.1 or v1.2.2<br />
<br />
  Just replace code. (For the v1.2 change, there are 5 new CSS declarations to indicate file ages and sort links.)<br />
<br />
From v1 to v1.1<br />
<br />
  Replace the older <span class="term">sourceer.php</span> (or the Sourceer class definition). There are extra arguments that are passed to Sourceer, and the argument order has changed. Some extra configuration is also possible with v1.1.<br />
</div>
<div class="sub-section"><h3>
<a name="s3.2" id="s3.2"></a><span class="item-no">3.2</span>  Change-log
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
v1.3.2 - released 5 July 2022<br />
   - made PHP 8-compatibile<br />
<br />
v1.3.1 - released July 31, 2008<br />
   - fixed a flaw that output unescaped GET values<br />
<br />
v1.3 - released Jun 7, 2008<br />
   - better external-highlighting implementation<br />
   - <span class="term">mb_string</span> functions for improved functionality with non-ASCII/UTF file-names<br />
<br />
v1.2.2 - released Feb 3, 2008<br />
   - compressed output<br />
   - minor, including documentation changes<br />
<br />
v1.2.1 - released Jan 19, 2008<br />
   - proper white-spacing of highlighted code<br />
   - better default font size<br />
<br />
v1.2 - released Sep 7, 2007<br />
   - care of non-XHTML tags in <span class="term">highlight_string()</span> of PHP < 5<br />
   - age indication<br />
   - directory mod. times<br />
   - sortability<br />
<br />
v1.1.1 - released Aug 27, 2007<br />
   - minor character encoding fixes<br />
<br />
v1.1 - released Aug 22, 2007<br />
   - Documentation<br />
   - Changed class definition<br />
   - Extra settings possible to pass values in query string, etc.<br />
   - More easily usable and configurable<br />
   - Namespacing for CSS and <span class="term">$_GET</span><br />
<code class="code">    etc.</code>
<br />
<br />
v1.0.1 - released Aug 10, 2007<br />
   - Security fix for filenames passed through <span class="term">$_GET</span><br />
   - Using <span class="term">$_SERVER["PHP_SELF"]</span><br />
<br />
v1.0 - released Aug 9, 2007<br />
</div>
<div class="sub-section"><h3>
<a name="s3.3" id="s3.3"></a><span class="item-no">3.3</span>  Support
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
For possible updates and forum support, follow up at <a href="https://bioinformatics.org/phplabware/internal_utilities">https://bioinformatics.org/phplabware/internal_utilities</a>.<br />
<br />
For debugging, use <span class="term">1</span> in <span class="term">ini_set("display_errors", 0)</span> at the top of <span class="term">sourceer.php</span>.<br />
<br />
For general PHP issues (not Sourceer-specific), check on the internet and at <a href="http://php.net">http://php.net</a>.<br />
</div>
<div class="sub-section"><h3>
<a name="s3.4" id="s3.4"></a><span class="item-no">3.4</span>  Known issues
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Files/directories with <span class="term">/</span> in their names (possible on some Mac OS systems) may not be accessible.<br />
<br />
Files/directories with unusual non-English characters in their names may not be accessible, and/or may have their names displayed with strange characters.<br />
<br />
Source-code may have characters displayed differently if the code uses a character encoding other than the <span class="term">charset</span> set in <span class="term">$cfg</span>.<br />
<br />
On some systems (e.g., Windows XP), indicated directory modification times may be incorrect.<br />
<br />
Sourceer uses <span class="term">GET</span> variables named <span class="term">Sd</span>, <span class="term">Sfd</span>, <span class="term">Sfs</span> and <span class="term">Sl</span>, and <span class="term">POST</span> variables named <span class="term">Sp</span> and <span class="term">St</span>. There will be issues if Sourceer is included in scripts that also use similar variables with identical names.<br />
</div>
<div class="sub-section"><h3>
<a name="s3.5" id="s3.5"></a><span class="item-no">3.5</span>  Donate
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
A donation in any currency and amount to appreciate or support this software can be sent by <a href="http://paypal.com">PayPal</a> to this email address: drpatnaik at yahoo dot com.<br />
<br />
Thank you!
</div>
<br />
<hr /><br /><br /><span class="subtle"><small>HTM version of <em><a href="sourceer_README.txt">sourceer_README.txt</a></em> generated on 06 Jul, 2022 using <a href="http://www.bioinformatics.org/phplabware/internal_utilities">rTxt2htm</a> from PHP Labware</small></span>
</div><!-- ended div body -->
</div><!-- ended div top -->
</body>
</html>Presented with Sourceer