mirror of
https://github.com/php/doc-en.git
synced 2026-03-27 01:02:08 +01:00
215fd48515
* random: Unify the short description for random_(bytes|int) with Randomizer * random: Use imperative mood for short descriptions of engine methods This is for consistency. The PHP manual appears to use imperative mood for the majority of functions and all of Randomizer’s functions already too. * random: Shorten the short description for random_int and Randomizer::getInt()
134 lines
3.4 KiB
XML
134 lines
3.4 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id="function.random-bytes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>random_bytes</refname>
|
|
<refpurpose>Get cryptographically secure random bytes</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description"><!-- {{{ -->
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>random_bytes</methodname>
|
|
<methodparam><type>int</type><parameter>length</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Generates an arbitrary length string of cryptographic random bytes that are
|
|
suitable for cryptographic use, such as when generating salts, keys or
|
|
initialization vectors.
|
|
</para>
|
|
&csprng.sources;
|
|
&csprng.function.backport;
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="parameters"><!-- {{{ -->
|
|
&reftitle.parameters;
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>length</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The length of the random string that should be returned in bytes; must be <literal>1</literal> or greater.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="returnvalues"><!-- {{{ -->
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
A string containing the requested number of cryptographically
|
|
secure random bytes.
|
|
</para>
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="errors"><!-- {{{ -->
|
|
&reftitle.errors;
|
|
<itemizedlist>
|
|
&csprng.errors;
|
|
<listitem>
|
|
<simpara>
|
|
If the value of <parameter>length</parameter> is less than <literal>1</literal>,
|
|
a <classname>ValueError</classname> will be thrown.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>8.2.0</entry>
|
|
<entry>
|
|
In case of a <acronym>CSPRNG</acronym> failure, this function will now throw a
|
|
<classname>Random\RandomException</classname>. Previously a plain
|
|
<classname>Exception</classname> was thrown.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples"><!-- {{{ -->
|
|
&reftitle.examples;
|
|
<example xml:id="random-bytes.example.basic"><!-- {{{ -->
|
|
<title><function>random_bytes</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$bytes = random_bytes(5);
|
|
var_dump(bin2hex($bytes));
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
string(10) "385e33f741"
|
|
]]>
|
|
</screen>
|
|
</example><!-- }}} -->
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="seealso"><!-- {{{ -->
|
|
&reftitle.seealso;
|
|
<simplelist>
|
|
<member><function>Random\Randomizer::getBytes</function></member>
|
|
<member><function>random_int</function></member>
|
|
<member><function>bin2hex</function></member>
|
|
</simplelist>
|
|
</refsect1><!-- }}} -->
|
|
|
|
</refentry>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|