Improve documentation, add PHP 8.1-8.5 CI matrix, and refactor codebase

.github/workflows/tests.yml

@@ -5,14 +5,17 @@ on: push
 jobs:
   testing:
     runs-on: ubuntu-latest
-    container:
-      image: lazerg/laravel:php81
+    strategy:
+      matrix:
+        php: ['8.1', '8.2', '8.3', '8.4', '8.5']
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
         with:
-          fetch-depth: 1
-      - name: install composer dependencies [by @lazerg]
-        run: |
-          composer install --no-scripts
-      - name: Run Tests [by @lazerg]
-        run: php -d memory_limit=2048M ./vendor/bin/pest
+          php-version: ${{ matrix.php }}
+          coverage: none
+      - name: Install composer dependencies
+        run: composer update --no-interaction --prefer-dist
+      - name: Run Tests
+        run: ./vendor/bin/pest

.gitignore

@@ -3,3 +3,4 @@ vendor/
 composer.lock
 
 .phpunit.result.cache
+.phpunit.cache/

CLAUDE.md

@@ -0,0 +1,90 @@
+# Laravel Enum Pro - Development Guide
+
+## Coding Rules
+
+### Performance First
+- Use native PHP functions (`array_column`, `array_map`, `array_combine`, `array_filter`, `array_keys`, `array_values`, `implode`, etc.) for better performance
+- Only use `Collection` when the method's return type requires it
+- Base methods should return arrays, Collection methods should wrap them with `collect()`
+
+### Method Organization
+Order methods from base (native PHP) to derived (Collection):
+1. `toArray()` methods first - use native PHP functions
+2. `toString()` methods - use native PHP with array methods
+3. Collection methods - wrap array methods with `collect()`
+4. Lookup methods last
+
+### Example Pattern
+```php
+// 1. Base method - native PHP
+public static function namesToArray(): array
+{
+    return array_column(self::cases(), 'name');
+}
+
+// 2. String method - uses base
+public static function namesToString(string $separator = ', '): string
+{
+    return implode($separator, self::namesToArray());
+}
+
+// 3. Collection method - wraps base
+public static function names(): Collection
+{
+    return collect(self::namesToArray());
+}
+```
+
+## Testing Rules
+
+### Use Pest with `it()` syntax
+- Use `it()` instead of `test()` for BDD-style readability
+- Start descriptions with "can" for success cases: `it('can get...')`
+- Start descriptions with "throws" for exception cases: `it('throws exception when...')`
+
+### Test Naming Convention
+```php
+// Success cases - describe capability
+it('can get all enum names as a collection', function () { ... });
+it('can get enum value by its name with case-insensitive lookup', function () { ... });
+
+// Exception cases - describe failure condition
+it('throws exception when requesting more random values than available', function () { ... });
+it('throws exception when calling non-existent case as static method', function () { ... });
+```
+
+### Best Practices
+- Chain expectations with `->and()` for multiple assertions
+- Keep test descriptions clear and specific
+- Describe what the method does, not how it does it
+- Include context (e.g., "as a collection", "as an array", "by its value")
+- Use `use Tests\DifficultyEnum;` at top of test files
+
+## Project Structure
+
+```
+src/
+├── EnumPro.php          # Main trait (combines all)
+├── EnumNames.php        # Name methods
+├── EnumValues.php       # Value methods
+├── EnumOptions.php      # Options/selections for forms
+├── EnumRandom.php       # Random selection
+├── EnumStaticCalls.php  # Magic methods
+└── Exceptions/
+    ├── UndefinedCaseException.php
+    └── TooManyRandomValuesException.php
+
+tests/
+├── DifficultyEnum.php   # Test enum fixture
+├── EnumNamesTest.php
+├── EnumValuesTest.php
+├── EnumOptionsTest.php
+├── EnumRandomTest.php
+└── EnumStaticCallsTest.php
+```
+
+## Testing
+
+```bash
+./vendor/bin/pest
+```

README.md

