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
. Also, the
file itself can be included in another script. Output of
, use output buffering functions. E.g.:
should be in the form of arrays (the arrays themselves can be empty; one or more elements of the
and the class definition can be removed, and one can use the Sourceer class code like so in the parent script:
once the Sourceer object is created. Thus, e.g.,
2.2.2 Parameters
(to top)
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
& -- 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&category=<main>. 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
(to top)
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
Sourceer 1.2, 7 September 2007
Copyright Santosh Patnaik
GPL 3 license
A PHP Labware internal utility - http://bioinformatics.org/phplabware/internal_utilities