cleaned up phpdoc comments, added README on how to install and use it

This commit is contained in:
El RIDO 2015-08-16 15:55:31 +02:00
parent 3a183470a6
commit 24d18c5313
12 changed files with 336 additions and 86 deletions

11
.gitignore vendored
View File

@ -1,11 +1,12 @@
# Ignore data/ and tmp/
data/
tmp/
# Ignore unit testing logs and eclipse project files
tst/log/
.settings/
.buildpath
.project
# Ignore for safety
.htaccess
.htpasswd
# Ignore unit testing logs, api docs and eclipse project files
tst/log/
doc/
.settings/
.buildpath
.project

19
doc/README.md Normal file
View File

@ -0,0 +1,19 @@
Generating documentation
========================
In order to generate the documentation, you will need to install the following
packages and its dependencies:
* phpdoc
* graphviz
Details about [installing phpDocumentor](http://phpdoc.org/docs/latest/getting-started/installing.html)
can be found in its own documentation.
Example for Debian and Ubuntu:
$ sudo aptitude install pear graphviz
$ sudo pear channel-discover pear.phpdoc.org
$ sudo pear install phpdoc/phpDocumentor
To generate the documentation, change into the main directory and run phpdoc:
$ cd ZeroBin
$ phpdoc -d lib/ -t doc/

View File

@ -1,8 +1,7 @@
<?php
/**
* RainTPL
* -------
*
* Realized by Federico Ulfo & maintained by the Rain Team
* Distributed under GNU/LGPL 3 License
*
@ -10,6 +9,9 @@
*/
/**
* RainTPL
*/
class RainTPL{
// -------------------------
@ -25,7 +27,9 @@ class RainTPL{
/**
* Cache directory. Is the directory where RainTPL will compile the template and save the cache
* Cache directory
*
* Is the directory where RainTPL will compile the template and save the cache
*
* @var string
*/
@ -33,7 +37,9 @@ class RainTPL{
/**
* Template base URL. RainTPL will add this URL to the relative paths of element selected in $path_replace_list.
* Template base URL
*
* RainTPL will add this URL to the relative paths of element selected in $path_replace_list.
*
* @var string
*/
@ -41,7 +47,7 @@ class RainTPL{
/**
* Template extension.
* Template extension
*
* @var string
*/
@ -49,10 +55,12 @@ class RainTPL{
/**
* Path replace is a cool features that replace all relative paths of images (<img src="...">), stylesheet (<link href="...">), script (<script src="...">) and link (<a href="...">)
* Should the path be replaced
*
* Path replace is a cool features that replace all relative paths of images (&lt;img src="..."&gt;), stylesheet (&lt;link href="..."&gt;), script (&lt;script src="..."&gt;) and link (&lt;a href="..."&gt;)
* Set true to enable the path replace.
*
* @var unknown_type
* @var boolean
*/
static $path_replace = true;
@ -69,22 +77,25 @@ class RainTPL{
/**
* You can define in the black list what string are disabled into the template tags
*
* @var unknown_type
* @var array
*/
static $black_list = array( '\$this', 'raintpl::', 'self::', '_SESSION', '_SERVER', '_ENV', 'eval', 'exec', 'unlink', 'rmdir' );
/**
* Check template.
* Check template
*
* true: checks template update time, if changed it compile them
* false: loads the compiled template. Set false if server doesn't have write permission for cache_directory.
*
* @var bool
*/
static $check_template_update = true;
/**
* PHP tags <? ?>
*
* True: php tags are enabled into the template
* False: php tags are disabled into the template and rendered as html
*
@ -94,7 +105,8 @@ class RainTPL{
/**
* Debug mode flag.
* Debug mode flag
*
* True: debug mode is used, syntax errors are displayed directly in template. Execution of script is not terminated.
* False: exception is thrown on found error.
*
@ -116,17 +128,44 @@ class RainTPL{
*/
public $var = array();
protected $tpl = array(), // variables to keep the template directories and info
$cache = false, // static cache enabled / disabled
$cache_id = null; // identify only one cache
/**
* variables to keep the template directories and info
*
* @var array
*/
protected $tpl = array(); //
protected static $config_name_sum = array(); // takes all the config to create the md5 of the file
/**
* static cache enabled / disabled
*
* @var bool
*/
protected $cache = false;
/**
* identify only one cache
*
* @var string
*/
protected $cache_id = '';
/**
* takes all the config to create the md5 of the file
*
* @var array the file
*/
protected static $config_name_sum = array();
// -------------------------
const CACHE_EXPIRE_TIME = 3600; // default cache expire time = hour
/**
* default cache expire time = hour
*
* @const int
*/
const CACHE_EXPIRE_TIME = 3600;
@ -134,11 +173,11 @@ class RainTPL{
* Assign variable
* eg. $t->assign('name','mickey');
*
* @access public
* @param mixed $variable_name Name of template variable or associative array name/value
* @param mixed $value value assigned to this variable. Not set if variable_name is an associative array
*/
function assign( $variable, $value = null ){
public function assign( $variable, $value = null ){
if( is_array( $variable ) )
$this->var += $variable;
else
@ -152,12 +191,12 @@ class RainTPL{
* eg. $html = $tpl->draw( 'demo', TRUE ); // return template in string
* or $tpl->draw( $tpl_name ); // echo the template
*
* @access public
* @param string $tpl_name template to load
* @param boolean $return_string true=return a string, false=echo the template
* @return string
*/
function draw( $tpl_name, $return_string = false ){
public function draw( $tpl_name, $return_string = false ){
try {
// compile the template if necessary and set the template filepath
@ -211,12 +250,13 @@ class RainTPL{
/**
* If exists a valid cache for this template it returns the cache
*
* @access public
* @param string $tpl_name Name of template (set the same of draw)
* @param int $expiration_time Set after how many seconds the cache expire and must be regenerated
* @param string $cache_id Suffix to be used when writing file to cache (optional)
* @return string it return the HTML or null if the cache must be recreated
*/
function cache( $tpl_name, $expire_time = self::CACHE_EXPIRE_TIME, $cache_id = null ){
public function cache( $tpl_name, $expire_time = self::CACHE_EXPIRE_TIME, $cache_id = '' ){
// set the cache_id
$this->cache_id = $cache_id;
@ -236,8 +276,12 @@ class RainTPL{
/**
* Configure the settings of RainTPL
*
* @access public
* @static
* @param array|string $setting array of settings or setting name
* @param mixed $value content to set in the setting (optional)
*/
static function configure( $setting, $value = null ){
public static function configure( $setting, $value = null ){
if( is_array( $setting ) )
foreach( $setting as $key => $value )
self::configure( $key, $value );
@ -249,8 +293,14 @@ class RainTPL{
// check if has to compile the template
// return true if the template has changed
/**
* Check if has to compile the template
*
* @access protected
* @param string $tpl_name template name to check
* @throws RainTpl_NotFoundException
* @return bool return true if the template has changed
*/
protected function check_template( $tpl_name ){
if( !isset($this->tpl['checked']) ){
@ -281,7 +331,10 @@ class RainTPL{
/**
* execute stripslaches() on the xml block. Invoqued by preg_replace_callback function below
*
* @access protected
* @param string $capture
* @return string
*/
protected function xml_reSubstitution($capture) {
return "<?php echo '<?xml ".stripslashes($capture[1])." ?>'; ?>";
@ -289,7 +342,15 @@ class RainTPL{
/**
* Compile and write the compiled template file
*
* @access protected
* @param string $tpl_basename
* @param string $tpl_basedir
* @param string $tpl_filename
* @param string $cache_dir
* @param string $compiled_filename
* @throws RainTpl_Exception
* @return void
*/
protected function compileFile( $tpl_basename, $tpl_basedir, $tpl_filename, $cache_dir, $compiled_filename ){
@ -328,7 +389,11 @@ class RainTPL{
/**
* Compile template
*
* @access protected
* @param string $template_code
* @param string $tpl_basedir
* @return string
*/
protected function compileTemplate( $template_code, $tpl_basedir ){
@ -369,7 +434,11 @@ class RainTPL{
/**
* Compile the code
*
* @access protected
* @param string $parsed_code
* @throws RainTpl_SyntaxException
* @return string
*/
protected function compileCode( $parsed_code ){
@ -585,9 +654,12 @@ class RainTPL{
/**
* Reduce a path, eg. www/library/../filepath//file => www/filepath/file
* @param type $path
* @return type
* Reduce a path
*
* eg. www/library/../filepath//file => www/filepath/file
*
* @param string $path
* @return string
*/
protected function reduce_path( $path ){
$path = str_replace( "://", "@not_replace@", $path );
@ -599,13 +671,16 @@ class RainTPL{
/**
* replace the path of image src, link href and a href.
* replace the path of image src, link href and a href
*
* url => template_dir/url
* url# => url
* http://url => http://url
*
* @access protected
* @param string $html
* @return string html sostituito
* @param string $tpl_basedir
* @return string html substitution
*/
protected function path_replace( $html, $tpl_basedir ){
@ -655,16 +730,40 @@ class RainTPL{
// replace const
function const_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
/**
* replace constants
*
* @access public
* @param string $html
* @param string $tag_left_delimiter
* @param string $tag_right_delimiter
* @param string $php_left_delimiter (optional)
* @param string $php_right_delimiter (optional)
* @param string $loop_level (optional)
* @param string $echo (optional)
* @return string
*/
public function const_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
// const
return preg_replace( '/\{\#(\w+)\#{0,1}\}/', $php_left_delimiter . ( $echo ? " echo " : null ) . '\\1' . $php_right_delimiter, $html );
}
// replace functions/modifiers on constants and strings
function func_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
/**
* replace functions/modifiers on constants and strings
*
* @access public
* @param string $html
* @param string $tag_left_delimiter
* @param string $tag_right_delimiter
* @param string $php_left_delimiter (optional)
* @param string $php_right_delimiter (optional)
* @param string $loop_level (optional)
* @param string $echo (optional)
* @return string
*/
public function func_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
preg_match_all( '/' . '\{\#{0,1}(\"{0,1}.*?\"{0,1})(\|\w.*?)\#{0,1}\}' . '/', $html, $matches );
@ -763,7 +862,20 @@ class RainTPL{
function var_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
/**
* replace variables
*
* @access public
* @param string $html
* @param string $tag_left_delimiter
* @param string $tag_right_delimiter
* @param string $php_left_delimiter (optional)
* @param string $php_right_delimiter (optional)
* @param string $loop_level (optional)
* @param string $echo (optional)
* @return string
*/
public function var_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
//all variables
if( preg_match_all( '/' . $tag_left_delimiter . '\$(\w+(?:\.\${0,1}[A-Za-z0-9_]+)*(?:(?:\[\${0,1}[A-Za-z0-9_]+\])|(?:\-\>\${0,1}[A-Za-z0-9_]+))*)(.*?)' . $tag_right_delimiter . '/', $html, $matches ) ){
@ -876,8 +988,10 @@ class RainTPL{
/**
* Check if function is in black list (sandbox)
*
* @access protected
* @param string $code
* @param string $tag
* @throws RainTpl_SyntaxException
* @return void
*/
protected function function_check( $code ){
@ -904,6 +1018,7 @@ class RainTPL{
/**
* Prints debug info about exception or passes it further if debug is disabled.
*
* @access protected
* @param RainTpl_Exception $e
* @return string
*/

View File

@ -55,6 +55,7 @@ class filter
* validate paste ID
*
* @access public
* @static
* @param string $dataid
* @return bool
*/
@ -68,6 +69,7 @@ class filter
* https://crackstation.net/hashing-security.htm?=rd#slowequals
*
* @access public
* @static
* @param string $a
* @param string $b
* @return bool

View File

@ -18,6 +18,8 @@
abstract class persistence
{
/**
* path in which to persist something
*
* @access private
* @static
* @var string

View File

@ -23,6 +23,8 @@
class serversalt extends persistence
{
/**
* generated salt
*
* @access private
* @static
* @var string

View File

@ -18,6 +18,8 @@
class trafficlimiter extends persistence
{
/**
* time limit in seconds, defaults to 10s
*
* @access private
* @static
* @var int

View File

@ -24,22 +24,67 @@
class vizhash16x16
{
/**
* hash values
*
* @access private
* @var array
*/
private $VALUES;
/**
* index of current value
*
* @access private
* @var int
*/
private $VALUES_INDEX;
/**
* image width
*
* @access private
* @var int
*/
private $width;
/**
* image height
*
* @access private
* @var int
*/
private $height;
/**
* salt used when generating the image
*
* @access private
* @var string
*/
private $salt;
function __construct()
/**
* constructor
*
* @access public
* @return void
*/
public function __construct()
{
$this->width=16;
$this->height=16;
$this->width = 16;
$this->height = 16;
$this->salt = serversalt::get();
}
// Generate a 16x16 png corresponding to $text.
// Input: $text (string)
// Output: PNG data. Or empty string if GD is not available.
function generate($text)
/**
* Generate a 16x16 png corresponding to $text.
*
* @access public
* @param string $text
* @return string PNG data. Or empty string if GD is not available.
*/
public function generate($text)
{
if (!function_exists('gd_info')) return '';
@ -85,7 +130,13 @@ class vizhash16x16
return $imagedata;
}
private function getInt() // Returns a single integer from the $VALUES array (0...255)
/**
* Returns a single integer from the $VALUES array (0...255)
*
* @access private
* @return int
*/
private function getInt()
{
$v= $this->VALUES[$this->VALUES_INDEX];
$this->VALUES_INDEX++;
@ -93,18 +144,41 @@ class vizhash16x16
return $v;
}
private function getX() // Returns a single integer from the array (roughly mapped to image width)
/**
* Returns a single integer from the array (roughly mapped to image width)
*
* @access private
* @return int
*/
private function getX()
{
return $this->width*$this->getInt()/256;
}
private function getY() // Returns a single integer from the array (roughly mapped to image height)
/**
* Returns a single integer from the array (roughly mapped to image height)
*
* @access private
* @return int
*/
private function getY()
{
return $this->height*$this->getInt()/256;
}
# Gradient function taken from:
# http://www.supportduweb.com/scripts_tutoriaux-code-source-41-gd-faire-un-degrade-en-php-gd-fonction-degrade-imagerie.html
/**
* Gradient function
*
* taken from:
* http://www.supportduweb.com/scripts_tutoriaux-code-source-41-gd-faire-un-degrade-en-php-gd-fonction-degrade-imagerie.html
*
* @access private
* @param resource $img
* @param string $direction
* @param array $color1
* @param array $color2
* @return resource
*/
private function degrade($img,$direction,$color1,$color2)
{
if($direction=='h') { $size = imagesx($img); $sizeinv = imagesy($img); }
@ -125,6 +199,15 @@ class vizhash16x16
return $img;
}
/**
* Draw a shape
*
* @access private
* @param resource $image
* @param int $action
* @param int $color
* @return void
*/
private function drawshape($image,$action,$color)
{
switch($action%7)

View File

@ -17,12 +17,16 @@
*/
class zerobin
{
/*
* @const string version
/**
* version
*
* @const string
*/
const VERSION = 'Alpha 0.19';
/**
* configuration array
*
* @access private
* @var array
*/
@ -31,26 +35,34 @@ class zerobin
);
/**
* data
*
* @access private
* @var string
*/
private $_data = '';
/**
* error message
*
* @access private
* @var string
*/
private $_error = '';
/**
* status message
*
* @access private
* @var string
*/
private $_status = '';
/**
* data storage model
*
* @access private
* @var zerobin_data
* @var zerobin_abstract
*/
private $_model;
@ -60,6 +72,7 @@ class zerobin
* initializes and runs ZeroBin
*
* @access public
* @return void
*/
public function __construct()
{
@ -128,7 +141,7 @@ class zerobin
* get the model, create one if needed
*
* @access private
* @return zerobin_data
* @return zerobin_abstract
*/
private function _model()
{

View File

@ -20,7 +20,7 @@ abstract class zerobin_abstract
/**
* singleton instance
*
* @access private
* @access protected
* @static
* @var zerobin
*/
@ -49,6 +49,7 @@ abstract class zerobin_abstract
*
* @access public
* @static
* @param array $options
* @return zerobin_abstract
*/
public static function getInstance($options) {}

View File

@ -17,10 +17,12 @@
*/
class zerobin_data extends zerobin_abstract
{
/*
/**
* directory where data is stored
*
* @access private
* @static
* @var string directory where data is stored
* @var string
*/
private static $_dir = 'data/';
@ -29,6 +31,7 @@ class zerobin_data extends zerobin_abstract
*
* @access public
* @static
* @param array $options
* @return zerobin_data
*/
public static function getInstance($options = null)

View File

@ -17,31 +17,37 @@
*/
class zerobin_db extends zerobin_abstract
{
/*
* @access private
* @static
* @var array to cache select queries
/**
* cache for select queries
*
* @var array
*/
private static $_cache = array();
/*
/**
* instance of database connection
*
* @access private
* @static
* @var PDO instance of database connection
* @var PDO
*/
private static $_db;
/*
/**
* table prefix
*
* @access private
* @static
* @var string table prefix
* @var string
*/
private static $_prefix = '';
/*
/**
* database type
*
* @access private
* @static
* @var string database type
* @var string
*/
private static $_type = '';
@ -50,6 +56,7 @@ class zerobin_db extends zerobin_abstract
*
* @access public
* @static
* @param array $options
* @throws Exception
* @return zerobin_db
*/