@@ -3,33 +3,23 @@
 ![Laravel Enum Pro](./wallpaper/wallpaper.png)
 
 [![Latest Version](https://img.shields.io/packagist/v/lazerg/laravel-enum-pro.svg?style=flat-square)](https://packagist.org/packages/lazerg/laravel-enum-pro)
+[![PHP Version](https://img.shields.io/packagist/php-v/lazerg/laravel-enum-pro?style=flat-square)](https://packagist.org/packages/lazerg/laravel-enum-pro)
 [![Downloads](https://img.shields.io/packagist/dm/lazerg/laravel-enum-pro.svg?style=flat-square)](https://packagist.org/packages/lazerg/laravel-enum-pro)
-[![Repository Size](https://img.shields.io/github/repo-size/lazerg/laravel-enum-pro?style=flat-square)](https://github.com/lazerg/laravel-enum-pro)
-[![Last Commit](https://img.shields.io/github/last-commit/lazerg/laravel-enum-pro?style=flat-square)](https://github.com/lazerg/laravel-enum-pro)
+[![Total Downloads](https://img.shields.io/packagist/dt/lazerg/laravel-enum-pro?style=flat-square)](https://packagist.org/packages/lazerg/laravel-enum-pro)
 [![Packagist Stars](https://img.shields.io/packagist/stars/lazerg/laravel-enum-pro?style=flat-square)](https://packagist.org/packages/lazerg/laravel-enum-pro)
 
-`Laravel Enum Pro` is a simple trait that extends PHP 8.1+ enums with helpful utilities for Laravel applications. It lets you access enum data in a variety of convenient ways while keeping your code clean and expressive.
-
-## Features
-
-- Works directly with native PHP enums
-- Access case values via static method calls
-- Retrieve enum names and values as collections, arrays or strings
-- Generate random values for testing and factories
-- Build option and selection lists for form inputs
+A powerful trait that supercharges PHP 8.1+ enums with Laravel-friendly utilities. Get values, names, random cases, and form-ready options with a clean, fluent API.
 
 ## Installation
 
 ```bash
 composer require lazerg/laravel-enum-pro
 ```
 
-## Basic Usage
-
-Create an enum and include the trait:
+## Enum Example
 
 ```php
-enum LevelTypes: int
+enum DifficultyEnum: int
 {
     use \Lazerg\LaravelEnumPro\EnumPro;
 
@@ -41,71 +31,102 @@ enum LevelTypes: int
 }
 ```
 
-### Accessing Values
+## Accessing Value
 
 ```php
-LevelTypes::VERY_EASY();          // 1
-LevelTypes::valueOf('very easy'); // 1
+// 1
+DifficultyEnum::VERY_EASY();
+
+// 3
+DifficultyEnum::MEDIUM();
+
+// 5
+DifficultyEnum::VERY_STRONG();
+
+// 3
+$enum = DifficultyEnum::MEDIUM;
+$enum();
 ```
 
-### Working With Names
+## Accessing Name
 
 ```php
-LevelTypes::names();         // Collection: ['VERY_EASY', 'EASY', 'MEDIUM', 'STRONG', 'VERY_STRONG']
-LevelTypes::namesToArray();  // ['VERY_EASY', 'EASY', 'MEDIUM', 'STRONG', 'VERY_STRONG']
-LevelTypes::namesToString(); // "VERY_EASY, EASY, MEDIUM, STRONG, VERY_STRONG"
-LevelTypes::nameOf(1);       // 'VERY_EASY'
+// ['VERY_EASY', 'EASY', 'MEDIUM', 'STRONG', 'VERY_STRONG']
+DifficultyEnum::namesToArray();
+
+// 'VERY_EASY, EASY, MEDIUM, STRONG, VERY_STRONG'
+DifficultyEnum::namesToString();
+
+// Collection(['VERY_EASY', 'EASY', 'MEDIUM', 'STRONG', 'VERY_STRONG'])
+DifficultyEnum::names();
+
+// 'MEDIUM'
+DifficultyEnum::nameOf(3);
 ```
 
-### Working With Values
+## Accessing Values
 
 ```php
-LevelTypes::values();         // Collection: [1, 2, 3, 4, 5]
-LevelTypes::valuesToArray();  // [1, 2, 3, 4, 5]
-LevelTypes::valuesToString(); // "1,2,3,4,5"
+// [1, 2, 3, 4, 5]
+DifficultyEnum::valuesToArray();
+
+// '1,2,3,4,5'
+DifficultyEnum::valuesToString();
+
+// Collection([1, 2, 3, 4, 5])
+DifficultyEnum::values();
+
+// 1
+DifficultyEnum::valueOf('VERY_EASY');
+
+// 3 (case-insensitive)
+DifficultyEnum::valueOf('medium');
+
+// 5 (spaces converted to underscores)
+DifficultyEnum::valueOf('Very strong');
 ```
 
-### Randomization
+## Accessing Options
 
 ```php
-LevelTypes::random();      // Collection with one random value
-LevelTypes::randomArray(); // Array with one random value
-LevelTypes::randomFirst(); // Single random value
-```
+// [1 => 'Very Easy', 2 => 'Easy', 3 => 'Medium', 4 => 'Strong', 5 => 'Very Strong']
+DifficultyEnum::optionsToArray();
 
-### Options and Selections
+// Collection([1 => 'Very Easy', 2 => 'Easy', 3 => 'Medium', 4 => 'Strong', 5 => 'Very Strong'])
+DifficultyEnum::options();
 
-Use these helpers when building form inputs.
+// 'Very Strong'
+DifficultyEnum::getOption(5);
 
-```php
-LevelTypes::options();       // Collection of [value => display]
-LevelTypes::optionsToArray();
-LevelTypes::selections();    // Collection of [value => ..., display => ...]
-LevelTypes::selectionsToArray();
+// ['Medium', 'Very Strong']
+DifficultyEnum::getOptions([3, 5]);
+
+// [['value' => 1, 'display' => 'Very Easy'], ['value' => 2, 'display' => 'Easy'], ...]
+DifficultyEnum::selectionsToArray();
+
+// Collection([['value' => 1, 'display' => 'Very Easy'], ['value' => 2, 'display' => 'Easy'], ...])
+DifficultyEnum::selections();
 ```
 
-Example output of `options()`:
+## Accessing Random Value
 
 ```php
-Illuminate\Support\Collection {
-    #items: [
-        1 => "Very Easy",
-        2 => "Easy",
-        3 => "Medium",
-        4 => "Strong",
-        5 => "Very Strong",
-    ]
-}
+// [3, 1] (random values)
+DifficultyEnum::randomArray(2);
+
+// 4 (single random value)
+DifficultyEnum::randomFirst();
+
+// Collection([2, 5, 1]) (random values)
+DifficultyEnum::random(3);
 ```
 
 ## Testing
 
-Run the test suite with [Pest](https://pestphp.com/):
-
 ```bash
 ./vendor/bin/pest
 ```
 
 ## License
 
-This package is open-sourced software licensed under the [MIT license](LICENSE) as specified in `composer.json`.
+This package is open-sourced software licensed under the [MIT license](LICENSE).

composer.json

@@ -1,30 +1,44 @@
 {
     "name": "lazerg/laravel-enum-pro",
-    "description": "Laravel Enum Pro",
+    "description": "A powerful PHP enum extension with collection support, random selection, and magic static calls",
     "type": "library",
     "license": "MIT",
+    "keywords": ["laravel", "enum", "php", "collection", "helper"],
+    "homepage": "https://github.com/lazerg/laravel-enum-pro",
     "authors": [
         {
             "name": "lazerg",
             "email": "lazerg2@gmail.com"
         }
     ],
+    "support": {
+        "issues": "https://github.com/lazerg/laravel-enum-pro/issues",
+        "source": "https://github.com/lazerg/laravel-enum-pro"
+    },
     "minimum-stability": "stable",
     "require": {
-        "php": "^8.1|^8.2|^8.3|^8.4",
-        "illuminate/support": "^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0"
+        "php": "^8.1",
+        "illuminate/support": "^9.0|^10.0|^11.0|^12.0"
     },
     "autoload": {
         "psr-4": {
             "Lazerg\\LaravelEnumPro\\": "src/"
         }
     },
+    "autoload-dev": {
+        "psr-4": {
+            "Tests\\": "tests/"
+        }
+    },
     "require-dev": {
-        "pestphp/pest": "^1.22|^2.0|^3.0"
+        "pestphp/pest": "^1.0|^2.0|^3.0"
     },
     "config": {
         "allow-plugins": {
             "pestphp/pest-plugin": true
         }
+    },
+    "scripts": {
+        "test": "pest"
     }
 }

phpunit.xml

@@ -3,16 +3,18 @@
          xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
          bootstrap="vendor/autoload.php"
          colors="true"
+         cacheDirectory=".phpunit.cache"
+         stopOnFailure="false"
 >
     <testsuites>
         <testsuite name="Test Suite">
             <directory suffix="Test.php">./tests</directory>
         </testsuite>
     </testsuites>
-    <coverage processUncoveredFiles="true">
+
+    <source>
         <include>
-            <directory suffix=".php">./app</directory>
             <directory suffix=".php">./src</directory>
         </include>
-    </coverage>
+    </source>
 </phpunit>