php: add api documentation, fix namespaces in composer.json and tests

3 files changed, 601 insertions, 21 deletions

diff --git a/php/composer.json b/php/composer.json
index 9cf4a1e..f0bdb51 100644
--- a/php/composer.json
+++ b/php/composer.json
@@ -22,7 +22,7 @@
 
   "autoload": {
     "psr-4": {
-      "Luigi\\": "src/"
+      "Pablotron\\Luigi\\": "src/"
     }
   },
 
diff --git a/php/src/Template.php b/php/src/Template.php
index da905d7..34dfe09 100644
--- a/php/src/Template.php
+++ b/php/src/Template.php
@@ -1,16 +1,51 @@
 <?php
-declare(strict_types = 1);
+/**
+ * Fast string templating library for JavaScript, PHP, Ruby, and Java.
+ *
+ * @author Paul Duncan <pabs@pablotron.org>
+ * @copyright 2010-2018 Paul Duncan <pabs@pablotron.org>
+ * @license MIT
+ * @package Pablotron\Luigi
+ */
 
-namespace Luigi;
+declare(strict_types = 1);
 
+/**
+ * Luigi Template namespace.
+ *
+ * @api
+ */
+namespace Pablotron\Luigi;
+
+/**
+ * Current version of Luigi Template.
+ *
+ * @api
+ */
 const VERSION = '0.4.2';
 
