Docbook2Wiki: Initial conversion from Docbook

2008-03-06T22:28:45Z

Initial conversion from Docbook

New page

{{PHP Cookbook/TOC}}

== Introduction ==

Along with conditional logic, variables are the core of what makes computer programs powerful and flexible. If you think of a variable as a bucket with a name that holds a value, PHP lets you have plain old buckets, buckets that contain the name of other buckets, buckets with numbers or strings in them, buckets holding arrays of other buckets, buckets full of objects, and just about any other variation on that analogy you can think of.

A variable is either set or unset. A variable with any value assigned to it, <tt>true</tt> or <tt>false</tt>, empty or nonempty, is set. The function <tt>isset( )</tt> returns <tt>true</tt> when passed a variable that's set. The only way to turn a variable that's set into one that's unset is to call <tt>unset( )</tt> on the variable. Scalars, arrays, and objects can all be passed to <tt>unset( )</tt>. You can also pass <tt>unset( )</tt> multiple variables to unset them all:

unset($vegetables);
unset($vegetables[12]);
unset($earth, $moon, $stars);

If a variable is present in the query string of a URL, even if it has no value assigned to it, it is set. Thus:

<nowiki>http://www.example.com/set.php?chimps=&monkeys=12</nowiki>

sets <tt>$_GET['monkeys']</tt> to <tt>12</tt> and <tt>$_GET['chimps']</tt> to the empty string.

All unset variables are also empty. Set variables may be empty or nonempty. Empty variables have values that evaluate to <tt>false</tt> as a boolean: the integer 0, the double 0.0, the empty string, the string "0", the boolean <tt>false</tt>, an array with no elements, an object with no variables or methods, and <tt>NULL</tt>. Everything else is nonempty. This includes the string "00", and the string " ", containing just a space character.

Variables evaluate to either <tt>true</tt> or <tt>false</tt>. The values listed earlier that evaluate to <tt>false</tt> as a boolean are the complete set of what's <tt>false</tt> in PHP. Every other value is <tt>true</tt>. The distinction between empty and false is that emptiness is only possible for variables. Constants and return values from functions can be <tt>false</tt>, but they can't be empty. For example, the following is valid because <tt>$first_name</tt> is a variable:

if (empty($first_name)) { .. }

On the other hand, these two examples return parse errors because <tt>0</tt> (a constant) and the return value from <tt>get_first_name( )</tt> can't be empty:

if (empty(0)) { .. }
if (empty(get_first_name())) { .. }

== Avoiding == Versus = Confusion ==

=== Problem ===

You don't want to accidentally assign values when comparing a variable and a constant.

=== Solution ===

Use:

if (12 == $dwarves) { ... }

instead of:

if ($dwarves == 12) { ... }

Putting the constant on the left triggers a parse error with the assignment operator. In other words, PHP complains when you write:

if (12 = $dwarves) { ... }

but:

if ($dwarves = 12) { ... }

silently executes, assigning <tt>12</tt> to the variable <tt>$dwarves</tt>, and then executing the code inside the block. (<tt>$dwarves = 12</tt> evaluates to <tt>12</tt>, which is <tt>true</tt>.)

=== Discussion ===

Putting a constant on the left side of a comparison coerces the comparison to the type of the constant. This causes problems when you are comparing an integer with a variable that could be an integer or a string. <tt>0 == $dwarves</tt> is <tt>true</tt> when <tt>$dwarves</tt> is <tt>0</tt>, but it's also true when <tt>$dwarves</tt> is <tt>sleepy</tt>. Since an integer (<tt>0</tt>) is on the left side of the comparison, PHP converts what's on the right (the string <tt>sleepy</tt>) to an integer (<tt>0</tt>) before comparing. To avoid this, use the identity operator, <tt>0 === $dwarves</tt>, instead.

=== See Also ===

Documentation for <tt>=</tt> at ''http://www.php.net/language.operators.assignment.php'' and for <tt>==</tt> and <tt>===</tt> at ''http://www.php.net/manual/language.operators.comparison.php''.

