Skip to content

Commit c2f5c3d

Browse files
abmmhasanabmmhasan
committed
Updated & added improvments/features
1 parent 4fb1d30 commit c2f5c3d

21 files changed

+1595
-150
lines changed

‎.gitattributes

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Exclude unnecessary files from exports
2+
tests export-ignore
3+
docs export-ignore
4+
.github export-ignore
5+
.readthedocs.yaml export-ignore
6+
captainhook.json export-ignore
7+
phpunit.xml export-ignore
8+
pint.json export-ignore
9+
rector.php export-ignore
10+
.gitattributes export-ignore
11+
12+
# Enforce LF
13+
* text eol=lf

‎.github/CODEOWNERS

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* abmmhasan

‎.github/dependabot.yml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "composer" # See documentation for possible values
4+
directory: "/" # Location of package manifests
5+
schedule:
6+
interval: "daily"

‎.github/workflows/php.yml ‎.github/workflows/build.yml

+12-5
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
1-
name: "Stability Test"
1+
name: "Security & Standards"
22

33
on:
4+
schedule:
5+
- cron: '0 0 * * 0'
46
push:
57
branches: [ '*' ]
68
pull_request:
7-
branches: [ "main" ]
9+
branches: [ "main", "master", "develop" ]
810

911
jobs:
10-
build:
12+
run:
1113
runs-on: ${{ matrix.operating-system }}
1214
strategy:
1315
matrix:
1416
operating-system: [ ubuntu-latest ]
15-
php-versions: [ '8.0', '8.1', '8.2', '8.3' ]
16-
name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
17+
php-versions: [ '8.2', '8.3' ]
18+
dependency-version: [ prefer-lowest, prefer-stable ]
19+
20+
name: PHP ${{ matrix.php-versions }} - ${{ matrix.operating-system }} - ${{ matrix.dependency-version }}
1721
steps:
1822
- name: Checkout
1923
uses: actions/checkout@v4
@@ -36,3 +40,6 @@ jobs:
3640

3741
- name: Package Audit
3842
run: composer audit
43+
44+
- name: Test
45+
run: composer tests

‎.gitignore

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1+
vendor
12
.idea
2-
/vendor
33
composer.lock
4-
example.php
4+
git-story_media
5+
test.php

‎README.md

+169-78
Original file line numberDiff line numberDiff line change
@@ -9,26 +9,28 @@
99
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/abmmhasan/game-draw)
1010

1111

12-
The Game Draw library provides 2 different way of winner selection based on user's input and selected method.
12+
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.
1313

1414
> 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.
1515
1616

17-
## Prerequisits
17+
## Prerequisites
1818

19-
Language: PHP 8/+
20-
21-
PHP Extension: BCMath (may need to install manually)
19+
- **Language:** PHP 8+
20+
- **PHP Extension:** BCMath (may need to install manually)
2221

2322
## Installation
2423

2524
```
26-
composer require abmmhasan/game-draw
25+
composer require infocyph/game-draw
2726
```
27+
## Overview
28+
29+
### 1. LuckyDraw
2830

29-
## Usage (Lucky Draw)
31+
The `LuckyDraw` class allows for winner selection based on item chances and weighted amounts.
3032

31-
### Input Data
33+
#### Input Data
3234

3335
```php
3436
$products = [
@@ -92,28 +94,29 @@ $products = [
9294
- Max should be greater than or equal to min, bias should be greater than 0
9395
- The higher the bias, the more the chance to pick the lowest amount
9496

95-
### Output Data
97+
#### Usage
9698

9799
```php
98100
$luckyDraw = new AbmmHasan\Draw\LuckyDraw($products);
99-
$luckyDraw->pick()
101+
$result = $luckyDraw->pick();
100102
```
101-
Will output the data similar as following,
103+
104+
Example Output:
102105

103106
```php
104107
[
105-
'item' => 'product_000_NoLuck', // The item name
106-
'amount' => 1 // the selected amount
108+
'item' => 'product_000_NoLuck',
109+
'amount' => 1
107110
]
108111
```
109112

110-
### Inventory Solutions
113+
> Inventory Solutions: Available stock should be passed (after subtracting used amount from stock amount) in chances properly.
111114
112-
Available stock should be passed (after subtracting used amount from stock amount) in chances properly.
115+
### 2. GrandDraw
113116

114-
## Usage (Grand Draw)
117+
The `GrandDraw` class is designed for large draws where items and user entries are managed in bulk.
115118

116-
### Input Data
119+
#### Input Data
117120

118121
```php
119122
$prizes =
@@ -130,79 +133,167 @@ $prizes =
130133

