Array-Related Functions

OverviewThis group of functions provides a great deal of power for dealing with PHP arrays. There are functions for sorting (in various fashions), constructing, deconstructing, analyzing, and otherwise manipulating arrays. These functions are built into PHP by default and can only be disabled by editing the source code and recompiling or by using the disable_functions directive in php.ini.

Array SpecificsAn array in PHP is a list of key/value elements in which any number of values can be stored (memory permitting). Each key in an array must be unique within that array. Keys can be either integers or strings, although as this book was being written support for keys of type float had been added and should be available in PHP 4.0.6 (in earlier versions, floating-point key behavior is undefined). An array having only integer keys is typically referred to as an indexed array; an array having string keys is typically called an associative array or a hash. No matter what kind of keys are used, PHP arrays are always hashes internally and will behave as such. This means that it's perfectly possible to have an indexed array with key values of 0, 1, 3, and 4 - note the lack of a 2. It's also possible to have an indexed array with its keys out of numeric order, or an array with both numeric and string keys. PHP internally maintains array order, unlike (for instance) Perl, and will not reorder arrays without your intervention.

All arrays contain an internal array pointer, which PHP uses to keep track of which element of the array is currently in use. There are several functions for maneuvering this pointer around the array, and for finding the key or value of the current element.

Element values are accessed by following the name of the array variable with a subscript containing the key of the desired element. A subscript is simply a pair of square brackets enclosing the key. If the key is a string literal, it should be in quotes within the subscript so that PHP doesn't try to parse it as a keyword:

/* Bad idea! 'default' is a reserved word in PHP. */
$some_array[default] = 'a default value';

/* This is how it should be done: */
$some_array['default'] = 'a default value';

However, if you are using a named constant as a subscript, it must not be in quotes.

Also note that when writing subscripts inside a double-quoted string, the subscript should not be placed in quotes:

echo "The value stored in \$array at key 'subscript' is:
                $array[subscript]";

Array elements can contain any kind of data, including other arrays; these subarrays behave as normal and may be nested as deeply as you like.

Arrays are not automatically passed by reference in PHP (unlike C, for instance). As with other variables, however, you can write your functions to accept arrays as pass-by-reference arguments. Of course, this applies only to PHP 4.

Elements can be added to an array in various ways. You can assign them directly to the array by using the subscript of the element to which you want to assign the new value, in which case the element will be added if it doesn't already exist, and updated if it does exist. You can also use the array() construct, as documented in the following example. Finally, you can use an empty subscript to assign to the array, in which case the new value will be appended to the array and assigned an integer key that is one larger than the largest previously existing integer key in that array, or 0 if there are no integer keys.

The following example provides a simple illustration of some basic array operations.

/* Create an array of user information with defaults, then fill it with information. */
$user_info = array('lastname' => '',
                   'initial' => '',
                   'firstname' => '',
                   'homedir' => '');
$user_info['lastname'] = 'User';
$user_info['initial'] = 'L.';
$user_info['firstname'] = 'Joe';
$user_info['homedir'] = '/home/joeluser';

/* Filling an indexed array with the letters of the English alphabet. */
$arr = array();
for ($i = 97; $i < 123; $i++) {
    $arr[] = chr($i);
}
print_r($arr);

/* Do the same thing, but make an array containing two arrays, one of uppercase
 * letters and one of lowercase. */
$arr = array();
for ($i = 97; $i < 123; $i++) {
    $arr['lowercase'][] = chr($i);
    $arr['uppercase'][] = chr($i - 32);
}
print_r($arr);