   #PHP Manual Types Strings Objects

          PHP Manual
   Prev Chapter 6. Types Next
   ______________________________________________________________________

Arrays

   An array in PHP is actually an ordered map. A map is a type that maps
   values to keys. This type is optimized in several ways, so you can use
   it as a real array, or a list (vector), hashtable (which is an
   implementation of a map), dictionary, collection, stack, queue and
   probably more. Because you can have another PHP array as a value, you
   can also quite easily simulate trees.

   Explanation of those data structures is beyond the scope of this
   manual, but you'll find at least one example for each of them. For
   more information we refer you to external literature about this broad
   topic.

Syntax

Specifying with array()

   An array can be created by the array() language-construct. It takes a
   certain number of comma-separated key => value pairs.

array( [key =>] value
     , ...
     )
// key may be an integer or string
// value may be any value

   <?php
   $arr = array("foo" => "bar", 12 => true);
   echo $arr["foo"]; // bar
   echo $arr[12];    // 1
   ?>

   A key may be either an integer or a string. If a key is the standard
   representation of an integer, it will be interpreted as such (i.e. "8"
   will be interpreted as 8, while "08" will be interpreted as "08").
   There are no different indexed and associative array types in PHP;
   there is only one array type, which can both contain integer and
   string indices.

   A value can be of any PHP type.

   <?php
   $arr = array("somearray" => array(6 => 5, 13 => 9, "a" => 42));
   echo $arr["somearray"][6];    // 5
   echo $arr["somearray"][13];   // 9
   echo $arr["somearray"]["a"];  // 42
   ?>

   If you do not specify a key for a given value, then the maximum of the
   integer indices is taken, and the new key will be that maximum value +
   1. If you specify a key that already has a value assigned to it, that
   value will be overwritten.

   <?php
   // This array is the same as ...
   array(5 => 43, 32, 56, "b" => 12);
   // ...this array
   array(5 => 43, 6 => 32, 7 => 56, "b" => 12);
   ?>

   Warning

   As of PHP 4.3.0, the index generation behaviour described above has
   changed. Now, if you append to an array in which the current maximum
   key is negative, then the next key created will be zero (0). Before,
   the new index would have been set to the largest existing key + 1, the
   same as positive indices are.

   Using TRUE as a key will evaluate to integer 1 as key. Using FALSE as
   a key will evaluate to integer 0 as key. Using NULL as a key will
   evaluate to the empty string. Using the empty string as key will
   create (or overwrite) a key with the empty string and its value; it is
   not the same as using empty brackets.

   You cannot use arrays or objects as keys. Doing so will result in a
   warning: Illegal offset type.

Creating/modifying with square-bracket syntax

   You can also modify an existing array by explicitly setting values in
   it.

   This is done by assigning values to the array while specifying the key
   in brackets. You can also omit the key, add an empty pair of brackets
   ("[]") to the variable name in that case.
