Pattern interpreter for generating random strings.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
tests
.gitignore
.travis.yml
LICENSE
README.md
composer.json
phpunit.xml

README.md

Paggern

Build Status Coverage Status Latest Stable Version License

Pattern interpreter for generating random strings.

Generator

$generator = new \Gajus\Paggern\Generator();

/**
 * Generate a set of random codes based on Paggern pattern.
 * Codes are guaranteed to be unique within the set.
 *
 * @param string $pattern Paggern pattern.
 * @param int $amount Number of codes to generate.
 * @param int $safeguard Number of additional codes generated in case there are duplicates that need to be replaced.
 * @return array
 */
$codes = $generator->generateFromPattern('FOO[A-Z]{10}[0-9]{2}', 100);

The above example will generate an array containing 100 codes, each prefixed with "FOO", followed by 10 characters from "ABCDEFGHKMNOPRSTUVWXYZ23456789" haystack and 2 numbers from "0123456789" haystack.

Paggern utilises RandomLib to generate the pattern matching random character pool.

Lexer

Lexer exposes a method to tokenise the string. Lexer is independant of the Generator. You can choose to interpret Lexer tokens using your own implementation of the Generator.

$lexer = new \Gajus\Paggern\Lexer();

/**
 * Tokeniser explodes input into components describing the properties expressed in the pattern.
 *
 * @param string $pattern
 * @param boolean $expand Augment token definition with the haystack of possible values.
 * @return array
 */
$lexer->tokenise('[a-c]{3}[1-3]{3}', true);
[
    [
        'type' => 'range',
        'token' => 'a-c',
        'repetition' => 3,
        'haystack' => 'abc'
    ],
    [
        'type' => 'range',
        'token' => '1-3',
        'repetition' => 3,
        'haystack' => 123
    ]
]

Supported Tokens

Literal

Pattern can consist of literal characters, e.g. prefix of suffix of the code.

$lexer->tokenise('abc');
[
    [
        'type' => 'literal',
        'string' => 'abc'
    ]
]

The above pattern commands that the string is literally "abc".

Range

Range can be either numeric or ASCII.

$lexer->tokenise('[a-z]');

In the [a-z] example, string must be a character from "abcdefghijklmnopqrstuvwxyz" haystack.

[
    [
        'type' => 'range',
        'token' => 'a-z',
        'repetition' => 1
    ]
]

Range with Repetition

If the character must occur more than once, use repetition.

$lexer->tokenise('[a-c]{3}');

In the [a-z]{3} example, string must consist of 3 characters from the "abc" haystack.

[
    [
        'type' => 'range',
        'token' => 'a-c',
        'repetition' => 3
    ]
]

Character Classes

Predefined character classes can be used instead of ranges.

Character Class Range
\U "ABCDEFGHKMNOPRSTUVWXYZ23456789" (or A-Z0-9 excluding IJLQ01) describes characters that are unambiguously recognised regardless of the font or case-sensitivity. The designated use case is voucher codes.

Character Classes with Repetition

Similar to the Range with Repetition, Character Classes can be used with repetition, e.g.

$lexer->tokenise('\U{3}');

Limitations

  • Pattern cannot include []{} characters.
  • Pattern cannot include characters outside of the ASCII.