add docblocks to all files, classes, methods and variables
authorChristian Weiske <cweiske@cweiske.de>
Thu, 20 Mar 2014 16:03:06 +0000 (17:03 +0100)
committerChristian Weiske <cweiske@cweiske.de>
Thu, 20 Mar 2014 16:03:06 +0000 (17:03 +0100)
19 files changed:
bin/bdrem.php
src/bdrem/Autoloader.php
src/bdrem/Cli.php
src/bdrem/Config.php
src/bdrem/Event.php
src/bdrem/Renderer.php
src/bdrem/Renderer/Console.php
src/bdrem/Renderer/Html.php
src/bdrem/Renderer/HtmlTable.php
src/bdrem/Renderer/Mail.php
src/bdrem/Source/Bdf.php
src/bdrem/Source/Ldap.php
src/bdrem/Source/Sql.php
src/bdrem/UserInterface.php
src/bdrem/Web.php
src/bdrem/WebText.php
src/phar-stub.php
www/index.php
www/text.php

index 4965c3d..d5a40db 100755 (executable)
@@ -1,9 +1,21 @@
 #!/usr/bin/env php
 <?php
+/**
+ * Script to start bdrem.
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 if (file_exists(__DIR__ . '/../src/bdrem/Autoloader.php')) {
-    require_once __DIR__ . '/../src/bdrem/Autoloader.php';
+    include_once __DIR__ . '/../src/bdrem/Autoloader.php';
     Autoloader::register();
 }
 $cli = new Cli();
index 093b1b0..cebd0eb 100644 (file)
@@ -1,16 +1,51 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Class autoloader, PSR-0 compliant.
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Autoloader
 {
+    /**
+     * Load the given class
+     *
+     * @param string $class Class name
+     *
+     * @return void
+     */
     public function load($class)
     {
         $file = strtr($class, '_\\', '//') . '.php';
         if (stream_resolve_include_path($file)) {
-            require $file;
+            include $file;
         }
     }
 