$arr[key] = value;
$arr[] = value;
// key may be an integer or string
// value may be any value

   If $arr doesn't exist yet, it will be created. So this is also an
   alternative way to specify an array. To change a certain value, just
   assign a new value to an element specified with its key. If you want
   to remove a key/value pair, you need to unset() it.

   <?php
   $arr = array(5 => 1, 12 => 2);
   $arr[] = 56;    // This is the same as $arr[13] = 56;
                   // at this point of the script
   $arr["x"] = 42; // This adds a new element to
                   // the array with key "x"

   unset($arr[5]); // This removes the element from the array
   unset($arr);    // This deletes the whole array
   ?>

     Note: As mentioned above, if you provide the brackets with no key
     specified, then the maximum of the existing integer indices is
     taken, and the new key will be that maximum value + 1 . If no
     integer indices exist yet, the key will be 0 (zero). If you specify
     a key that already has a value assigned to it, that value will be
     overwritten.

   Warning

   As of PHP 4.3.0, the index generation behaviour described above has
   changed. Now, if you append to an array in which the current maximum
   key is negative, then the next key created will be zero (0). Before,
   the new index would have been set to the largest existing key + 1, the
   same as positive indices are.

     Note that the maximum integer key used for this need not currently
     exist in the array. It simply must have existed in the array at
     some time since the last time the array was re-indexed. The
     following example illustrates:

   <?php
   // Create a simple array.
   $array = array(1, 2, 3, 4, 5);
   print_r($array);
   // Now delete every item, but leave the array itself intact:
   foreach ($array as $i => $value) {
       unset($array[$i]);
   }
   print_r($array);
   // Append an item (note that the new key is 5, instead of 0 as you
   // might expect).
   $array[] = 6;
   print_r($array);
   // Re-index:
   $array = array_values($array);
   $array[] = 7;
   print_r($array);
   ?>

   The above example would produce the following output:
Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
Array
(
)
Array
(
    [5] => 6
)
Array
(
    [0] => 6
    [1] => 7
)

Useful functions

   There are quite a few useful functions for working with arrays. See
   the array functions section.

     Note: The unset() function allows unsetting keys of an array. Be
     aware that the array will NOT be reindexed. If you only use "usual
     integer indices" (starting from zero, increasing by one), you can
     achieve the reindex effect by using array_values().

   <?php
   $a = array(1 => 'one', 2 => 'two', 3 => 'three');
   unset($a[2]);
   /* will produce an array that would have been defined as
      $a = array(1 => 'one', 3 => 'three');
      and NOT
      $a = array(1 => 'one', 2 =>'three');
   */
   $b = array_values($a);
   // Now $b is array(0 => 'one', 1 =>'three')
   ?>

   The foreach control structure exists specifically for arrays. It
   provides an easy way to traverse an array.

Array do's and don'ts

Why is $foo[bar] wrong?

   You should always use quotes around a string literal array index. For
   example, use $foo['bar'] and not $foo[bar]. But why is $foo[bar]
   wrong? You might have seen the following syntax in old scripts:

   <?php
   $foo[bar] = 'enemy';
   echo $foo[bar];
   // etc
   ?>

   This is wrong, but it works. Then, why is it wrong? The reason is that
   this code has an undefined constant (bar) rather than a string ('bar'
   - notice the quotes), and PHP may in future define constants which,
   unfortunately for your code, have the same name. It works because PHP
   automatically converts a bare string (an unquoted string which does
   not correspond to any known symbol) into a string which contains the
   bare string. For instance, if there is no defined constant named bar,
   then PHP will substitute in the string 'bar' and use that.

     Note: This does not mean to always quote the key. You do not want
     to quote keys which are constants or variables, as this will
     prevent PHP from interpreting them.

   <?php
   error_reporting(E_ALL);
   ini_set('display_errors', true);
   ini_set('html_errors', false);
   // Simple array:
   $array = array(1, 2);
   $count = count($array);
   for ($i = 0; $i < $count; $i++) {
       echo "\nChecking $i: \n";
       echo "Bad: " . $array['$i'] . "\n";
       echo "Good: " . $array[$i] . "\n";
       echo "Bad: {$array['$i']}\n";
       echo "Good: {$array[$i]}\n";
   }
   ?>

     Note: The output from the above is:

Checking 0:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Bad:
Good: 1
Notice: Undefined index:  $i in /path/to/script.html on line 11
Bad:
Good: 1

