{"id":22725080,"url":"https://github.com/katmore/intl-rand-string","last_synced_at":"2025-03-29T23:22:33.577Z","repository":{"id":57004765,"uuid":"135636081","full_name":"katmore/intl-rand-string","owner":"katmore","description":"generate internationalized random alpha-numeric strings","archived":false,"fork":false,"pushed_at":"2018-06-12T05:22:44.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T00:44:16.694Z","etag":null,"topics":["character-encoding","coupon-code-generator","international","internationalization","password-generator","php","php-library","phpunit-tests","random-generation","random-string","random-string-generators","vanilla-php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/katmore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-31T21:15:42.000Z","updated_at":"2018-06-12T05:21:15.000Z","dependencies_parsed_at":"2022-08-21T12:40:37.121Z","dependency_job_id":null,"html_url":"https://github.com/katmore/intl-rand-string","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fintl-rand-string","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fintl-rand-string/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fintl-rand-string/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katmore%2Fintl-rand-string/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/katmore","download_url":"https://codeload.github.com/katmore/intl-rand-string/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246256093,"owners_count":20748190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["character-encoding","coupon-code-generator","international","internationalization","password-generator","php","php-library","phpunit-tests","random-generation","random-string","random-string-generators","vanilla-php"],"created_at":"2024-12-10T15:08:48.000Z","updated_at":"2025-03-29T23:22:33.555Z","avatar_url":"https://github.com/katmore.png","language":"PHP","readme":"# IntlRandString\ngenerate internationalized random alpha-numeric strings\n\n * [Usage in a PHP Project](#usage-in-a-php-project)\n * [Standalone Utility](#rand-string-standalone-installation)\n * [Development](#development)\n\n## About\nThe **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.\n\n## Usage in a PHP Project\nuse composer to add **IntlRandString** to your PHP project:\n```sh\ncomposer require katmore/intl-rand-string\n```\n\nA random string can be generated with the following character sets:\n * [Cyrillic](#cyrillic-charset)\n * [English](#english-charset)\n * [German](#german-charset)\n * [Italian](#italian-charset)\n * [Spanish](#spanish-charset)\n\n### Cyrillic Charset\nExample, using the **Cyrillic** Charset to generate a random string:\n```php\n$randString = new IntlRandString\\Charset\\Cyrillic();\necho $randString-\u003erandomString(12);\n```\nThe above example should output a random string that includes only cyrillic characters and latin digits, such as follows:\n```txt\nМхЫЖЬкхЛДхЦЗ\n```\n\n### English Charset\nExample, using the **English** Charset to generate a random string:\n```php\n$randString = new IntlRandString\\Charset\\English();\necho $randString-\u003erandomString(12);\n```\nThe above example should output a random string that includes only latin characters and latin digits as used in English, such as follows:\n```txt\nfMomhRErXWa8\n```\n\n### German Charset\nExample, using the **German** Charset to generate a random string:\n```php\n$randString = new IntlRandString\\Charset\\German();\necho $randString-\u003erandomString(12);\n```\nThe above example should output a random string that includes only latin characters and latin digits as used in German, such as follows:\n```txt\n0ZNuXÄGksyse\n```\n\n### Italian Charset\nExample, using the **Italian** Charset to generate a random string:\n```php\n$randString = new IntlRandString\\Charset\\Italian();\necho $randString-\u003erandomString(12);\n```\nThe above example should output a random string that includes only latin characters and latin digits as used in Italian, such as follows:\n```txt\nDMFPZNusSJTO\n```\n\n### Spanish Charset\nExample, using the **Spanish** Charset to generate a random string:\n```php\n$randString = new IntlRandString\\Charset\\Spanish();\necho $randString-\u003erandomString(12);\n```\nThe above example should output a random string that includes only latin characters and latin digits as used in Spanish, such as follows:\n```txt\nUí64DSYjWóQr\n```\n\n## Development\nThe following utility scripts facilitate development of character sets:\n * [make-charset.php](#make-charsetphp-dev-utility)\n * [make-all-charsets.sh](#make-all-charsetssh-dev-utility)\n \n### unit tests\nThe unit tests specified by [`phpunit.xml`](./phpunit.xml) check the basic sanity and entropy of generated random strings for each character set.\n```sh\n$ vendor/bin/phpunit\n```\n\n### make-charset.php dev utility\nThe **`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](#unit-tests) to ensure conformity.\n\nSpecifying the `--help` option will display usage details.\n```sh\n$ bin/devel/make-charset.php --help\n```\n\n### make-all-charsets.sh dev utility\nThe **`bin/devel/make-all-charsets.sh`** command-line developer utility script contains the Unicode start and end points for all [*Charset* class defintions](#character-sets). Invoking it will (re-)generate all [character set defintion source files](./src/IntlRandString/Charset). \n\n```sh\n$ bin/devel/make-all-charsets.sh\n```\n\nThe Unicode character ranges for the *Charsets* are ultimately defined in [bin/devel/make-all-charsets.sh](./bin/devel/make-all-charsets.sh#L52-L10000). Therefore, by modifying the [make-all-charsets.sh](./bin/devel/make-all-charsets.sh#L52-L10000) 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](#unit-tests) to ensure conformity.\n\nFor example, the [\"German\" character set](./src/IntlRandString/Charset/German.php) is defined in [*make-all-charsets.sh*](./bin/devel/make-all-charsets.sh#L82-L92) as follows:\n```sh\n#\n# German Charset\n#\nCHARSET_LETTERS=\nCHARSET_LETTERS=\"$CHARSET_LETTERS U+00E4 U+00E5 U+00F6 U+00F7 U+00FC U+00FD\" #diaresis a,o,u\nCHARSET_LETTERS=\"$CHARSET_LETTERS U+00C4 U+00C5 U+00D6 U+00D7 U+00DC U+00DD\" #diaresis A,O,U\nCHARSET_LETTERS=\"$CHARSET_LETTERS U+00DF U+00E0 U+1E9E U+1E9F\" #sharp s,S\nmake_charset german\\\n   $LATIN_NUMBERS\\\n   $BASIC_LATIN_LETTERS\\\n   $CHARSET_LETTERS\n```\n\n## rand-string utility\nA standalone utility is provided by the [`bin/rand-string.php`](./bin/rand-string.php) script. Details regarding the usage of this utility and instructions for an optional global installation are included in this section.\n\n### rand-string standalone installation\nThese installation instructions rely on the `make-phar.sh` installer script. See the [*make-phar.sh utility*](#make-pharsh-utility) section for more in-depth details and troubleshooting.\n\nInstallation instructions:\n * Download **intl-rand-string** project using git (or similar), and enter the project directory.\n   ```sh\n   $ git clone git@github.com:katmore/intl-rand-string.git\n   $ cd intl-rand-string\n   ```\n * Use the `bin/install/make-phar.sh` utility with the `--install` flag to create and install the phar package on your system.\n   ```sh\n   $ bin/install/make-phar.sh --install\n   ```\n\n### rand-string utility examples\nThe `rand-string` (or `bin/rand-string.php`) command line utility generates random strings.\n\nExample #1, using default charset and length.\n * the following command\n   ```sh\n   $ rand-string\n   ```\n * should produce output similar to the following\n   ```txt\n   195tTXDob0ol\n   ```\n\nThe first positional argument specifies the length of the random string.\n\nExample #2, using default charset and specifying length:\n * the following command\n   ```sh\n   $ rand-string 20\n   ```\n * should produce output similar to the following\n   ```txt\n   3QCBSV3YC3Dow62Jib5C\n   ```\n\nA charset may be specified for one-time use with the `--charset=\u003cCHARSET-NAME\u003e` flag.\n\nExample #3, using `cyrillic` charset:\n * the following command\n   ```sh\n   $ rand-string --charset=cyrillic\n   ```\n * should produce output similar to the following\n   ```txt\n   ЯИкМСзГД8уя9\n   ```\n\nThe `English` charset is the global default, though this may be changed [(see usage)](#rand-string-utility-usage).\n\nExample #3, setting the `german` as default:\n * the following command\n   ```sh\n   $ rand-string --set-default-charset=german\n   ```\n * should produce output similar to the following\n   ```txt\n   $ rand-string: default-charset is now 'german'\n   ```\n * subsequent executions should produce random strings using the `german` charset, the following command\n   ```sh\n   $ rand-string\n   ```\n * should produce output similar to the following\n   ```txt\n   öt7ß1vCQwtNE\n   ```\n\nAny Charset available in [`IntlRandString\\Charset`](./src/IntlRandString/Charset) may be used.\n\nExample #4, getting a list of available charsets:\n * the following command\n   ```sh\n   $ rand-string --list\n   ```\n * should produce output similar to the following\n   ```txt\n   Cyrillic\n   English\n   German\n   Italian\n   Spanish\n   ```\n * and thus, the following command\n   ```sh\n   $ rand-string --charset=Spanish\n   ```\n * should produce output similar to the following\n   ```txt\n   rñQ0m1úDkáMV\n   ```\n\n### rand-string utility usage\n```txt\nusage:\nrand-string [-hl|\u003csetting command\u003e] | [--charset=][\u003cchar flags...\u003e][\u003cLEN\u003e]\n\nmode flags:\n  -h,--help \n    Print a help message and exit.\n  -l,--list\n    Print each available charset and exit.\n\nsetting commands:\n  --set-default-charset=\u003cCHARSET-NAME\u003e\n    Set the default charset for the current user and exit.\n  --print-default-charset\n    Print the default charset for the current user and exit.\n\nrandom string options:\n  --charset=\u003cCHARSET-NAME\u003e\n    Optionally specify random string charset.\n\n  char flags:\n    --no-upper-letters\n      Random string will not include upper-case characters.\n    --no-lower-letters\n      Random string will not include lower-case letter characters.\n    --no-digits\n      Random string will not include digit numeral characters.\n    --only-upper-letters\n      Random string will only include upper-case characters.\n      Cannot be used with any other char flag.\n    --only-lower-letters\n      Random string will only include lower-case characters.\n      Cannot be used with any other char flag.\n    --only-digits\n      Random string will only include digit numerical characters.\n      Cannot be used with any other char flag.\n    \narguments:\n  \u003cLEN\u003e\n    Optionally specify random string length.\n    Default: 12\n```\n\n### make-phar.sh utility\nThe [`bin/install/make-phar.sh`](./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.\n\n**Prerequisites**\n * composer\n * php command line binary\n\n**Usage**\n```txt\nmake-phar.sh [-h] | [--install [--install-path=\u003cPATH\u003e]] [\u003cbin path options\u003e]\noptions:\n  -h,--help: Print a help message and exit.\n  --install: Optionally install as a global system command.\n  --install-path=\u003cPATH\u003e\n    Optionally specify global system command installation path.\n    Default: /usr/local/bin/rand-string\n\nbin path options:\n  --composer-bin=\u003cCOMPOSER-PATH\u003e\n    Optionally specify path to composer.\n  --php-bin=\u003cPHP-PATH\u003e\n    Optionally specify path to php binary.\n```\n\n\n## Legal\n### Copyright\nIntlRandString - https://github.com/katmore/intl-rand-string\n\nCopyright (c) 2012-2018 Doug Bird. All Rights Reserved.\n\n### License\nIntlRandString is copyrighted free software.\nYou may redistribute and modify it under either the terms and conditions of the\n\"The MIT License (MIT)\"; or the terms and conditions of the \"GPL v3 License\".\nSee [LICENSE](https://github.com/katmore/intl-rand-string/blob/master/LICENSE) and [GPLv3](https://github.com/katmore/intl-rand-string/blob/master/GPLv3).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatmore%2Fintl-rand-string","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatmore%2Fintl-rand-string","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatmore%2Fintl-rand-string/lists"}