+    /**
+     * Register this autoloader
+     *
+     * @return void
+     */
     public static function register()
     {
         set_include_path(
index f108e8e..0525a37 100644 (file)
@@ -1,8 +1,39 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Command line user interface for the terminal/shell.
+ * Renders an ASCII table by default.
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Cli extends UserInterface
 {
+    /**
+     * Load parameters for the CLI option parser.
+     * Set the default renderer to "console" and adds some CLI-only commands
+     * like "readme" and "config".
+     *
+     * @return \Console_CommandLine CLI option parser
+     */
     protected function loadParameters()
     {
         $parser = parent::loadParameters();
@@ -24,6 +55,13 @@ class Cli extends UserInterface
         return $parser;
     }
 
+    /**
+     * Handle any commands given on the CLI
+     *
+     * @param object $res Command line parameters and options
+     *
+     * @return void
+     */
     protected function handleCommands($res)
     {
         if ($res->command_name == '') {
@@ -37,12 +75,22 @@ class Cli extends UserInterface
         }
     }
 
+    /**
+     * Handle the "readme" command and output the readme.
+     *
+     * @return void
+     */
     protected function showReadme()
     {
         readfile(__DIR__ . '/../../README.rst');
         exit();
     }
 
+    /**
+     * Handle the "config" command and output the default configuration
+     *
+     * @return void
+     */
     protected function extractConfig()
     {
         readfile(__DIR__ . '/../../data/bdrem.config.php.dist');
index 57d0cfd..f586ed3 100644 (file)
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Configuration options for bdrem
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Config
 {
+    /**
+     * Current date, YYYY-MM-DD
+     * @var string
+     */
     public $date;
+
+    /**
+     * Days to show before $date
+     * @var integer
+     */
     public $daysPrev;
+
+    /**
+     * Days to show after $date
+     * @var integer
+     */
     public $daysNext;
+
+    /**
+     * Locale to render the dates in, e.g. "de_DE.UTF-8"
+     * @var string
+     */
     public $locale;
+
+    /**
+     * Renderer name to use (e.g. "console")
+     * @var string
+     */
     public $renderer;
+
+    /**
+     * Event source configuration.
+     * - First value is source name ("Ldap", "Sql")
+     * - Second value is the source configuration
+     * @var array
+     */
     public $source;
+
+    /**
+     * Do not output anything if there are no events to show
+     * @var boolean
+     */
     public $stopOnEmpty;
 
+    /**
+     * List of config file paths that were tried to load
+     * @var array
+     */
     public $cfgFiles = array();
+
+    /**
+     * If a configuration file could be found
+     * @var boolean
+     */
     public $cfgFileExists;
 
 
 
+    /**
+     * Init configuration file path loading
+     */
     public function __construct()
     {
         $this->loadConfigFilePaths();
     }
 
+    /**
+     * Load the configuration from the first configuration file found.
+     *
+     * @return void
+     */
     public function load()
     {
         foreach ($this->cfgFiles as $file) {
@@ -32,6 +108,11 @@ class Config
         $this->cfgFileExists = false;
     }
 
+    /**
+     * Load possible configuration file paths into $this->cfgFiles.
+     *
+     * @return void
+     */
     protected function loadConfigFilePaths()
     {
         $pharFile = \Phar::running();
@@ -47,6 +128,13 @@ class Config
         $this->cfgFiles[] = '/etc/bdrem.php';
     }
 
+    /**
+     * Load a single configuration file and set the config class variables
+     *
+     * @param string $filename Configuration file path
+     *
+     * @return void
+     */
     protected function loadFile($filename)
     {
         include $filename;
@@ -58,6 +146,12 @@ class Config
         }
     }
 
+    /**
+     * Load a event source from $this->source.
+     * Class name has to be \bdrem\Source_$source
+     *
+     * @return object Source object
+     */
     public function loadSource()
     {
         if ($this->source === null) {
@@ -70,6 +164,13 @@ class Config
         return new $class($settings[0]);
     }
 
+    /**
+     * Set the current date
+     *
+     * @param string $date Date in any format
+     *
+     * @return void
+     */
     public function setDate($date)
     {
         if ($date === null) {
@@ -80,6 +181,15 @@ class Config
         }
     }
 
+    /**
+     * Get a configuration variable
+     *
+     * @param string $varname Configuration variable name
+     * @param string $default Default value in case the variable is not set
+     *                        or is empty
+     *
+     * @return mixed Configuration value or default
+     */
     public function get($varname, $default = '')
     {
         if (!isset($this->$varname) || $this->$varname == '') {
index 29585e7..e0d1839 100644 (file)
@@ -1,20 +1,46 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Event model with title, type and date.
+ * Contains calculation methods
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Event
 {
     /**
      * Title of the event or name of the person that has the event
+     * @var string
      */
     public $title;
 
     /**
      * Type of the event, e.g. "birthday"
+     * @var string
      */
     public $type;
 
     /**
-     * Date of the event. 
+     * Date of the event.
      * ???? as year is allowed
      *
      * @var string YYYY-MM-DD
@@ -53,6 +79,13 @@ class Event
 
 
 
+    /**
+     * Set event data
+     *
+     * @param string $title Name of person the event relates to
+     * @param string $type  Type of the event (e.g. "birthday")
+     * @param string $date  Date of the event in format YYYY-MM-DD
+     */
     public function __construct($title = null, $type = null, $date = null)
     {
         $this->title = $title;
@@ -64,9 +97,13 @@ class Event
      * Checks if the event's date is within the given date.
      * Also calculates the age and days since the event.
      *
+     * @param string  $strDate       Date, YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
      * @return boolean True if the event's date is within the given range
      */
-    public function isWithin($strDate, $nDaysPrev, $nDaysNext)
+    public function isWithin($strDate, $nDaysPrevious, $nDaysNext)
     {
         $this->refDate = $strDate;
         list($rYear, $rMonth, $rDay) = explode('-', $strDate);
@@ -106,13 +143,19 @@ class Event
         if ($nDiff > 0) {
             return $nDiff <= $nDaysNext;
         } else {
-            return -$nDiff <= $nDaysPrev;
+            return -$nDiff <= $nDaysPrevious;
         }
 
         return false;
     }
 
     /**
+     * Compare two events by by their date, then by their title.
+     * Used for sorting
+     *
+     * @param Event $e1 Event #1
+     * @param Event $e2 Event #2
+     *
      * @return integer x < 0: e1 is less than e2
      *                 x > 0: e1 is larger than e2
      */
@@ -120,7 +163,7 @@ class Event
     {
         list($e1Year, $e1Month, $e1Day) = explode('-', $e1->date);
         list($e2Year, $e2Month, $e2Day) = explode('-', $e2->date);
-        
+
         if ($e1Month < 3 && $e2Month > 10) {
             return 1;
         } else if ($e1Month > 10 && $e2Month < 3) {
index 363d413..7357af6 100644 (file)
@@ -1,10 +1,44 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Base event renderer
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 abstract class Renderer
 {
+    /**
+     * HTTP content type of output
+     * @var string
+     */
     protected $httpContentType = null;
 
+    /**
+     * Call the renderer and output the rendering result to shell or browser
+     *
+     * @param array $arEvents Event objects to render
+     *
+     * @return void
+     */
     public function renderAndOutput($arEvents)
     {
         if (PHP_SAPI != 'cli' && $this->httpContentType !== null) {
@@ -13,12 +47,31 @@ abstract class Renderer
         echo $this->render($arEvents);
     }
 
+    /**
+     * Do something when there are no events to render
+     *
+     * @return void
+     */
     public function handleStopOnEmpty()
     {
     }
 
+    /**
+     * Display the events in some way
+     *
+     * @param array $arEvents Events to display
+     *
+     * @return string Event representation
+     */
     abstract public function render($arEvents);
 
+    /**
+     * Converts the given date string according to the user's locale setting.
+     *
+     * @param string $dateStr Date in format YYYY-MM-DD
+     *
+     * @return string Formatted date
+     */
     protected function getLocalDate($dateStr)
     {
         if ($dateStr{0} != '?') {
index 87eeb9a..61fb67e 100644 (file)
@@ -1,8 +1,35 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Render events on the terminal as ASCII table
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Renderer_Console extends Renderer
 {
+    /**
+     * HTTP content type
+     * @var string
+     */
     protected $httpContentType = 'text/plain; charset=utf-8';
 
     /**
@@ -17,6 +44,13 @@ class Renderer_Console extends Renderer
      */
     protected $cc;
 
+    /**
+     * Render events as console table
+     *
+     * @param array $arEvents Array of events to render
+     *
+     * @return string ASCII table
+     */
     public function render($arEvents)
     {
         $this->loadConfig();
@@ -70,6 +104,14 @@ class Renderer_Console extends Renderer
         return $tbl->getTable();
     }
 
+    /**
+     * Wrap each string in an array in an ANSI color code
+     *
+     * @param array  $data      Array of strings
+     * @param string $colorCode ANSI color code or name
+     *
+     * @return array Wrapped data
+     */
     protected function ansiWrap($data, $colorCode = null)
     {
         if (!$this->ansi || $colorCode === null) {
@@ -84,6 +126,11 @@ class Renderer_Console extends Renderer
         return $data;
     }
 
+    /**
+     * Load configuration values into the class
+     *
+     * @return void
+     */
     protected function loadConfig()
     {
         if (isset($this->config->ansi)) {
index 637a838..428f819 100644 (file)
@@ -1,22 +1,64 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * HTML page renderer. Renders a full HTML page.
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Renderer_Html extends Renderer
 {
+    /**
+     * HTTP content type
+     * @var string
+     */
     protected $httpContentType = 'application/xhtml+xml; charset=utf-8';
 
+    /**
+     * Send out HTTP headers when nothing shall be outputted.
+     *
+     * @return void
+     */
     public function handleStopOnEmpty()
     {
         header('HTTP/1.0 204 No Content');
     }
 
+    /**
+     * Generate a HTML page with the given events.
+     *
+     * @param array $arEvents Events to display on the HTML page
+     *
+     * @return string HTML code
+     *
+     * @see Renderer_HtmlTable
+     */
     public function render($arEvents)
     {
         $tr = new Renderer_HtmlTable();
         $table = $tr->render($arEvents);
         $s = <<<HTM
 <?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
   <title>bdrem</title>
index 2c792f8..892c50a 100644 (file)
@@ -1,10 +1,44 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Renders events in a HTML table.
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Renderer_HtmlTable extends Renderer
 {
+    /**
+     * HTTP content type
+     * @var string
+     */
     protected $httpContentType = 'text/html; charset=utf-8';
 
+    /**
+     * Render the events in a HTML table
+     *
+     * @param array $arEvents Event objects to render
+     *
+     * @return string HTML table
+     */
     public function render($arEvents)
     {
         $s = <<<HTM
index 8e0e625..bc7e220 100644 (file)
@@ -1,10 +1,44 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 require_once 'Mail/mime.php';
 
+/**
+ * Send out mails
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Renderer_Mail extends Renderer
 {
+    /**
+     * Render the events - send out mails.
+     *
+     * Uses the config's "mail_to" array as recipients.
+     * Sends out a single mail for each recipient.
+     * Config "mail_from" can also be used.
+     *
+     * @param array $arEvents Array of events to display
+     *
+     * @return void
+     */
     public function render($arEvents)
     {
         $todays = array();
@@ -49,6 +83,15 @@ class Renderer_Mail extends Renderer
         }
     }
 
+    /**
+     * Shorten the given string to the specified length.
+     * Adds ... when the string was too long
+     *
+     * @param string  $str String to shorten
+     * @param integer $len Maximum length of the string
+     *
+     * @return string Shortened string
+     */
     protected function shorten($str, $len)
     {
         if (mb_strlen($str) <= $len) {
index f38e30f..651360a 100644 (file)
@@ -1,13 +1,41 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 /**
  * Reads birthday reminder 2's birthday files (.bdf).
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
  */
 class Source_Bdf
 {
+    /**
+     * Full path of bdf birthday file
+     * @var string
+     */
     protected $filename;
 
+    /**
+     * Set the birthday file name
+     *
+     * @param string $filename Path to bdf file
+     */
     public function __construct($filename)
     {
         $this->filename = $filename;
@@ -19,9 +47,16 @@ class Source_Bdf
     }
 
     /**
-     * @param string $strDate Date the events shall be found for, YYYY-MM-DD
+     * Return all events for the given date range
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
+     * @return Event[] Array of matching event objects
      */
-    public function getEvents($strDate, $nDaysPrev, $nDaysNext)
+    public function getEvents($strDate, $nDaysPrevious, $nDaysNext)
     {
         $x = simplexml_load_file($this->filename);
 
@@ -38,7 +73,7 @@ class Source_Bdf
                 (string) $xPerson->event,
                 $date
             );
-            if ($event->isWithin($strDate, $nDaysPrev, $nDaysNext)) {
+            if ($event->isWithin($strDate, $nDaysPrevious, $nDaysNext)) {
                 $arEvents[] = $event;
             }
         }
index 335be07..aa45b0a 100644 (file)
@@ -1,12 +1,42 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 /**
  * Fetch data from an LDAP server.
  * Works fine with evolutionPerson schema.
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
  */
 class Source_Ldap
 {
+    /**
+     * LDAP server configuration
+     *
+     * Keys:
+     * - host   - LDAP server host name
+     * - basedn - root DN that gets searched
+     * - binddn - Username to authenticate with
+     * - bindpw - Password for username
+     *
+     * @var array
+     */
     protected $config;
 
     /**
@@ -25,7 +55,14 @@ class Source_Ldap
     }
 
     /**
-     * @param string $strDate Date the events shall be found for, YYYY-MM-DD
+     * Return all events for the given date range
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
+     * @return Event[] Array of matching event objects
      */
     public function getEvents($strDate, $nDaysPrevious, $nDaysNext)
     {
@@ -89,6 +126,14 @@ class Source_Ldap
         return $arEvents;
     }
 
+    /**
+     * Extract the name from the given LDAP entry object.
+     * Uses displayName or givenName + sn
+     *
+     * @param object $entry LDAP entry
+     *
+     * @return string Name or NULL
+     */
     protected function getNameFromEntry(\Net_LDAP2_Entry $entry)
     {
         $arEntry = $entry->getValues();
@@ -103,6 +148,13 @@ class Source_Ldap
     }
 
     /**
+     * Create an array of dates that are included in the given range.
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
      * @return array Values like "-01-24" ("-$month-$day")
      */
     protected function getDates($strDate, $nDaysPrevious, $nDaysNext)
@@ -117,6 +169,5 @@ class Source_Ldap
         } while (--$numDays >= 0);
         return $arDays;
     }
-
 }
 ?>
index 57f9a80..81ce5be 100644 (file)
@@ -1,17 +1,73 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 /**
  * Fetch data from an SQL database
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
  */
 class Source_Sql
 {
+    /**
+     * PDO data source description
+     * @var string
+     */
     protected $dsn;
+
+    /**
+     * Database user name
+     * @var string
+     */
     protected $user;
+
+    /**
+     * Database password
+     * @var string
+     */
     protected $password;
+
+    /**
+     * Database table with event data
+     * @var string
+     */
     protected $table;
-    protected $fields ;
 
+    /**
+     * Field configuration
+     * Keys:
+     * - date - array of columns with dates and their event title,
+     *          e.g. 'c_birthday' => 'Birthday'
+     * - name - array of name columns
+     * - nameFormat - sprintf-compatible name formatting instruction,
+     *                uses name columns
+     *
+     * @var array
+     */
+    protected $fields;
+
+    /**
+     * Set SQL server configuration
+     *
+     * @param array $config SQL server configuration with keys:
+     *                      dsn, user, password, table and fields
+     */
     public function __construct($config)
     {
         $this->dsn      = $config['dsn'];
@@ -22,7 +78,14 @@ class Source_Sql
     }
 
     /**
-     * @param string $strDate Date the events shall be found for, YYYY-MM-DD
+     * Return all events for the given date range
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
+     * @return Event[] Array of matching event objects
      */
     public function getEvents($strDate, $nDaysPrevious, $nDaysNext)
     {
@@ -85,6 +148,13 @@ class Source_Sql
     }
 
     /**
+     * Create an array of dates that are included in the given range.
+     *
+     * @param string  $strDate       Date the events shall be found for,
+     *                               YYYY-MM-DD
+     * @param integer $nDaysPrevious Include number of days before $strDate
+     * @param integer $nDaysNext     Include number of days after $strDate
+     *
      * @return array Key is the month, value an array of days
      */
     protected function getDates($strDate, $nDaysPrevious, $nDaysNext)
index 2ba1cfb..de6d3bb 100644 (file)
@@ -1,10 +1,42 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * Generic user interface class
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 abstract class UserInterface
 {
+    /**
+     * Configuration
+     * @var Config
+     */
     protected $config;
 
+    /**
+     * Start the user interface, load config, parse and render events.
+     *
+     * @return void
+     */
     public function run()
     {
         try {
@@ -16,7 +48,7 @@ abstract class UserInterface
             if (!$this->config->cfgFileExists) {
                 throw new \Exception(
                     "No config file found. Looked at the following places:\n"
-                    . '- ' . implode ("\n- ", $this->config->cfgFiles)
+                    . '- ' . implode("\n- ", $this->config->cfgFiles)
                 );
             }
 
@@ -37,6 +69,11 @@ abstract class UserInterface
         }
     }
 
+    /**
+     * Load parameters for the CLI option parser.
+     *
+     * @return \Console_CommandLine CLI option parser
+     */
     protected function loadParameters()
     {
         $parser = new \Console_CommandLine();
@@ -115,7 +152,14 @@ abstract class UserInterface
         return $parser;
     }
 
-    protected function parseParameters($parser)
+    /**
+     * Let the CLI option parser parse the options.
+     *
+     * @param object $parser Option parser
+     *
+     * @return object Parsed command line parameters
+     */
+    protected function parseParameters(\Console_CommandLine $parser)
     {
         try {
             $result = $parser->parse();
@@ -136,6 +180,13 @@ abstract class UserInterface
         }
     }
 
+    /**
+     * Output the events
+     *
+     * @param array $arEvents Event objects to render
+     *
+     * @return void
+     */
     protected function render($arEvents)
     {
         $r = $this->getRenderer();
@@ -148,6 +199,11 @@ abstract class UserInterface
         $r->renderAndOutput($arEvents);
     }
 
+    /**
+     * Load the configured renderer
+     *
+     * @return Renderer Renderer instance
+     */
     protected function getRenderer()
     {
         $renderer = ucfirst($this->config->renderer);
@@ -158,10 +214,22 @@ abstract class UserInterface
         return new $class();
     }
 
+    /**
+     * Handle any commands given on the CLI
+     *
+     * @param object $res Command line parameters and options
+     *
+     * @return void
+     */
     protected function handleCommands($res)
     {
     }
 
+    /**
+     * Do something before a parameter parsing error is shown
+     *
+     * @return void
+     */
     protected function preRenderParameterError()
     {
     }
index 10120ec..d85136a 100644 (file)
@@ -1,8 +1,37 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * HTTP user interface that renders a HTML page
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class Web extends UserInterface
 {
+    /**
+     * Load parameters for the CLI option parser.
+     * Set the default renderer to "html".
+     *
+     * @return \Console_CommandLine CLI option parser
+     */
     protected function loadParameters()
     {
         $parser = parent::loadParameters();
@@ -12,6 +41,11 @@ class Web extends UserInterface
         return $parser;
     }
 
+    /**
+     * Sends HTTP headers before a parameter error is shown
+     *
+     * @return void
+     */
     protected function preRenderParameterError()
     {
         header('Content-type: text/plain; charset=utf-8');
index 3587f70..51d6d7b 100644 (file)
@@ -1,8 +1,37 @@
 <?php
+/**
+ * Part of bdrem
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
+/**
+ * HTTP user interface that renders a ASCII table
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @version   Release: @package_version@
+ * @link      http://cweiske.de/bdrem.htm
+ */
 class WebText extends Web
 {
+    /**
+     * Load parameters for the CLI option parser.
+     * Set the default renderer to "console".
+     *
+     * @return \Console_CommandLine CLI option parser
+     */
     protected function loadParameters()
     {
         $parser = parent::loadParameters();
index 58ee78e..64c463e 100644 (file)
@@ -1,4 +1,16 @@
 <?php
+/**
+ * Phar stub file for bdrem. Handles startup of the .phar file.
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 if (!in_array('phar', stream_get_wrappers()) || !class_exists('Phar', false)) {
     echo "Phar extension not avaiable\n";
     exit(255);
@@ -7,6 +19,14 @@ if (!in_array('phar', stream_get_wrappers()) || !class_exists('Phar', false)) {
 $web = 'www/index.php';
 $cli = 'bin/phar-bdrem.php';
 
+/**
+ * Rewrite the HTTP request path to an internal file.
+ * Maps "" and "/" to "www/index.php".
+ *
+ * @param string $path Path from the browser, relative to the .phar
+ *
+ * @return string Internal path.
+ */
 function rewritePath($path)
 {
     if ($path == '' || $path == '/') {
@@ -21,6 +41,6 @@ set_include_path(
     . PATH_SEPARATOR . 'phar://' . __FILE__ . '/lib/'
 );
 Phar::webPhar(null, $web, null, array(), 'rewritePath');
-include 'phar://' . __FILE__ . '/' . $cli;
+require 'phar://' . __FILE__ . '/' . $cli;
 __HALT_COMPILER();
 ?>
index 14defde..79d572f 100644 (file)
@@ -1,8 +1,20 @@
 <?php
+/**
+ * Start the bdrem HTML web interface
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 if (file_exists(__DIR__ . '/../src/bdrem/Autoloader.php')) {
-    require_once __DIR__ . '/../src/bdrem/Autoloader.php';
+    include_once __DIR__ . '/../src/bdrem/Autoloader.php';
     Autoloader::register();
 }
 $web = new Web();
index ffe530a..d2ff095 100644 (file)
@@ -1,8 +1,20 @@
 <?php
+/**
+ * Start the bdrem plain text web interface
+ *
+ * PHP version 5
+ *
+ * @category  Tools
+ * @package   Bdrem
+ * @author    Christian Weiske <cweiske@cweiske.de>
+ * @copyright 2014 Christian Weiske
+ * @license   http://www.gnu.org/licenses/agpl.html GNU AGPL v3
+ * @link      http://cweiske.de/bdrem.htm
+ */
 namespace bdrem;
 
 if (file_exists(__DIR__ . '/../src/bdrem/Autoloader.php')) {
-    require_once __DIR__ . '/../src/bdrem/Autoloader.php';
+    include_once __DIR__ . '/../src/bdrem/Autoloader.php';
     Autoloader::register();
 }
 $web = new WebText();