/*
sourceer_README.txt
Sourceer 1.2.1, 19 January 2008
Copyright Santosh Patnaik
GPL 3 license
A PHP Labware internal utility - http://bioinformatics.org/phplabware/internal_utilities
*/

Download latest original file from http://bioinformatics.og/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
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. Filesizes 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 'Geshi' or 'dpSyntaxHighlighter' 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 (http://bioinformatics.org/phplabware) for this purpose. Sourceer's original code was based on Stuart Montgomery's 'DirPHP' v1.0 code. That was modified for extra features, standard-compliant output, and bug- and performance-fixes.
  
Easy integrability and high customizability set Sourceer apart from other such software.


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


-- 2.1  Basic -------------------------------------------------------
    
    
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.
    
    
-- 2.2  Advanced ---------------------------------------------------o

  
For formatting of source code (syntax highlighting, etc.), if you want to use 'Geshi', etc., instead of Sourceer, you can easily do so as the '$sourceer->work()' call returns an array containing the filepath (with extension), the raw file content and the footer when source viewing is being done (see note on 'returned values').

Example with 'Geshi':
   
    $sourceer = new Sourceer($a, $b, $c, $d, 1);
    $code = $sourceer->work();
    if(isset($code['code']))
    {
     include_once('./labwiki/ext/geshi/geshi.php');
     $lang = strtolower(substr(strrchr($code['filepath'], '.'), 1)); // file extension (thus, language)
     $geshi = new GeSHi($code['code'], $lang);
     echo $geshi->parse_code();
     echo $code['foot']; // the footer (Sourceer's regular output after the source code)
    }

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.
    
     
.. 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 lower-cased extension names, like 'array("php", "htaccess", "js")'. Note that other file-types (e.g., 'jpg') are `downloadable` as well (but not through Sourceer/PHP) as 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.
  
*$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.
    
*$presrc*
Should be '0' or '1'. With '0', the default value, Sourceer will format source code for display. With '1', it will return the raw source without formatting. This allows one to use a different formatting software (such as the 'Geshi' syntax highlighter). See section:- #2.2.
    
*$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'
    
   'css' - style declarations (meaningless if 'head', below, is not set to use default value. If not set, or set to '0', default is used. 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 HTML htitle element). If set as an array, like 'array("<p>Home</p>")', will get appended to default head. Default: (with HTML doctype, CSS declarations, etc.)
    
   '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.
  
In addition, these are set when '$presrc' is set to '1' and the raw code of a file is being sent for highlighting outside Sourceer (see section:- #2.2):
  
   'code' - the raw code
    
   'foot' - footer HTML
  

.. 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', '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.
  
  
== 3  Other ======================================================ooo


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


From v1.1 to v1.2, and from v1.2 to v1.2.1
  
  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.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, follow up at http://www.bioinformatics.org/phplabware/internal_utilities (also has a forum).
  
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.
  
  
-- 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
@@encoding: utf-8
@@description: Sourceer code / file / directory browser / viewer