feat(string-extra): Add singularize and pluralize filter

doc/filters/pluralize.rst

@@ -0,0 +1,45 @@
+``pluralize``
+========
+
+The ``pluralize`` filter transforms a given noun in its singular form into its plural version.
+
+Here is an example:
+
+.. code-block:: twig
+
+    {{ 'partitions'|pluralize('en') }}
+    partition
+
+.. note::
+    `lang` parameter is mandatory for this filter as only English and French are supported by the Inflector in Symfony.
+
+The ``pluralize`` filter uses the method by the same name in Symfony's
+`Inflector <https://symfony.com/doc/current/components/string.html#inflector>`_.
+
+.. note::
+
+    The ``pluralize`` filter is part of the ``StringExtension`` which is not
+    installed by default. Install it first:
+
+    .. code-block:: bash
+
+        $ composer require twig/string-extra
+
+    Then, on Symfony projects, install the ``twig/extra-bundle``:
+
+    .. code-block:: bash
+
+        $ composer require twig/extra-bundle
+
+    Otherwise, add the extension explicitly on the Twig environment::
+
+        use Twig\Extra\String\StringExtension;
+
+        $twig = new \Twig\Environment(...);
+        $twig->addExtension(new StringExtension());
+
+Arguments
+---------
+
+* ``lang``: The lang of the original string. Only English (`en`) and French (`fr`) are supported.
+* ``singleResult``: This argument is optional. If set to false, the filter will return an array of pluralized words. Default is true.

doc/filters/singularize.rst

@@ -0,0 +1,45 @@
+``singularize``
+========
+
+The ``singularize`` filter transforms a given noun in its plural form into its singular version.
+
+Here is an example:
+
+.. code-block:: twig
+
+    {{ 'partitions'|singularize('en') }}
+    partition
+
+.. note::
+    `lang` parameter is mandatory for this filter as only English and French are supported by the Inflector in Symfony.
+
+The ``singularize`` filter uses the method by the same name in Symfony's
+`Inflector <https://symfony.com/doc/current/components/string.html#inflector>`_.
+
+.. note::
+
+    The ``singularize`` filter is part of the ``StringExtension`` which is not
+    installed by default. Install it first:
+
+    .. code-block:: bash
+
+        $ composer require twig/string-extra
+
+    Then, on Symfony projects, install the ``twig/extra-bundle``:
+
+    .. code-block:: bash
+
+        $ composer require twig/extra-bundle
+
+    Otherwise, add the extension explicitly on the Twig environment::
+
+        use Twig\Extra\String\StringExtension;
+
+        $twig = new \Twig\Environment(...);
+        $twig->addExtension(new StringExtension());
+
+Arguments
+---------
+
+* ``lang``: The lang of the original string. Only English (`en`) and French (`fr`) are supported.
+* ``singleResult``: This argument is optional. If set to false, the filter will return an array of singularized nouns. Default is true.

extra/string-extra/README.md

@@ -10,7 +10,13 @@ object to give access to [methods of the class][2].
 It also provides a [`slug`][3] filter which is simply a wrapper for the 
 [`AsciiSlugger`][4]'s `slug` method.
 
+In addition, two filters are provided to [`singularize`][5] and [`pluralize`][6] a noun. 
+Behind the scenes, it uses the [`Inflector`][6] class from the Symfony String component.
+
 [1]: https://twig.symfony.com/u
 [2]: https://symfony.com/doc/current/components/string.html
 [3]: https://twig.symfony.com/slug
 [4]: https://symfony.com/doc/current/components/string.html#slugger
+[5]: https://twig.symfony.com/singularize
+[6]: https://twig.symfony.com/pluralize
+[7]: https://symfony.com/doc/current/components/string.html#inflector

extra/string-extra/StringExtension.php

@@ -12,6 +12,9 @@
 namespace Twig\Extra\String;
 
 use Symfony\Component\String\AbstractUnicodeString;
+use Symfony\Component\String\Inflector\EnglishInflector;
+use Symfony\Component\String\Inflector\FrenchInflector;
+use Symfony\Component\String\Inflector\InflectorInterface;
 use Symfony\Component\String\Slugger\AsciiSlugger;
 use Symfony\Component\String\Slugger\SluggerInterface;
 use Symfony\Component\String\UnicodeString;
