Added documentation about all the way to declare enums, removed all fashioned ways to use enums from the README

Author: yann-eugone

DependencyInjection/EnumExtension.php

@@ -6,6 +6,7 @@
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 use Symfony\Component\HttpKernel\DependencyInjection\Extension;
+use Yokai\EnumBundle\Enum\EnumInterface;
 
 /**
  * @author Yann Eugoné <[email protected]>
@@ -27,5 +28,10 @@ public function load(array $configs, ContainerBuilder $container)
         $xmlLoader->load('forms.xml');
         $xmlLoader->load('validators.xml');
         $xmlLoader->load('twig.xml');
+
+        if (method_exists($container, 'registerForAutoconfiguration')) {
+            $container->registerForAutoconfiguration(EnumInterface::class)
+                ->addTag('enum');
+        }
     }
 }

README.md

@@ -20,98 +20,51 @@ Installation
 ### Add the bundle as dependency with Composer
 
 ``` bash
-$ php composer.phar require yokai/enum-bundle
+$ composer require yokai/enum-bundle
 ```
 
 ### Enable the bundle in the kernel
 
 ``` php
 <?php
-// app/AppKernel.php
+// config/bundles.php
 
-public function registerBundles()
-{
-    $bundles = [
+return [
         // ...
-        new Yokai\EnumBundle\YokaiEnumBundle(),
-    ];
-}
+    Yokai\EnumBundle\YokaiEnumBundle::class => ['all' => true],
+];
 ```
 
 
 Usage
 -----
 
-Let's take an example : our application has some members and each member has a `gender` and a `state`.
+Let's take an example : our application has some members and each member has a `gender` which can be "male" (`m`) or "female" (`f`).
 
 We first need to create the classes that will handle our enums :
 
+> **Note** this example is optimized for latest versions of Symfony, you will find more in dedicated doc file.
+
 ``` php
 <?php
-// src/AppBundle/Enum/Member/GenderEnum.php
-namespace AppBundle\Enum\Member;
+// src/App/Enum/Member/GenderEnum.php
+namespace App\Enum\Member;
 
 use Yokai\EnumBundle\Enum\EnumInterface;
+use Yokai\EnumBundle\Enum\EnumWithClassAsNameTrait;
 
 class GenderEnum implements EnumInterface
 {
-    const NAME = 'member.gender';
+    use EnumWithClassAsNameTrait;
 
     public function getChoices()
     {
-        return ['male' => 'Male', 'female' => 'Female'];
-    }
-
-    public function getName()
-    {
-        return static::NAME;
-    }
-}
-```
-
-``` php
-<?php
-// src/AppBundle/Enum/Member/StateEnum.php
-namespace AppBundle\Enum\Member;
-
-use Yokai\EnumBundle\Enum\AbstractTranslatedEnum;
-
-class StateEnum extends AbstractTranslatedEnum
-{
-    const NAME = 'member.state';
-
-    protected function getValues()
-    {
-        return ['new', 'validated', 'disabled'];
-    }
-
-    public function getName()
-    {
-        return static::NAME;
+        return ['m' => 'Male', 'f' => 'Female'];
     }
 }
 ```
 
-Then we must declare these classes as services :
-
-``` xml
-<!-- src/AppBundle/Resources/config/services.xml -->
-<services>
-    <!-- ... -->
-
-    <service id="enum.member.gender" class="AppBundle\Enum\Member\GenderEnum" public="false">
-        <tag name="enum"/>
-    </service>
-
-    <service id="enum.member.state" class="AppBundle\Enum\Member\StateEnum" 
-             parent="enum.abstract_translated" public="false">
-        <argument>choice.member.state.%s</argument>
-
-        <tag name="enum"/>
-    </service>
-
-</services>
-```
+If you are using PSR-4 service discovery, then your service is already registered.
 
 That's it, now the bundle know your enum services. You can start using it.
 
@@ -126,23 +79,12 @@ use Yokai\EnumBundle\Validator\Constraints\Enum;
 
 class Member
 {
-    //...
-
     /**
      * @var string
      *
-     * @Enum("member.state")
-     */
-    protected $state;
-
-    /**
-     * @var string
-     *
-     * @Enum("member.gender")
+     * @Enum("App\Enum\Member\GenderEnum")
      */
     protected $gender;