== Establishing a Default Value ==

=== Problem ===

You want to assign a default value to a variable that doesn't already have a value. It often happens that you want a hardcoded default value for a variable that can be overridden from form input or through an environment variable.

=== Solution ===

Use <tt>isset( )</tt> to assign a default to a variable that may already have a value:

if (! isset($cars)) { $cars = $default_cars; }

Use the ternary (<tt>a ? b : c</tt>) operator to give a new variable a (possibly default) value:

$cars = isset($_REQUEST['cars']) ? $_REQUEST['cars'] : $default_cars;

=== Discussion ===

Using <tt>isset( )</tt> is essential when assigning default values. Without it, the nondefault value can't be <tt>0</tt> or anything else that evaluates to <tt>false</tt>. Consider this assignment:

$cars = $_REQUEST['cars'] ? $_REQUEST['cars'] : $default_cars;

If <tt>$_REQUEST['cars']</tt> is <tt>0</tt>, <tt>$cars</tt> is set to <tt>$default_cars</tt> even though <tt>0</tt> may be a valid value for <tt>$cars</tt>.

You can use an array of defaults to set multiple default values easily. The keys in the defaults array are variable names, and the values in the array are the defaults for each variable:

$defaults = array('emperors' => array('Rudolf II','Caligula'),
'vegetable' => 'celery',
'acres' => 15);

foreach ($defaults as $k => $v) {
if (! isset($GLOBALS[$k])) { $GLOBALS[$k] = $v; }
}

Because the variables are set in the global namespace, the previous code doesn't work for setting function-private defaults. To do that, use variable variables:

foreach ($defaults as $k => $v) {
if (! isset($$k)) { $$k = $v; }
}

=== See Also ===

Documentation on <tt>isset( )</tt> at ''http://www.php.net/isset''; variable variables are discussed in [[PHP Cookbook/Variables#Creating a Dynamic Variable Name|Recipe 5.5]] and at ''http://www.php.net/language.variables.variable''.

== Exchanging Values Without Using Temporary Variables ==

=== Problem ===

You want to exchange the values in two variables without using additional variables for storage.

=== Solution ===

To swap <tt>$a</tt> and <tt>$b</tt>:

list($a,$b) = array($b,$a);

=== Discussion ===

PHP's <tt>list( )</tt> language construct lets you assign values from an array to individual variables. Its counterpart on the right side of the expression, <tt>array( )</tt> , lets you construct arrays from individual values. Assigning the array that <tt>array( )</tt> returns to the variables in the <tt>list( )</tt> lets you juggle the order of those values. This works with more than two values, as well:

list($yesterday,$today,$tomorrow) = array($today,$tomorrow,$yesterday);

This method isn't faster than using temporary variables, so you should use it for clarity, but not speed.

=== See Also ===

Documentation on <tt>list( )</tt> at ''http://www.php.net/list'' and <tt>array( )</tt> at ''http://www.php.net/array''.

== Creating a Dynamic Variable Name ==

=== Problem ===

You want to construct a variable's name dynamically. For example, you want to use variable names that match the field names from a database query.

=== Solution ===

Use PHP's variable variable syntax by prepending a <tt>$</tt> to a variable whose value is the variable name you want:

$animal = 'turtles';
$turtles = 103;
print $$animal;
'''103'''

=== Discussion ===

The previous example prints <tt>103</tt>. Because <tt>$animal</tt> <tt>=</tt> <tt>'turtles',</tt> <tt>$$animal</tt> is <tt>$turtles</tt>, which equals 103.

Using curly braces, you can construct more complicated expressions that indicate variable names:

$stooges = array('Moe','Larry','Curly');
$stooge_moe = 'Moses Horwitz';
$stooge_larry = 'Louis Feinberg';
$stooge_curly = 'Jerome Horwitz';

foreach ($stooges as $s) {
print "$s's real name was ${'stooge_'.strtolower($s)}.\n";
}
'''Moe's real name was Moses Horwitz.'''
'''Larry's real name was Louis Feinberg.'''
'''Curly's real name was Jerome Horwitz.'''

