Add "first" and "last" helpers

src/Collection/FirstHelper.php

@@ -0,0 +1,50 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Collection;
+
+use Handlebars\Context;
+use Handlebars\Helper as HelperInterface;
+use Handlebars\Template;
+
+/**
+ * Returns the first item of the collection.
+ *
+ * If the passed in collection is empty boolean false will be returned.
+ *
+ * Usage:
+ * ```handlebars
+ *   {{first collection}}
+ * ```
+ *
+ * Arguments:
+ *  - "collection": an array or an instance of \Traversable which first element
+ *    should be returned.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class FirstHelper implements HelperInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function execute(Template $template, Context $context, $args, $source)
+    {
+        $parsed_args = $template->parseArguments($args);
+        if (count($parsed_args) != 1) {
+            throw new \InvalidArgumentException(
+                '"first" helper expects exactly one argument.'
+            );
+        }
+        $collection = $context->get($parsed_args[0]);
+
+        return reset($collection);
+    }
+}

src/Collection/Helpers.php

@@ -0,0 +1,32 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Collection;
+
+use Handlebars\Helpers as BaseHelpers;
+
+/**
+ * Contains all collections related helpers.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class Helpers extends BaseHelpers
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function addDefaultHelpers()
+    {
+        parent::addDefaultHelpers();
+
+        $this->add('first', new FirstHelper());
+        $this->add('last', new LastHelper());
+    }
+}

src/Collection/LastHelper.php

@@ -0,0 +1,50 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Collection;
+
+use Handlebars\Context;
+use Handlebars\Helper as HelperInterface;
+use Handlebars\Template;
+
+/**
+ * Returns the last item of the collection.
+ *
+ * If the passed in collection is empty boolean false will be returned.
+ *
+ * Usage:
+ * ```handlebars
+ *   {{last collection}}
+ * ```
+ *
+ * Arguments:
+ *  - "collection": an array or an instance of \Traversable which last element
+ *    should be returned.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class LastHelper implements HelperInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function execute(Template $template, Context $context, $args, $source)
+    {
+        $parsed_args = $template->parseArguments($args);
+        if (count($parsed_args) != 1) {
+            throw new \InvalidArgumentException(
+                '"last" helper expects exactly one argument.'
+            );
+        }
+        $collection = $context->get($parsed_args[0]);
+
+        return end($collection);
+    }
+}

src/Helpers.php

@@ -29,6 +29,10 @@ class Helpers extends BaseHelpers
         // Date helpers
         $this->add('formatDate', new Date\FormatDateHelper());
 
+        // Collection helpers
+        $this->add('first', new Collection\FirstHelper());
+        $this->add('last', new Collection\LastHelper());
+
         // Comparison helpers
         $this->add('ifAny', new Comparison\IfAnyHelper());
         $this->add('ifEqual', new Comparison\IfEqualHelper());

tests/Collection/FirstHelperTest.php

@@ -0,0 +1,88 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Tests\Collection;
+
+use JustBlackBird\HandlebarsHelpers\Collection\FirstHelper;
+
+/**
+ * Test class for "first" helper.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class FirstHelperTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests that the first item returned.
+     *
+     * @dataProvider collectionsProvider
+     */
+    public function testFirstItem($collection, $result)
+    {
+        $helpers = new \Handlebars\Helpers(array('first' => new FirstHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $this->assertEquals(
+            $engine->render(
+                '{{first collection}}',
+                array('collection' => $collection)
+            ),
+            $result
+        );
+    }
+
+    /**
+     * A data provider for testFirstItem method.
+     */
+    public function collectionsProvider()
+    {
+        return array(
+            // Test arrays with numeric keys
+            array(array('a', 'b', 'c'), 'a'),
+            array(array('z'), 'z'),
+            // Test associative arrays
+            array(array('a' => '10', 'b' => '11', 'c' => '12'), '10'),
+            array(array('f' => '15'), '15'),
+            // Test \Traversable instance
+            array(new \ArrayIterator(array('a', 'b', 'c')), 'a'),
+            array(new \ArrayIterator(array('z')), 'z'),
+            // Test empty collections
+            array(array(), false),
+            array(new \ArrayIterator(array()), false),
+        );
+    }
+
+    /**
+     * Tests that exception is thrown if wrong number of arguments is used.
+     *
+     * @expectedException InvalidArgumentException
+     * @dataProvider wrongArgumentsProvider
+     */
+    public function testArgumentsCount($template)
+    {
+        $helpers = new \Handlebars\Helpers(array('first' => new FirstHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $engine->render($template, array());
+    }
+
+    /**
+     * A data provider for testArgumentsCount method.
+     */
+    public function wrongArgumentsProvider()
+    {
+        return array(
+            // Not enough arguments
+            array('{{first}}'),
+            // Too much arguments
+            array('{{first "Arg" "ANOTHER ARG"}}'),
+        );
+    }
+}

tests/Collection/HelpersTest.php

@@ -0,0 +1,45 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Tests\Collection;
+
+use JustBlackBird\HandlebarsHelpers\Collection\Helpers;
+
+/**
+ * Test class for Collection Helpers Set.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class HelpersTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests that all helpers in the set exist and have valid classes.
+     *
+     * @dataProvider helpersProvider
+     */
+    public function testHelper($name, $class)
+    {
+        $helpers = new Helpers();
+
+        $this->assertTrue($helpers->has($name), sprintf('There is no "%s" helper', $name));
+        $this->assertInstanceOf($class, $helpers->{$name});
+    }
+
+    /**
+     * A data provider for testHelper method.
+     */
+    public function helpersProvider()
+    {
+        return array(
+            array('first', '\\JustBlackBird\\HandlebarsHelpers\\Collection\\FirstHelper'),
+            array('last', '\\JustBlackBird\\HandlebarsHelpers\\Collection\\LastHelper'),
+        );
+    }
+}

tests/Collection/LastHelperTest.php

@@ -0,0 +1,88 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Tests\Collection;
+
+use JustBlackBird\HandlebarsHelpers\Collection\LastHelper;
+
+/**
+ * Test class for "last" helper.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class LastHelperTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests that the last item returned.
+     *
+     * @dataProvider collectionsProvider
+     */
+    public function testLastItem($collection, $result)
+    {
+        $helpers = new \Handlebars\Helpers(array('last' => new LastHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $this->assertEquals(
+            $engine->render(
+                '{{last collection}}',
+                array('collection' => $collection)
+            ),
+            $result
+        );
+    }
+
+    /**
+     * A data provider for testLastItem method.
+     */
+    public function collectionsProvider()
+    {
+        return array(
+            // Test arrays with numeric keys
+            array(array('a', 'b', 'c'), 'c'),
+            array(array('z'), 'z'),
+            // Test associative arrays
+            array(array('a' => '10', 'b' => '11', 'c' => '12'), '12'),
+            array(array('f' => '15'), '15'),
+            // Test \Traversable instance
+            array(new \ArrayIterator(array('a', 'b', 'c')), 'c'),
+            array(new \ArrayIterator(array('z')), 'z'),
+            // Test empty collections
+            array(array(), false),
+            array(new \ArrayIterator(array()), false),
+        );
+    }
+
+    /**
+     * Tests that exception is thrown if wrong number of arguments is used.
+     *
+     * @expectedException InvalidArgumentException
+     * @dataProvider wrongArgumentsProvider
+     */
+    public function testArgumentsCount($template)
+    {
+        $helpers = new \Handlebars\Helpers(array('last' => new LastHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $engine->render($template, array());
+    }
+
+    /**
+     * A data provider for testArgumentsCount method.
+     */
+    public function wrongArgumentsProvider()
+    {
+        return array(
+            // Not enough arguments
+            array('{{last}}'),
+            // Too much arguments
+            array('{{last "Arg" "ANOTHER ARG"}}'),
+        );
+    }
+}

tests/HelpersTest.php

@@ -41,6 +41,10 @@ class HelpersTest extends \PHPUnit_Framework_TestCase
             // Date helpers
             array('formatDate', '\\JustBlackBird\\HandlebarsHelpers\\Date\\FormatDateHelper'),
 
+            // Collection helpers
+            array('first', '\\JustBlackBird\\HandlebarsHelpers\\Collection\\FirstHelper'),
+            array('last', '\\JustBlackBird\\HandlebarsHelpers\\Collection\\LastHelper'),
+
             // Comparison helpers
             array('ifAny', '\\JustBlackBird\\HandlebarsHelpers\\Comparison\\IfAnyHelper'),
             array('ifEqual', '\\JustBlackBird\\HandlebarsHelpers\\Comparison\\IfEqualHelper'),