philip Tue Jan 21 16:26:43 2003 EDT
Modified files:
/phpdoc/en/reference/http/functions setcookie.xml
Log:
Moved and greatly expanded parameter information into a table. And mention
register_globals and $_REQUEST as well as print_r($_COOKIE) for debugging.
Index: phpdoc/en/reference/http/functions/setcookie.xml
diff -u phpdoc/en/reference/http/functions/setcookie.xml:1.14
phpdoc/en/reference/http/functions/setcookie.xml:1.15
--- phpdoc/en/reference/http/functions/setcookie.xml:1.14 Mon Jan 20 13:46:35
2003
+++ phpdoc/en/reference/http/functions/setcookie.xml Tue Jan 21 16:26:43 2003
@@ -1,5 +1,6 @@
+
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.14 $ -->
+<!-- $Revision: 1.15 $ -->
<!-- splitted from ./en/functions/http.xml, last change in rev 1.2 -->
<refentry id="function.setcookie">
<refnamediv>
@@ -33,17 +34,105 @@
All the arguments except the <parameter>name</parameter> argument
are optional. If only the name argument is present, the cookie
by that name will be deleted from the remote client. You may
- also replace any argument with an empty string
+ also replace an argument with an empty string
(<emphasis>""</emphasis>) in order to skip that
- argument. The <parameter>expire</parameter> and
- <parameter>secure</parameter> arguments are integers and cannot
- be skipped with an empty string. Use a zero
- (<emphasis>0</emphasis>) instead. The
- <parameter>expire</parameter> argument is a regular Unix time
- integer as returned by the <function>time</function> or
- <function>mktime</function> functions. The
- <parameter>secure</parameter> indicates that the cookie should
- only be transmitted over a secure HTTPS connection.
+ argument. Because the <parameter>expire</parameter> and
+ <parameter>secure</parameter> arguments are integers, they cannot
+ be skipped with an empty string, use a zero (<emphasis>0</emphasis>)
+ instead. The following table explains each parameter of
+ <function>setcookie</function>:
+ </para>
+ <para>
+ <table>
+ <title><function>setcookie</function> parameters explained</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Parameter</entry>
+ <entry>Description</entry>
+ <entry>Examples</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><parameter>name</parameter></entry>
+ <entry>
+ The name of the cookie.
+ </entry>
+ <entry>
+ 'cookiename' is called as <varname>$_COOKIE['cookiename']</varname>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>value</parameter></entry>
+ <entry>
+ The value of the cookie. This value is stored on the clients
+ computer; do not store sensitive information.
+ </entry>
+ <entry>
+ Assuming the <parameter>name</parameter> is 'cookiename', this
+ value is retrieved through <varname>$_COOKIE['cookiename']</varname>
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>expire</parameter></entry>
+ <entry>
+ The time the cookie expires. This is a unix timestamp so is
+ in number of seconds since the epoch. In otherwords, you'll
+ most likely set this with the <function>time</function> function
+ plus the number of seconds before you want it to expire. Or
+ you might use <function>mktime</function>.
+ </entry>
+ <entry>
+ <literal>time()+60*60*24*30</literal> will set the cookie to
+ expire in 30 days. If not set, the cookie will expire at
+ the end of the session (when the browser closes).
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>path</parameter></entry>
+ <entry>
+ The path on the server in which the cookie will be available on.
+ </entry>
+ <entry>
+ If set to <literal>'/'</literal>, the cookie will be available
+ within the entire <parameter>domain</parameter>. If set to
+ <literal>'/foo/'</literal>, the cookie will only be available
+ within the <literal>/foo/</literal> directory and all
+ sub-directories such as <literal>/foo/bar/</literal> of
+ <parameter>domain</parameter>. The default value is the
+ current directory that the cookie is being set in.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>domain</parameter></entry>
+ <entry>
+ The domain that the cookie is available.
+ </entry>
+ <entry>
+ To make the cookie available on all subdomains of example.com
+ then you'd set it to <literal>'.example.com'</literal>. The
+ <literal>.</literal> is not required but makes it compatable
+ with more browsers. Setting it to <literal>www.example.com</literal>
+ will make the cookie only available in the <literal>www</literal>
+ subdomain.
+ </entry>
+ </row>
+ <row>
+ <entry><parameter>secure</parameter></entry>
+ <entry>
+ Indicates that the cookie should only be transmitted over a
+ secure HTTPS connection. When set to <literal>1</literal>, the
+ cookie will only be set if a secure connection exists. The default
+ is <literal>0</literal>.
+ </entry>
+ <entry>
+ <literal>0</literal> or <literal>1</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</para>
<para>
Once the cookies have been set, they can be accessed on the next page load
@@ -52,8 +141,18 @@
<link linkend="language.variables.superglobals">autoglobals</link>
such as <varname>$_COOKIE</varname> became available in PHP
<ulink url="&url.php.release4.1.0;">4.1.0</ulink>.
- <varname>$HTTP_COOKIE_VARS</varname> has existed since PHP 3.
+ <varname>$HTTP_COOKIE_VARS</varname> has existed since PHP 3. Cookie
+ values also exist in <link linkend="reserved.variables.request">
+ $_REQUEST</link>.
</para>
+ <note>
+ <para>
+ If the PHP directive <link
+linkend="ini.register-globals">register_globals</link>
+ is set to <literal>on</literal> then cookie values will also be made into
+ variables. In our examples below, <varname>$TextCookie</varname> will
+ exist. It's recommended to use <varname>$_COOKIE</varname>.
+ </para>
+ </note>
<para>
Common Pitfalls:
<itemizedlist>
@@ -63,7 +162,8 @@
the cookie should be visible for. To test if a cookie was successfully
set, check for the cookie on a next loading page before the cookie
expires. Expire time is set via the <parameter>expire</parameter>
- parameter.
+ parameter. A nice way to debug the existence of cookies is by
+ simply calling <literal>print_r($_COOKIE);</literal>.
</simpara>
</listitem>
<listitem>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
