Skip to content

Documentation

Jump to bottom
Glad Chinda edited this page Jan 26, 2017 · 4 revisions

Abstract Generators

The AbstractGenerator class is the base generator class implemented by all generators, including the Keygen class. The AbstractGenerator class uses the KeyManipulation, MutableGenerator and GeneratorMutation traits to provide access to convenient properties and methods.

Generator Mutation

The properties of an AbstractGenerator instance can be mutated due to changes in the same properties of another instance. This behaviour is provided by the MutableGenerator and GeneratorMutation traits. The following are the only properties that can be mutated:

  • length
  • prefix
  • suffix

At the instantiation of an AbstractGenerator, all the properties are immutable. Two methods namely: mutable() and immutable() are available for controlling the mutable properties. Each method takes one or more properties as arguments. Properties passed to the mutable() method will change due to changes in the same properties of the AbstractGenerator instance the calling generator is linked to while those passed to the immutable() method will not be changed.

The property changes are not automatic. The AbstractGenerator instance must be linked to another instance to watch changes from that instance. Two methods namely: mutate() and dontMutate() are provided for controlling linked instances. Each method takes one or more AbstractGenerator instances as arguments. The mutate() method whitelists instances to watch changes while the dontMutate() method blacklists instances.

The methods: numeric(), alphanum(), bytes() and token() of the Keygen class return an AbstractGenerator instance when called. They also internally link the calling Keygen instance to the returned AbstractGenerator instance. Hence, the mutable properties of the calling Keygen instance change when there is a corresponding change of those properties in the returned AbstractGenerator instance.

// Mutable Properties: length, prefix
$keygen = Keygen::length(10)->mutable('length', 'prefix');
var_dump($keygen->mutables);

// Inherits $keygen length => 10
echo $keygen->numeric()->generate(); // e.g 6433786212

// Inherits $keygen length => 10
// Prevents prefix from propagating to linked instances (false)
echo $keygen->numeric()->prefix('ID-', false)->generate(); // e.g ID-2107150

// Remove length property from mutables
// Hence $keygen length still => 10
// Prefix propagates to linked instances (default: true)
echo $keygen->immutable('length')->numeric(15)->prefix('TM-')->generate(); // e.g TM-189039552479

// Length property not mutated
// Hence $keygen length still => 10
// Previous prefix still in use
echo $keygen->alphanum()->generate('strtoupper'); // e.g TM-3X5T80V

AbstractGenerator Properties

length
The value of the length property is the specified or inherited length of keys to be generated by this generator. It always returns an integer and defaults to 16 for fresh instances without length specification.

prefix
The value of the prefix property is the string to be affixed at the beginning of keys generated by this generator. It returns null if no prefix has been specified.

suffix
The value of the suffix property is the string to be affixed at the end of keys generated by this generator. It returns null if no suffix has been specified.

mutables
The mutables property is an array of the specified mutable properties that can change their values due to changes in the values of the same properties in another configured AbstractGenerator instance.

mutates
The mutates property is an array of AbstractGenerator instances that are linked to this generator to inherit the property changes from it.

AbstractGenerator Methods

length ( int $length , bool $propagateMutation = true )

The length() method sets the key length property of the generator. If the $length parameter is missing or not a number, then the length property remains unchanged. The $propagateMutation parameter is a boolean that indicates if change in the length property should be inherited by generators in the mutates collection of this generator. It defaults to true.

prefix ( string $prefix , bool $propagateMutation = true )

The prefix() method sets the prefix of the generator. If the $prefix string is empty, it clears any existing prefix on the generator. The $propagateMutation parameter is a boolean that indicates if change in the prefix property should be inherited by generators in the mutates collection of this generator. It defaults to true.

suffix ( string $suffix , bool $propagateMutation = true )

The suffix() method sets the suffix of the generator. If the $suffix string is empty, it clears any existing suffix on the generator. The $propagateMutation parameter is a boolean that indicates if change in the suffix property should be inherited by generators in the mutates collection of this generator. It defaults to true.

mutable ( string $prop [...] )

The mutable() method whitelists one or more mutable properties of the generator. It takes one or more AbstractGenerator properties as arguments. Properties passed to the mutable() method will change due to changes in the same properties of the AbstractGenerator instance this generator is linked to.

immutable ( string $prop [...] )

The immutable() method blacklists one or more mutable properties of the generator. It takes one or more AbstractGenerator properties as arguments. Properties passed to the immutable() method will never inherit changes.

mutate ( AbstractGenerator $generator [...] )

The mutate() method whitelists one or more AbstractGenerator instances, passed as arguments to it, to be linked to the generator. AbstractGenerator instances passed to the mutate() method will watch for and inherit property changes from this generator.

dontMutate ( AbstractGenerator $generator [...] )

The dontMutate() method blacklists one or more AbstractGenerator instances, passed as arguments to it, from watching for and inheriting property changes from this generator.

