Merge pull request #1 from webfox/readme-update

Update README.md
webfox · Sep 19, 2022 · 8414b56 · 8414b56
2 parents b107bd6 + f4c1286
commit 8414b56
Showing 1 changed file with 65 additions and 73 deletions.
diff --git a/README.md b/README.md
@@ -15,10 +15,10 @@ composer require webfox/laravel-backed-enums
 
 ## Usage
 
-### Using the trait
+### Setup your enum
 
-The enum you create must implement BackedEnum, this interface allows the toArray and toJson functions from within IsBackEnum to be called on your
-enum.
+The enum you create must implement the `BackedEnum` interface and also use the `IsBackedEnum` trait.
+The interface is required for Laravel to cast your enum correctly and the trait is what gives your enum its superpowers.
 
 ```php
 use Webfox\LaravelBackedEnums\BackedEnum;
@@ -43,43 +43,53 @@ Create enums.php lang file and create labels for your enum values.
 // resources/lang/en/enums.php
 
 return [
-     VolumeUnitEnum::class          => [
+     VolumeUnitEnum::class => [
         VolumeUnitEnum::MILLIGRAMS->name => "mg",
         VolumeUnitEnum::GRAMS->name      => "g",
         VolumeUnitEnum::KILOGRAMS->name  => "kg",
         VolumeUnitEnum::TONNE->name      => "t"
      ]
 ];
 ```
+You may then access these localized values using the `->label()` or `::labelFor()` methods
+```php
+VolumeUnitEnum::MILLIGRAMS->label(); // "mg"
+VolumeUnitEnum::labelFor(VolumeUnitEnum::TONNE); // "t"
+```
+If you do not specify a label in the lang file these methods will return the translation key e.g. `enums.\\App\\Enums\\VolumeUnitEnum.GRAMS`
 
 ### Meta data
 
 Adding metadata allows you to return additional values alongside the label and values.
 
-Create a withMeta function on your enum to add metadata.
+Create a withMeta method on your enum to add metadata.
 
 ```php
 public function withMeta(): array
-    {
-        return match ($this) {
-            self::MILLIGRAMS                => [
-                'background_color' => 'bg-green-100',
-                'text_color' => 'text-green-800',
-            ],
-            self::GRAMS                     => [
-                'background_color' => 'bg-red-100',
-                'text_color' => 'text-red-800',
-            ],
-            self::KILOGRAMS, self::TONNE    => [
-                'background_color' => 'bg-gray-100',
-                'text_color' => 'text-gray-800',
-            ],
-            default                         => throw new \Exception('Unexpected match value'),
-        };
-    }
+{
+    return match ($this) {
+        self::MILLIGRAMS                => [
+            'background_color' => 'bg-green-100',
+            'text_color'       => 'text-green-800',
+        ],
+        self::GRAMS                     => [
+            'background_color' => 'bg-red-100',
+            'text_color'       => 'text-red-800',
+        ],
+        self::KILOGRAMS, self::TONNE    => [
+            'background_color' => 'bg-gray-100',
+            'text_color'       => 'text-gray-800',
+        ],
+        default                         => [
+            'background_color' => 'bg-blue-100',
+            'text_color'       => 'text-blue-800',
+        ],
+    };
+}
 ```
+If you do not specify a `withMeta` method, meta will be an empty array.
 
-## Other functions
+## Other methods
 
 ### options
 
@@ -100,15 +110,15 @@ returns
         'label' => 'mg',
         'meta'  => [
             'background_color' => 'bg-green-100',
-            'text_color' => 'text-green-800',
+            'text_color'       => 'text-green-800',
         ],
     ],
     [
         'value' => 'Grams',
         'label' => 'g',
         'meta'  => [
             'background_color' => 'bg-red-100',
-            'text_color' => 'text-red-800',
+            'text_color'       => 'text-red-800',
         ],
         ...
     ]
@@ -129,10 +139,10 @@ returns
 
 ```php
 [
-    'Milligrams',
-    'Grams',
-    'Kilograms',
-    'Tonne',
+    'MILLIGRAMS',
+    'GRAMS',
+    'KILOGRAMS',
+    'TONNE',
 ]
 ```
 
@@ -178,40 +188,6 @@ returns
 ]
 ```
 
-
-### labelFor
-
-Returns the label for a given enum name.
-
-#### Usage
-
-```php
-VolumeUnitEnum::labelFor(VolumeUnitEnum::MILLIGRAMS);
-```
-
-returns
-
-```php
-'mg'
-```
-
-### label
-
-Returns the label for the current enum.
-
-#### Usage
-
-```php
-VolumeUnitEnum::MILLIGRAMS->label();
-```
-
-returns
-
-```php
-'mg'
-```
-
-
 ### toArray
 
 Returns an array of a single enum value with its label and metadata.
@@ -239,33 +215,49 @@ returns
 
 An alias for toArray.
 
-### isA
-Allows you to check if an enum is a given value. Returns a boolean.
+### isA/isAn
+Allows you to check if an enum is a given value. Returns a boolean.  
+> **Note**
+> `isAn` is just an alias for `isA`.
 
 #### Usage
 
 ```php
-VolumeUnitEnum::MILLIGRAMS->isA(VolumeUnitEnum::GRAMS);
+VolumeUnitEnum::MILLIGRAMS->isA(VolumeUnitEnum::GRAMS); //false
+VolumeUnitEnum::MILLIGRAMS->isA(VolumeUnitEnum::MILLIGRAMS); //true
 ```
 
-#### Negation
-The negated method also exists. Being isNot
+### isNotA/isNotAn
+Allows you to check if an enum is not a given value. Returns a boolean.
+> **Note**
+> `isNotAn` is just an alias for `isNotA`.
 
+#### Usage
 
-### isAn
-Alias for isA.
+```php
+VolumeUnitEnum::MILLIGRAMS->isA(VolumeUnitEnum::GRAMS); //true
+VolumeUnitEnum::MILLIGRAMS->isA(VolumeUnitEnum::MILLIGRAMS); //false
+```
 
 ### isAny
 Allows you to check if an enum is contained in an array. Returns a boolean.
 
 #### Usage
 
 ```php
-VolumeUnitEnum::MILLIGRAMS->isAny([VolumeUnitEnum::GRAMS, VolumeUnitEnum::TONNE]);
+VolumeUnitEnum::MILLIGRAMS->isAny([VolumeUnitEnum::GRAMS, VolumeUnitEnum::TONNE]); // false
+VolumeUnitEnum::MILLIGRAMS->isAny([VolumeUnitEnum::GRAMS, VolumeUnitEnum::MILLIGRAMS]); // true
 ```
 
-#### Negation
-The negated method also exists. Being isNotAny
+### isNotAny
+Allows you to check if an enum is not contained in an array. Returns a boolean.
+
+#### Usage
+
+```php
+VolumeUnitEnum::MILLIGRAMS->isAny([VolumeUnitEnum::GRAMS, VolumeUnitEnum::TONNE]); // true
+VolumeUnitEnum::MILLIGRAMS->isAny([VolumeUnitEnum::GRAMS, VolumeUnitEnum::MILLIGRAMS]); // false
+```
 
 ## Changelog