/*
sourceer_README.txt
Sourceer 1.3.2, 5 July 2022
Source code viewer
Copyright Santosh Patnaik
GPL v3 license
A PHP Labware internal utility - https://bioinformatics.org/phplabware/internal_utilities
*/

Download latest version from https://bioinformatics.org/phplabware/downloads/sourceer.zip

== Content ==========================================================


1  About
2  Usage
  2.1  Basic
  2.2  Advanced
    2.2.1  Authentication and security
    2.2.2  Parameters
    2.2.3  Returned values
    2.2.4  Layout and style
    2.2.5  Non-Sourceer file security
3  Other
  3.1  Upgrade
  3.2  Change-log
  3.3  Support
  3.4  Known issues
  3.5  Donate
  

== 1  About =========================================================

  
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 'Geshi', or the client-side, Javascript-based 'dpSyntaxHighlighter' scripts can easily be used.
  
Among other things, Sourceer is useful for presenting contents of software projects (a much simple alternative to 'Trac', 'PHPDoc', 'Doxygen', SVN/CVS systems, etc.). Sourceer was developed at PHP Labware (https://bioinformatics.org/phplabware) for this purpose. Sourceer's original code was based on Stuart Montgomery's 'DirPHP' v1.0 code.
  
Easy integrability and high customizability set Sourceer apart from other such software.


== 2  Usage ========================================================o


-- 2.1  Basic -------------------------------------------------------
    
    
Sourceer works with *PHP versions 5 and above*. Put 'sourceer.php' in the directory that is to be browsed. Change parameter values at top if desired -- see section:- #2.2.2. Change layout and style if desired -- see section:- #2.2.4. Also see section:- #2.2.1 for authentication setup, and section:- #2.2.5 for file-security measures.
    
    
-- 2.2  Advanced ---------------------------------------------------o

  
For formatting of source code (*syntax highlighting*, etc.) using 'Geshi', etc., instead of Sourceer (which uses PHP's 'highlight_string' function) set the 'hiliter' parameter of '$cfg' 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 'hiliter' in section:- #2.2.2.

An example of such `external` highlighting using this:- http://mihai.bazon.net/projects/javascript-syntax-highlighting-engine Javascript-based syntax highlighter:
   
    ...
    $cfg['hiliter'] = 'myHl';
    ...
    function myHl($in, $type, $path, $enc){

     // Let Sourceer handle .txt file-type.
     // Also we want only .css and .js handled this way.
     
     if($type == 'txt' or ($type != 'css' and $type != 'js)){
      return 0;
     }

     // Long code is too resource-intensive to syntax-highlight.
     // Just return as plain-formatted, preserving white-spaces.
     
     if(isset($in[30000])){
      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))));
     }

     // Return array with formatted code, style and script declarations, etc.

     return array(

      // Formatted code

      0 => '<pre name="code" class="'. $type. '">'. htmlspecialchars($in, ENT_COMPAT, $enc). '</pre>',

      // Additional CSS style declaration for HTML head

      1 => '<link rel="stylesheet" type="text/css" href="style.css" />',

      // Additional Javascript declaration for HTML head

      2 => '<script type="text/javascript" src="hl-all.js"></script>',

      // Additional HTML declaration for HTML foot

      3 => '<script type="text/javascript">DlHighlight.HELPERS.highlightByName("code", "pre");</script>'

     );
    }


You can copy the 'Sourceer' class and use it like using 'sourceer.php'. Also, the 'sourceer.php' file itself can be included in another script. Output of 'sourceer.php' can be obtained by including the file -- 'include("path/to/sourceer.php")' -- and then using such two lines of code either in the parent script or in 'sourceer.php' itself: 
  
    $var = new Sourceer($sec_dirs, $sec_files, $src_filetypes, $cfg, $presrc);
    $var->work();


For displaying the Sourceer output `later`, use output buffering functions. E.g.:
  
    $sourceer = new Sourceer($a, $b, $c, $d);
    ob_start();
    $sourceer->work();
    $sourceer_out = ob_get_contents;
    ob_end_clean();
    ...
    echo $sourceer_out;   


The arguments '$sec_dirs', '$sec_files', '$src_filetypes', and '$cfg' should be in the form of arrays (the arrays themselves can be empty; one or more elements of the '$cfg' array may not be defined -- see note on 'parameter values' below). 


All code in sourceer.php that is between the '<?php' and the class definition can be removed, and one can use the Sourceer class code like so in the parent script:
    
    $out = new Sourceer(array(), array('.htaccess'), array('php'), array('root'=>'../pics/nat', 'head'=>'<table id="S">', 'foot'=>'</table>'), 0);
    $out->work();   