@@ -21,6 +24,8 @@ use Twig\TwigFilter;
 final class StringExtension extends AbstractExtension
 {
     private $slugger;
+    private $frenchInflector;
+    private $englishInflector;
 
     public function __construct(?SluggerInterface $slugger = null)
     {
@@ -32,6 +37,8 @@ final class StringExtension extends AbstractExtension
         return [
             new TwigFilter('u', [$this, 'createUnicodeString']),
             new TwigFilter('slug', [$this, 'createSlug']),
+            new TwigFilter('pluralize', [$this, 'pluralize']),
+            new TwigFilter('singularize', [$this, 'singularize']),
         ];
     }
 
@@ -44,4 +51,42 @@ final class StringExtension extends AbstractExtension
     {
         return $this->slugger->slug($string, $separator, $locale);
     }
+
+    /**
+     * @return array|string
+     */
+    public function pluralize(string $value, string $lang, bool $singleResult = true)
+    {
+        switch (true) {
+            case $singleResult:
+                return $this->getInflector($lang)->pluralize($value)[0];
+            default:
+                return $this->getInflector($lang)->pluralize($value);
+        }
+    }
+
+    /**
+     * @return array|string
+     */
+    public function singularize(string $value, string $lang, bool $singleResult = true)
+    {
+        switch (true) {
+            case $singleResult:
+                return $this->getInflector($lang)->singularize($value)[0];
+            default:
+                return $this->getInflector($lang)->singularize($value);
+        }
+    }
+
+    private function getInflector(string $lang): InflectorInterface
+    {
+        switch ($lang) {
+            case 'fr':
+                return $this->frenchInflector ?? $this->frenchInflector = new FrenchInflector();
+            case 'en':
+                return $this->englishInflector ?? $this->englishInflector = new EnglishInflector();
+            default:
+                throw new \InvalidArgumentException(sprintf('Language "%s" is not supported.', $lang));
+        }
+    }
 }

extra/string-extra/Tests/Fixtures/pluralize-invalid-language.test

@@ -0,0 +1,10 @@
+--TEST--
+"pluralize" filter
+--TEMPLATE--
+{{ 'partition'|pluralize('it') }}
+
+--DATA--
+return []
+
+--EXCEPTION--
+Twig\Error\RuntimeError: An exception has been thrown during the rendering of a template ("Language "it" is not supported.") in "index.twig" at line 2.

extra/string-extra/Tests/Fixtures/pluralize.test

@@ -0,0 +1,17 @@
+--TEST--
+"pluralize" filter
+--TEMPLATE--
+{{ 'partition'|pluralize('fr') }}
+{{ 'partition'|pluralize('fr', false)|first }}
+{{ 'person'|pluralize('fr') }}
+{{ 'person'|pluralize('en', false)|first }}
+{{ 'person'|pluralize('en', false)|last }}
+
+--DATA--
+return []
+--EXPECT--
+partitions
+partitions
+persons
+persons
+people

extra/string-extra/Tests/Fixtures/singularize.test

@@ -0,0 +1,19 @@
+--TEST--
+"singularize" filter
+--TEMPLATE--
+{{ 'partitions'|singularize('fr') }}
+{{ 'partitions'|singularize('fr', false)|first }}
+{{ 'persons'|singularize('fr') }}
+{{ 'persons'|singularize('en', false)|first }}
+{{ 'people'|singularize('en') }}
+{{ 'people'|singularize('en', false)|first }}
+
+--DATA--
+return []
+--EXPECT--
+partition
+partition
+person
+person
+person
+person

extra/string-extra/Tests/Fixtures/singularizelize-invalid-language.test

@@ -0,0 +1,10 @@
+--TEST--
+"singularize" filter
+--TEMPLATE--
+{{ 'partitions'|singularize('it') }}
+
+--DATA--
+return []
+
+--EXCEPTION--
+Twig\Error\RuntimeError: An exception has been thrown during the rendering of a template ("Language "it" is not supported.") in "index.twig" at line 2.