Download the PHP package meshachviktor/secure-random without Composer
On this page you can find all versions of the php package meshachviktor/secure-random. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package secure-random
This library was originally built with resources from Arteri Africa.
Introduction
SecureRandom is a library designed for generating random values. With SecureRandom you can generate the following types of values:
- Raw bytes
- Floating point numbers
- Integers
- Hexadecimal strings
- Alphanumeric strings (mixed case)
- Universally Unique Identifiers (Version 4)
All values generated by SecureRandom come from cryptographically secure sources. Integers and Floating point numbers generated by SecureRandom are sourced from PHP's random_int()
function. All other types are sourced from the random_bytes()
function. These functions, according to the PHP documentation, are suitable for cryptographic use as the values they produce are from a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG). The randomness of the values generated by these functions consequentially applies to the values generated by SecureRandom.
SecureRandom is useful for generating the following:
- One-Time passwords
- Temporary/default passwords
- Two-Factor Authentication (2FA) codes
- API keys
- Password salts
- File names
The list above is not exhaustive. You can use SecureRandom for a lot more.
Usage
To use SecureRandom add the dependency to your project using the following composer command.
Then import the library to your project as shown below.
Generating random bytes
You can generate random bytes using the library by calling the bytes()
method.
SecureRandom::bytes(int $length) :string
This method takes an optional integer argument named $length
. By default $length
has a value of 64 but can be any number between the range of 1 and 64 (inclusive). Supplying a value less than 1 or greater than 64 will result in the method throwing \RangeException
. The bytes()
method is limited to returning a maximum of 64 bytes due to a lot of reasons. If you need more than 64 bytes use PHP's built in random_bytes()
instead.
Examples
Generating random floats
The library provides some methods for generating random floating point numbers. The fractional part of all floating point numbers generated are limited to a maximum of 14 decimal digits. All numbers returned by these methods are less than 1. Negative values are in the range of -0.99999999999999 to -0.1 while positive values are in the range of 0.1 to 0.99999999999999.
SecureRandom::float(int $fractional_digits = 14) :float
The float()
method returns a random positive or negative floating point number. The method takes an optional integer argument, $fractional_digits
, whose value defaults to 14. The value of $fractional_digits
determines how many decimal digits will appear after the decimal point of the floating point number generated. Supplying a value less than 1 or greater than 14 causes the method to throw \RangeException
.
Examples
SecureRandom::positiveFloat(int $fractional_digits = 14) :float
The positiveFloat()
method returns a random positive floating point number. The method takes an optional integer argument, $fractional_digits
, whose value defaults to 14. The value of $fractional_digits
determines how many decimal digits will appear after the decimal point of the floating point number generated. Supplying a value less than 1 or greater than 14 causes the method to throw \RangeException
.
Examples
SecureRandom::negativeFloat(int $fractional_digits = 14) :float
The negativeFloat()
method returns a random negative floating point number. The method takes an optional integer argument, $fractional_digits
, whose value defaults to 14. The value of $fractional_digits
determines how many decimal digits will appear after the decimal point of the floating point number generated. Supplying a value less than 1 or greater than 14 causes the method to throw \RangeException
.
Examples
SecureRandom::floatBetween(float $min, float $max) :float
The floatBetween()
method takes two float arguments $min
and $max
and returns a floating point number between the range of $min and $max (inclusive). The method accepts only positive float values and as a results only returns positive values. The method will throw \RangeException
if the value of $min or $max is outside of the range 0.1 and 0.99999999999999. The method will also throw Meshachviktor\SecureRandom\Exception\ValueException
if the value of $min
is greater than the value of $max
.
Examples
Important note
Due to the effect of rounding, the fractional parts of values returned by methods that generate floats will sometimes be one less than the value of $fractional_digits
.
Generating random integers
The library provides some functions for generating random integers. Values returned by these functions are between PHP_INT_MIN
and PHP_INT_MAX
(inclusive).
SecureRandom::integer() :int
The integer()
method takes no argument and returns a value between PHP_INT_MIN
and PHP_INT_MAX
.
Examples
SecureRandom::positiveInteger(int $length = 19) :int
The positiveInteger()
method returns a random positive integer. The method takes an integer argument, $length
, whose value defaults to 19. Supplying a value less than 1 or greater than 19 causes the method to throw \RangeException
. The method returns an integer whose total number of digits equals the value of $length
.
Examples
SecureRandom::negativeInteger(int $length = 19) :int
The negativeInteger()
method returns a random negative integer. The method takes an integer argument, $length
, whose value defaults to 19. Supplying a value less than 1 or greater than 19 causes the method to throw \RangeException
. The method returns a negative integer whose total number of digits equals the value of $length
.
Examples
SecureRandom::integerBetween(int $min, int $max) :int
The integerBetween()
method takes two integer arguments $min
and $max
and returns an integer between the range of $min
and $max
(inclusive). The method will throw Meshachviktor\SecureRandom\Exception\ValueException
if the value of $min
is greater than the value of $max
.
Examples
Generating random strings
The library provides some functions for generating random strings. There are three types of strings that can be generated.
- Hexadecimal strings.
- Mixed case alphanumeric strings
- Version 4 UUIDs
When generating hexadecimal strings and alphanumric strings the corresponding methods take a single integer argument, $length
, which determines how long the generated string should be. The value of $lenth
defaults to 64. \RangeException
is thrown is the value of $length
is less than 1 or if it is greater than 64.
The method that generates UUIDs takes no argument.
SecureRandom::hexadecimalString(int $length = 64) :string
Generates a hexadecimal string of given length.
Examples
SecureRandom::alphanumericString(int $length = 64) :string
Generates an alphanumeric string of given length.
Examples
SecureRandom::uuid() : string
Generates version 4 UUIDs.
Examples
License
MIT