katmore/intl-rand-string

generate internationalized random alpha-numeric strings

IntlRandString

generate internationalized random alpha-numeric strings, _(*1)

• Usage in a PHP Project
• Standalone Utility
• Development

About

The IntlRandString package facilitates generating random strings in multiple internationalized character sets. A typical use-case is generating random passwords in a targeted "language", i.e. using characters familiar to a language rather than simply using only english latin characters, as is typical. For similar reasons, it could also prove ideal in other use-cases, such as: password reset validation codes, coupon or promotional codes, etc., _(*2)

Usage in a PHP Project

use composer to add IntlRandString to your PHP project:, _(*3)

composer require katmore/intl-rand-string

A random string can be generated with the following character sets: * Cyrillic * English * German * Italian * Spanish, _(*4)

Cyrillic Charset

Example, using the Cyrillic Charset to generate a random string:, _(*5)

$randString = new IntlRandString\Charset\Cyrillic();
echo $randString->randomString(12);

The above example should output a random string that includes only cyrillic characters and latin digits, such as follows:, _(*6)

МхЫЖЬкхЛДхЦЗ

English Charset

Example, using the English Charset to generate a random string:, _(*7)

$randString = new IntlRandString\Charset\English();
echo $randString->randomString(12);

The above example should output a random string that includes only latin characters and latin digits as used in English, such as follows:, _(*8)

fMomhRErXWa8

German Charset

Example, using the German Charset to generate a random string:, _(*9)

$randString = new IntlRandString\Charset\German();
echo $randString->randomString(12);

The above example should output a random string that includes only latin characters and latin digits as used in German, such as follows:, _(*10)

0ZNuXÄGksyse

Italian Charset

Example, using the Italian Charset to generate a random string:, _(*11)

$randString = new IntlRandString\Charset\Italian();
echo $randString->randomString(12);

The above example should output a random string that includes only latin characters and latin digits as used in Italian, such as follows:, _(*12)

DMFPZNusSJTO

Spanish Charset

Example, using the Spanish Charset to generate a random string:, _(*13)

$randString = new IntlRandString\Charset\Spanish();
echo $randString->randomString(12);

The above example should output a random string that includes only latin characters and latin digits as used in Spanish, such as follows:, _(*14)

Uí64DSYjWóQr

Development

The following utility scripts facilitate development of character sets: * make-charset.php * make-all-charsets.sh, _(*15)

unit tests

The unit tests specified by phpunit.xml check the basic sanity and entropy of generated random strings for each character set., _(*16)

$ vendor/bin/phpunit

make-charset.php dev utility

The bin/devel/make-charset.php command-line developer utility script creates a character set class defintion PHP source file in the src/IntlRandString/Charset directory. After creating a character set, perform all unit tests to ensure conformity., _(*17)

Specifying the --help option will display usage details., _(*18)

$ bin/devel/make-charset.php --help

make-all-charsets.sh dev utility

The bin/devel/make-all-charsets.sh command-line developer utility script contains the Unicode start and end points for all Charset class defintions. Invoking it will (re-)generate all character set defintion source files., _(*19)

$ bin/devel/make-all-charsets.sh

The Unicode character ranges for the Charsets are ultimately defined in bin/devel/make-all-charsets.sh. Therefore, by modifying the make-all-charsets.sh source file, character sets can be permanently added or modified. After modifying the source and invoking to (re-)generate character sets, perform all unit tests to ensure conformity., _(*20)

For example, the "German" character set is defined in make-all-charsets.sh as follows:, _(*21)

#
# German Charset
#
CHARSET_LETTERS=
CHARSET_LETTERS="$CHARSET_LETTERS U+00E4 U+00E5 U+00F6 U+00F7 U+00FC U+00FD" #diaresis a,o,u
CHARSET_LETTERS="$CHARSET_LETTERS U+00C4 U+00C5 U+00D6 U+00D7 U+00DC U+00DD" #diaresis A,O,U
CHARSET_LETTERS="$CHARSET_LETTERS U+00DF U+00E0 U+1E9E U+1E9F" #sharp s,S
make_charset german\
   $LATIN_NUMBERS\
   $BASIC_LATIN_LETTERS\
   $CHARSET_LETTERS

rand-string utility