131134
- **amounts**: Amount of gift. It must be a positive integer value.
132135

133-
To pass users, you've to make a CSV file with at-least 1 column. 1st column will indicate user identity.
136+
User entries are loaded using a CSV file:
134137

135138
```csv
136139
"usr47671",
137140
"usr57665",
138-
"usr47671",.....
141+
"usr47671",
142+
.....
139143
```
140144

141-
### Output Data
145+
#### Usage
142146

143147
```php
144-
$bucket = new GrandDraw();
145-
146-
// set resources
147-
$bucket->setItems([ // set prizes
148-
'product_001' => 10, // Item Code/Identifier => Amount of the item
149-
'product_002' => 5,
150-
'product_003' => 3,
151-
'product_004' => 2,
152-
'product_005' => 1
153-
])->setUserListFilePath('./Sample1000.csv'); // set the CSV file location
154-
155-
// get the winners
156-
$bucket->getWinners()
148+
$grandDraw = new AbmmHasan\Draw\GrandDraw();
149+
$grandDraw->setItems($prizes)
150+
->setUserListFilePath('./Sample1000.csv');
151+
$winners = $grandDraw->getWinners();
157152
```
158-
Will provide the output similar as following,
153+
154+
Example Output:
155+
159156
```php
160-
Array
161-
(
162-
[product_001] => Array
163-
(
164-
[0] => usr47671
165-
[1] => usr57665
166-
[2] => usr92400
167-
[3] => usr7249
168-
[4] => usr37860
169-
[5] => usr57280
170-
[6] => usr97204
171-
[7] => usr82268
172-
[8] => usr16521
173-
[9] => usr24864
174-
)
175-
176-
[product_002] => Array
177-
(
178-
[0] => usr50344
179-
[1] => usr60450
180-
[2] => usr62662
181-
[3] => usr26976
182-
[4] => usr56486
183-
)
184-
185-
[product_003] => Array
186-
(
187-
[0] => usr92895
188-
[1] => usr37642
189-
[2] => usr85241
190-
)
191-
192-
[product_004] => Array
193-
(
194-
[0] => usr84327
195-
[1] => usr22985
196-
)
197-
198-
[product_005] => Array
199-
(
200-
[0] => usr26819
201-
)
202-
203-
)
157+
[
158+
'product_001' => ['usr47671', 'usr57665', 'usr92400'],
159+
'product_002' => ['usr50344', 'usr60450', 'usr62662']
160+
]
204161
```
205162