$cfg parameters can also be passed using 'set_cfg()' once the Sourceer object is created. Thus, e.g.,
    
    $out = new Sourceer(array(), array('.htaccess'), array('php'), array('root'=>'../pics/nat', 'head'=>'<table id="S">', 'foot'=>'</table>'), 0);
    $sourceer->set_cfg('dl', 0);
    $out->work();


.. 2.2.1  Authentication and security ...............................


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 section:- #2.2.2 for more.
  
To secure (hide or limit access to) certain files/directories, set the appropriate parameters (section:- #2.2.2). 
  
Sourceer filters the URL query string ('$_GET') values for filenames, so one cannot attempt to move up-root using strings like '/..' or '//'. If up-root traversal is permitted (section:- #2.2.2), then one may use the string '/..' in the 'Sl' parameter of the query string.

Also see section:- #2.2.5.
    
     
.. 2.2.2  Parameters ...............................................o


Valid PHP code can be used for the parameter values.

*$src_filetypes*

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 'array("php"=>"php", "php4"=>"php", "htaccess"=>"txt", "txt"=>"txt", "js"=>"js")'. Thus, as per this example, an '.htaccess' file and a 'hello.txt' file both have the 'txt' file-type (but different file-extensions -- '.htaccess' and '.txt'). An empty key '""' can be used to refer to files that have no extension ('""=>"txt"').

Note that other file-types (e.g., 'jpg') are `downloadable` as well (but not through Sourceer/PHP) as links shown for such files can be clicked on for the browser to receive.
  
*$sec_files*

Specifies `secured` files that, depending on '$cfg', may not be listed or looked into. Elements are paths to such files relative to the root ('$cfg["root"]') directory. E.g., 'array("./.htaccess", "../.htaccess", "./pics/.HTACCESS")'.
  
You can use PHP PCRE-compatible regular expressions to indicate many filenames in a simpler way. To do so, put this in the array: 'array("x", "y", ...)' where 'x', 'y', etc., are the expression patterns with delimiters. E.g., 'array("./.htaccess", "../.htaccess", "./pics/.HTACCESS", array("!\.htaccess$!i", "!\.ini$!i"))'. The expression patterns should be PHP/PCRE-compatible and should use the exclamation mark ('!') as the delimiter.

To secure the 'sourceer.php' file itself, either set the root directory below 'sourceer.php' and turn off up-root browsing (see '$cfg' below), or put the relative path to 'sourceer.php' in '$sec_files'.
  
*$sec_dir*

Similar to '$sec_files' but for directories
   
   Consider this file structure:
    
   +---------------------------------------+
    
      __________dir___www___pics___.HTACCESS
      |         |     |
      |___x.ini |     |___.htaccess
                |     |
                |     |___sourceer.php
                |
                |___.htaccess
       
   +---------------------------------------+
    
   Here, sourceer.php is in 'dir/www/' and if the '$cfg' 'root' parameter (more below) is set to '.', then the effective root is 'www'. With the '$sec_files' set to 'array("./.htaccess", "../.htaccess", "./pics/.HTACCESS", array("!\.htaccess$!i", "!\.ini$!i"))', 'www/.htaccess' and 'www/pics/.HTACCESS' are both secured. Even if there is no './../.htaccess' in the array, the file 'dir/.htaccess' is secure, like all files in 'dir/' if the 'up_root' parameter is set to '0'.
    
   However, if 'up_root' is '1', then unlike other files in 'dir/', the '.htaccess' file gets secured. With '$sec_dirs' set to 'array("./pics")', or to 'array(array("\pics$\"))', 'www/pics/' is secured.
    
   The file 'x.ini' at './../..' can be secured by having 'up_root' set to '0' (most restrictive), or the element 'array("`(^|\.)/../..(/|$)`")' in '$sec_dirs' (less restrictive), or the element './../../x.ini' in '$sec_files' (least restrictive). There are obviously many other possibilities with different levels of restrictiveness.
    
*$cfg*

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.
  
   'auth' - '1' if a password is needed unless the user's IP address is in the 'ok_ips' array. The MD5 hash of the password prefixed with 'sourceer' is specified in 'hash'. Default: '0'
    
   'base' - base URL. E.g., 'http://domain.com/sourceer.php', 'sourceer.php', 'https://localhost', etc. It can have a query string. E.g., 'http://domain.com/index.php?page=codes&guest=1' (note the '&' is not '&amp;' -- don't use entities). Default: code to auto-determine correct URL
    
   'charset' - character encoding, for HTML rendering purposes only. Probably best if set to encoding used the server's filesystem. Default: 'utf-8'

   'compress' - gzip-compress output to reduce bandwidth. Sourceer will auto-check other parameters (e.g., if browser accepts compressed content). To turn off, set to '0'. Default: '1'
    
   'css' - style declarations. If not set, or set to '0', default is used. If set as an array, like 'array("div.p {color: red;}")', will get appended to default CSS. Default: (complete declarations)
    
   'cookie' - 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: 'sourceer'
    
   'date_type' - specifies the date format; should be compatible with PHP's 'date()' function (like 'm-d-y'). Default: 'm/d/y'

   'dl' - '1' if '$src_filetypes' files can be downloaded. Default: '1'
    
   'file_info' - '0' if file-sizes and modification times are not to be shown. Default: '1'
    
   'foot' - HTML string to append to the output. Can be empty, '</body></html>', etc. If not set, or set to '0', default is used. If set as an array, like 'array("<p>Home</p>")', will get prepended to default foot. Default: '</div></body></html>'
    
   'hash' - see 'auth'. Default: MD5 hash of 'sourceerpass' (i.e., default password is 'pass')
    
   'head' - HTML string to prepend to the output. Can be empty, full-blown HTML like '<html>...</head><body>', etc. If not set, or set to '0', default is used. If set otherwise, the string '_Sourceer_dynamic_title_' can be used in the text, and Sourceer will replace it with a dynamically generated, page context-specific short title (useful for the HTML 'title' element). If set as an array, like 'array("<p>Home</p>")', will get appended to default head. Default: (with HTML doctype, CSS declarations, etc.)

   'hiliter' - name of a custom highlighting function to use for syntax-highlighting of source codes. The function must be defined somewhere. If not, or if 'hiliter' is set to '0', 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 'hiliter' 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 'style' 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: '0'.

   'js' - like for 'CSS' above.
    
   'lang' - language; RFC3066 specified-values such as 'en' for English; used for HTML language specification only (not user interface) Default: 'en'
    
   'ok_ips' - see 'auth'. Default: 'array()'
    
   'query_plus' - string to append to URLs. E.g., if sourceer.php is used at URL 'domain.com/wiki.php?page=home', you may want to set it to 'page=home'. Don't use entities. Thus, e.g., 'page=home&category=<main>' and not 'page=home&amp;category=&lt;main&gt;'. Default: ''
    
   'root' - root directory for browsing. Use '.' if same as 'sourceer.php' (or the parent script when 'sourceer.php' is included), or './..' for the directory above it. Or, e.g., './../../dir2' where 'dir2' is an 'uncle' directory. Don't use trailing or leading slashes, double slashes or backslashes. Default: '.'
    
   'sec_check_off' - '1' to turn off checking if files/directories are secured (to be hidden). Default: '0'
    
   'sec_dir_into' - '1' if '$secure_dirs' can be looked into. Default: '0'
    
   'sec_dir_list' - '1' if '$secure_dirs' are to be shown listed in directory content lists. Default: '0'
  
   'sec_file_dl' - '1' if '$sec_files' can be downloaded. Default: '0'
   
   'sec_file_list' - '1' if '$sec_file's can be listed (shown). Default: '0'
   
   'sec_file_src' - 1 if source code of '$sec_files' can be viewed. Default: '0'
    
   'src' - '1' to turn on source code viewing of '$src_filetypes' files. Default: '1'
    
   'timeout' - time limit for script to execute (when sending downloads, any time-limit is always ignored). Default: '300'
    
   'title' - a title for the Sourceer pages. HTML entities may or may not be used. Default: 'Sourceer file and code viewer'

   'up_root'  - '1' allows move to higher levels than 'root' using '/..' in the 'Sl' parameter in the query string of the URL (e.g. 'sourceer.php?Sl=../../dir3&Sd=file3'). Irrespective of the setting, specifying files to download/source-view using '..' is not allowed. Runs of '/', like '//' and '///', are always reduced to '/'. Default: '0'


.. 2.2.3  Returned values ..........................................o


This can be helpful when integrating Sourceer in other systems. The '$sourceer->work()' 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):
  
   'error' - a brief description of any error; e.g., if a specified directory is absent
    
   'filepath' - filepath, relative to Sourceer's root ('$cfg["root"]'), of directory being viewed or of file being accessed, or false. For directory, there will be a trailing slash ('/').
    
   'task' - task that was performed; possible values, that also indicate progress:
    
   - `browse` - a directory view request processed     
   - `download` - a download request processed     
   - `instantiate` - Sourceer object created    
   - `login` - a password-based login request processed    
   - `pathchecks` - requested filepaths processed   
   - `source` - a source code view request processed
      
   'title' - a short title; useful for use in HTML head section, etc.

   'css', 'foot' and 'js' - 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.
  

.. 2.2.4  Layout and style .........................................o


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 'css', 'js', 'foot' and/or 'head' elements of '$cfg'.
  
If you set '$cfg' 'head' to not use Sourceer's default 'head', the '$cfg' 'css' becomes meaningless. Then, do keep in mind that CSS declarations for HTML elements in the Sourceer output (like 'Sfile1' and 'Scode') are not lost from the HTML page that has the Sourceer output.


.. 2.2.5  Non-Sourceer file security ...............................o


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).

Sourceer administrators should therefore appropriately configure the web server (e.g., by editing the 'httpd.conf' file or by placing the right 'htaccess' files in case of Apache servers). E.g., the following content in an 'htaccess' placed in the root directory (that also holds 'sourceer.php') will disable unwanted execution of PHP files:

    <FilesMatch "(?<!sourceer)\.php$">
     Order deny,allow
     Deny from all
    </FilesMatch>
  
  
== 3  Other ======================================================ooo


-- 3.1  Upgrade -----------------------------------------------------


From v1.2 to v1.3

  Just replace code. Note that you have to use the '$cfg["hiliter"]' parameter for highlighting source code using an external application like 'Geshi'.

From v1.1 to v1.2, and from v1.2 to v1.2.1 or v1.2.2
  
  Just replace code. (For the v1.2 change, there are 5 new CSS declarations to indicate file ages and sort links.)
  
From v1 to v1.1
  
  Replace the older 'sourceer.php' (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.


-- 3.2  Change-log -------------------------------------------------o


v1.3.2 - released 5 July 2022
   - made PHP 8-compatibile

v1.3.1 - released July 31, 2008
   - fixed a flaw that output unescaped GET values

v1.3 - released Jun 7, 2008
   - better external-highlighting implementation
   - 'mb_string' functions for improved functionality with non-ASCII/UTF file-names

v1.2.2 - released Feb 3, 2008
   - compressed output
   - minor, including documentation changes

v1.2.1 - released Jan 19, 2008
   - proper white-spacing of highlighted code
   - better default font size

v1.2 - released Sep 7, 2007
   - care of non-XHTML tags in 'highlight_string()' of PHP < 5
   - age indication
   - directory mod. times
   - sortability
  
v1.1.1 - released Aug 27, 2007
   - minor character encoding fixes
  
v1.1 - released Aug 22, 2007
   - Documentation
   - Changed class definition
   - Extra settings possible to pass values in query string, etc.
   - More easily usable and configurable
   - Namespacing for CSS and '$_GET'
    etc.
    
v1.0.1 - released Aug 10, 2007
   - Security fix for filenames passed through '$_GET'
   - Using '$_SERVER["PHP_SELF"]'

v1.0 - released Aug 9, 2007
  
  
-- 3.3  Support ----------------------------------------------------o


For possible updates and forum support, follow up at https://bioinformatics.org/phplabware/internal_utilities.
  
For debugging, use '1' in 'ini_set("display_errors", 0)' at the top of 'sourceer.php'.
  
For general PHP issues (not Sourceer-specific), check on the internet and at http://php.net.
  
  
-- 3.4  Known issues ----------------------------------------------o
  
  
Files/directories with '/' in their names (possible on some Mac OS systems) may not be accessible.
  
Files/directories with unusual non-English characters in their names may not be accessible, and/or may have their names displayed with strange characters.
  
Source-code may have characters displayed differently if the code uses a character encoding other than the 'charset' set in '$cfg'.

On some systems (e.g., Windows XP), indicated directory modification times may be incorrect.

Sourceer uses 'GET' variables named 'Sd', 'Sfd', 'Sfs' and 'Sl', and 'POST' variables named 'Sp' and 'St'. There will be issues if Sourceer is included in scripts that also use similar variables with identical names.
  
  
-- 3.5  Donate ----------------------------------------------------o


A donation in any currency and amount to appreciate or support this software can be sent by PayPal:- http://paypal.com to this email address: drpatnaik at yahoo dot com.

Thank you!

________________________________________________________________o

@@title: Sourceer documentation
@@language: en
@@keywords: 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
@@encoding: utf-8
@@description: Sourceer code / file / directory browser / viewer