<!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 entries 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)</p><p class="refpurpose"><span class="refname">array_rand</span> — <span class="dc-title">Pick one or more random entries 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.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.array-rand-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">array</code></em></span>
<dd>
<p class="para">
The input array.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">num</code></em></span>
<dd>
<p class="para">
Specifies how many entries should be picked.
</p>
</dd>
</dt>
</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>5.2.10</td>
<td>
The resulting array of keys is no longer shuffled.
</td>
</tr>
<tr><td>4.2.0</td><td>The random
number generator is seeded automatically.</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-4974">
<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>
