Add phpdoc comments

This commit is contained in:
Frédéric Guillot 2014-09-23 19:46:05 +02:00
parent 484c9614d1
commit dd7579e5a8
2 changed files with 393 additions and 58 deletions

View File

@ -4,6 +4,11 @@ use Core\Event;
use Core\Translator;
use PicoDb\Database;
/**
* Send a debug message to the log files
*
* @param mixed $message Variable or string
*/
function debug($message)
{
if (! is_string($message)) {
@ -13,11 +18,21 @@ function debug($message)
error_log($message.PHP_EOL, 3, 'data/debug.log');
}
/**
* Setup events
*
* @return Core\Event
*/
function setup_events()
{
return new Event;
}
/**
* Setup the mailer according to the configuration
*
* @return Swift_SmtpTransport
*/
function setup_mailer()
{
require_once __DIR__.'/../vendor/swiftmailer/swift_required.php';
@ -39,52 +54,30 @@ function setup_mailer()
return $transport;
}
/**
* Setup the database driver and execute schema migration
*
* @return PicoDb\Database
*/
function setup_db()
{
switch (DB_DRIVER) {
case 'sqlite':
require_once __DIR__.'/Schema/Sqlite.php';
$params = array(
'driver' => 'sqlite',
'filename' => DB_FILENAME
);
$db = setup_sqlite();
break;
case 'mysql':
require_once __DIR__.'/Schema/Mysql.php';
$params = array(
'driver' => 'mysql',
'hostname' => DB_HOSTNAME,
'username' => DB_USERNAME,
'password' => DB_PASSWORD,
'database' => DB_NAME,
'charset' => 'utf8',
);
$db = setup_mysql();
break;
case 'postgres':
require_once __DIR__.'/Schema/Postgres.php';
$params = array(
'driver' => 'postgres',
'hostname' => DB_HOSTNAME,
'username' => DB_USERNAME,
'password' => DB_PASSWORD,
'database' => DB_NAME,
);
$db = setup_postgres();
break;
default:
die('Database driver not supported');
}
$db = new Database($params);
if ($db->schema()->check(Schema\VERSION)) {
return $db;
}
@ -94,42 +87,119 @@ function setup_db()
}
}
// Get a translation
/**
* Setup the Sqlite database driver
*
* @return PicoDb\Database
*/
function setup_sqlite()
{
require_once __DIR__.'/Schema/Sqlite.php';
return new Database(array(
'driver' => 'sqlite',
'filename' => DB_FILENAME
));
}
/**
* Setup the Mysql database driver
*
* @return PicoDb\Database
*/
function setup_mysql()
{
require_once __DIR__.'/Schema/Mysql.php';
return new Database(array(
'driver' => 'mysql',
'hostname' => DB_HOSTNAME,
'username' => DB_USERNAME,
'password' => DB_PASSWORD,
'database' => DB_NAME,
'charset' => 'utf8',
));
}
/**
* Setup the Postgres database driver
*
* @return PicoDb\Database
*/
function setup_postgres()
{
require_once __DIR__.'/Schema/Postgres.php';
return new Database(array(
'driver' => 'postgres',
'hostname' => DB_HOSTNAME,
'username' => DB_USERNAME,
'password' => DB_PASSWORD,
'database' => DB_NAME,
));
}
/**
* Translate a string
*
* @return string
*/
function t()
{
$t = new Translator;
return call_user_func_array(array($t, 'translate'), func_get_args());
}
// translate with no html escaping
/**
* Translate a string with no HTML escaping
*
* @return string
*/
function e()
{
$t = new Translator;
return call_user_func_array(array($t, 'translateNoEscaping'), func_get_args());
}
// Get a locale currency
/**
* Translate a currency
*
* @return string
*/
function c($value)
{
$t = new Translator;
return $t->currency($value);
}
// Get a formatted number
/**
* Translate a number
*
* @return string
*/
function n($value)
{
$t = new Translator;
return $t->number($value);
}
// Get a locale date
/**
* Translate a date
*
* @return string
*/
function dt($format, $timestamp)
{
$t = new Translator;
return $t->datetime($format, $timestamp);
}
// Plurals, return $t2 if $value > 1
/**
* Handle plurals, return $t2 if $value > 1
*
* @todo Improve this function
* @return mixed
*/
function p($value, $t1, $t2) {
return $value > 1 ? $t2 : $t1;
}

View File

