README

A PHP library that uses cryptographically-secure randomization to generate a password of a given length from given sets of characters.

Installation

With Composer installed on your computer and initialized for your project, run this command in your project’s root directory:

composer require lamansky/random-password

Requires PHP 7.1 or above.

Examples

<?php
use Lamansky\RandomPassword\RandomPasswordFactory;

// The alpha() static method returns a factory that will generate passwords
// which alternate between uppercase and lowercase characters.
$rpf = RandomPasswordFactory::alpha();
echo $rpf->generate(8);  // sJtNbZtA
echo $rpf->generate(10); // UcBkCwHdYm

// A numeric() factory uses only numbers.
echo RandomPasswordFactory::numeric()->generate(8); // 54088998

// An alphanumeric() factory rotates between lowercase letters, uppercase
// letters, and numbers.
echo RandomPasswordFactory::alphanumeric()->generate(10); // r9Tj4Nw5Qn

// If you want a truly random alphanumeric password, without rotation between
// character sets, you can instead construct your own factory with a `uln`
// configuration string. Because passwords generated from such a factory
// are more random, they will, ironically, sometimes look *less* random, since
// such passwords could theoretically spell a word, or consist solely of
// uppercase letters, for example.
echo (new RandomPasswordFactory('uln'))->generate(10); // fWQeV8WBNn

// A loweralphanumeric() factory is like alphanumeric() but without uppercase letters.
echo RandomPasswordFactory::loweralphanumeric()->generate(8); // p7h2q4e2

// An ascii() factory rotates between lowercase, uppercase, numbers, and symbols.
$rpf = RandomPasswordFactory::ascii();
$rpf->generate(12); // 7R_y5M#f8E@t
$rpf->generate(12); // ^fU2!zH9#bR3

// A custom() factory will use only the characters you specify.
echo RandomPasswordFactory::custom('abc')->generate(12); // cbbcaccaabab

API

The library consists of a single class: Lamansky\RandomPassword\RandomPasswordFactory.

Constructor Parameters

1. Optional: $set_codes (string or null): A configuration string indicating the character sets that should be used in generating the random password. If this is set to null, the default of u l n (equivalent to the configuration of the static alphanumeric() method) will be used.
2. Optional: $custom_set (string): A set of characters to be used if $set_codes includes c.

Set Codes

The $set_codes string is used to specify which characters should be used in generating random passwords. The available character sets are:

Passwords will be generated by rotating between different space-separated groups in your configuration string. Here are some sample values for $set_codes with corresponding behavior:

Static Factory Methods

The RandomPasswordFactory class has various static factory methods, each of which serves as a shortcut for constructing a factory using a preconfigured value for $set_codes.

The generate() Method

Parameters

1. $length (int): The number of characters in the password to be generated. For security reasons, it is strongly recommended that this be set to 12 or higher.
2. Optional: $set_codes (string or null): If set, overrides the global $set_codes value set in the constructor.
3. Optional: $custom_set (string): If set, overrides the global $custom_set value set in the constructor.

Return Value

Returns a random password as a string.

Unit Tests

To run the development test suite, execute this command:

./vendor/phpunit/phpunit/phpunit tests