Checking 1:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Bad:
Good: 2
Notice: Undefined index:  $i in /path/to/script.html on line 11
Bad:
Good: 2

   More examples to demonstrate this fact:

   <?php
   // Let's show all errors
   error_reporting(E_ALL);
   $arr = array('fruit' => 'apple', 'veggie' => 'carrot');
   // Correct
   print $arr['fruit'];  // apple
   print $arr['veggie']; // carrot
   // Incorrect.  This works but also throws a PHP error of
   // level E_NOTICE because of an undefined constant named fruit
   //
   // Notice: Use of undefined constant fruit - assumed 'fruit' in...
   print $arr[fruit];    // apple
   // Let's define a constant to demonstrate what's going on.  We
   // will assign value 'veggie' to a constant named fruit.
   define('fruit', 'veggie');
   // Notice the difference now
   print $arr['fruit'];  // apple
   print $arr[fruit];    // carrot
   // The following is okay as it's inside a string.  Constants are not
   // looked for within strings so no E_NOTICE error here
   print "Hello $arr[fruit]";      // Hello apple
   // With one exception, braces surrounding arrays within strings
   // allows constants to be looked for
   print "Hello {$arr[fruit]}";    // Hello carrot
   print "Hello {$arr['fruit']}";  // Hello apple
   // This will not work, results in a parse error such as:
   // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or
   T_NUM_STRING'
   // This of course applies to using autoglobals in strings as well
   print "Hello $arr['fruit']";
   print "Hello $_GET['foo']";
   // Concatenation is another option
   print "Hello " . $arr['fruit']; // Hello apple
   ?>

   When you turn error_reporting() up to show E_NOTICE level errors (such
   as setting it to E_ALL) then you will see these errors. By default,
   error_reporting is turned down to not show them.

   As stated in the syntax section, there must be an expression between
   the square brackets ('[' and ']'). That means that you can write
   things like this:

   <?php
   echo $arr[somefunc($bar)];
   ?>

   This is an example of using a function return value as the array
   index. PHP also knows about constants, as you may have seen the E_*
   ones before.

   <?php
   $error_descriptions[E_ERROR]   = "A fatal error has occured";
   $error_descriptions[E_WARNING] = "PHP issued a warning";
   $error_descriptions[E_NOTICE]  = "This is just an informal notice";
   ?>

   Note that E_ERROR is also a valid identifier, just like bar in the
   first example. But the last example is in fact the same as writing:

   <?php
   $error_descriptions[1] = "A fatal error has occured";
   $error_descriptions[2] = "PHP issued a warning";
   $error_descriptions[8] = "This is just an informal notice";
   ?>

   because E_ERROR equals 1, etc.

   As we already explained in the above examples, $foo[bar] still works
   but is wrong. It works, because bar is due to its syntax expected to
   be a constant expression. However, in this case no constant with the
   name bar exists. PHP now assumes that you meant bar literally, as the
   string "bar", but that you forgot to write the quotes.

So why is it bad then?

   At some point in the future, the PHP team might want to add another
   constant or keyword, or you may introduce another constant into your
   application, and then you get in trouble. For example, you already
   cannot use the words empty and default this way, since they are
   special reserved keywords.

     Note: To reiterate, inside a double-quoted string, it's valid to
     not surround array indexes with quotes so "$foo[bar]" is valid. See
     the above examples for details on why as well as the section on
     variable parsing in strings.

Converting to array

   For any of the types: integer, float, string, boolean and resource, if
   you convert a value to an array, you get an array with one element
   (with index 0), which is the scalar value you started with.

   If you convert an object to an array, you get the properties (member
   variables) of that object as the array's elements. The keys are the
   member variable names.

   If you convert a NULL value to an array, you get an empty array.

