PHP: How to read a function definition (prototype) - Manual

downloads | documentation | faq | getting help | mailing lists | reporting bugs | php.net sites | links | conferences | my php.net

search for in the

PHP versions documented in this manual О заметках пользователей

Last updated: Sat, 27 Jan 2007

view this page in

# How to read a function definition (prototype)

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, you will want to know how to read function definitions (prototypes). Let's begin:

> Prerequisite: Basic understanding of types: Although PHP is a loosely typed language, it's important to have a basic understanding of types as they have important meaning.

Function definitions tell us what type of value is returned. Let's use the definition for strlen() as our first example:

    strlen

    (PHP 3, PHP 4, PHP 5)
    strlen -- Get string length

    Description
    int strlen ( string str )

    Returns the length of string.

Таблица S-1. Explanation of a function definition

Part | Description
--- | ---
strlen | The function name.
(PHP 3, PHP 4, PHP 5) | strlen() has been around in all versions of PHP 3, PHP 4 and PHP 5
int | Type of value this function returns, which is an integer (i.e. the length of a string is measured in numbers).
( string str ) | The first (and in this case the only) parameter/argument for this function is named `str`, and it's a string.

We could rewrite the above function definition in a generic way:

    returned type    function name    ( parameter type   parameter name )

Many functions take on multiple parameters, such as in_array(). Its prototype is as follows:

    bool in_array ( mixed needle, array haystack [, bool strict])

What does this mean? in_array() returns a boolean value, `TRUE` on success (if the `needle` was found in the `haystack`) or `FALSE` on failure (if the `needle` was not found in the `haystack`). The first parameter is named `needle` and it can be of many different types, so we call it "mixed". This mixed `needle` (what we're looking for) can be either a scalar value (string, integer, or float), or an array. `haystack` (the array we're searching in) is the second parameter. The third optional parameter is named `strict`. All optional parameters are seen in [ brackets ]. The manual states that the `strict` parameter defaults to boolean `FALSE`. See the manual page on each function for details on how they work.

There are also functions with more complex PHP version information. Take html_entity_decode() as an example:

    (PHP 4 >= 4.3.0, PHP 5)

This means that this function was not available in PHP 3, and is only available in a released version since PHP 4.3.0.

add a note User Contributed Notes
How to read a function definition (prototype)
php dot devel at homelinkcs dot com
12-Jul-2005 05:50
`More specifically, an ampersand (&) prepended to an argument name means that the argument will be passed by reference (http://www.php.net/manual/en/language.references.pass.php).`
ceo at l-i-e dot com
09-Mar-2005 03:16
`Another thing to watch for is the & in the argument list.
That generally means that the function is going to *CHANGE* the value you pass in, in some way, and you can't rely on it being the same as what you handed off to the function.`
add a note
PHP versions documented in this manual О заметках пользователей

Last updated: Sat, 27 Jan 2007
show source | credits | stats | sitemap | contact | advertising | mirror sites
Copyright © 2001-2007 The PHP Group
All rights reserved.
This mirror generously provided by: Yahoo! Inc.
Last updated: Sat Mar 10 10:36:09 2007 PST