Merge pull request #114 from doctrine/improve-dx

Improve developer experience and make it easier to create an Inflector instance.

docs/en/index.rst

@@ -1,141 +1,68 @@
 Introduction
 ============
 
-The Doctrine Inflector has methods for inflecting text.
-The features include pluralization, singularization,
-converting between camelCase and under_score and capitalizing
+The Doctrine Inflector has methods for inflecting text. The features include pluralization,
+singularization, converting between camelCase and under_score and capitalizing
 words.
 
-All you need to use the Inflector is the ``Doctrine\Inflector\Inflector`` class.
-
 Installation
 ============
 
 You can install the Inflector with composer:
 
-.. code-block::
+.. code-block:: console
 
     $ composer require doctrine/inflector
 
-Here are the available methods that you can use:
-
-Default Setup
-=============
-
-If you want to use the default rules for a language you can use the following. The following languages are supported.
-
-- English
-- French
-- Norwegian Bokmal
-- Portuguese
-- Spanish
-- Turkish
-
-English
--------
-
-.. code-block:: php
-
-    use Doctrine\Inflector\CachedWordInflector;
-    use Doctrine\Inflector\RulesetInflector;
-    use Doctrine\Inflector\Rules\English;
-
-    $inflector = new Inflector(
-        new CachedWordInflector(new RulesetInflector(
-            English\Rules::getSingularRuleset()
-        )),
-        new CachedWordInflector(new RulesetInflector(
-            English\Rules::getPluralRuleset()
-        ))
-    );
+Usage
+=====
 
-French
-------
+Using the inflector is easy, you can create a new ``Doctrine\Inflector\Inflector`` instance by using
+the ``Doctrine\Inflector\InflectorFactory`` class:
 
 .. code-block:: php
 
-    use Doctrine\Inflector\CachedWordInflector;
-    use Doctrine\Inflector\RulesetInflector;
-    use Doctrine\Inflector\Rules\French;
-
-    $inflector = new Inflector(
-        new CachedWordInflector(new RulesetInflector(
-            French\Rules::getSingularRuleset()
-        )),
-        new CachedWordInflector(new RulesetInflector(
-            French\Rules::getPluralRuleset()
-        ))
-    );
-
-Norwegian Bokmal
-----------------
-
-.. code-block:: php
+    use Doctrine\Inflector\InflectorFactory;
 
-    use Doctrine\Inflector\CachedWordInflector;
-    use Doctrine\Inflector\RulesetInflector;
-    use Doctrine\Inflector\Rules\NorwegianBokmal;
+    $inflectorFactory = new InflectorFactory();
 
-    $inflector = new Inflector(
-        new CachedWordInflector(new RulesetInflector(
-            NorwegianBokmal\Rules::getSingularRuleset()
-        )),
-        new CachedWordInflector(new RulesetInflector(
-            NorwegianBokmal\Rules::getPluralRuleset()
-        ))
-    );
+    $inflector = $inflectorFactory();
 
-Portuguese
-----------
+By default it will create an English inflector. If you want to use another language, just pass the language
+you want to create an inflector for to the ``create()`` method:
 
 .. code-block:: php
 
-    use Doctrine\Inflector\CachedWordInflector;
-    use Doctrine\Inflector\RulesetInflector;
-    use Doctrine\Inflector\Rules\Portuguese;
-
-    $inflector = new Inflector(
-        new CachedWordInflector(new RulesetInflector(
-            Portuguese\Rules::getSingularRuleset()
-        )),
-        new CachedWordInflector(new RulesetInflector(
-            Portuguese\Rules::getPluralRuleset()
-        ))
-    );
+    use Doctrine\Inflector\InflectorFactory;
+    use Doctrine\Inflector\Language;
 
-Spanish
--------
+    $inflectorFactory = new InflectorFactory();
 
-.. code-block:: php
+    $inflector = $inflectorFactory(Language::SPANISH);
 
-    use Doctrine\Inflector\CachedWordInflector;
-    use Doctrine\Inflector\RulesetInflector;
-    use Doctrine\Inflector\Rules\Spanish;
+The supported languages are as follows:
 
-    $inflector = new Inflector(
-        new CachedWordInflector(new RulesetInflector(
-            Spanish\Rules::getSingularRuleset()
-        )),
-        new CachedWordInflector(new RulesetInflector(
-            Spanish\Rules::getPluralRuleset()
-        ))
-    );
+- ``Language::ENGLISH``
+- ``Language::FRENCH``
+- ``Language::NORWEGIAN_BOKMAL``
+- ``Language::PORTUGUESE``
+- ``Language::SPANISH``
+- ``Language::TURKISH``
 
-Turkish
--------
+If you want to manually construct the inflector instead of using a factory, you can do so like this:
 
 .. code-block:: php
 
     use Doctrine\Inflector\CachedWordInflector;
     use Doctrine\Inflector\RulesetInflector;
-    use Doctrine\Inflector\Rules\Turkish;
+    use Doctrine\Inflector\Rules\English;
 
     $inflector = new Inflector(
         new CachedWordInflector(new RulesetInflector(
-            Turkish\Rules::getSingularRuleset()
+            English\Rules::getSingularRuleset()
         )),
         new CachedWordInflector(new RulesetInflector(
-            Turkish\Rules::getPluralRuleset()
+            English\Rules::getPluralRuleset()
         ))
     );
 
