From: Michael Wallner <mike@php.net>
Date: Tue, 5 Nov 2013 16:06:20 +0000 (+0100)
Subject: cookie
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=33f241f193fcbb16d297441c793a0aa0341f48cb;p=mdref%2Fmdref-http

cookie
---

diff --git a/http/Cookie.md b/http/Cookie.md
new file mode 100644
index 0000000..e0ca8cb
--- /dev/null
+++ b/http/Cookie.md
@@ -0,0 +1,16 @@
+# class http\Cookie extends http\Object
+
+A class representing a lisdt of cookies with specific attributes.
+
+## Constants:
+
+* PARSE_RAW  
+  Do not decode cookie contents.
+* SECURE  
+  The cookies' flags have the secure attribute set.
+* HTTPONLY  
+  The cookies' flags have the httpOnly attribute set.
+
+## Properties:
+
+None.
diff --git a/http/Cookie/.md b/http/Cookie/.md
new file mode 100644
index 0000000..e69de29
diff --git a/http/Cookie/__construct.md b/http/Cookie/__construct.md
new file mode 100644
index 0000000..ac0cf01
--- /dev/null
+++ b/http/Cookie/__construct.md
@@ -0,0 +1,63 @@
+# void http\Cookie::__construct([mixed $cookies = NULL[, int $flags = 0[, array $allowed_extras = NULL]]])
+
+Create a new cookie list.
+
+## Params:
+
+* Optional mixed $cookies = NULL  
+  The string or list of cookies to parse or set.
+* Optional int $flags = 0  
+  Parse flags. See http\Cookie::PARSE_* constants.
+* Optional array $allowed_extras = NULL  
+  List of extra attribute names to recognize.
+
+## Throws:
+
+* http\Exception.
+
+## Example:
+
+    <?php
+    $cookie = new http\Cookie("c1=v1; c2=v2; extra=foo; ".
+        "expires=Thu, Nov  7 2013 10:00:00 GMT; path=/a/b/c", 
+        0, ["extra"]);
+    var_dump([
+        "cookies" => $cookie->getCookies(),
+        "extras" => $cookie->getExtras(),
+        "expires" => $cookie->getExpires(),
+        "max-age" => $cookie->getMaxAge(),
+        "domain" => $cookie->getDomain(),
+        "path" => $cookie->getPath(),
+        "flags" => $cookie->getFlags(),
+        "string" => (string) $cookie
+    ]);
+    ?>
+
+Yields:
+
+    array(8) {
+      ["cookies"]=>
+      array(2) {
+        ["c1"]=>
+        string(2) "v1"
+        ["c2"]=>
+        string(2) "v2"
+      }
+      ["extras"]=>
+      array(1) {
+        ["extra"]=>
+        string(3) "foo"
+      }
+      ["expires"]=>
+      int(1383818400)
+      ["max-age"]=>
+      int(-1)
+      ["domain"]=>
+      NULL
+      ["path"]=>
+      string(6) "/a/b/c"
+      ["flags"]=>
+      int(0)
+      ["string"]=>
+      string(77) "c1=v1; c2=v2; path=/a/b/c; expires=Thu, 07 Nov 2013 10:00:00 GMT; extra=foo; "
+    }
diff --git a/http/Cookie/__toString.md b/http/Cookie/__toString.md
new file mode 100644
index 0000000..bab217f
--- /dev/null
+++ b/http/Cookie/__toString.md
@@ -0,0 +1,21 @@
+# string http\Cookie::__toString()
+
+String cast handler. Alias of http\Cookie::toString().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the cookie(s) represented as string.
+
+## Example:
+
+    <?php
+    echo new http\Cookie("country=us; httpOnly; secure; path=/; domain=.php.net");
+    ?>
+
+Yields:
+
+    country=us; domain=.php.net; path=/; secure; httpOnly; 
diff --git a/http/Cookie/addCookie.md b/http/Cookie/addCookie.md
new file mode 100644
index 0000000..e2c1396
--- /dev/null
+++ b/http/Cookie/addCookie.md
@@ -0,0 +1,15 @@
+# http\Cookie http\Cookie::addCookie(string $cookie_name, string $cookie_value)
+
+Add a cookie.
+See http\Cookie::setCookie() and http\Cookie::addCookies().
+
+## Params:
+
+* string $cookie_name  
+  The key of the cookie.
+* string $cookie_value  
+  The value of the cookie.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/addCookies.md b/http/Cookie/addCookies.md
new file mode 100644
index 0000000..70e727f
--- /dev/null
+++ b/http/Cookie/addCookies.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::addCookies(array $cookies)
+
+(Re)set the cookies.
+See http\Cookie::setCookies().
+
+## Params:
+
+* array $cookies  
+  Add cookies of this array of form ["name" => "value"].
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/addExtra.md b/http/Cookie/addExtra.md
new file mode 100644
index 0000000..4d7716e
--- /dev/null
+++ b/http/Cookie/addExtra.md
@@ -0,0 +1,15 @@
+# http\Cookie http\Cookie::addExtra(string $extra_name, string $extra_value)
+
+Add an extra attribute to the cookie list.
+See http\Cookie::setExtra().
+
+## Params:
+
+* string $extra_name  
+  The key of the extra attribute.
+* string $extra_value  
+  The value of the extra attribute.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/addExtras.md b/http/Cookie/addExtras.md
new file mode 100644
index 0000000..be04741
--- /dev/null
+++ b/http/Cookie/addExtras.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::addExtras(array $extras)
+
+Add several extra attributes.
+See http\Cookie::addExtra().
+
+## Params:
+
+* array $extras  
+  A list of extra attributes of the form ["key" => "value"].
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/getCookie.md b/http/Cookie/getCookie.md
new file mode 100644
index 0000000..4100648
--- /dev/null
+++ b/http/Cookie/getCookie.md
@@ -0,0 +1,14 @@
+# string http\Cookie::getCookie(string $cookie_name)
+
+Retrieve a specific cookie value.
+See http\Cookie::setCookie().
+
+## Params:
+
+* string $cookie_name  
+  The key of the cookie to look up.
+
+## Returns:
+
+* string, the cookie value.
+* NULL, if $cookie_name could not be found.
diff --git a/http/Cookie/getCookies.md b/http/Cookie/getCookies.md
new file mode 100644
index 0000000..80ec619
--- /dev/null
+++ b/http/Cookie/getCookies.md
@@ -0,0 +1,12 @@
+# array http\Cookie::getCookies()
+
+Get the list of cookies.
+See http\Cookie::setCookies().
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the list of cookies of form ["name" => "value"].
diff --git a/http/Cookie/getDomain.md b/http/Cookie/getDomain.md
new file mode 100644
index 0000000..01d357e
--- /dev/null
+++ b/http/Cookie/getDomain.md
@@ -0,0 +1,12 @@
+# string http\Cookie::getDomain()
+
+Retrive the effective domain of the cookie list.
+See http\Cookie::setDomain().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the effective domain.
diff --git a/http/Cookie/getExpires.md b/http/Cookie/getExpires.md
new file mode 100644
index 0000000..46300a5
--- /dev/null
+++ b/http/Cookie/getExpires.md
@@ -0,0 +1,14 @@
+# int http\Cookie::getExpires()
+
+Get the currently set expires attribute.
+See http\Cookie::setExpires().
+
+> **Note:** A return value of -1 means that the attribute is not set.
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, the currently set expires attribute as seconds since the epoch.
diff --git a/http/Cookie/getExtra.md b/http/Cookie/getExtra.md
new file mode 100644
index 0000000..7f5abc9
--- /dev/null
+++ b/http/Cookie/getExtra.md
@@ -0,0 +1,13 @@
+# string http\Cookie::getExtra(string $name)
+
+Retrieve an extra attribute.
+See http\Cookie::setExtra().
+
+## Params:
+
+* string $name  
+  The key of the extra attribute.
+
+## Returns:
+
+* string, the value of the extra attribute.
diff --git a/http/Cookie/getExtras.md b/http/Cookie/getExtras.md
new file mode 100644
index 0000000..efb4936
--- /dev/null
+++ b/http/Cookie/getExtras.md
@@ -0,0 +1,12 @@
+# array http\Cookie::getExtras()
+
+Retrieve the list of extra attributes.
+See http\Cookie::setExtras().
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the list of extra attributes of the form ["key" => "value"].
diff --git a/http/Cookie/getFlags.md b/http/Cookie/getFlags.md
new file mode 100644
index 0000000..dadbd43
--- /dev/null
+++ b/http/Cookie/getFlags.md
@@ -0,0 +1,12 @@
+# int http\Cookie::getFlags()
+
+Get the currently set flags.
+See http\Cookie::SECURE and http\Cookie::HTTPONLY constants.
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, the currently set flags bitmask.
diff --git a/http/Cookie/getMaxAge.md b/http/Cookie/getMaxAge.md
new file mode 100644
index 0000000..88c476f
--- /dev/null
+++ b/http/Cookie/getMaxAge.md
@@ -0,0 +1,14 @@
+# int http\Cookie::getMaxAge()
+
+Get the currently set max-age attribute of the cookie list.
+See http\Cookie::setMaxAge().
+
+> **Note:** A return value of -1 means that the attribute is not set.
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, the currently set max-age.
diff --git a/http/Cookie/getPath.md b/http/Cookie/getPath.md
new file mode 100644
index 0000000..7cfe88d
--- /dev/null
+++ b/http/Cookie/getPath.md
@@ -0,0 +1,12 @@
+# string http\Cookie::getPath()
+
+Retrieve the path the cookie(s) of this cookie list are effective at.
+See http\Cookie::setPath().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the effective path.
diff --git a/http/Cookie/setCookie.md b/http/Cookie/setCookie.md
new file mode 100644
index 0000000..5b26502
--- /dev/null
+++ b/http/Cookie/setCookie.md
@@ -0,0 +1,17 @@
+# http\Cookie http\Cookie::setCookie(string $cookie_name, string $cookie_value)
+
+(Re)set a cookie.
+See http\Cookie::addCookie() and http\Cookie::setCookies().
+
+> **Note:** The cookie will be deleted from the list if $cookie_value is NULL.
+
+## Params:
+
+* string $cookie_name  
+  The key of the cookie.
+* string $cookie_value  
+  The value of the cookie.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setCookies.md b/http/Cookie/setCookies.md
new file mode 100644
index 0000000..d518aa2
--- /dev/null
+++ b/http/Cookie/setCookies.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::setCookies([array $cookies = NULL])
+
+(Re)set the cookies.
+See http\Cookie::addCookies().
+
+## Params:
+
+* Optional array $cookies = NULL  
+  Set the cookies to this array.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setDomain.md b/http/Cookie/setDomain.md
new file mode 100644
index 0000000..ed7f8b9
--- /dev/null
+++ b/http/Cookie/setDomain.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::setDomain([string $value = NULL])
+
+Set the effective domain of the cookie list.
+See http\Cookie::setPath().
+
+## Params:
+
+* Optional string $value = NULL  
+  The domain the cookie(s) belong to.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setExpires.md b/http/Cookie/setExpires.md
new file mode 100644
index 0000000..9878e88
--- /dev/null
+++ b/http/Cookie/setExpires.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::setExpires([int $value = -1])
+
+Set the traditional expires timestamp.
+See http\Cookie::setMaxAge() for a safer alternative.
+
+## Params:
+
+* Optional int $value = -1  
+  The expires timestamp as seconds since the epoch.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setExtra.md b/http/Cookie/setExtra.md
new file mode 100644
index 0000000..6308f63
--- /dev/null
+++ b/http/Cookie/setExtra.md
@@ -0,0 +1,17 @@
+# http\Cookie http\Cookie::setExtra(string $extra_name[, string $extra_value = NULL])
+
+(Re)set an extra attribute.
+See http\Cookie::addExtra().
+
+> **Note:** The attribute will be removed from the extras list if $extra_value is NULL.
+
+## Params:
+
+* string $extra_name  
+  The key of the extra attribute.
+* Optional string $extra_value  
+  The value of the extra attribute.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setExtras.md b/http/Cookie/setExtras.md
new file mode 100644
index 0000000..b77caee
--- /dev/null
+++ b/http/Cookie/setExtras.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::setExtras([array $extras = NULL])
+
+(Re)set the extra attributes.
+See http\Cookie::addExtras().
+
+## Params:
+
+* Optional array $extras = NULL  
+  Set the extra attributes to this array.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setFlags.md b/http/Cookie/setFlags.md
new file mode 100644
index 0000000..818eb42
--- /dev/null
+++ b/http/Cookie/setFlags.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::setFlags([int $value = 0])
+
+Set the flags to specified $value.
+See http\Cookie::SECURE and http\Cookie::HTTPONLY constants.
+
+## Params:
+
+* Optional int $value = 0  
+  The new flags bitmask.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setMaxAge.md b/http/Cookie/setMaxAge.md
new file mode 100644
index 0000000..724cc54
--- /dev/null
+++ b/http/Cookie/setMaxAge.md
@@ -0,0 +1,14 @@
+# http\Cookie http\Cookie::setMaxAge([int $value = -1])
+
+Set the maximum age the cookie may have on the client side.
+This is a client clock departure safe alternative to the "expires" attribute.
+See http\Cookie::setExpires().
+
+## Params:
+
+* Optional int $value = -1  
+  The max-age in seconds.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/setPath.md b/http/Cookie/setPath.md
new file mode 100644
index 0000000..fa04628
--- /dev/null
+++ b/http/Cookie/setPath.md
@@ -0,0 +1,13 @@
+# http\Cookie http\Cookie::setPath([string $path = NULL])
+
+Set the path the cookie(s) of this cookie list should be effective at.
+See http\Cookie::setDomain().
+
+## Params:
+
+* Optional string $path = NULL  
+  The URL path the cookie(s) should take effect within.
+
+## Returns:
+
+* http\Cookie, self.
diff --git a/http/Cookie/toArray.md b/http/Cookie/toArray.md
new file mode 100644
index 0000000..4c1e9d2
--- /dev/null
+++ b/http/Cookie/toArray.md
@@ -0,0 +1,41 @@
+# array http\Cookie::toArray()
+
+Get the cookie list as array.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the cookie list as array.
+
+## Example:
+
+    <?php
+    $cookie = new http\Cookie("country=us; secure");
+    var_dump($cookie->toArray());
+    ?>
+
+Yields:
+
+    array(7) {
+      ["cookies"]=>
+      array(1) {
+        ["country"]=>
+        string(2) "us"
+      }
+      ["extras"]=>
+      array(0) {
+      }
+      ["flags"]=>
+      int(16)
+      ["expires"]=>
+      int(-1)
+      ["max-age"]=>
+      int(-1)
+      ["path"]=>
+      string(0) ""
+      ["domain"]=>
+      string(0) ""
+    }
diff --git a/http/Cookie/toString.md b/http/Cookie/toString.md
new file mode 100644
index 0000000..016a187
--- /dev/null
+++ b/http/Cookie/toString.md
@@ -0,0 +1,12 @@
+# string http\Cookie::toString()
+
+Retrieve the string representation of the cookie list.
+See http\Cookie::toArray().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the cookie list as string.