<!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>How to read a function definition (prototype)</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="about.notes.html">About user notes</a></div>
<div class="next" style="text-align: right; float: right;"><a href="about.phpversions.html">PHP versions documented in this manual</a></div>
<div class="up"><a href="about.html">About the manual</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="about.prototypes" class="sect1">
<h2 class="title">How to read a function definition (prototype)</h2>
<p class="para">
Each function in the manual is documented for quick reference. Knowing how
to read and understand the text will make learning PHP
much easier. Rather than relying on examples or cut/paste, everyone should
know how to read function definitions (prototypes). Let's begin:
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>
Prerequisite: Basic understanding of <a href="language.types.html" class="link">types</a>
</strong><br />
<p class="para">
Although PHP is a loosely typed language, it's important to have
a basic understanding of <a href="language.types.html" class="link">types</a> as
they have important meaning.
</p>
</p></blockquote>
<p class="para">
Function definitions tell us what
type of value is <a href="functions.returning-values.html" class="link">returned</a>.
Let's use the definition for <span class="function"><a href="function.strlen.html" class="function">strlen()</a></span> as our first example:
</p>
<p class="para">
<div class="example-contents screen">
<div class="cdata"><pre>
strlen
(PHP 4, PHP 5)
strlen -- Get string length
Description
int strlen ( string $string )
Returns the length of given string.
</pre></div>
</div>
</p>
<p class="para">
<table class="doctable table">
<caption><strong>Explanation of a function definition</strong></caption>
<thead>
<tr>
<th>Part</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>
strlen
</td>
<td>
The function name.
</td>
</tr>
<tr>
<td>
(PHP 4, PHP 5)
</td>
<td>
strlen() has been around in all versions of PHP 4 and PHP 5
</td>
</tr>
<tr>
<td>
int
</td>
<td>
Type of value this function returns, which is an
<span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span> (i.e. the length of a string is measured in
numbers).
</td>
</tr>
<tr>
<td>
( string $string )
</td>
<td>
The first (and in this case the only) parameter/argument for this
function is named <em><code class="parameter">string</code></em>, and it's a
<span class="type"><a href="language.types.string.html" class="type string">string</a></span>.
</td>
</tr>
</tbody>
</table>
</p>
<p class="para">
We could rewrite the above function definition in a generic way:
</p>
<p class="para">
<div class="example-contents screen">
<div class="cdata"><pre>
returned type function name ( parameter type parameter name )
</pre></div>
</div>
</p>
<p class="para">
Many functions take on multiple parameters, such as <span class="function"><a href="function.in-array.html" class="function">in_array()</a></span>.
Its prototype is as follows:
</p>
<p class="para">
<div class="example-contents screen">
<div class="cdata"><pre>
bool in_array ( mixed $needle, array $haystack [, bool $strict])
</pre></div>
</div>
</p>
<p class="para">
What does this mean? in_array() returns a
<a href="language.types.boolean.html" class="link">boolean</a> value, <strong><code>TRUE</code></strong> on
success (if the <em><code class="parameter">needle</code></em> was found in the
<em><code class="parameter">haystack</code></em>) or <strong><code>FALSE</code></strong> on failure (if the
<em><code class="parameter">needle</code></em> was not found in the
<em><code class="parameter">haystack</code></em>). The first parameter is named
<em><code class="parameter">needle</code></em> and it can be of many different
<a href="language.types.html" class="link">types</a>, so we call it
"<em class="emphasis">mixed</em>". This mixed <em><code class="parameter">needle</code></em>
(what we're looking for) can be either a scalar value (string, integer,
or <a href="language.types.float.html" class="link">float</a>), or an
<a href="language.types.array.html" class="link">array</a>.
<em><code class="parameter">haystack</code></em> (the array we're searching in) is the
second parameter. The third <em class="emphasis">optional</em> parameter is
named <em><code class="parameter">strict</code></em>. All optional parameters are seen
in <em class="emphasis">[</em> brackets <em class="emphasis">]</em>. The manual
states that the <em><code class="parameter">strict</code></em> parameter defaults to
boolean <strong><code>FALSE</code></strong>. See the manual page on each function for details on
how they work.
</p>
<p class="para">
There are also functions with more complex PHP version information. Take
<span class="function"><a href="function.html-entity-decode.html" class="function">html_entity_decode()</a></span> as an example:
</p>
<p class="para">
<div class="example-contents screen">
<div class="cdata"><pre>
(PHP 4 >= 4.3.0, PHP 5)
</pre></div>
</div>
</p>
<p class="para">
This means that this function has only been
available in a released version since PHP 4.3.0.
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="about.notes.html">About user notes</a></div>
<div class="next" style="text-align: right; float: right;"><a href="about.phpversions.html">PHP versions documented in this manual</a></div>
<div class="up"><a href="about.html">About the manual</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
