hedronium / casus
A Library to Generate anything Random.
Requires
- php: >=5.4.0
- ext-mcrypt: *
Requires (Dev)
- phpunit/phpunit: ~4.4
This package is not auto-updated.
Last update: 2024-10-26 18:38:48 UTC
README
Just another Randomizer Library but cooler! With many out of the box features and support for 'Cryptographically Secure Pseudo Random Number Generators' (CSPRNGs) provided by MCrypt and/or OpenSSL
#Installation
The easiest way to install Casus for use in your own projects is through composer. You could manually download the
files and use an alternative psr-4 compatible autoloader to autoload the file
in the src
directory but this is not recommended and highly discouraged.
Through composer.json File
Add this line in your composer.json
file and run composer install
on the command line
"require": { "hedronium/casus": "*" }
Through the command line
Just run in your project directory
composer require hedronium/casus
#Usage Basically all you do is instantiate an object of the Casus Class and you're good to go!
<?php //Include the Composer Autoloader include "vendor/autoload.php"; $casus = new \hedronium\Casus\Casus(); echo $casus->integer();
The above example will out put a number between 0
and PHP_INT_MAX
of your PHP installation.
The casus class actually forwards all method calls to the generator instance, thus you could, if you prefer to, get the generator instance and call methods directly on it. Like:
<?php $casus = new \hedronium\Casus\Casus(); $random_generator = $casus->getGenerator(); echo $random_generator->integer();
#Methods
Method List
- integer - Generates a random integer
- float - Generates a random floating point number
- boolean - Generates a random boolean value
- alpha - Generates a random string with alphabets
- alphanum - Generates a random string with alphabets and numbers
- asciiRange - Generates a random string from a range in the ascii table
- string - Generates a random string from a character set
- integerArray - Generates an array of random Integers
- uniqueIntegerArray - Generates an array of unique random Integers
- floatArray - Generates an array of random floating point integers
- randomize - Takes an array or string and randomizes its order
- selectRandom - Selects elements from an array at random
- byte - Generates a random byte
- byteString - Generates a string of random bytes
The $secure
parameter on each method is used to temporarily override the secure generator for an insecure one, in a secure instance. (This can be done by setting it to false
). By default it is set to true
.
integer ($min, $max [, $secure])
Returns a Number between $min
& $max
Parameters
-
int
$min
(0
)Lower Bound of numbers returned
-
int
$max
(PHP_INT_MAX
)Upper Bound of numbers returned
float ($min, $max, $precision [, $secure])
Returns a Floating point number between $min
& $max
Parameters
-
int
$min
(0
)Lower Bound of numbers returned
-
int
$max
(PHP_INT_MAX
)Upper Bound of numbers returned
-
int
$precision
(4
)Number of decimal digits
boolean ([$secure])
Returns a boolean
value (true
or false
)
alpha ($length, $case_randomization [, $secure])
Returns a string consisting of alphabets
Parameters
-
int
$length
(32
)Length of the Random String
-
boolean
$case_randomization
(true
)To randomize case or not
alphanum ($length, $case_randomization [, $secure])
Returns a string consisting of alphabets & numbers
Parameters
-
int
$length
(32
)Length of the Random String
-
boolean
$case_randomization
(true
)2nd parameter)To randomize case or not
asciiRange ($length, $ranges [, $secure])
Returns a string consisting of ASCII characters with the the range
defined by $ranges
Parameters
-
int
$length
(32
)Length of the Random String
-
array
$ranges
([[65,90],[97,122],[48,57]]
)The Ranges of Character codes in the ASCII table to choose from It could be a single dimensional array with the first value being the starting point and the second being the ending point
eg.asciiRange(32, [97, 122])
[A-Z]Or
It could be a multidimensional array defining a set of ranges like:
$ranges = [ [65,90], [97,122], [48,57] ]; asciiRange(32, $ranges)
The above produces a string consisting of lower case letters, upper case letters and numbers
string ($length, $charset [, $secure])
Returns a string consisting of the characters specified in $charset
Parameters
-
int
$length
(32
)Length of the Random String
-
array/string
$charset
(abcdefghijklmopqrstuvwxyz
)An Array or String of characters to be used in the random string
integerArray ($min, $max, $length [, $secure])
Returns an array of random integers
Parameters
-
int
$min
(0
)Lower Bound of numbers returned
-
int
$max
(PHP_INT_MAX
)Upper Bound of numbers returned
-
int
$length
(10
)Length of generated Array
uniqueIntegerArray ($min, $max, $length [, $secure])
Returns an array of unique random integers
Parameters
-
int
$min
(0
)Lower Bound of numbers returned
-
int
$max
(PHP_INT_MAX
)Upper Bound of numbers returned
-
int
$length
(10
)Length of generated Array
floatArray ($min, $max, $precision, $length [, $secure])
Returns an array of random floating point numbers
Parameters
-
int
$min
(0
)Lower Bound of numbers returned
-
int
$max
(PHP_INT_MAX
)Upper Bound of numbers returned
-
int
$precision
(4
)Number of decimal digits Array or String
-
int
$length
(10
)Length of generated Integer Array
randomize ($input [, $secure])
Takes a Array or String and returns a randomized version of it.
Parameters
- array/string
$input
The Array or String to be randomized
selectRandom ($input, $length [, $secure])
Selects random elements from an array or string
Parameters
-
array/string
$input
The Array or String to be randomly selected from
-
int
$length
(10
)Length of generated Array or String
byte ([$secure])
Returns a Random Byte
byteString ($length [, $secure])
Returns a Random String of Bytes
Parameters
- int
$length
(32
)Length of generated Byte String
Initialization Options
$secure
type: boolean
default: true
To use a Cryptographically Secure Generator or not. By default, a CSPRNG
like MCrypt
or OpenSSL
will be used
$casus = new Casus(false);
The Above example makes Casus use a Generator that is not cryptographically secure. (It just uses
PHP's built in mt_rand
function)
$generator
type: Generator
default: null
Injects the Generator Instance to use. (Must be an instance of a child of \hedronium\Casus\Generator
)
$generator = new \hedronium\Casus\OpenSSL(); $casus = new Casus(true, $generator);
The Above example specifies an instance of the default OpenSSL generator.
Note: If the provided generator is not secure and $secure
is set to true, Casus will throw an
\hedronium\Casus\errors\Insecure
Exception.
#Misc Methods
isSecure()
Returns: boolean
Returns if the current Generator in use is Secure or not.
hasMCrypt()
Returns: boolean
Returns if your PHP installation has the MCrypt extension enabled or not.
hasOpenSSL()
Returns: boolean
Returns if your PHP installation has the OpenSSL extension enabled or not.
getGenerator()
Returns: Generator
Returns the current Generator Instance in use.
setGenerator($secure, $generator)
Returns: boolean
Set a new generator based on arguments. (This is actually the method the constructor calls behind the scenes)
Returns true on success, and throws hedronium\Casus\errors\Insecure
Exception if the first parameter is true but the generator parameter is not a secure generator, or if no secure generator extension was found.
#Writing Custom Generators
##Creating a Generator
To create a generator all you have to do is write a class that extends
the abstract class \hedronium\Casus\Generator
. It is absolutely required that you implement the integer ($min, $max)
method. (It's already an Abstract Method, so you should get an error in the event that you forget to implement it)
Example Generator:
<?php class SuperGenerator extends \hedronium\Casus\Generator { public function integer($min, $max) { return rand($min, $max); } }
##Using your Custom Generator Just Pass it in as the second parameter of the Casus constructor
<?php $generator = new SuperGenerator(); $casus = new \hedronium\Casus\Casus(false, $generator);
Or Just directly instantiate your Generator class (the Casus Main Class is useless anyway, it actually just forwards all the method calls to the generator instance)
<?php $random = new SuperGenerator();
Note: The Casus main class could be used to enforce secure Generators.
##Cryptographically Secure? If your Generator is Cryptographically Secure (uses an CSPRNG Algorithm) then you have to specify it so that Casus doesn't complain.
You can do that simply by setting the $secure
property in your Generator class to true
like:
<?php class SuperGenerator extends \hedronium\Casus\Generator { protected $secure = true; public function integer($min, $max) { return rand($min, $max); } }
##Unit Testing Your Generator
The simplest way to Unit test your Custom Generator would be to extend the GeneratorTest
class in Casus's Tests
directory. The CeneratorTest
class already extends the PHPUnit_Framework_TestCase
class so you don't have to.
You do have to implement the setUp()
though so that it sets the casus
property of the TestClass Object to an instance of your Generator Class.
Example:
<?php include_once __DIR__.'/../vendor/autoload.php'; include_once __DIR__.'/GeneratorTest.php'; class SuperGeneratorTest extends \GeneratorTest { public function setUp() { $this->casus = new \AwesomePerson\SuperGenerator(); } }
This will test all the standard methods that comes packaged with Casus. You could go ahead and add tests for your Special Methods.