├── composer.json ├── LICENSE.md ├── src ├── VoucherTransformer.php └── VoucherGenerator.php ├── tests └── VoucherTest.php └── README.md /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "amestsantim/voucherator", 3 | "description": "A generic PHP package that can generate all sorts of random voucher/coupon codes. Laravel compatible.", 4 | "keywords": [ 5 | "amestsantim", 6 | "voucherator", 7 | "keygen", 8 | "code", 9 | "random" 10 | ], 11 | "homepage": "https://github.com/amestsantim/voucherator", 12 | "authors": [{ 13 | "name": "Nahom Tamerat", 14 | "email": "nahomt@amestsantim.com" 15 | }], 16 | "autoload": { 17 | "psr-4": { 18 | "AmestSantim\\Voucherator\\": "src/" 19 | } 20 | }, 21 | "autoload-dev": { 22 | "psr-4": { 23 | "Amestsantim\\Voucherator\\Tests\\Unit\\": "tests" 24 | } 25 | }, 26 | "require": { 27 | "php": "^7.3|^8.0", 28 | "illuminate/collections": "8.*" 29 | }, 30 | "license": "MIT" 31 | } 32 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Nahom Tamerat 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/VoucherTransformer.php: -------------------------------------------------------------------------------- 1 | charSet = array_merge(range(0, 9), range('a', 'z'), range('A', 'Z')); 12 | } 13 | 14 | /* Used for debugging and testing purpose */ 15 | public function charSet() 16 | { 17 | return $this->charSet; 18 | } 19 | 20 | public function generate($count = 1) 21 | { 22 | $poolSize = count($this->charSet); 23 | $vouchers = []; 24 | for ($i = 0; $i < $count; $i++) { 25 | $generatedString = ''; 26 | while (strlen($generatedString) < $this->length) { 27 | try { 28 | $pickedPosition = random_int(0, $poolSize); 29 | $generatedString .= $this->charSet[$pickedPosition]; 30 | $generatedString = str_shuffle($generatedString); 31 | } catch (\Exception $e) { 32 | // Loop back for another try 33 | } 34 | } 35 | array_push($vouchers, $generatedString); 36 | } 37 | return $vouchers; 38 | } 39 | 40 | public function length($length) 41 | { 42 | $this->length = $length; 43 | return $this; 44 | } 45 | 46 | /* The following methods (numerals, letters, upperCase, lowerCase, exclude and augment) affect/mutate the 47 | character set (charSet) */ 48 | 49 | public function numerals() 50 | { 51 | $this->charSet = range(0, 9); 52 | return $this; 53 | } 54 | 55 | public function letters() 56 | { 57 | $this->charSet = array_merge(range('a', 'z'), range('A', 'Z')); 58 | return $this; 59 | } 60 | 61 | public function upperCase() 62 | { 63 | $upper = collect($this->charSet)->map(function ($item) { 64 | return strtoupper($item); 65 | }); 66 | $this->charSet = $upper->unique()->toArray(); 67 | return $this; 68 | } 69 | 70 | public function lowerCase() 71 | { 72 | $lower = collect($this->charSet)->map(function ($item) { 73 | return strtolower($item); 74 | }); 75 | $this->charSet = $lower->unique()->toArray(); 76 | return $this; 77 | } 78 | 79 | public function exclude($charsAsString) 80 | { 81 | $exclusionList = str_split($charsAsString); 82 | $this->charSet = collect($this->charSet)->reject(function ($item) use ($exclusionList) { 83 | return in_array($item, $exclusionList); 84 | })->toArray(); 85 | return $this; 86 | } 87 | 88 | public function augment($charsAsString) 89 | { 90 | $inclusionList = str_split($charsAsString); 91 | $this->charSet = collect($this->charSet)->merge($inclusionList)->unique()->toArray(); 92 | return $this; 93 | } 94 | } -------------------------------------------------------------------------------- /tests/VoucherTest.php: -------------------------------------------------------------------------------- 1 | generator = new VoucherGenerator(); 17 | } 18 | 19 | public function testConstructor() 20 | { 21 | $this->assertEquals(array_merge(range(0, 9), range('a', 'z'), range('A', 'Z')), $this->generator->charSet()); 22 | } 23 | 24 | private function checkCountAndLength($arr, $count, $length) 25 | { 26 | $this->assertIsArray($arr); 27 | $this->assertEquals($count, count($arr)); 28 | $green = true; 29 | foreach ($arr as $item) { 30 | $green = $green || ($length === strlen($item)); 31 | } 32 | $this->assertTrue($green); 33 | } 34 | 35 | public function testDefaultGenerateMethod() 36 | { 37 | $generated = $this->generator->generate(3); 38 | $this->checkCountAndLength($generated, 3, 8); 39 | } 40 | 41 | public function testLengthMethod() 42 | { 43 | $generated = $this->generator->generate(2); 44 | $this->checkCountAndLength($generated, 2, 12); 45 | } 46 | 47 | public function testExcludeMethod() 48 | { 49 | $this->assertFalse(in_array('A', $this->generator->letters()->exclude('A')->charSet())); 50 | } 51 | 52 | public function testAugmentMethod() 53 | { 54 | $this->assertTrue(in_array('#', $this->generator->letters()->augment('#')->charSet())); 55 | } 56 | 57 | public function testNumeralsMethod() 58 | { 59 | $this->assertEquals(range(0, 9), $this->generator->numerals()->charSet()); 60 | } 61 | 62 | public function testUpperCaseMethod() 63 | { 64 | $this->assertEquals(range('A', 'Z'), $this->generator->letters()->upperCase()->charSet()); 65 | } 66 | 67 | public function testLowerCaseMethod() 68 | { 69 | $this->assertEquals(range('a', 'z'), $this->generator->letters()->lowerCase()->charSet()); 70 | } 71 | 72 | public function testCapitalizeFirstCharacter() 73 | { 74 | $generated = $this->generator->generate(); 75 | $generated = VoucherTransformer::capitalizeFirstCharacter($generated); 76 | $this->assertEquals(ucfirst($generated[0])[0], $generated[0][0]); 77 | } 78 | 79 | public function testAddSeparator() 80 | { 81 | $generated = $this->generator->generate(); 82 | $generated = VoucherTransformer::addSeparator($generated, 4, '-'); 83 | $pieces = explode('-', $generated[0]); 84 | $this->assertEquals(2, count($pieces)); 85 | $this->assertEquals(4, strlen($pieces[0])); 86 | $this->assertEquals(4, strlen($pieces[1])); 87 | } 88 | 89 | public function testPrefix() 90 | { 91 | $generated = $this->generator->generate(); 92 | $generated = VoucherTransformer::addPrefix($generated, 'ET'); 93 | $this->assertEquals('ET', substr($generated[0], 0, 2)); 94 | } 95 | } 96 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Voucherator 2 | [![Total Downloads](https://poser.pugx.org/amestsantim/voucherator/downloads)](https://packagist.org/packages/amestsantim/voucherator) [![License](https://poser.pugx.org/amestsantim/voucherator/license)](https://packagist.org/packages/amestsantim/voucherator) 3 | 4 | The only voucher (alphanumeric code) generator you will ever need for PHP. 5 | Voucherator has a fluent Generator class that can generate various types of random alphanumeric codes. The package also includes a Transformer class that you can use to apply some transformations to the generated vouchers. You can use it to generate passwords, pass codes, keys, vouchers, coupons, tickets, tokens etc. 6 | 7 | ## Prerequisites 8 | 9 | This package uses PHP 7's `random_int()` function which generates cryptographic random integers that are suitable for use where unbiased results are critical, such as when shuffling a deck of cards for a poker game. 10 | 11 | The sources of randomness used for this function are as follows and if your machine does not provide one of these, you will not be able to use this package. 12 | 13 | - On Windows, [» **CryptGenRandom()**](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx) will always be used. As of PHP 7.2.0, the [» CNG-API](https://docs.microsoft.com/en-us/windows/desktop/SecCNG/cng-portal) will always be used instead. 14 | - On Linux, the [» getrandom(2)](http://man7.org/linux/man-pages/man2/getrandom.2.html) syscall will be used if available. 15 | - On other platforms, /dev/urandom will be used. 16 | - If none of the aforementioned sources are available, then an [Exception](http://php.net/manual/en/class.exception.php) will be thrown. (caught and supressed by this package) 17 | 18 | ## Installation 19 | 20 | 21 | ### Via Composer 22 | 23 | This package can be installed easily with composer - just require the `amestsantim/voucherator` package from the command line. 24 | 25 | ``` 26 | composer require amestsantim/voucherator 27 | ``` 28 | 29 | Alternatively, you can manually add the voucherator package to your `composer.json` file and then run `composer install` from the command line as follows: 30 | ``` 31 | { 32 | "require": { 33 | "amestsantim/voucherator": "~2.1" 34 | } 35 | } 36 | ``` 37 | ``` 38 | composer install 39 | ``` 40 | 41 | You can use it in your PHP code like this: 42 | ```php 43 | letters()->length(12)->lowerCase()->generate()[0]; 49 | // Your coupon code is pxEJvcvRjwNg 50 | ``` 51 | If you are using it in Laravel, you can instantiate an object from the `AmestSantim\Voucherator\VoucherGenerator` and statically access the methods from the `AmestSantim\Voucherator\VoucherTransformer` class, if you need to apply transformations on your generated vouchers. 52 | 53 | ## Usage 54 | 55 | ```php 56 | $v = AmestSantim\Voucherator\VoucherGenerator(); 57 | 58 | $v->generate(10); 59 | // ["6ae4OgTp", ...] 60 | 61 | $v->letters()->generate(5); 62 | // ["sVnkujCq", ...] 63 | 64 | $v->numerals()->length(16)->generate(); 65 | // ["1734785015950957", ...] 66 | 67 | $v->letters()->upperCase()->generate(200); 68 | // ["JTMAZNIZDDSUGVHC", ...] 69 | 70 | $v->numerals()->exclude('018')->generate(3); 71 | // ["4454525224222425", ...] 72 | 73 | $vouchers = $v->augment('#*')->generate(3); 74 | VoucherTransformer::addPrefix($vouchers, 'ET'); 75 | // ["ET69376##4492*2736", ...] 76 | 77 | $vouchers = $v->length(14)->generate(3); 78 | VoucherTransformer::addSeparator(VoucherTransformer::addPrefix($voucher, 'AA'), 4, '-'); 79 | // ["AA4Z-c3pP-APDU-E4u2", ...] 80 | 81 | $v->length(6)->numerals(); 82 | $v->generate(100) 83 | // ["939374", ...] 84 | ``` 85 | ## Documentation 86 | The package is organized very simply. It contains only two classes: 87 | 88 | - VoucherGenerator 89 | - VoucherTransformer 90 | 91 | ### VoucherGenerator 92 | The methods of the `VoucherGenerator` class can be semantically classified into two: 93 | 94 | ##### Mutators 95 | These are the functions that mutate the character set (charSet) from which the vouchers/codes are generated. The default is lower case alphabets, upper case alphabets and numerals. Be mindful that the order in which you apply these function will result in different outcomes. 96 | - **letters()** 97 | Calling this function will set the character set to be lower (a - z) and upper (A - Z) case alphabets. 98 | 99 | - **numerals()** 100 | This will set the character set to be numerals (0123456789). 101 | 102 | - **upperCase()** 103 | This will change the characters in the character set all to upper case (A - Z). If the set happend to be upper and lower case letters before the application of the function, then the set will be consolidated (redundancies removed). 104 | 105 | - **lowerCase()** 106 | This will change the characters in the character set all to lower case (a - z). If the set happend to be upper and lower case letters before the application of the function, then the set will be consolidated (redundancies removed). 107 | 108 | - **exclude(string $exclusionList)** 109 | This function will remove the given characters (\$exclusionList) from the character set. If the given characters are not in the character set then it will be ignored. 110 | Example: `$v->exclude('0o1li')->generate()` 111 | 112 | - **augment(string $inclusionList)** 113 | This function will add the given characters (\$inclusionList) to the character set. If the given characters (some) are already in the character set then they will not be added again. 114 | Example: `$v->augment('#_*@?')->generate()` 115 | 116 | ##### Action and Related 117 | These function are action functions which tell the object to actually generate the vouchers/codes based on the (possibly previously mutated) character set. 118 | 119 | - **generate(int $count)** 120 | This function needs to be called at the end of a fluent chain. You can not call generate() in the middle of a chain. It accepts the number of vouchers to generate and returns an array of generated vouchers (even for a single voucher). 121 | 122 | - **length(int $voucherLength)** 123 | This function is used to set the length (size) of your vouchers. The default value used (if you do not call this function) is 8. 124 | 125 | - **charSet()** 126 | This function returns the current character set as is. The return is array. It is included for testing and debugging purposes and would have no conceivable use in production. 127 | 128 | ### VoucherTransformer 129 | The methods of the `VoucherTransformer` class are all static and can be used without instantiating an object. They act upon the vouchers/codes after they have been generated by transforming the vouchers in superficial (presentational) ways such as re-formatting and decorating them. All the functions are static and accept and return an array of vouchers. 130 | 131 | - **capitalizeFirstCharacter(array $vouchers)** 132 | This function will capitalize the first character of each voucher/code. 133 | Example: `$myProperCaseVouchers = VoucherTransformer::capitalizeFirstCharacter($myVouchers)` 134 | 135 | - **addSeparator(array $vouchers, int $chunkSize, character $separator)** 136 | This function will group the characters of the vouchers in to chunks of size $chunkSize and join them with the given character ($separator) 137 | 138 | - **addPrefix(array $vouchers, string $prefix)** 139 | This function will prefix all generated vouchers/codes with the given string ($prefix) 140 | 141 | ## Contributing 142 | 143 | The code follows the PSR-2 coding style guide. It was also written with extensibility in mind. Please feel free to submit a pull request, if you come up with any useful improvements. 144 | 145 | ## Versioning 146 | 147 | We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/your/project/tags). 148 | 149 | ## Authors 150 | 151 | * **Nahom Tamerat** 152 | 153 | ## License 154 | 155 | This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details 156 | 157 | ## Acknowledgments 158 | 159 | * This package was inspired by [keygen-php](https://github.com/gladchinda/keygen-php) 160 | 161 | --------------------------------------------------------------------------------