Updated & added improvments/features

.gitattributes

@@ -0,0 +1,13 @@
+# Exclude unnecessary files from exports
+tests export-ignore
+docs export-ignore
+.github export-ignore
+.readthedocs.yaml export-ignore
+captainhook.json export-ignore
+phpunit.xml export-ignore
+pint.json export-ignore
+rector.php export-ignore
+.gitattributes export-ignore
+
+# Enforce LF
+*  text eol=lf

.github/CODEOWNERS

@@ -0,0 +1 @@
+* abmmhasan

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "composer" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

.github/workflows/php.yml → .github/workflows/build.yml

@@ -1,19 +1,23 @@
-name: "Stability Test"
+name: "Security & Standards"
 
 on:
+  schedule:
+    - cron: '0 0 * * 0'
   push:
     branches: [ '*' ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "master", "develop" ]
 
 jobs:
-  build:
+  run:
     runs-on: ${{ matrix.operating-system }}
     strategy:
       matrix:
         operating-system: [ ubuntu-latest ]
-        php-versions: [ '8.0', '8.1', '8.2', '8.3' ]
-    name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
+        php-versions: [ '8.2', '8.3' ]
+        dependency-version: [ prefer-lowest, prefer-stable ]
+
+    name: PHP ${{ matrix.php-versions }} - ${{ matrix.operating-system }} - ${{ matrix.dependency-version }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -36,3 +40,6 @@ jobs:
 
       - name: Package Audit
         run: composer audit
+
+      - name: Test
+        run: composer tests

.gitignore

@@ -1,4 +1,5 @@
+vendor
 .idea
-/vendor
 composer.lock
-example.php
+git-story_media
+test.php

README.md

@@ -9,26 +9,28 @@
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/abmmhasan/game-draw)
 
 
-The Game Draw library provides 2 different way of winner selection based on user's input and selected method.
+The **Game Draw** library provides flexible and varied methods for selecting winners based on different types of draws, **Lucky Draw**, **Grand Draw**, and a customizable **Flexible Draw** to meet a range of requirements.
 
 > Please don't use this to generate things/prizes with People's hard-earned money. It is intended to make things fun with bonus gifts only.
 
 
-## Prerequisits
+## Prerequisites
 
-Language: PHP 8/+
-
-PHP Extension: BCMath (may need to install manually)
+- **Language:** PHP 8+
+- **PHP Extension:** BCMath (may need to install manually)
 
 ## Installation
 
 ```
-composer require abmmhasan/game-draw
+composer require infocyph/game-draw
 ```
+## Overview
+
+### 1. LuckyDraw
 
-## Usage (Lucky Draw)
+The `LuckyDraw` class allows for winner selection based on item chances and weighted amounts.
 
-### Input Data
+#### Input Data
 
 ```php
 $products = [
@@ -92,28 +94,29 @@ $products = [
       - Max should be greater than or equal to min, bias should be greater than 0
       - The higher the bias, the more the chance to pick the lowest amount
 
-### Output Data
+#### Usage
 
 ```php
 $luckyDraw = new AbmmHasan\Draw\LuckyDraw($products);
-$luckyDraw->pick()
+$result = $luckyDraw->pick();
 ```
-Will output the data similar as following,
+
+Example Output:
 
 ```php
 [
-    'item' => 'product_000_NoLuck', // The item name
-    'amount' => 1 // the selected amount
+    'item' => 'product_000_NoLuck',
+    'amount' => 1
 ]
 ```
 
-### Inventory Solutions
+> Inventory Solutions: Available stock should be passed (after subtracting used amount from stock amount) in chances properly.
 
-Available stock should be passed (after subtracting used amount from stock amount) in chances properly.
+### 2. GrandDraw
 
-## Usage (Grand Draw)
+The `GrandDraw` class is designed for large draws where items and user entries are managed in bulk.
 
-### Input Data
+#### Input Data
 
 ```php
 $prizes = 
@@ -130,79 +133,167 @@ $prizes =
 
 - **amounts**: Amount of gift. It must be a positive integer value.
 
-To pass users, you've to make a CSV file with at-least 1 column. 1st column will indicate user identity.
+User entries are loaded using a CSV file:
 
 ```csv
 "usr47671",
 "usr57665",
-"usr47671",.....
+"usr47671",
+.....
 ```
 
-### Output Data
+#### Usage
 
 ```php
-$bucket = new GrandDraw();
-
-// set resources
-$bucket->setItems([ // set prizes
-    'product_001' => 10,        // Item Code/Identifier => Amount of the item
-    'product_002' => 5,
-    'product_003' => 3,
-    'product_004' => 2,
-    'product_005' => 1
-])->setUserListFilePath('./Sample1000.csv'); // set the CSV file location
-
-// get the winners
-$bucket->getWinners()
+$grandDraw = new AbmmHasan\Draw\GrandDraw();
+$grandDraw->setItems($prizes)
+          ->setUserListFilePath('./Sample1000.csv');
+$winners = $grandDraw->getWinners();
 ```
