PHP CookBook

Recipe 8.2 Setting Cookies

8.2.1 Problem

You want to set a cookie.

8.2.2 Solution

Use setcookie( ):

setcookie('flavor','chocolate chip');

8.2.3 Discussion

Cookies are sent with the HTTP headers, so setcookie( ) must be called before any output is generated.

You can pass additional arguments to setcookie( ) to control cookie behavior. The third argument to setcookie( ) is an expiration time, expressed as an epoch timestamp. For example, this cookie expires at noon GMT on December 3, 2004:

setcookie('flavor','chocolate chip',1102075200);

If the third argument to setcookie( ) is missing (or empty), the cookie expires when the browser is closed. Also, many systems can't handle a cookie expiration time greater than 2147483647, because that's the largest epoch timestamp that fits in a 32-bit integer, as discussed in the introduction to Chapter 3.

The fourth argument to setcookie( ) is a path. The cookie is sent back to the server only when pages whose path begin with the specified string are requested. For example, the following cookie is sent back only to pages whose path begins with /products/:

setcookie('flavor','chocolate chip','','/products/');

The page that's setting this cookie doesn't have to have a URL that begins with /products/, but the following cookie is sent back only to pages that do.

The fifth argument to setcookie( ) is a domain. The cookie is sent back to the server only when pages whose hostname ends with the specified domain are requested. For example, the first cookie in the following code is sent back to all hosts in the example.com domain, but the second cookie is sent only with requests to the host jeannie.example.com:

setcookie('flavor','chocolate chip','','','.example.com');
setcookie('flavor','chocolate chip','','','jeannie.example.com');

If the first cookie's domain was just example.com instead of .example.com, it would be sent only to the single host example.com (and not www.example.com or jeannie.example.com).

The last optional argument to setcookie( ) is a flag that if set to 1, instructs the browser only to send the cookie over an SSL connection. This can be useful if the cookie contains sensitive information, but remember that the data in the cookie is stored in the clear on the user's computer.

Different browsers handle cookies in slightly different ways, especially with regard to how strictly they match path and domain strings and how they determine priority between different cookies of the same name. The setcookie( ) page of the online manual has helpful clarifications of these differences.

8.2.4 See Also

Recipe 8.3 shows how to read cookie values; Recipe 8.4 shows how to delete cookies; Recipe 8.13 explains output buffering; Recipe 8.19 shows how to avoid the "headers already sent" error message that sometimes occurs when calling setcookie( ); documentation on setcookie( ) at http://www.php.net/setcookie; an expanded cookie specification is detailed in RFC 2965 at http://www.faqs.org/rfcs/rfc2965.html.