<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Pick one or more random keys out of an array</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.array-push.html">array_push</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.array-reduce.html">array_reduce</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.array-rand" class="refentry">
<div class="refnamediv">
<h1 class="refname">array_rand</h1>
<p class="verinfo">(PHP 4, PHP 5, PHP 7)</p><p class="refpurpose"><span class="refname">array_rand</span> — <span class="dc-title">Pick one or more random keys out of an array</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.array-rand-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <span class="methodname"><strong>array_rand</strong></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter">$array</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$num</code><span class="initializer"> = 1</span></span>
] )</div>
<p class="para rdfs-comment">
Picks one or more random entries out of an array, and returns the
key (or keys) of the random entries.
It uses a pseudo random number generator that is not suitable for
cryptographic purposes.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.array-rand-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<code class="parameter">array</code></dt>
<dd>
<p class="para">
The input array.
</p>
</dd>
<dt>
<code class="parameter">num</code></dt>
<dd>
<p class="para">
Specifies how many entries should be picked.
</p>
</dd>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.array-rand-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
When picking only one entry, <span class="function"><strong>array_rand()</strong></span> returns
the key for a random entry. Otherwise, an array of keys for the random
entries is returned. This is done so that random keys can be picked
from the array as well as random values. Trying to pick more elements
than there are in the array will result in an
<strong><code>E_WARNING</code></strong> level error, and NULL will be returned.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.array-rand-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>7.1.0</td>
<td>
The internal randomization algorithm <a href="migration71.incompatible.html#migration71.incompatible.rand-srand-aliases" class="link">has been changed</a> to use the <a href="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html" class="link external">» Mersenne Twister</a> Random Number Generator instead of the libc rand function.
</td>
</tr>
<tr>
<td>5.2.10</td>
<td>
The resulting array of keys is no longer shuffled.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.array-rand-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-6188">
<p><strong>Example #1 <span class="function"><strong>array_rand()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$input </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"Neo"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Morpheus"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Trinity"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Cypher"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Tank"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$rand_keys </span><span style="color: #007700">= </span><span style="color: #0000BB">array_rand</span><span style="color: #007700">(</span><span style="color: #0000BB">$input</span><span style="color: #007700">, </span><span style="color: #0000BB">2</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">$input</span><span style="color: #007700">[</span><span style="color: #0000BB">$rand_keys</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]] . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />echo </span><span style="color: #0000BB">$input</span><span style="color: #007700">[</span><span style="color: #0000BB">$rand_keys</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]] . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.array-rand-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><span class="function"><a href="function.shuffle.html" class="function" rel="rdfs-seeAlso">shuffle()</a> - Shuffle an array</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.array-push.html">array_push</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.array-reduce.html">array_reduce</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