A standalone utility is provided by the bin/rand-string.php script. Details regarding the usage of this utility and instructions for an optional global installation are included in this section., _(*22)

rand-string standalone installation

These installation instructions rely on the make-phar.sh installer script. See the make-phar.sh utility section for more in-depth details and troubleshooting., _(*23)

Installation instructions: * Download intl-rand-string project using git (or similar), and enter the project directory. sh $ git clone git@github.com:katmore/intl-rand-string.git $ cd intl-rand-string * Use the bin/install/make-phar.sh utility with the --install flag to create and install the phar package on your system. sh $ bin/install/make-phar.sh --install, _(*24)

rand-string utility examples

The rand-string (or bin/rand-string.php) command line utility generates random strings., _(*25)

Example #1, using default charset and length. * the following command sh $ rand-string * should produce output similar to the following txt 195tTXDob0ol, _(*26)

The first positional argument specifies the length of the random string., _(*27)

Example #2, using default charset and specifying length: * the following command sh $ rand-string 20 * should produce output similar to the following txt 3QCBSV3YC3Dow62Jib5C, _(*28)

A charset may be specified for one-time use with the --charset=<CHARSET-NAME> flag., _(*29)

Example #3, using cyrillic charset: * the following command sh $ rand-string --charset=cyrillic * should produce output similar to the following txt ЯИкМСзГД8уя9, _(*30)

The English charset is the global default, though this may be changed (see usage)., _(*31)

Example #3, setting the german as default: * the following command sh $ rand-string --set-default-charset=german * should produce output similar to the following txt $ rand-string: default-charset is now 'german' * subsequent executions should produce random strings using the german charset, the following command sh $ rand-string * should produce output similar to the following txt öt7ß1vCQwtNE, _(*32)

Any Charset available in IntlRandString\Charset may be used., _(*33)

Example #4, getting a list of available charsets: * the following command sh $ rand-string --list * should produce output similar to the following txt Cyrillic English German Italian Spanish * and thus, the following command sh $ rand-string --charset=Spanish * should produce output similar to the following txt rñQ0m1úDkáMV, _(*34)

rand-string utility usage

usage:
rand-string [-hl|<setting command>] | [--charset=][<char flags...>][<LEN>]

mode flags:
  -h,--help 
    Print a help message and exit.
  -l,--list
    Print each available charset and exit.

setting commands:
  --set-default-charset=<CHARSET-NAME>
    Set the default charset for the current user and exit.
  --print-default-charset
    Print the default charset for the current user and exit.

random string options:
  --charset=<CHARSET-NAME>
    Optionally specify random string charset.

  char flags:
    --no-upper-letters
      Random string will not include upper-case characters.
    --no-lower-letters
      Random string will not include lower-case letter characters.
    --no-digits
      Random string will not include digit numeral characters.
    --only-upper-letters
      Random string will only include upper-case characters.
      Cannot be used with any other char flag.
    --only-lower-letters
      Random string will only include lower-case characters.
      Cannot be used with any other char flag.
    --only-digits
      Random string will only include digit numerical characters.
      Cannot be used with any other char flag.

arguments:
  <LEN>
    Optionally specify random string length.
    Default: 12

make-phar.sh utility

The bin/install/make-phar.sh utility creates a standalone rand-string.phar phar package file using bin/rand-string.php as the entrypoint. Optionally, it will copy the phar package file to an installation path., _(*35)

Prerequisites * composer * php command line binary, _(*36)

Usage, _(*37)

make-phar.sh [-h] | [--install [--install-path=<PATH>]] [<bin path options>]
options:
  -h,--help: Print a help message and exit.
  --install: Optionally install as a global system command.
  --install-path=<PATH>
    Optionally specify global system command installation path.
    Default: /usr/local/bin/rand-string

bin path options:
  --composer-bin=<COMPOSER-PATH>
    Optionally specify path to composer.
  --php-bin=<PHP-PATH>
    Optionally specify path to php binary.

Legal

Copyright

IntlRandString - https://github.com/katmore/intl-rand-string, _(*38)

Copyright (c) 2012-2018 Doug Bird. All Rights Reserved., _(*39)

License

IntlRandString is copyrighted free software. You may redistribute and modify it under either the terms and conditions of the "The MIT License (MIT)"; or the terms and conditions of the "GPL v3 License". See LICENSE and GPLv3., _(*40)