Generators

A Generator is an extension of the AbstractGenerator and thus inherits the properties and methods of the AbstractGenerator class. It implements the GeneratorInterface and must define the keygen() method which provides the key generation algorithm. The GeneratorInterface also requires that a generate() method be defined, which actually runs the key generation routine.

The Keygen package ships with four built-in Generators and provides four methods on the Keygen class to expose these generators namely: numeric(), alphanum(), bytes(), token(). Each of these methods takes an optional length parameter which specifies the key length; and returns an instance of the corresponding Generator. If the length parameter is omitted, it defaults to the key length of the calling Keygen instance.

// Create Keygen instance
$keygen = new Keygen;
echo $keygen->length; // 16

// returns Keygen\Generators\NumericGenerator
// inherits length from $keygen
$numeric = $keygen->numeric();
echo $numeric->length; // 16

// returns Keygen\Generators\AlphaNumericGenerator
$alphanum = $keygen->alphanum(12);
echo $alphanum->length; // 12

// returns Keygen\Generators\RandomByteGenerator
// inherits length from $keygen
$bytes = $keygen->bytes();
echo $bytes->length; // 16

// returns Keygen\Generators\TokenGenerator
$token = $keygen->token(24);
echo $token->length; // 24

Generator Methods

The Generator class extends the AbstractGenerator and thus inherits the properties and methods of the AbstractGenerator class.

Inherited Methods

  • length()
  • prefix()
  • suffix()
  • mutable()
  • immutable()
  • mutate()
  • dontMutate()

hex ( )

The hex() method only applies to the RandomByteGenerator. It returns the generated random bytes as hexadecimal using the generator key length. It should be called before the generate() method of the generator - that actually generates the keys.

// As Binary
echo Keygen::bytes()->generate(); // e.g ���E���)�B�%^$^

// As Hexadecimal
echo Keygen::bytes(20)->hex()->generate(); // e.g 8cd681c009e97ad2550a

generate ( [ bool $inclusiveDisabled = false , ] [ callable $transformation [...] ] )

The generate() method returns the generated key. When affixes (prefix and/or suffix) are specified in a generator, the length of the generated key includes the string length of the affixes (inclusive affixes). The generate() method can take an optional boolean first parameter which enables/disables inclusive affixes behaviour for generators that have affixes.

One or more transformations can be applied on keys before they are generated. A transformation is simply a callable that can take the generated key as the first argument and returns a string. One or more transformations can be applied by passing them as arguments to the generate() method. If the key contains one or more affixes, the optional boolean first parameter of the generate() method may still be specified before specifying the transformations.

The Keygen Class

The Keygen class is an extension of the AbstractGenerator and thus inherits the properties and methods of the AbstractGenerator class. It is built to provide a simple and expressive interface for flexible key generation. It supports method chaining, making it possible to write compact implementation codes.

The Keygen class acts as a facade to expose the four built-in Generators via four convenience methods namely: numeric(), alphanum(), bytes() and token(). Each of these methods takes an optional $length parameter which specifies the key length; and returns an instance of the corresponding Generator. If the $length parameter is omitted, it defaults to the key length of the calling Keygen instance.

Creating an instance

An instance can be created using the new construct. The constructor of the Keygen class takes an optional $length parameter which specifies the length of keys that can be generated from the given instance. If the $length parameter is omitted, it defaults to 16.

All the methods of the Keygen class (both own and inherited methods) can also be called statically. Calling any of these methods statically returns a new instance of the Keygen class.

// Using Constructor
// Key length defaults to 16
$instance1 = new Keygen;

// Static call
// Equivalent to: $instance2 = new Keygen(10);
$instance2 = Keygen::length(10);

Keygen Methods

The Keygen class extends the AbstractGenerator and thus inherits the properties and methods of the AbstractGenerator class.

Inherited Methods

  • length()
  • prefix()
  • suffix()
  • mutable()
  • immutable()
  • mutate()
  • dontMutate()

The following are own methods of the Keygen class. Each takes a $length parameter as the only argument and returns a built-in Generator instance. The $length parameter is an integer that specifies the length property for the returned generator. If the $length parameter is missing or is not an integer, the length is inherited from the length property of the Keygen generator.

numeric ( int $length )

The numeric() method returns an instance of the built-in NumericGenerator which generates keys containing only digit characters.

alphanum ( int $length )

The alphanum() method returns an instance of the built-in AlphaNumericGenerator which generates keys containing both alphabetic and digit characters.

bytes ( int $length )

The bytes() method returns an instance of the built-in RandomByteGenerator which generates sequences of random bytes in binary form. The hex() method of the RandomByteGenerator can be called before the generate() method to return the bytes in hexadecimal form and of the same key length.

token ( int $length )

The token() method returns an instance of the built-in TokenGenerator which generates base64-encoded tokens.

Clone this wiki locally