-Will provide the output similar as following,
+
+Example Output:
+
 ```php
-Array
-(
-    [product_001] => Array
-        (
-            [0] => usr47671
-            [1] => usr57665
-            [2] => usr92400
-            [3] => usr7249
-            [4] => usr37860
-            [5] => usr57280
-            [6] => usr97204
-            [7] => usr82268
-            [8] => usr16521
-            [9] => usr24864
-        )
-
-    [product_002] => Array
-        (
-            [0] => usr50344
-            [1] => usr60450
-            [2] => usr62662
-            [3] => usr26976
-            [4] => usr56486
-        )
-
-    [product_003] => Array
-        (
-            [0] => usr92895
-            [1] => usr37642
-            [2] => usr85241
-        )
-
-    [product_004] => Array
-        (
-            [0] => usr84327
-            [1] => usr22985
-        )
-
-    [product_005] => Array
-        (
-            [0] => usr26819
-        )
-
-)
+[
+    'product_001' => ['usr47671', 'usr57665', 'usr92400'],
+    'product_002' => ['usr50344', 'usr60450', 'usr62662']
+]
 ```
 
+### 3. FlexibleDraw
+
+The `FlexibleDraw` class provides a versatile approach to selection, offering various types of draw methods, including probability-based, elimination, round-robin, time-based, and more. This flexibility allows for customized and dynamic draws, suitable for a range of applications.
+
+#### Supported Draw Types
+- **Probability Draw**: Selects items based on assigned probability weights.
+- **Elimination Draw**: Items are drawn and removed from the selection pool, ensuring no repeats.
+- **Weighted Elimination Draw**: Similar to Elimination Draw, but selections are weighted.
+- **Round Robin Draw**: Items are selected in a round-robin sequence, cycling through each item.
+- **Cumulative Draw**: Draws items based on cumulative scores, with higher scores increasing selection probability.
+- **Batched Draw**: Draws a specified number of items in one call, with or without replacement.
+- **Time-Based Weighted Draw**: Selects items based on weight and a specified time interval, e.g., daily or weekly.
+- **Weighted Batch Draw**: Draws a batch of items using weighted probabilities.
+- **Sequential Draw**: Draws items in a fixed sequence, restarting once all items are drawn.
+- **Range Weighted Draw**: Selects a random number within a defined range, weighted by probability.
+
+#### FlexibleDraw Options and Usage Examples
+
+Below are usage examples for each draw type. Define your items array based on the draw type requirements.
+
+1. **Probability Draw**:
+    - Selects items based on weighted probabilities. Higher-weight items have a greater likelihood of selection.
+   ```php
+   $items = [
+       ['name' => 'item1', 'weight' => 10],
+       ['name' => 'item2', 'weight' => 20],
+   ];
+   ```
+
+2. **Elimination Draw**:
+    - Items are drawn once, removed from the pool after selection.
+   ```php
+   $items = [
+       ['name' => 'item1'],
+       ['name' => 'item2'],
+   ];
+   ```
+
+3. **Weighted Elimination Draw**:
+    - Similar to elimination, but uses weights to influence item selection.
+   ```php
+   $items = [
+       ['name' => 'item1', 'weight' => 10],
+       ['name' => 'item2', 'weight' => 20],
+   ];
+   ```
+
+4. **Round Robin Draw**:
+    - Cycles through items in a round-robin sequence.
+   ```php
+   $items = [
+       ['name' => 'item1'],
+       ['name' => 'item2'],
+   ];
+   ```
+
+5. **Cumulative Draw**:
+    - Draws items based on cumulative scores, with selection probabilities adjusted over time.
+   ```php
+   $items = [
+       ['name' => 'item1'],
+       ['name' => 'item2'],
+   ];
+   ```
+
+6. **Batched Draw**:
+    - Draws a batch of items in one call, with optional replacement.
+   ```php
+   $items = [
+       ['name' => 'item1'],
+       ['name' => 'item2'],
+   ];
+   ```
+
+7. **Time-Based Weighted Draw**:
+    - Selects items based on weight and a specified time interval (e.g., daily or weekly).
+   ```php
+   $items = [
+       ['name' => 'item1', 'weight' => 10, 'time' => 'daily'],
+       ['name' => 'item2', 'weight' => 20, 'time' => 'weekly'],
+   ];
+   ```
+
+8. **Weighted Batch Draw**:
+    - Draws a batch of items using weighted probabilities, balancing selections by item weight.
+   ```php
+   $items = [
+       ['name' => 'item1', 'weight' => 10],
+       ['name' => 'item2', 'weight' => 20],
+   ];
+   ```
+
+9. **Sequential Draw**:
+    - Selects items in a predefined sequence.
+   ```php
+   $items = [
+       ['name' => 'item1'],
+       ['name' => 'item2'],
+   ];
+   ```
+
+10. **Range Weighted Draw**:
+    - Specifies a range for each item using `min`, `max`, and `weight`.
+    ```php
+    $items = [
+        ['name' => 'item1', 'min' => 1, 'max' => 50, 'weight' => 10],
+        ['name' => 'item2', 'min' => 5, 'max' => 25, 'weight' => 15],
+    ];
+    ```
+
+#### Usage
+
+To use the `FlexibleDraw` class, create an instance with your items array and specify the draw type in the `draw` method:
+
+```php
+$flexibleDraw = new FlexibleDraw($items);
+$result = $flexibleDraw->draw('drawType'); // Replace 'drawType' with the desired draw type, e.g., 'probability'
+```
+
+### Example Output
+
+The output depends on the draw type and item configuration. For example, a probability draw with weights might yield:
+
+```php
+[
+    'item' => 'item2',
+    'weight' => 20,
+]
+```
+
+### FlexibleDraw Configuration Summary
+
+The `FlexibleDraw` class is highly adaptable, supporting various selection methods and configurations such as `weight`, `group`, `min`, `max`, and `time`. Ideal for applications needing nuanced and dynamic draws, it is more versatile than simpler draw mechanisms but optimized for manageable volumes.
+
 ## Support
 
 Having trouble? Create an issue!