PHP evaluates the expression between the curly braces and uses it as a variable name. That expression can even have function calls in it, such as <tt>strtolower( )</tt>.

Variable variables are also useful when iterating through similarly named variables. Say you are querying a database table that has fields named <tt>title_1</tt>, <tt>title_2</tt>, etc. If you want to check if a title matches any of those values, the easiest way is to loop through them like this:

for ($i = 1; $i <= $n; $i++) {
$t = "title_$i";
if ($title == $$t) { /* match */ }
}

Of course, it would be more straightforward to store these values in an array, but if you are maintaining old code that uses this technique (and you can't change it), variable variables are helpful.

The curly brace syntax is also necessary in resolving ambiguity about array elements. The variable variable <tt>$$donkeys[12]</tt> could have two meanings. The first is "take what's in the 12th element of the <tt>$donkeys</tt> array and use that as a variable name." Write this as: <tt>${$donkeys[12]}</tt>. The second is, "use what's in the scalar <tt>$donkeys</tt> as an array name and look in the 12th element of that array." Write this as: <tt>${$donkeys}[12]</tt>.

=== See Also ===

''http://www.php.net/language.variables.variable'' for documentation on variable variables.

== Using Static Variables ==

=== Problem ===

You want a local variable to retain its value between invocations of a function.

=== Solution ===

Declare the variable as <tt>static</tt>:

function track_times_called( ) {
static $i = 0;
$i++;
return $i;
}

=== Discussion ===

Declaring a variable <tt>static</tt> causes its value to be remembered by a function. So, if there are subsequent calls to the function, you can access the value of the saved variable. The <tt>pc_check_the_count( )</tt> function shown in [[PHP Cookbook/Variables#phpckbk-CHP-5-EX-1|Example 5-1]] uses <tt>static</tt> variables to keep track of the strikes and balls for a baseball batter.

<div id="phpckbk-CHP-5-EX-1">
'''Example 5-1. pc_check_the_count( )'''

function pc_check_the_count($pitch) {
static $strikes = 0;
static $balls = 0;

switch ($pitch) {
case 'foul':
if (2 == $strikes) break; // nothing happens if 2 strikes
// otherwise, act like a strike
case 'strike':
$strikes++;
break;
case 'ball':
$balls++;
break;
}

if (3 == $strikes) {
$strikes = $balls = 0;
return 'strike out';
}
if (4 == $balls) {
$strikes = $balls = 0;
return 'walk';
}
return 'at bat';
}

$what_happened = check_the_count($pitch);
</div>

In <tt>pc_check_the_count( )</tt>, the logic of what happens to the batter depending on the pitch count is in the <tt>switch</tt> statement inside the function. You can instead return the number of strikes and balls, but this requires you to place the checks for striking out, walking, and staying at the plate in multiple places in the code.

While <tt>static</tt> variables retain their values between function calls, they do so only during one invocation of a script. A <tt>static</tt> variable accessed in one request doesn't keep its value for the next request to the same page.

=== See Also ===

Documentation on <tt>static</tt> variables at ''http://www.php.net/language.variables.scope''.

== Sharing Variables Between Processes ==

=== Problem ===

You want a way to share information between processes that provides fast access to the shared data.

=== Solution ===

Store the data in a shared memory segment, and guarantee exclusive access to the shared memory with a semaphore:

$semaphore_id = 100;
$segment_id = 200;
// get a handle to the semaphore associated with the shared memory
// segment we want
$sem = sem_get($semaphore_id,1,0600);
// ensure exclusive access to the semaphore
sem_acquire($sem) or die("Can't acquire semaphore");
// get a handle to our shared memory segment
$shm = shm_attach($segment_id,16384,0600);
// retrieve a value from the shared memory segment
$population = shm_get_var($shm,'population');
// manipulate the value
$population += ($births + $immigrants - $deaths - $emigrants);
// store the value back in the shared memory segment
shm_put_var($shm,'population',$population);
// release the handle to the shared memory segment
shm_detach($shm);
// release the semaphore so other processes can acquire it
sem_release($sem);

=== Discussion ===

A shared memory segment is a slice of your machine's RAM that different processes (such as the multiple web server processes that handle requests) can access. A semaphore makes sure that the different processes don't step on each other's toes when they access the shared memory segment. Before a process can use the segment, it needs to get control of the semaphore. When it's done with the segment, it releases the semaphore for another process to grab.

To get control of a semaphore, use <tt>sem_get( )</tt> to find the semaphore's ID. The first argument to <tt>sem_get( )</tt> is an integer semaphore key. You can make the key any integer you want, as long as all programs that need to access this particular semaphore use the same key. If a semaphore with the specified key doesn't already exist, it's created, the maximum number of processes that can access the semaphore is set to the second argument of <tt>sem_get( )</tt> (in this case, <tt>1</tt>), and the semaphore's permissions are set to <tt>sem_get( )</tt>'s third argument (<tt>0600</tt>). These permissions work just like file permissions, so <tt>0600</tt> means that the user that created the semaphore can read it and write to it. In this context, user doesn't just mean the process that created the semaphore but any process with the same user ID. Permissions of <tt>0600</tt> should be appropriate for most uses, in which web server processes run as the same user.

<tt>sem_get( )</tt> returns an identifier that points to the underlying system semaphore. Use this ID to gain control of the semaphore with <tt>sem_acquire( )</tt> . This function waits until the semaphore can be acquired (perhaps waiting until other processes release the semaphore) and then returns <tt>true</tt>. It returns <tt>false</tt> on error. Errors include invalid permissions or not enough memory to create the semaphore. Once the semaphore is acquired, you can read from the shared memory segment.

First, establish a link to the particular shared memory segment with <tt>shm_attach( )</tt> . As with <tt>sem_get( )</tt>, the first argument to <tt>shm_attach( )</tt> is an integer key. This time, however it identifies the desired segment, not the semaphore. If the segment with the specified key doesn't exist, the other arguments create it. The second argument (<tt>16384</tt>) is the size in bytes of the segment, and the last argument (<tt>0600</tt>) are the permissions on the segment. <tt>shm_attach(200,16384,0600)</tt> creates a 16K shared memory segment that can be read from and written to only by the user who created it. The function returns the identifier you need to read from and write to the shared memory segment.

After attaching to the segment, pull variables out of it with <tt>shm_get_var($shm, 'population')</tt> . This looks in the shared memory segment identified by <tt>$shm</tt> and retrieves the value of the variable called <tt>population</tt>. You can store any type of variable in shared memory. Once the variable is retrieved, it can be operated on like other variables. <tt>shm_put_var($shm,'population',$population)</tt> puts the value of <tt>$population</tt> back into the shared memory segment as a variable called <tt>population</tt>.

You're now done with the shared memory statement. Detach from it with <tt>shm_detach( )</tt> and release the semaphore with <tt>sem_release( )</tt> so another process can use it.

Shared memory's chief advantage is that it's fast. But since it's stored in RAM, it can't hold too much data, and it doesn't persist when a machine is rebooted (unless you take special steps to write the information in shared memory to disk before shutdown and then load it into memory again at startup). Also, shared memory is not available on Windows.

=== See Also ===

[[PHP Cookbook/Web Basics#Program: Abusive User Checker|Recipe 8.28]] includes a program that uses shared memory; documentation on shared memory and semaphore functions at ''http://www.php.net/sem''.

== Encapsulating Complex Data Types as a String ==

=== Problem ===

You want a string representation of an array or object for storage in a file or database. This string should be easily reconstitutable into the original array or object.

=== Solution ===

Use <tt>serialize( )</tt> to encode variables and their values into a textual form:

$pantry = array('sugar' => '2 lbs.','butter' => '3 sticks');
$fp = fopen('/tmp/pantry','w') or die ("Can't open pantry");
fputs($fp,serialize($pantry));
fclose($fp);

To recreate the variables, use <tt>unserialize( )</tt> :

<nowiki>$new_pantry = unserialize(join('',file('/tmp/pantry')));</nowiki>

=== Discussion ===

The serialized string that is reconstituted into <tt>$pantry</tt> looks like:

a:2:{s:5:"sugar";s:6:"2 lbs.";s:6:"butter";s:8:"3 sticks";}

This stores enough information to bring back all the values in the array, but the variable name itself isn't stored in the serialized representation.

When passing serialized data from page to page in a URL, call <tt>urlencode( )</tt> on the data to make sure URL metacharacters are escaped in it:

$shopping_cart = array('Poppy Seed Bagel' => 2,
'Plain Bagel' => 1,
'Lox' => 4);
print '<a href="next.php?cart='.urlencode(serialize($shopping_cart)).'">Next</a>';

The <tt>magic_quotes_gpc</tt> and <tt>magic_quotes_runtime</tt> configuration settings affect data being passed to <tt>unserialize( )</tt>. If <tt>magic_quotes_gpc</tt> is <tt>on</tt>, data passed in URLs, POST variables, or cookies must be processed with <tt>stripslashes( )</tt> before it's unserialized:

$new_cart = unserialize(stripslashes($cart)); // if magic_quotes_gpc is on
$new_cart = unserialize($cart); // if magic_quotes_gpc is off

If <tt>magic_quotes_runtime</tt> is <tt>on</tt>, serialized data stored in a file must be processed with <tt>addslashes( )</tt> when writing and <tt>stripslashes()</tt> when reading:

<nowiki>$fp = fopen('/tmp/cart,'w');
fputs($fp,addslashes(serialize($a)));
fclose($fp);

// if magic_quotes_runtime is on
$new_cart = unserialize(stripslashes(join('',file('/tmp/cart'))));
// if magic_quotes_runtime is off
$new_cart = unserialize(join('',file('/tmp/cart')));</nowiki>

Serialized data read from a database must also be processed with <tt>stripslashes( )</tt> when <tt>magic_quotes_runtime</tt> is <tt>on</tt>:

mysql_query(
"INSERT INTO cart (id,data) VALUES (1,'".addslashes(serialize($cart))."')");

$r = mysql_query('SELECT data FROM cart WHERE id = 1');
$ob = mysql_fetch_object($r);
// if magic_quotes_runtime is on
$new_cart = unserialize(stripslashes($ob->data));
// if magic_quotes_runtime is off
$new_cart = unserialize($ob->data);

Serialized data going into a database always needs to have <tt>addslashes( )</tt> called on it (or another database-appropriate escaping method) to ensure it's saved properly.

=== See Also ===

[[PHP Cookbook/Database Access#Repeating Queries Efficiently|Recipe 10.8]] for information on escaping data for a database.

== Dumping Variable Contents as Strings ==

=== Problem ===

You want to inspect the values stored in a variable. It may be a complicated nested array or object, so you can't just print it out or loop through it.

=== Solution ===

Use <tt>print_r( )</tt> or <tt>var_dump( )</tt>:

$array = array("name" => "frank", 12, array(3, 4));

print_r($array);
'''Array'''
'''('''
''' [name] => frank'''
''' [0] => 12'''
''' [1] => Array'''
''' ('''
''' [0] => 3'''
''' [1] => 4'''
''' )'''
''')'''
var_dump($array);
'''array(3) {'''
''' ["name"]=>'''
''' string(5) "frank"'''
''' [0]=>'''
''' int(12)'''
''' [1]=>'''
''' array(2) {'''
''' [0]=>'''
''' int(3)'''
''' [1]=>'''
''' int(4)'''
''' }'''
'''}'''

=== Discussion ===

The output of <tt>print_r( )</tt> is more concise and easier to read. The output of <tt>var_dump( )</tt>, however, gives data types and lengths for each variable.

Since these functions recursively work their way through variables, if you have references within a variable pointing back to the variable itself, you can end up with an infinite loop. Both functions stop themselves from printing variable information forever, though. Once <tt>print_r( )</tt> has seen a variable once, it prints <tt>*RECURSION*</tt> instead of printing information about the variable again and continues iterating through the rest of the information it has to print. When <tt>var_dump( )</tt> sees a variable more than three times, it throws a fatal error and ends script execution. Consider the arrays <tt>$user_1</tt> and <tt>$user_2</tt>, which reference each other through their <tt>friend</tt> elements:

$user_1 = array('name' => 'Max Bialystock',
'username' => 'max');

$user_2 = array('name' => 'Leo Bloom',
'username' => 'leo');

// Max and Leo are friends
$user_2['friend'] = &$user_1;
$user_1['friend'] = &$user_2;

// Max and Leo have jobs
$user_1['job'] = 'Swindler';
$user_2['job'] = 'Accountant';

The output of <tt>print_r($user_2)</tt> is:

Array
(
[name] => Leo Bloom
[username] => leo
[friend] => Array
(
[name] => Max Bialystock
[username] => max
[friend] => Array
(
[name] => Leo Bloom
[username] => leo
[friend] => Array
*RECURSION*
[job] => Accountant
)

[job] => Swindler
)

[job] => Accountant
)

When <tt>print_r( )</tt> sees the reference to <tt>$user_1</tt> the second time, it prints <tt>*RECURSION*</tt> instead of descending into the array. It then continues on its way, printing the remaining elements of <tt>$user_1</tt> and <tt>$user_2</tt>.

Confronted with recursion, <tt>var_dump( )</tt> behaves differently:

array(4) {
["name"]=>
string(9) "Leo Bloom"
["username"]=>
string(3) "leo"
["friend"]=>
&array(4) {
["name"]=>
string(14) "Max Bialystock"
["username"]=>
string(3) "max"
["friend"]=>
&array(4) {
["name"]=>
string(9) "Leo Bloom"
["username"]=>
string(3) "leo"
["friend"]=>
&array(4) {
["name"]=>
string(14) "Max Bialystock"
["username"]=>
string(3) "max"
["friend"]=>
&array(4) {
["name"]=>
string(9) "Leo Bloom"
["username"]=>
string(3) "leo"
["friend"]=>
&array(4) {
["name"]=>
string(14) "Max Bialystock"
["username"]=>
string(3) "max"
["friend"]=>
&array(4) {
["name"]=>
string(9) "Leo Bloom"
["username"]=>
string(3) "leo"
["friend"]=>
&array(4) {
<br />
<b>Fatal error</b>: Nesting level too deep - recursive dependency? in
<b>var-dump.php</b> on line <b>15</b><br />

It's not until the fourth appearance of the reference to <tt>$user_1</tt> that <tt>var_dump( )</tt> stops recursing. When it does, it throws a fatal error, and no more variable dumping (or script execution) occurs.

Even though <tt>print_r( )</tt> and <tt>var_dump( )</tt> print their results instead of returning them, you can capture the data without printing it using output buffering:

ob_start();
var_dump($user);
$dump = ob_get_contents();
ob_end_clean();

This puts the results of <tt>var_dump($user)</tt> in <tt>$dump</tt>.

=== See Also ===

Output buffering is discussed in [[PHP Cookbook/Web Basics#Buffering Output to the Browser|Recipe 8.13]]; error handling with PEAR's DB module, shown in [[PHP Cookbook/Database Access#Finding the Number of Rows Returned by a Query|Recipe 10.9]], uses output buffering with <tt>print_r( )</tt> to save error messages; documentation on <tt>print_r( )</tt> at ''http://www.php.net/print-r'' and <tt>var_dump( )</tt> at ''http://www.php.net/var-dump'' .

PHP Cookbook/Variables - Revision history

Docbook2Wiki: Initial conversion from Docbook

Evanlenz: 1 revision(s)

Docbook2Wiki: Initial conversion from Docbook