163+
### 3. FlexibleDraw
164+
165+
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.
166+
167+
#### Supported Draw Types
168+
- **Probability Draw**: Selects items based on assigned probability weights.
169+
- **Elimination Draw**: Items are drawn and removed from the selection pool, ensuring no repeats.
170+
- **Weighted Elimination Draw**: Similar to Elimination Draw, but selections are weighted.
171+
- **Round Robin Draw**: Items are selected in a round-robin sequence, cycling through each item.
172+
- **Cumulative Draw**: Draws items based on cumulative scores, with higher scores increasing selection probability.
173+
- **Batched Draw**: Draws a specified number of items in one call, with or without replacement.
174+
- **Time-Based Weighted Draw**: Selects items based on weight and a specified time interval, e.g., daily or weekly.
175+
- **Weighted Batch Draw**: Draws a batch of items using weighted probabilities.
176+
- **Sequential Draw**: Draws items in a fixed sequence, restarting once all items are drawn.
177+
- **Range Weighted Draw**: Selects a random number within a defined range, weighted by probability.
178+
179+
#### FlexibleDraw Options and Usage Examples
180+
181+
Below are usage examples for each draw type. Define your items array based on the draw type requirements.
182+
183+
1. **Probability Draw**:
184+
- Selects items based on weighted probabilities. Higher-weight items have a greater likelihood of selection.
185+
```php
186+
$items = [
187+
['name' => 'item1', 'weight' => 10],
188+
['name' => 'item2', 'weight' => 20],
189+
];
190+
```
191+
192+
2. **Elimination Draw**:
193+
- Items are drawn once, removed from the pool after selection.
194+
```php
195+
$items = [
196+
['name' => 'item1'],
197+
['name' => 'item2'],
198+
];
199+
```
200+
201+
3. **Weighted Elimination Draw**:
202+
- Similar to elimination, but uses weights to influence item selection.
203+
```php
204+
$items = [
205+
['name' => 'item1', 'weight' => 10],
206+
['name' => 'item2', 'weight' => 20],
207+
];
208+
```
209+
210+
4. **Round Robin Draw**:
211+
- Cycles through items in a round-robin sequence.
212+
```php
213+
$items = [
214+
['name' => 'item1'],
215+
['name' => 'item2'],
216+
];
217+
```
218+
219+
5. **Cumulative Draw**:
220+
- Draws items based on cumulative scores, with selection probabilities adjusted over time.
221+
```php
222+
$items = [
223+
['name' => 'item1'],
224+
['name' => 'item2'],
225+
];
226+
```
227+
228+
6. **Batched Draw**:
229+
- Draws a batch of items in one call, with optional replacement.
230+
```php
231+
$items = [
232+
['name' => 'item1'],
233+
['name' => 'item2'],
234+
];
235+
```
236+
237+
7. **Time-Based Weighted Draw**:
238+
- Selects items based on weight and a specified time interval (e.g., daily or weekly).
239+
```php
240+
$items = [
241+
['name' => 'item1', 'weight' => 10, 'time' => 'daily'],
242+
['name' => 'item2', 'weight' => 20, 'time' => 'weekly'],
243+
];
244+
```
245+
246+
8. **Weighted Batch Draw**:
247+
- Draws a batch of items using weighted probabilities, balancing selections by item weight.
248+
```php
249+
$items = [
250+
['name' => 'item1', 'weight' => 10],
251+
['name' => 'item2', 'weight' => 20],
252+
];
253+
```
254+
255+
9. **Sequential Draw**:
256+
- Selects items in a predefined sequence.
257+
```php
258+
$items = [
259+
['name' => 'item1'],
260+
['name' => 'item2'],
261+
];
262+
```
263+
264+
10. **Range Weighted Draw**:
265+
- Specifies a range for each item using `min`, `max`, and `weight`.
266+
```php
267+
$items = [
268+
['name' => 'item1', 'min' => 1, 'max' => 50, 'weight' => 10],
269+
['name' => 'item2', 'min' => 5, 'max' => 25, 'weight' => 15],
270+
];
271+
```
272+
273+
#### Usage
274+
275+
To use the `FlexibleDraw` class, create an instance with your items array and specify the draw type in the `draw` method:
276+
277+
```php
278+
$flexibleDraw = new FlexibleDraw($items);
279+
$result = $flexibleDraw->draw('drawType'); // Replace 'drawType' with the desired draw type, e.g., 'probability'
280+
```
281+
282+
### Example Output
283+
284+
The output depends on the draw type and item configuration. For example, a probability draw with weights might yield:
285+
286+
```php
287+
[
288+
'item' => 'item2',
289+
'weight' => 20,
290+
]
291+
```
292+
293+
### FlexibleDraw Configuration Summary
294+
295+
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.
296+
206297
## Support
207298

208299
Having trouble? Create an issue!

0 commit comments

Comments
 (0)