Home/ Manual/ random / functions/ random_bytes

random_bytes

PHP function Edit on GitHub ✎

(PHP 7, PHP 8)

Get cryptographically secure random bytes

Description

random_bytes(int $length): string

Generates a string containing uniformly selected random bytes with the requested length.

As the returned bytes are selected completely randomly, the resulting string is likely to contain unprintable characters or invalid UTF-8 sequences. It may be necessary to encode it before transmission or display.

The randomness generated by this function is suitable for all applications, including the generation of long-term secrets, such as encryption keys.

Sources Backport

Parameters

length: The length of the random string that should be returned in bytes; must be 1 or greater.

Return Values

A string containing the requested number of cryptographically secure random bytes.

Errors/Exceptions

If the value of length is less than 1, a ValueError will be thrown.

Changelog

Version	Description
8.2.0	In case of a CSPRNG failure, this function will now throw a `Random\RandomException`. Previously a plain `Exception` was thrown.

Examples

random_bytes() example

php

<?php
$bytes = random_bytes(5);
var_dump(bin2hex($bytes));
?>

The above example will output something similar to:

output

string(10) "385e33f741"