Add phpdoc comments

2 files changed, 393 insertions, 58 deletions

diff --git a/app/functions.php b/app/functions.php
index dc6431b9..c39eaf98 100644
--- a/app/functions.php
+++ b/app/functions.php
@@ -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;
 }
diff --git a/app/helpers.php b/app/helpers.php
index 3586c3b3..0638e5a4 100644
--- a/app/helpers.php
+++ b/app/helpers.php
@@ -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');