hedronium/casus

A Library to Generate anything Random.

v1.1 2015-10-10 11:39 UTC

Requires

• php: >=5.4.0
• ext-mcrypt: *

Requires (Dev)

• phpunit/phpunit: ~4.4

MIT

• Omran Jamal

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.