@ -2,50 +2,110 @@
namespace Helper;
use Core\Security;
/**
* Template helpers
*
*/
use Core\Security;
use Core\Template;
use Core\Tool;
use Michelf\MarkdownExtra;
/**
* Append a CSRF token to a query string
*
* @return string
*/
function param_csrf()
{
return '&csrf_token='.Security::getCSRFToken();
}
/**
* Add a Javascript asset
*
* @param string $filename Filename
* @return string
*/
function js($filename)
{
return '<script type="text/javascript" src="'.$filename.'?'.filemtime($filename).'"></script>';
}
/**
* Add a stylesheet asset
*
* @param string $filename Filename
* @return string
*/
function css($filename)
{
return '<link rel="stylesheet" href="'.$filename.'?'.filemtime($filename).'" media="screen">';
}
/**
* Load a template
*
* @param string $name Template name
* @param array $args Template parameters
* @return string
*/
function template($name, array $args = array())
{
$tpl = new \Core\Template;
$tpl = new Template;
return $tpl->load($name, $args);
}
/**
* Check if the given user_id is the connected user
*
* @param integer $user_id User id
* @return boolean
*/
function is_current_user($user_id)
{
return $_SESSION['user']['id'] == $user_id;
}
/**
* Check if the current user is administrator
*
* @return boolean
*/
function is_admin()
{
return $_SESSION['user']['is_admin'] == 1;
}
function get_username($user = false)
/**
* Return the username
*
* @param array $user User properties (optional)
* @return string
*/
function get_username(array $user = array())
{
return $user ? ($user['name'] ?: $user['username'])
return ! empty($user) ? ($user['name'] ?: $user['username'])
: ($_SESSION['user']['name'] ?: $_SESSION['user']['username']);
}
/**
* Get the current user id
*
* @return integer
*/
function get_user_id()
{
return $_SESSION['user']['id'];
}
/**
* Transform a Markdown text to HTML and add some post-processing
*
* @param string $text Markdown content
* @return string
*/
function parse($text)
{
$text = markdown($text);
@ -53,20 +113,28 @@ function parse($text)
return $text;
}
/**
* Markdown transformation
*
* @param string $text Markdown content
* @return string
*/
function markdown($text)
{
require_once __DIR__.'/../vendor/Michelf/MarkdownExtra.inc.php';
$parser = new \Michelf\MarkdownExtra;
$parser = new MarkdownExtra;
$parser->no_markup = true;
$parser->no_entities = true;
return $parser->transform($text);
}
/**
* Get the current URL without the querystring
*
* @return string
*/
function get_current_base_url()
{
$url = \Core\Tool::isHTTPS() ? 'https://' : 'http://';
$url = Tool::isHTTPS() ? 'https://' : 'http://';
$url .= $_SERVER['SERVER_NAME'];
$url .= $_SERVER['SERVER_PORT'] == 80 || $_SERVER['SERVER_PORT'] == 443 ? '' : ':'.$_SERVER['SERVER_PORT'];
$url .= dirname($_SERVER['PHP_SELF']) !== '/' ? dirname($_SERVER['PHP_SELF']).'/' : '/';
@ -74,11 +142,23 @@ function get_current_base_url()
return $url;
}
/**
* HTML escaping
*
* @param string $value Value to escape
* @return string
*/
function escape($value)
{
return htmlspecialchars($value, ENT_QUOTES, 'UTF-8', false);
}
/**
* Dispplay the flash session message
*
* @param string $html HTML wrapper
* @return string
*/
function flash($html)
{
$data = '';
@ -91,6 +171,12 @@ function flash($html)
return $data;
}
/**
* Display the flash session error message
*
* @param string $html HTML wrapper
* @return string
*/
function flash_error($html)
{
$data = '';
@ -103,6 +189,13 @@ function flash_error($html)
return $data;
}
/**
* Format a file size
*
* @param integer $size Size in bytes
* @param integer $precision Precision
* @return string
*/
function format_bytes($size, $precision = 2)
{
$base = log($size) / log(1024);
@ -111,11 +204,14 @@ function format_bytes($size, $precision = 2)
return round(pow(1024, $base - floor($base)), $precision).$suffixes[(int)floor($base)];
}
function get_host_from_url($url)
{
return escape(parse_url($url, PHP_URL_HOST)) ?: $url;
}
/**
* Truncate a long text
*
* @param string $value Text
* @param integer $max_length Max Length
* @param string $end Text end
* @return string
*/
function summary($value, $max_length = 85, $end = '[...]')
{
$length = strlen($value);
@ -127,11 +223,26 @@ function summary($value, $max_length = 85, $end = '[...]')
return $value;
}
/**
* Return true if needle is contained in the haystack
*
* @param string $haystack Haystack
* @param string $needle Needle
* @return boolean
*/
function contains($haystack, $needle)
{
return strpos($haystack, $needle) !== false;
}
/**
* Return a value from a dictionary
*
* @param mixed $id Key
* @param array $listing Dictionary
* @param string $default_value Value displayed when the key doesn't exists
* @return string
*/
function in_list($id, array $listing, $default_value = '?')
{
if (isset($listing[$id])) {
@ -141,11 +252,25 @@ function in_list($id, array $listing, $default_value = '?')
return $default_value;
}
/**
* Display the form error class
*
* @param array $errors Error list
* @param string $name Field name
* @return string
*/
function error_class(array $errors, $name)
{
return ! isset($errors[$name]) ? '' : ' form-error';
}
/**
* Display a list of form errors
*
* @param array $errors List of errors
* @param string $name Field name
* @return string
*/
function error_list(array $errors, $name)
{
$html = '';
@ -164,6 +289,13 @@ function error_list(array $errors, $name)
return $html;
}
/**
* Get an escaped form value
*
* @param mixed $values Values
* @param string $name Field name
* @return string
*/
function form_value($values, $name)
{
if (isset($values->$name)) {
@ -173,23 +305,39 @@ function form_value($values, $name)
return isset($values[$name]) ? 'value="'.escape($values[$name]).'"' : '';
}
/**
* Hidden CSRF token field
*
* @return string
*/
function form_csrf()
{
return '<input type="hidden" name="csrf_token" value="'.Security::getCSRFToken().'"/>';
}
function form_hidden($name, $values = array())
/**
* Display a hidden form field
*
* @param string $name Field name
* @param array $values Form values
* @return string
*/
function form_hidden($name, array $values = array())
{
return '<input type="hidden" name="'.$name.'" id="form-'.$name.'" '.form_value($values, $name).'/>';
}
function form_default_select($name, array $options, $values = array(), array $errors = array(), $class = '')
{
$options = array('' => '?') + $options;
return form_select($name, $options, $values, $errors, $class);
}
function form_select($name, array $options, $values = array(), array $errors = array(), $class = '')
/**
* Display a select field
*
* @param string $name Field name
* @param array $options Options
* @param array $values Form values
* @param array $errors Form errors
* @param string $class CSS class
* @return string
*/
function form_select($name, array $options, array $values = array(), array $errors = array(), $class = '')
{
$html = '<select name="'.$name.'" id="form-'.$name.'" class="'.$class.'">';
@ -209,6 +357,14 @@ function form_select($name, array $options, $values = array(), array $errors = a
return $html;
}
/**
* Display a radio field group
*
* @param string $name Field name
* @param array $options Options
* @param array $values Form values
* @return string
*/
function form_radios($name, array $options, array $values = array())
{
$html = '';
@ -220,21 +376,59 @@ function form_radios($name, array $options, array $values = array())
return $html;
}
/**
* Display a radio field
*
* @param string $name Field name
* @param string $label Form label
* @param string $value Form value
* @param boolean $selected Field selected or not
* @param string $class CSS class
* @return string
*/
function form_radio($name, $label, $value, $selected = false, $class = '')
{
return '<label><input type="radio" name="'.$name.'" class="'.$class.'" value="'.escape($value).'" '.($selected ? 'selected="selected"' : '').'>'.escape($label).'</label>';
}
/**
* Display a checkbox field
*
* @param string $name Field name
* @param string $label Form label
* @param string $value Form value
* @param boolean $checked Field selected or not
* @param string $class CSS class
* @return string
*/
function form_checkbox($name, $label, $value, $checked = false, $class = '')
{
return '<label><input type="checkbox" name="'.$name.'" class="'.$class.'" value="'.escape($value).'" '.($checked ? 'checked="checked"' : '').'>&nbsp;'.escape($label).'</label>';
}
/**
* Display a form label
*
* @param string $name Field name
* @param string $label Form label
* @param array $attributes HTML attributes
* @return string
*/
function form_label($label, $name, array $attributes = array())
{
return '<label for="form-'.$name.'" '.implode(' ', $attributes).'>'.escape($label).'</label>';
}
/**
* Display a textarea
*
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_textarea($name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
$class .= error_class($errors, $name);
@ -249,6 +443,17 @@ function form_textarea($name, $values = array(), array $errors = array(), array
return $html;
}
/**
* Display a input field
*
* @param string $type HMTL input tag type
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_input($type, $name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
$class .= error_class($errors, $name);
@ -261,31 +466,91 @@ function form_input($type, $name, $values = array(), array $errors = array(), ar
return $html;
}
/**
* Display a text field
*
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_text($name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
return form_input('text', $name, $values, $errors, $attributes, $class);
}
/**
* Display a password field
*
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_password($name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
return form_input('password', $name, $values, $errors, $attributes, $class);
}
/**
* Display an email field
*
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_email($name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
return form_input('email', $name, $values, $errors, $attributes, $class);
}
/**
* Display a date field
*
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_date($name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
return form_input('date', $name, $values, $errors, $attributes, $class);
}
/**
* Display a number field
*
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_number($name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
return form_input('number', $name, $values, $errors, $attributes, $class);
}
/**
* Display a numeric field (allow decimal number)
*
* @param string $name Field name
* @param array $values Form values
* @param array $errors Form errors
* @param array $attributes HTML attributes
* @param string $class CSS class
* @return string
*/
function form_numeric($name, $values = array(), array $errors = array(), array $attributes = array(), $class = '')
{
return form_input('text', $name, $values, $errors, $attributes, $class.' form-numeric');