Random character sequence generator

RandomCharacterSequenceGenerator.class.php

<?php

/**
 * Generate a random sequence of characters. Result is not guaranteed to contain one character of every option.
 *
 * <code>
 * require_once 'RandomCharacterSequenceGenerator.class.php';
 *
 * $generator = new RandomCharacterSequenceGenerator(array('avoid_confusion' => false));
 * echo $generator->execute();
 *
 * $generator->configure(array('other_chars' => ';:<>'));
 * echo $generator->execute();
 * </code>
 */
class RandomCharacterSequenceGenerator
{
    /**
     * Store the configuration of this instance
     *
     * @var array $options
     */
    private $options;

    /**
     * @param array $options An array of options used to configure this instance
     */
    public function __construct(array $options = null)
    {
        $this->options = $this->getDefaultOptions();

        if (null !== $options) {
            $this->configure($options);
        }
    }

    /**
     * Return an array of sane defaults for any instance
     *
     * @return array $options
     */
    protected function getDefaultOptions()
    {
        return array(
            'length' => 8,
            'include_letters' => true,
            'include_vowels' => false,
            'include_consonants' => true,
            'include_upper' => true,
            'include_lower' => false,
            'include_numbers' => true,
            'other_chars' => '',
            'avoid_confusion' => true
        );
    }

    /**
     * Configure how this instance behaves.
     *
     * Available options:
     *
     *  * length:             integer   The length of the generated sequence. Default: 8
     *  * include_letters:    boolean   Whether or not to include alpha characters in the result. Default: true
     *  * include_vowels:     boolean   If include_letters is true, also include vowels in the result. Default: false
     *  * include_consonants: boolean   If include_letters is true, also include consonants in the result. Default: true
     *  * include_upper:      boolean   If include_letters is true, also include upper case letters in the result. Default: true
     *  * include_lower:      boolean   If include_letters is true, also include lower case letters in the result. Default: false
     *  * include_numbers:    boolean   Whether or not to include numeric characters in the result. Default: true
     *  * other_chars:        string    A string containing other characters to be potentially included in the generated sequence.
     *  * avoid_confusion:    boolean   Omit chars which could easily be mistaken for others. E.g. 0 and o, 1 and l. Default: true
     *
     * @param array $options An array of options to set on this instance.
     */
    public function configure(array $options)
    {
        $this->options = array_merge($this->options, $options);
    }

    /**
     * Return the value of an option.
     *
     * @param string $option The name of the option to retrieve.
     * @return mixed The value of the option
     */
    protected function getOption($option)
    {
        return isset($this->options[$option]) ? $this->options[$option] : null;
    }

    /**
     * Generate a sequence of characters from which the randomly generated sequence will draw from.
     *
     * @return string
     */
    protected function generatePoolFromOptions()
    {
        $pool = '';

        $includeLetters = $this->getOption('include_letters');
        $includeVowels = $this->getOption('include_vowels');
        $includeConsonants = $this->getOption('include_consonants');
        $includeNumbers = $this->getOption('include_numbers');
        $otherchars = $this->getOption('other_chars');

        $includeUpper = $this->getOption('include_upper');
        $includeLower = $this->getOption('include_lower');
        $avoidConfusion = $this->getOption('avoid_confusion');

        if ($includeLetters) {
            if ($includeVowels) {
                if ($includeUpper) {
                    $pool .= 'AEU';
                    if (!$avoidConfusion) $pool .= 'IO';
                }

                if ($includeLower) {
                    $pool .= 'aeu';
                    if (!$avoidConfusion) $pool .= 'io';
                }
            }

            if ($includeConsonants) {
                if ($includeUpper) {
                    $pool .= 'BCDFGHJKLMNPQRTVWXY';
                    if (!$avoidConfusion) $pool .= 'SZ';
                }

                if ($includeLower) {
                    $pool .= 'bcdfghjkmnpqrtvwxy';
                    if (!$avoidConfusion) $pool .= 'lsz';
                }
            }
        }

        if ($includeNumbers) {
            $pool .= '3456789';
            if (!$avoidConfusion) $pool .= '012';
        }

        $pool .= $otherchars;

        return $pool;
    }

    /**
     * Generate a random sequence of characters based on this instance's configuration.
     *
     * @return string
     */
    public function execute()
    {
        $length = $this->getOption('length');

        $pool = str_split($this->generatePoolFromOptions());

        if (0 === count($pool)) throw new Exception('Could not generate random string from empty pool.');

        $string = '';

        do {
            $string .= $pool[array_rand($pool)];
        } while(strlen($string) < $length);

        return $string;
    }
}