Examples

   The array type in PHP is very versatile, so here will be some examples
   to show you the full power of arrays.

   <?php
   // this
   $a = array( 'color' => 'red',
               'taste' => 'sweet',
               'shape' => 'round',
               'name'  => 'apple',
                          4        // key will be 0
             );
   // is completely equivalent with
   $a['color'] = 'red';
   $a['taste'] = 'sweet';
   $a['shape'] = 'round';
   $a['name']  = 'apple';
   $a[]        = 4;        // key will be 0
   $b[] = 'a';
   $b[] = 'b';
   $b[] = 'c';
   // will result in the array array(0 => 'a' , 1 => 'b' , 2 => 'c'),
   // or simply array('a', 'b', 'c')
   ?>

   Example 6-4. Using array()
   <?php
   // Array as (property-)map
   $map = array( 'version'    => 4,
                 'OS'         => 'Linux',
                 'lang'       => 'english',
                 'short_tags' => true
               );

   // strictly numerical keys
   $array = array( 7,
                   8,
                   0,
                   156,
                   -10
                 );
   // this is the same as array(0 => 7, 1 => 8, ...)
   $switching = array(         10, // key = 0
                       5    =>  6,
                       3    =>  7,
                       'a'  =>  4,
                               11, // key = 6 (maximum of integer-indices
   was 5)
                       '8'  =>  2, // key = 8 (integer!)
                       '02' => 77, // key = '02'
                       0    => 12  // the value 10 will be overwritten by
   12
                     );

   // empty array
   $empty = array();
   ?>

   Example 6-5. Collection
   <?php
   $colors = array('red', 'blue', 'green', 'yellow');
   foreach ($colors as $color) {
       echo "Do you like $color?\n";
   }
   /* output:
   Do you like red?
   Do you like blue?
   Do you like green?
   Do you like yellow?
   */
   ?>

   Note that it is currently not possible to change the values of the
   array directly in such a loop. A workaround is the following:

   Example 6-6. Collection
   <?php
   foreach ($colors as $key => $color) {
       // won't work:
       //$color = strtoupper($color);

       // works:
       $colors[$key] = strtoupper($color);
   }
   print_r($colors);
   /* output:
   Array
   (
       [0] => RED
       [1] => BLUE
       [2] => GREEN
       [3] => YELLOW
   )
   */
   ?>

   This example creates a one-based array.

   Example 6-7. One-based index
   <?php
   $firstquarter  = array(1 => 'January', 'February', 'March');
   print_r($firstquarter);
   /* output:
   Array
   (
       [1] => 'January'
       [2] => 'February'
       [3] => 'March'
   )
   */
   ?>

   Example 6-8. Filling an array
   <?php
   // fill an array with all items from a directory
   $handle = opendir('.');
   while (false !== ($file = readdir($handle))) {
       $files[] = $file;
   }
   closedir($handle);
   ?>

   Arrays are ordered. You can also change the order using various
   sorting functions. See the array functions section for more
   information. You can count the number of items in an array using the
   count() function.

   Example 6-9. Sorting an array
   <?php
   sort($files);
   print_r($files);
   ?>

   Because the value of an array can be anything, it can also be another
   array. This way you can make recursive and multi-dimensional arrays.

   Example 6-10. Recursive and multi-dimensional arrays
   <?php
   $fruits = array ( "fruits"  => array ( "a" => "orange",
                                          "b" => "banana",
                                          "c" => "apple"
                                        ),
                     "numbers" => array ( 1,
                                          2,
                                          3,
                                          4,
                                          5,
                                          6
                                        ),
                     "holes"   => array (      "first",
                                          5 => "second",
                                               "third"
                                        )
                   );
   // Some examples to address values in the array above
   echo $fruits["holes"][5];    // prints "second"
   echo $fruits["fruits"]["a"]; // prints "orange"
   unset($fruits["holes"][0]);  // remove "first"
   // Create a new multi-dimensional array
   $juices["apple"]["green"] = "good";
   ?>

   You should be aware that array assignment always involves value
   copying. You need to use the reference operator to copy an array by
   reference.

   <?php
   $arr1 = array(2, 3);
   $arr2 = $arr1;
   $arr2[] = 4; // $arr2 is changed,
                // $arr1 is still array(2, 3)

   $arr3 = &$arr1;
   $arr3[] = 4; // now $arr1 and $arr3 are the same
   ?>
   ______________________________________________________________________

   Prev    Home    Next
   Strings  Up  Objects
