From 6991869787c27e00a2455030fdb9fd2483a54a67 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 7 Apr 2016 09:25:19 +0200 Subject: [PATCH 1/5] Documented the arguments of the Cookie class --- components/http_foundation/introduction.rst | 32 ++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/introduction.rst b/components/http_foundation/introduction.rst index 2cbae21727c..dc030a8d0a2 100644 --- a/components/http_foundation/introduction.rst +++ b/components/http_foundation/introduction.rst @@ -344,7 +344,37 @@ attribute:: The :method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::setCookie` method takes an instance of -:class:`Symfony\\Component\\HttpFoundation\\Cookie` as an argument. +:class:`Symfony\\Component\\HttpFoundation\\Cookie` as an argument. This class +takes eight arguments in its constructor: + +``$name`` + **type**: ``string`` **default**: none (this argument is mandatory) + The name of the cookie. +``$value`` + **type**: ``string`` **default**: ``null`` + The value stored in the cookie. +``$expire`` + **type**: ``int``|``string``|``DateTime``|``DateTimeInterface`` **default**: 0 + The time the cookie expires. This value can be set as a timestamp integer, + as a ``strtotime()`` valid date string (e.g. ``+1 week``), as a ``DateTime`` + object or as an object which implements ``DateTimeInterface``. + The default value is ``0``, which deletes the cookie as soon as the browser + is closed. +``$path`` + **type**: ``string`` **default**: ``/`` + The path on the server in which the cookie will be available on. The default + values makes the cookie available on any URL of the server. +``$domain`` + **type**: ``string`` **default**: ``null`` + The domain that the cookie is available to. The default value makes the cookie + available just for the current domain (and any of its subdomains). +``$secure`` + **type**: ``bool`` **default**: ``false`` + Whether the cookie should only be transmitted over a secure HTTPS connection + from the client. +``$httpOnly`` + **type**: ``bool`` **default**: ``true`` + Whether the cookie will be made accessible only through the HTTP protocol. You can clear a cookie via the :method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::clearCookie` method. From 4bcc9d31bc636e7219e93006d66eef55f20157c6 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 7 Apr 2016 09:45:58 +0200 Subject: [PATCH 2/5] Rewords and improvements --- components/http_foundation/introduction.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/http_foundation/introduction.rst b/components/http_foundation/introduction.rst index dc030a8d0a2..b6d7cee5ad5 100644 --- a/components/http_foundation/introduction.rst +++ b/components/http_foundation/introduction.rst @@ -355,9 +355,9 @@ takes eight arguments in its constructor: The value stored in the cookie. ``$expire`` **type**: ``int``|``string``|``DateTime``|``DateTimeInterface`` **default**: 0 - The time the cookie expires. This value can be set as a timestamp integer, - as a ``strtotime()`` valid date string (e.g. ``+1 week``), as a ``DateTime`` - object or as an object which implements ``DateTimeInterface``. + The time the cookie expires. This value can be a timestamp integer, + a :phpfunction:`strtotime` valid date string (e.g. ``+1 week``), a + ``DateTime`` object or an object which implements ``DateTimeInterface``. The default value is ``0``, which deletes the cookie as soon as the browser is closed. ``$path`` From dc9b8524d194c35b81f5ad84d55bd3a6648a45ae Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 10 Apr 2016 19:26:44 +0200 Subject: [PATCH 3/5] Minor fixes and improved httpOnly explanation --- components/http_foundation/introduction.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/introduction.rst b/components/http_foundation/introduction.rst index b6d7cee5ad5..84f3e94ca45 100644 --- a/components/http_foundation/introduction.rst +++ b/components/http_foundation/introduction.rst @@ -349,32 +349,42 @@ takes eight arguments in its constructor: ``$name`` **type**: ``string`` **default**: none (this argument is mandatory) + The name of the cookie. ``$value`` **type**: ``string`` **default**: ``null`` + The value stored in the cookie. ``$expire`` **type**: ``int``|``string``|``DateTime``|``DateTimeInterface`` **default**: 0 + The time the cookie expires. This value can be a timestamp integer, a :phpfunction:`strtotime` valid date string (e.g. ``+1 week``), a ``DateTime`` object or an object which implements ``DateTimeInterface``. + The default value is ``0``, which deletes the cookie as soon as the browser is closed. ``$path`` **type**: ``string`` **default**: ``/`` + The path on the server in which the cookie will be available on. The default values makes the cookie available on any URL of the server. ``$domain`` **type**: ``string`` **default**: ``null`` + The domain that the cookie is available to. The default value makes the cookie available just for the current domain (and any of its subdomains). ``$secure`` **type**: ``bool`` **default**: ``false`` + Whether the cookie should only be transmitted over a secure HTTPS connection from the client. ``$httpOnly`` **type**: ``bool`` **default**: ``true`` - Whether the cookie will be made accessible only through the HTTP protocol. + + Whether the cookie will be made accessible only through the HTTP protocol + (which include both HTTP and HTTPS requests). If ``true``, the cookie won't + be accessible via non-HTTP methods, such as JavaScript's ``document.cookie``. You can clear a cookie via the :method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::clearCookie` method. From e6a20d1a5493e94acff96feb614bac1d40339b8d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 10 Apr 2016 19:34:50 +0200 Subject: [PATCH 4/5] Minor syntax improvement --- components/http_foundation/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/http_foundation/introduction.rst b/components/http_foundation/introduction.rst index 84f3e94ca45..3af6aa899aa 100644 --- a/components/http_foundation/introduction.rst +++ b/components/http_foundation/introduction.rst @@ -356,7 +356,7 @@ takes eight arguments in its constructor: The value stored in the cookie. ``$expire`` - **type**: ``int``|``string``|``DateTime``|``DateTimeInterface`` **default**: 0 + **type**: ``int`` | ``string`` | ``DateTime`` | ``DateTimeInterface`` **default**: 0 The time the cookie expires. This value can be a timestamp integer, a :phpfunction:`strtotime` valid date string (e.g. ``+1 week``), a From 1589634dd4da9f2918dc9cbbac856ea2bfe85163 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 11 Apr 2016 10:12:08 +0200 Subject: [PATCH 5/5] More tweaks and fixes --- components/http_foundation/introduction.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/components/http_foundation/introduction.rst b/components/http_foundation/introduction.rst index 3af6aa899aa..1895b1a3f7a 100644 --- a/components/http_foundation/introduction.rst +++ b/components/http_foundation/introduction.rst @@ -345,16 +345,18 @@ The :method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::setCookie` method takes an instance of :class:`Symfony\\Component\\HttpFoundation\\Cookie` as an argument. This class -takes eight arguments in its constructor: +takes seven arguments in its constructor: ``$name`` **type**: ``string`` **default**: none (this argument is mandatory) The name of the cookie. + ``$value`` **type**: ``string`` **default**: ``null`` The value stored in the cookie. + ``$expire`` **type**: ``int`` | ``string`` | ``DateTime`` | ``DateTimeInterface`` **default**: 0 @@ -364,21 +366,25 @@ takes eight arguments in its constructor: The default value is ``0``, which deletes the cookie as soon as the browser is closed. + ``$path`` **type**: ``string`` **default**: ``/`` The path on the server in which the cookie will be available on. The default values makes the cookie available on any URL of the server. + ``$domain`` **type**: ``string`` **default**: ``null`` The domain that the cookie is available to. The default value makes the cookie available just for the current domain (and any of its subdomains). + ``$secure`` **type**: ``bool`` **default**: ``false`` Whether the cookie should only be transmitted over a secure HTTPS connection from the client. + ``$httpOnly`` **type**: ``bool`` **default**: ``true``