-
-    //...
 }
 ```
 
@@ -156,43 +98,31 @@ namespace AppBundle\Form\Type;
 use AppBundle\Enum\GenderEnum;
 use AppBundle\Enum\StateEnum;
 use Symfony\Component\Form\AbstractType;
-// For Symfony >= 2.8
-use Yokai\EnumBundle\Form\Type\EnumType;
 
 class MemberType extends AbstractType
 {
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
         $builder
             // Let the bundle guess the form type for you (requires that you configured the validation)
-            ->add('state')
             ->add('gender')
-
-            // Manual form type binding for Symfony >= 2.8
-            ->add('state', EnumType::class, ['enum' => StateEnum::NAME])
-            ->add('gender', EnumType::class, ['enum' => GenderEnum::NAME])
-
-            // Manual form type binding for Symfony 2.7
-            ->add('state', 'enum', ['enum' => StateEnum::NAME])
-            ->add('gender', 'enum', ['enum' => GenderEnum::NAME])
         ;
     }
 }
 ```
 
-
 Displaying the label for an enum value within a template :
 
 ```twig
-    {{ value|enum_label(constant('AppBundle\\Enum\\Member\\StateEnum::NAME')) }}
-    {{ value|enum_label(constant('AppBundle\\Enum\\Member\\GenderEnum::NAME')) }}
+    {{ value|enum_label(constant('AppBundle\\Enum\\Member\\GenderEnum')) }}
 ```
 
 
 Recipes
 ------------
 
 - Usage in [SonataAdminBundle](https://github.com/sonata-project/SonataAdminBundle) : see [doc](Resources/doc/sonata-admin.md)
+- All the ways to [declare enums](Resources/doc/declaring-enum.md)
 
 
 MIT License

Resources/doc/declaring-enum.md

@@ -0,0 +1,97 @@
+Declaring enum
+==============
+
+An enum is nothing more than a class with 2 methods : `getName` & `getChoices`, registered as a service.
+
+There is a lot of way to create and declare such classes
+
+
+The classic way
+-----
+
+Create a new class, implement both `getName` & `getChoices` methods.
+
+```php
+<?php
+
+namespace App\Enum;
+
+use Yokai\EnumBundle\Enum\EnumInterface;
+
+class GenderEnum implements EnumInterface
+{
+    public function getName()
+    {
+        return 'gender';
+    }
+
+    public function getChoices()
+    {
+        return ['m' => 'Male', 'f' => 'Female'];
+    }
+}
+```
+
+Define an enum service for it.
+
+``` yaml
+services:
+    enum.member.gender:
+        class: 'App\Enum\GenderEnum'
+        public: false
+        tags: ['enum']
+```
+
+
+The class as name way
+-----
+
+Create a new class, use `EnumWithClassAsNameTrait` trait and implement `getChoices` methods.
+
+```php
+<?php
+
+namespace App\Enum;
+
+use Yokai\EnumBundle\Enum\EnumInterface;
+use Yokai\EnumBundle\Enum\EnumWithClassAsNameTrait;
+
+class GenderEnum implements EnumInterface
+{
+    use EnumWithClassAsNameTrait;
+
+    public function getChoices()
+    {
+        return ['m' => 'Male', 'f' => 'Female'];
+    }
+}
+```
+
+Define an enum service for it.
+
+``` yaml
+services:
+    enum.member.gender:
+        class: 'App\Enum\GenderEnum'
+        public: false
+        tags: ['enum']
+```
+
+
+The configurable way
+-----
+
+No need for a class, just use the `ConfigurableEnum` class and define a new enum service.
+
+``` yaml
+services:
+    enum.member.gender:
+        class: 'Yokai\EnumBundle\Enum\ConfigurableEnum'
+        public: false
+        tags: ['enum']
+        arguments:
+            - "gender"
+            - m: 'Male'
+              f: 'Female'
+```
+