-class Error extends \Exception {};
-
-class UnknownTypeError extends Error {
+/**
+ * Base class for all exceptions raised by Luigi Template.
+ */
+class LuigiError extends \Exception {};
+
+/**
+ * Base class for all all unknown type errors.
+ */
+class UnknownTypeError extends LuigiError {
+  /**
+    * @var string $type Unknown item type name ("method", "template", etc).
+    * @var string $name Unknown item name.
+    */
   public $type,
          $name;
 
+  /**
+   * Create a new UnknownTypeError error.
+   *
+   * @param string $type Unknown item type name.
+   * @param string $name Unknown item name.
+   */
   public function __construct(string $type, string $name) {
     $this->type = $type;
     $this->name = $name;
@@ -18,61 +53,153 @@ class UnknownTypeError extends Error {
   }
 };
 
+/**
+ * Thrown when attempting to get an unknown template from a Cache.
+ *
+ * @see Cache
+ */
 final class UnknownTemplateError extends UnknownTypeError {
+  /**
+   * Create a new UnknownTemplateError.
+   *
+   * @param string $name Unknown template name.
+   */
   public function __construct(string $name) {
     parent::__construct('template', $name);
   }
 };
 
+/**
+ * Thrown when attempting to apply an unknown filter.
+ */
 final class UnknownFilterError extends UnknownTypeError {
+  /**
+   * Create a new UnknownFilterError.
+   *
+   * @param string $name Unknown filter name.
+   */
   public function __construct(string $name) {
     parent::__construct('filter', $name);
   }
 };
 
+/**
+ * Thrown when attempting to get an unknown key.
+ */
 final class UnknownKeyError extends UnknownTypeError {
+  /**
+   * Create a new UnknownKeyError.
+   *
+   * @param string $name Unknown key name.
+   */
   public function __construct(string $name) {
     parent::__construct('key', $name);
   }
 };
 
-final class MissingFilterParameterError extends Error {
+/**
+ * Thrown when trying to use a filter with with a missing parameter.
+ */
+final class MissingFilterParameterError extends LuigiError {
+  /** @var string $filter_name Name of filter. */
   public $filter_name;
 
+  /**
+   * Create a new MissingFilterParameterError.
+   *
+   * @param string $filter_name Name of filter.
+   */
   public function __construct(string $filter_name) {
     $this->filter_name = $filter_name;
     parent::__construct("missing required filter parameter for filter $filter_name");
   }
 };
 
-final class InvalidTemplateError extends Error {
+/**
+ * Thrown when trying to parse an invalid template string.
+ */
+final class InvalidTemplateError extends LuigiError {
+  /** @var string $template Template string. */
   public $template;
 
+  /**
+   * Create a new InvalidTemplateError.
+   *
+   * @param string $template Template string.
+   */
   public function __construct(string $template) {
     $this->template = $template;
     parent::__construct("invalid template: $template");
   }
 };
 
+/**
+ * Wrapper for context during Template#run().
+ *
+ * @internal
+ */
 final class RunContext {
+  /**
+   * @var array $args Hash of arguments.
+   * @var array $filters Hash of filters.
+   */
   public $args,
          $filters;
 
+/**
+ * Create a RunContext.
+ *
+ * @internal
+ *
+ * @param array $args Arguments hash.
+ * @param array $filters Filters hash.
+ */
   public function __construct(array $args, array $filters) {
     $this->args = $args;
     $this->filters = $filters;
   }
 };
 
+/**
+ * Parsed filter name and arguments.
+ *
+ * @internal
+ */
 final class TemplateFilter {
+  /**
+   * @var string $name Filter name.
+   * @var array $args Filter arguments.
+   */
   private $name,
           $args;
 
+  /**
+   * Create a TemplateFilter.
+   *
+   * @internal
+   *
+   * @param string $name Filter name.
+   * @param array $args Filter arguments.
+   */
   public function __construct(string $name, array $args) {
     $this->name = $name;
     $this->args = $args;
   }
 
+  /**
+   * Run filter on given value, arguments, and filter set.
+   *
+   * @internal
+   *
+   * @param string $v Input value.
+   * @param array $args Hash passed to Template#run().
+   * @param array $filters Hash of filters.
+   *
+   * @return mixed Filter result.
+   *
+   * @throws UnknownFilterError If this filter does not exist in filter
+   * hash.
+   */
   public function run($v, array &$args, array &$filters) {
     if (!isset($filters[$this->name])) {
       throw new UnknownFilterError($this->name);
@@ -86,32 +213,97 @@ final class TemplateFilter {
   }
 };
 
-
+/**
+ * Abstract base class for parser tokens.
+ *
+ * @internal
+ */
 abstract class Token {
+  /**
+   * Apply this token.
+   *
+   * @internal
+   *
+   * @param RunContext $ctx Run context.
+   *
+   * @return string
+   */
   public abstract function run(RunContext &$ctx) : string;
 };
 
+/**
+ * Literal parser token.
+ *
+ * @internal
+ */
 final class LiteralToken extends Token {
+  /** @var string $val Literal value. */
   private $val;
 
+  /**
+   * Create a new LiteralToken.
+   *
+   * @internal
+   *
+   * @param string $val Literal string.
+   */
   public function __construct(string $val) {
     $this->val = $val;
   }
 
+  /**
+   * Returns the literal value.
+   *
+   * @internal
+   *
+   * @param RunContext $ctx Run context.
+   *
+   * @return string Literal value.
+   */
   public function run(RunContext &$ctx) : string {
     return $this->val;
   }
 };
 
+/**
+ * Filter parser token.
+ *
+ * @internal
+ */
 final class FilterToken extends Token {
+  /**
+   * @var string $key Argument name.
+   * @var array $filters Array of TemplateFilter instances.
+   */
   private $key,
           $filters;
 
+  /**
+   * Create a new LiteralToken.
+   *
+   * @internal
+   *
+   * @param string $key Argument name.
+   * @param array $filters Array of TemplateFilter instances.
+   */
   public function __construct(string $key, array $filters) {
     $this->key = $key;
     $this->filters = $filters;
   }
 
+  /**
+   * Get key from arguments hash and apply filters to it, then return
+   * the result.
+   *
+   * @internal
+   *
+   * @param RunContext $ctx Run context.
+   *
+   * @return string Filtered result.
+   *
+   * @throws UnknownKeyError If the given key does not exist in the
+   * arguments hash.
+   */
   public function run(RunContext &$ctx) : string {
     # check key
     if (!isset($ctx->args[$this->key])) {
@@ -133,6 +325,11 @@ final class FilterToken extends Token {
   }
 };
 
+/**
+ * Token parser regular expression.
+ *
+ * @internal
+ */
 const TOKEN_RE = '/
   # match opening brace
   %\{
@@ -156,6 +353,11 @@ const TOKEN_RE = '/
   | (?<text>[^%]* | %)
 /mx';
 
+/**
+ * Filter parser regular expression.
+ *
+ * @internal
+ */
 const FILTER_RE = '/
   # match filter name
   (?<name>\S+)
@@ -167,10 +369,32 @@ const FILTER_RE = '/
   \s*
 /mx';
 
+/**
+ * Filter delimiter regular expression.
+ *
+ * @internal
+ */
 const DELIM_FILTERS_RE = '/\s*\|\s*/m';
 
+/**
+ * Filter argument delimiter regular expression.
+ *
+ * @internal
+ */
 const DELIM_ARGS_RE = '/\s+/m';
 
+/**
+ * Parse a string containing a filter clause into an array of
+ * TemplateFilter instances.
+ *
+ * @internal
+ *
+ * @param string $filters Input filter string.
+ *
+ * @return array Array of TemplateFilter instances.
+ *
+ * @throws UnknownFilterError if a filter clause could not be parsed.
+ */
 function parse_filters(string $filters) : array {
   # split into individual filters
   $r = [];
@@ -200,6 +424,17 @@ function parse_filters(string $filters) : array {
   return $r;
 }
 
+/**
+ * Parse a template string into an array of Token instances.
+ *
+ * @internal
+ *
+ * @param string $template Input template string.
+ *
+ * @return array Array of Token instances.
+ *
+ * @throws InvalidTemplateError if the template could not be parsed.
+ */
 function parse_template(string $template) : array {
   # build list of matches
   $matches = [];
@@ -226,9 +461,64 @@ function parse_template(string $template) : array {
   }, []);
 }
 
+/**
+ * Static class containing global filter map.
+ *
+ * The built-in default filters are:
+ *
+ * * `h`: HTML-escape input string (including quotes).
+ * * `u`: URL-escape input string.
+ * * `json`: JSON-encode input value.
+ * * `hash`: Hash input value.  Requires hash algorithm as parameter.
+ * * `base64`: Base64-encode input string.
+ * * `nl2br`: Convert newlines to `\<br/\>` elements.
+ * * `uc`: Upper-case input string.
+ * * `lc`: Lower-case input string.
+ * * `trim`: Trim leading and trailing whitespace from input string.
+ * * `ltrim`: Trim leading whitespace from input string.
+ * * `rtrim`: Trim trailing whitespace from input string.
+ * * `s`: Return '' if input number is 1, and 's' otherwise (used for
+ *   pluralization).
+ * * `strlen`: Return the length of the input string.
+ * * `count`: Return the number of elements in the input array.
+ * * `key`: Get the given key from the input array.  Requires key as a
+ *   parameter.
+ *
+ * You can add your own filters to the default set of filters by
+ * modifying `\Luigi\Filters::$FILTERS`, like so:
+ *
+ *     # add a filter named "my-filter"
+ *     \Luigi\Filters['my-filter'] = function($s) {
+ *       # filter input string
+ *       return "foo-{$s}-bar";
+ *     };
+ *
+ *     # use custom filter in template
+ *     echo Template::once('%{some-key | my-filter}', [
+ *       'some-key' => 'example',
+ *     ]) . "\n";
+ *
+ *     # prints "foo-example-bar"
+ *
+ * @api
+ */
 class Filters {
+  /**
+   * @var array $FILTERS Global filter map.
+   *
+   * @api
+   */
   public static $FILTERS = null;
 
+  /**
+   * Initialize global filter map.
+   *
+   * Called internally by LuigiTemplate.
+   *
+   * @internal
+   *
+   * @return void
+   */
   public static function init() : void {
     # prevent double initialization
     if (self::$FILTERS !== null)
@@ -315,13 +605,62 @@ class Filters {
   }
 };
 
+# initialize filters
 Filters::init();
 
+/**
+ * Template object.
+ *
+ * Parse a template string into a Template instance, and then apply the
+ * Template via the Template#run() method.
+ *
+ * Example:
+ *
+ *     # load template class
+ *     use \Pablotron\Luigi\Template;
+ *
+ *     # create template
+ *     $tmpl = new Template('hello %{name}');
+ *
+ *     # run template and print result
+ *     echo $tmpl->run([
+ *       'name' => 'Paul',
+ *     ]) . "\n";
+ *
+ *     # prints "hello Paul"
+ *
+ * @api
+ *
+ */
 final class Template {
-  private $template,
-          $filters,
+  /** @var string $template Input template string. */
+  public $template;
+
+  /**
+   * @var array $filters Filter map.
+   * @var array $tokens Parsed template tokens.
+   */
+  private $filters,
           $tokens;
 
+  /**
+   * Create a new Template object.
+   *
+   * Parse a template string into tokens.
+   *
+   * Example:
+   *
+   *     # load template class
+   *     use \Pablotron\Luigi\Template;
+   *
+   *     # create template
+   *     $tmpl = new Template('hello %{name}');
+   *
+   * @api
+   *
+   * @param string $template Template string.
+   * @param array $custom_filters Custom filter map (optional).
+   */
   public function __construct(
     string $template,
     array $custom_filters = []
@@ -333,6 +672,33 @@ final class Template {
     $this->tokens = parse_template($template);
   }
 
+  /**
+   * Apply given arguments to template and return the result as a
+   * string.
+   *
+   * Example:
+   *
+   *     # load template class
+   *     use \Pablotron\Luigi\Template;
+   *
+   *     # create template
+   *     $tmpl = new Template('hello %{name}');
+   *
+   *     # run template and print result
+   *     echo $tmpl->run([
+   *       'name' => 'Paul',
+   *     ]) . "\n";
+   *
+   *     # prints "hello Paul"
+   *
+   * @api
+   *
+   * @param array $args Template arguments.
+   *
+   * @return string Expanded template.
+   *
+   * @throws UnknownKeyError If a referenced key is missing from $args.
+   */
   public function run(array $args = []) : string {
     # create run context
     $ctx = new RunContext($args, $this->filters);
@@ -342,6 +708,53 @@ final class Template {
     }, $this->tokens));
   }
 
+  /**
+   * Return the input template string.
+   *
+   * Example:
+   *
+   *     # load template class
+   *     use \Pablotron\Luigi\Template;
+   *
+   *     # create template
+   *     $tmpl = new Template('hello %{name}');
+   *
+   *     # print template string
+   *     echo $tmpl . "\n";
+   *
+   *     # prints "hello %{name}"
+   *
+   * @api
+   *
+   * @return string Input template string.
+   */
+  public function __toString() : string {
+    return $this->template;
+  }
+
+  /**
+   * Parse template string, expand it using given arguments, and return
+   * the result as a string.
+   *
+   * Example:
+   *
+   *     # load template class
+   *     use \Pablotron\Luigi\Template;
+   *
+   *     # create template, run it, and print result
+   *     echo Template::once('foo-%{some-key}-bar', [
+   *       'some-key' => 'example',
+   *     ]) . "\n";
+   *
+   *     # prints "foo-example-bar"
+   * @api
+   *
+   * @param string $template Template string.
+   * @param array $args Template arguments.
+   * @param array $filters Custom filter map (optional).
+   *
+   * @return string Expanded template.
+   */
   public static function once(
     string $template,
     array $args = [],
@@ -352,21 +765,107 @@ final class Template {
   }
 };
 
+/**
+ * Lazy-loading template cache.
+ *
+ * Group a set of templates together and only parse them on an as-needed
+ * basis.
+ *
+ * @api
+ */
 final class Cache implements \ArrayAccess {
+  /**
+   * @var array $templates Map of keys to template strings.
+   * @var array $filters Filter map (optional).
+   * @var array $lut Parsed template cache.
+   */
   private $templates,
           $filters,
           $lut = [];
 
+  /**
+   * Create a new template cache.
+   *
+   * Example:
+   *
+   *     # load cache class
+   *     use \Pablotron\Luigi\Cache;
+   *
+   *     # create template cache
+   *     $cache = new Cache([
+   *       'hi' => 'hi %{name}!',
+   *     ]);
+   *
+   * @api
+   *
+   * @param array $templates Map of template keys to template strings.
+   * @param array $filters Custom filter map (optional).
+   */
   public function __construct(array $templates, array $filters = []) {
     $this->templates = $templates;
     $this->filters = (count($filters) > 0) ? $filters : Filters::$FILTERS;
   }
 
+  /**
+   * Returns true if the given template key exists in this cache.
+   *
+   * Example:
+   *
+   *     # load cache class
+   *     use \Pablotron\Luigi\Cache;
+   *
+   *     # create cache
+   *     $cache = new Cache([
+   *       'hi' => 'hi %{name}!',
+   *     ]);
+   *
+   *     # get template 'hi' from cache
+   *     foreach (array('hi', 'nope') as $tmpl_key) {
+   *       echo "$key: " . (isset($cache[$key]) ? 'Yes' : 'No') . "\n"
+   *     }
+   *
+   *     # prints "hi: Yes" and "nope: No"
+   * @api
+   *
+   * @param string $key Template key.
+   *
+   * @return bool Returns true if the template key exists.
+   */
   public function offsetExists($key) : bool {
     return isset($this->templates[$key]);
   }
 
-  public function offsetGet($key) {
+  /**
+   * Get the template associated with the given template key.
+   *
+   * Example:
+   *
+   *     # load cache class
+   *     use \Pablotron\Luigi\Cache;
+   *
+   *     # create cache
+   *     $cache = new Cache([
+   *       'hi' => 'hi %{name}!',
+   *     ]);
+   *
+   *     # get template 'hi' from cache
+   *     $tmpl = $cache['hi'];
+   *
+   *     echo $tmpl->run([
+   *       'name' => 'Paul',
+   *     ]);
+   *
+   *     # prints "hi Paul!"
+   *
+   * @api
+   *
+   * @param string $key Template key.
+   *
+   * @return Template Returns template associated with this key.
+   *
+   * @throws UnknownTemplateError if the given template does not exist.
+   */
+  public function offsetGet($key) : Template {
     if (isset($this->lut[$key])) {
       return $this->lut[$key];
     } else if (isset($this->templates[$key])) {
@@ -377,17 +876,98 @@ final class Cache implements \ArrayAccess {
     }
   }
 
+  /**
+   * Remove the template associated with the given template key.
+   *
+   * Example:
+   *
+   *     # load cache class
+   *     use \Pablotron\Luigi\Cache;
+   *
+   *     # create cache
+   *     $cache = new Cache([
+   *       'hi' => 'hi %{name}!',
+   *     ]);
+   *
+   *     # remove template 'hi' from cache
+   *     unset($cache['hi']);
+   *
+   *     echo $cache['hi']->run([
+   *       'name' => 'Paul',
+   *     ]);
+   *
+   *     # throws UnknownTemplateError
+   *
+   * @api
+   *
+   * @param array $key Template key.
+   *
+   * @return void
+   */
   public function offsetUnset($key) : void {
     unset($this->lut[$key]);
     unset($this->templates[$key]);
   }
 
+  /**
+   * Set the template associated with the given template key.
+   *
+   * Example:
+   *
+   *     # load cache class
+   *     use \Pablotron\Luigi\Cache;
+   *
+   *     # create cache
+   *     $cache = new Cache();
+   *
+   *     # add template to cache as 'hash-name'
+   *     $cache['hash-name'] = 'hashed name: %{name | hash sha1}';
+   *
+   *     echo $cache['hash-name']->run([
+   *       'name' => 'Paul',
+   *     ]);
+   *
+   *     # prints "sha1 of name: c3687ab9880c26dfe7ab966a8a1701b5e017c2ff"
+   *
+   * @api
+   *
+   * @param string $key Template key.
+   * @param string $val Template string.
+   *
+   * @return void
+   */
   public function offsetSet($key, $val) : void {
     unset($this->lut[$key]);
     $this->templates[$key] = $val;
   }
 
-
+  /**
+   * Run template with the given arguments and return the result.
+   *
+   * Example:
+   *
+   *     # load cache class
+   *     use \Pablotron\Luigi\Cache;
+   *
+   *     # create cache
+   *     $cache = new Cache([
+   *       'my-template' => 'hello %{name | uc}',
+   *     ]);
+   *
+   *     # run template
+   *     echo $cache->run('my-template', [
+   *       'name' => 'Paul',
+   *     ]);
+   *
+   *     # prints "hello PAUL"
+   *
+   * @api
+   *
+   * @param string $key Template key.
+   * @param array $args Template arguments.
+   *
+   * @return string Returns the expanded template result.
+   */
   public function run(string $key, array $args = []) : string {
     return $this->offsetGet($key)->run($args);
   }
diff --git a/php/tests/TemplateTest.php b/php/tests/TemplateTest.php
index 18e5a6e..b6e72c9 100644
--- a/php/tests/TemplateTest.php
+++ b/php/tests/TemplateTest.php
@@ -3,7 +3,7 @@ declare(strict_types = 1);
 
 namespace Pablotron\Luigi\Tests;
 use \PHPUnit\Framework\TestCase;
-use \Luigi\Template;
+use \Pablotron\Luigi\Template;
 
 final class TemplateTest extends TestCase {
   public function testNewTemplate() : void {
@@ -89,12 +89,12 @@ final class TemplateTest extends TestCase {
   }
 
   public function testCustomGlobalFilter() : void {
-    \Luigi\Filters::$FILTERS['barify'] = function($s) {
+    \Pablotron\Luigi\Filters::$FILTERS['barify'] = function($s) {
       return 'BAR';
     };
 
     # create template cache
-    $cache = new \Luigi\Cache([
+    $cache = new \Pablotron\Luigi\Cache([
       'foo' => 'foo%{bar|barify}',
     ]);
 
@@ -124,7 +124,7 @@ final class TemplateTest extends TestCase {
 
   public function testCache() : void {
     # create template cache
-    $cache = new \Luigi\Cache([
+    $cache = new \Pablotron\Luigi\Cache([
       'foo' => 'foo%{bar}',
     ]);
 
@@ -148,7 +148,7 @@ final class TemplateTest extends TestCase {
   }
 
   public function testUnknownKeyError() : void {
-    $this->expectException(\Luigi\UnknownKeyError::class);
+    $this->expectException(\Pablotron\Luigi\UnknownKeyError::class);
 
     # run template
     $r = Template::once('foo%{unknown-key}', [
@@ -157,7 +157,7 @@ final class TemplateTest extends TestCase {
   }
 
   public function testUnknownFilterError() : void {
-    $this->expectException(\Luigi\UnknownFilterError::class);
+    $this->expectException(\Pablotron\Luigi\UnknownFilterError::class);
 
     # run template
     $r = Template::once('foo%{bar|unknown-filter}', [
@@ -166,10 +166,10 @@ final class TemplateTest extends TestCase {
   }
 
   public function testUnknownTemplateError() : void {
-    $this->expectException(\Luigi\UnknownTemplateError::class);
+    $this->expectException(\Pablotron\Luigi\UnknownTemplateError::class);
 
     # create cache
-    $cache = new \Luigi\Cache([
+    $cache = new \Pablotron\Luigi\Cache([
       'foo' => 'foo%{bar}',
     ]);