Приглашаем посетить

8.1 Working with Cookies

To set a cookie, use the setcookie( ) function. This tells a web client to remember a cookie name and value and send them back to the server on subsequent requests. Example 8-1 sets a cookie named userid to value ralph.

Example 8-1. Setting a cookie

setcookie('userid','ralph');

To read a previously set cookie from your PHP program, use the $_COOKIE auto-global array. Example 8-2 prints the value of the userid cookie.

Example 8-2. Printing a cookie value

print 'Hello, ' . $_COOKIE['userid'];

The value for a cookie that you provide to setcookie( ) can be a string or a number. It can't be an array or more complicated data structure.

When you call setcookie( ), the response that the PHP interpreter generates to send back to the web client includes a special header that tells the web client about the new cookie. On subsequent requests, the web client sends that cookie name and value back to the server. This two-step conversation is illustrated in Figure 8-1.

Figure 8-1. Client and server communication when setting a cookie

Usually, you must call setcookie( ) before the page generates any output. This means that setcookie( ) must come before any print statements. It also means that there can't be any text before the PHP <?php start tag in the page that comes before the setcookie( ) function. Later in this chapter, Section 8.6 explains why this requirement exists, and how, in some cases, you can get around it.

Example 8-3 shows the correct way to put a setcookie( ) call at the top of your page.

Example 8-3. Starting a page with setcookie( )

<?php

setcookie('userid','ralph');

?>

<html><head><title>Page with cookies</title><head>

<body>

This page sets a cookie properly, because the PHP block

with setcookie( ) in it comes before all of the HTML.

</body></html>

Cookies show up in $_COOKIE only when the web client sends them along with the request. This means that a name and value do not appear in $_COOKIE immediately after you call setcookie( ). Only after that cookie-setting response is digested by the web client does the client know about the cookie. And only after the client sends the cookie back on a subsequent request does it appear in $_COOKIE.

The default lifetime for a cookie is the lifetime of the web client. When you quit Internet Explorer or Mozilla, the cookie is deleted. To make a cookie live longer (or shorter), use the third argument to setcookie( ). This is an optional cookie expiration time. Example 8-4 shows some cookies with different expiration times.

Example 8-4. Setting cookie expiration

// The cookie expires one hour from now

setcookie('short-userid','ralph',time( ) + 60*60);



// The cookie expires one day from now

setcookie('longer-userid','ralph',time( ) + 60*60*24);



// The cookie expires at noon on October 1, 2006

setcookie('much-longer-userid','ralph',mktime(12,0,0,10,1,2006));

The cookie expiration time needs to be given to setcookie( ) expressed as the number of seconds elapsed since midnight on January 1, 1970. (As crazily arbitrary as that sounds, there are some good reasons for expressing time values that way, which are explained in Chapter 9.)

Two functions make coming up with appropriate expiration times easier: time( ) and mktime( ). The time( ) function returns the current number of elapsed seconds since January 1, 1970. So if you want the cookie expiration time to be a certain number of seconds from now, add that value to what time( ) returns. There are 60 seconds in a minute and 60 minutes in an hour, so 60*60 is the number of seconds in an hour. That makes time( ) + 60*60 equal to the "elapsed seconds" value for an hour from now. Similarly, 60*60*24 is the number of seconds in a day, so time( ) + 60*60*24 is the "elapsed seconds" value for a day from now.

The mktime( ) function computes an appropriate "elapsed seconds" value for a given date and time. The arguments to mktime( ) are hour, minute, second, month, day, and year. So, mktime(12,0,0,10,1,2006) returns the correct value for noon (hour: 12, minute: 0, second: 0), on October 1, 2006 (month: 10, day: 1, year: 2006).

Setting a cookie with a specific expiration time makes the cookie last even if the web client exits and restarts.

Aside from expiration time, there are two other cookie parameters that are helpful to adjust: the path and the domain. Each of these affect with what requests the web client sends back the cookie.

Normally, cookies are only sent back with requests for pages in the same directory (or below) as the page that set the cookie. A cookie set by http://www.example.com/buy.php is sent back with all requests to www.example.com, because buy.php is in the top-level directory of the web server. A cookie set by http://www.example.com/catalog/list.php is sent back with other requests in the catalog directory, such as http://www.example.com/catalog/search.php. It is also sent back with requests for pages in subdirectories of catalog, such as http://www.example.com/catalog/detailed/search.php. But it is not sent back with requests for pages above or outside the catalog directory such as http://www.example.com/sell.php or http://www.example.com/users/profile.php.

The part of the URL after the hostname (such as /buy.php, /catalog/list.php, or /users/profile.php) is called the path. To tell the web client to match against a different path when determining whether to send a cookie to the server, provide that path as the fourth argument to setcookie( ). The most flexible path to provide is /, which means "send this cookie back with all requests to the server." Example 8-5 sets a cookie with the path set to /.

Example 8-5. Setting the cookie path

setcookie('short-userid','ralph',0,'/');

In Example 8-5, the expiration time argument to setcookie( ) is 0. This tells setcookie( ) to use the default expiration time (when the web client exits) for the cookie. When you specify a path to setcookie( ), you have to fill in something for the expiration time argument. It can be a specific time value (such as time( ) + 60*60), or it can be 0 to use the default expiration time.

Setting the path to something other than / is a good idea if you are on a shared server and all of your pages are under a specific directory. For example, if your web space is under http://students.example.edu/~alice/, then you should set the cookie path to /~alice/, as shown in Example 8-6.

Example 8-6. Setting the cookie path to a specific directory

setcookie('short-userid','ralph',0,'/~alice/');

With a cookie path of /~alice/, the short-userid cookie is sent with a request to http://students.example.edu/~alice/search.php, but not with requests to other students' web pages such as http://students.example.edu/~bob/sneaky.php or http://students.example.edu/~charlie/search.php.

The last argument that affects which requests the web client decides to send a particular cookie with is the domain. The default behavior is to send cookies only with requests to the same host that set the cookie. If http://www.example.com/login.php set a cookie, then that cookie is sent back with other requests to www.example.com—not with requests to shop.example.com, www.yahoo.com, or www.example.org.

You can alter this behavior slightly. A fifth argument to setcookie( ) tells the web client to send the cookie with requests that have a hostname whose end matches the argument. The most common use of this feature is to set the cookie domain to something like .example.com. (The period at the beginning is important.) This tells the web client that the cookie should accompany future requests to the servers www.example.com, shop.example.com, testing.development.example.com, and any other server name that ends in .example.com. Example 8-7 shows how to set a cookie like this.

Example 8-7. Setting the cookie domain

setcookie('short-userid','ralph',0,'/','.example.com');

The cookie in Example 8-7 expires when the web client exits and is sent with requests in any directory (because the path is /) on any server that ends with .example.com.

The path that you provide to setcookie( ) must match the end of the name of your server. If your PHP programs are hosted on the server students.example.edu, you can't supply .yahoo.com as a cookie path and have the cookie you set sent back to all servers in the yahoo.com domain. You can, however, specify .example.edu as a cookie domain to have your cookie sent with all requests to any server in the example.edu domain.

To delete a cookie, call setcookie( ) with the name of the cookie you want to delete and the empty string as the cookie value, as shown in Example 8-8.

Example 8-8. Deleting a cookie

setcookie('short-userid','');

If you've set a cookie with nondefault values for an expiration time, path, or domain, you must provide those same values again when you delete the cookie for the cookie to be deleted properly.

Most of the time, any cookies you set are fine with the default values for expiration time, path, or domain. But understanding how these values can be changed helps you understand how PHP's sessions behavior can be customized.

Table of Contents