@@ -235,7 +162,7 @@ This method uses `Classify`_ and then converts the first character to lowercase:
 
     echo $inflector->camelize('model_name'); // modelName
 
-capitalize
+Capitalize
 ==========
 
 Takes a string and capitalizes all of the words, like PHP's built-in
@@ -265,13 +192,17 @@ Returns a word in plural form.
 Singularize
 ===========
 
+Returns a word in singular form.
+
 .. code-block:: php
 
     echo $inflector->singularize('browsers'); // browser
 
 Urlize
 ======
 
+Generate a URL friendly string from a string of text:
+
 .. code-block:: php
 
     echo $inflector->urlize('My first blog post'); // my-first-blog-post

lib/Doctrine/Inflector/InflectorFactory.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Inflector;
+
+use Doctrine\Inflector\Rules\English;
+use Doctrine\Inflector\Rules\French;
+use Doctrine\Inflector\Rules\NorwegianBokmal;
+use Doctrine\Inflector\Rules\Portuguese;
+use Doctrine\Inflector\Rules\Spanish;
+use Doctrine\Inflector\Rules\Turkish;
+use InvalidArgumentException;
+use function sprintf;
+
+final class InflectorFactory
+{
+    public function __invoke(string $language = Language::ENGLISH) : Inflector
+    {
+        switch ($language) {
+            case Language::ENGLISH:
+                return (new English\InflectorFactory())();
+
+            case Language::FRENCH:
+                return (new French\InflectorFactory())();
+
+            case Language::NORWEGIAN_BOKMAL:
+                return (new NorwegianBokmal\InflectorFactory())();
+
+            case Language::PORTUGUESE:
+                return (new Portuguese\InflectorFactory())();
+
+            case Language::SPANISH:
+                return (new Spanish\InflectorFactory())();
+
+            case Language::TURKISH:
+                return (new Turkish\InflectorFactory())();
+
+            default:
+                throw new InvalidArgumentException(sprintf(
+                    'Language "%s" is not supported.',
+                    $language
+                ));
+        }
+    }
+}

lib/Doctrine/Inflector/Language.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Inflector;
+
+final class Language
+{
+    public const ENGLISH          = 'english';
+    public const FRENCH           = 'french';
+    public const NORWEGIAN_BOKMAL = 'norwegian-bokmal';
+    public const PORTUGUESE       = 'portuguese';
+    public const SPANISH          = 'spanish';
+    public const TURKISH          = 'turkish';
+
+    private function __construct()
+    {
+    }
+}

lib/Doctrine/Inflector/Rules/English/InflectorFactory.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Inflector\Rules\English;
+
+use Doctrine\Inflector\CachedWordInflector;
+use Doctrine\Inflector\Inflector;
+use Doctrine\Inflector\RulesetInflector;
+
+final class InflectorFactory
+{
+    public function __invoke() : Inflector
+    {
+        return new Inflector(
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getSingularRuleset()
+            )),
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getPluralRuleset()
+            ))
+        );
+    }
+}

lib/Doctrine/Inflector/Rules/French/InflectorFactory.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Inflector\Rules\French;
+
+use Doctrine\Inflector\CachedWordInflector;
+use Doctrine\Inflector\Inflector;
+use Doctrine\Inflector\RulesetInflector;
+
+final class InflectorFactory
+{
+    public function __invoke() : Inflector
+    {
+        return new Inflector(
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getSingularRuleset()
+            )),
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getPluralRuleset()
+            ))
+        );
+    }
+}

lib/Doctrine/Inflector/Rules/NorwegianBokmal/InflectorFactory.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Inflector\Rules\NorwegianBokmal;
+
+use Doctrine\Inflector\CachedWordInflector;
+use Doctrine\Inflector\Inflector;
+use Doctrine\Inflector\RulesetInflector;
+
+final class InflectorFactory
+{
+    public function __invoke() : Inflector
+    {
+        return new Inflector(
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getSingularRuleset()
+            )),
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getPluralRuleset()
+            ))
+        );
+    }
+}

lib/Doctrine/Inflector/Rules/Portuguese/InflectorFactory.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Inflector\Rules\Portuguese;
+
+use Doctrine\Inflector\CachedWordInflector;
+use Doctrine\Inflector\Inflector;
+use Doctrine\Inflector\RulesetInflector;
+
+final class InflectorFactory
+{
+    public function __invoke() : Inflector
+    {
+        return new Inflector(
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getSingularRuleset()
+            )),
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getPluralRuleset()
+            ))
+        );
+    }
+}

lib/Doctrine/Inflector/Rules/Spanish/InflectorFactory.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Inflector\Rules\Spanish;
+
+use Doctrine\Inflector\CachedWordInflector;
+use Doctrine\Inflector\Inflector;
+use Doctrine\Inflector\RulesetInflector;
+
+final class InflectorFactory
+{
+    public function __invoke() : Inflector
+    {
+        return new Inflector(
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getSingularRuleset()
+            )),
+            new CachedWordInflector(new RulesetInflector(
+                Rules::getPluralRuleset()
+            ))
+        );
+    }
+}