Back to Codeigniter4

Cookie Helper

user_guide_src/source/helpers/cookie_helper.rst

4.7.25.1 KB
Original Source

############# Cookie Helper #############

The Cookie Helper file contains functions that assist in working with cookies.

.. contents:: :local: :depth: 2

Loading this Helper

This helper is loaded using the following code:

.. literalinclude:: cookie_helper/001.php

Available Functions

The following functions are available:

.. php:function:: set_cookie($name[, $value = ''[, $expire = 0[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = false[, $httpOnly = false[, $sameSite = '']]]]]]]])

:param    array|Cookie|string    $name: Cookie name *or* associative array of all of the parameters available to this function *or* an instance of ``CodeIgniter\Cookie\Cookie``
:param    string    $value: Cookie value
:param    int    $expire: Number of seconds until expiration. If set to ``0`` the cookie will only last as long as the browser is open
:param    string    $domain: Cookie domain (usually: .yourdomain.com)
:param    string    $path: Cookie path
:param    string    $prefix: Cookie name prefix. If ``''``, the default from **app/Config/Cookie.php** is used
:param    bool    $secure: Whether to only send the cookie through HTTPS. If ``null``, the default from **app/Config/Cookie.php** is used
:param    bool    $httpOnly: Whether to hide the cookie from JavaScript. If ``null``, the default from **app/Config/Cookie.php** is used
:param    string    $sameSite: The value for the SameSite cookie parameter. If ``null``, the default from **app/Config/Cookie.php** is used
:rtype:    void

.. note:: Prior to v4.2.7, the default values of ``$secure`` and ``$httpOnly`` were ``false``
    due to a bug, and these values from **app/Config/Cookie.php** were never used.

This helper function gives you friendlier syntax to set browser
cookies. Refer to the :doc:`Response Library </outgoing/response>` for
a description of its use, as this function is an alias for
:php:meth:`CodeIgniter\\HTTP\\Response::setCookie()`.

.. note:: This helper function just sets browser cookies to the global response
    instance that ``Services::response()`` returns. So, if you create and
    return another response instance (e.g., if you call :php:func:`redirect()`),
    the cookies set here will not be sent automatically.

.. php:function:: get_cookie($index[, $xssClean = false[, $prefix = '']])

:param    string    $index: Cookie name
:param    bool    $xssClean: Whether to apply XSS filtering to the returned value
:param    string|null  $prefix: Cookie name prefix. If set to ``''``, the default value from **app/Config/Cookie.php** will be used. If set to ``null``, no prefix
:returns:    The cookie value or null if not found
:rtype:    mixed

.. note:: Since v4.2.1, the third parameter ``$prefix`` has been introduced and the behavior has been changed a bit due to a bug fix. See :ref:`Upgrading <upgrade-421-get_cookie>` for details.

This helper function gives you friendlier syntax to get browser
cookies. Refer to the :doc:`IncomingRequest Library </incoming/incomingrequest>` for
detailed description of its use, as this function acts very
similarly to :php:meth:`CodeIgniter\\HTTP\\IncomingRequest::getCookie()`,
except it will also prepend
the ``Config\Cookie::$prefix`` that you might've set in your
**app/Config/Cookie.php** file.

.. warning:: Using XSS filtering is a bad practice. It does not prevent XSS attacks perfectly. Using :php:func:`esc()` with the correct ``$context`` in the views is recommended.

.. php:function:: delete_cookie($name[, $domain = ''[, $path = '/'[, $prefix = '']]])

:param string $name: Cookie name
:param string $domain: Cookie domain (usually: .yourdomain.com)
:param string $path: Cookie path
:param string $prefix: Cookie name prefix
:rtype: void

Lets you delete a cookie. Unless you've set a custom path or other
values, only the name of the cookie is needed.

.. literalinclude:: cookie_helper/002.php

This function is otherwise identical to :php:func:`set_cookie()`, except that it
does not have the ``value`` and ``expire`` parameters.

This also just sets browser cookies for deleting the cookies to the global
response instance that ``Services::response()`` returns.

.. note:: When you use :php:func:`set_cookie()`,
    if the ``value`` is set to empty string and the ``expire`` is set to ``0``, the cookie will be deleted.
    If the ``value`` is set to non-empty string and the ``expire`` is set to ``0``, the cookie will only last as long as the browser is open.

You can submit an
array of values in the first parameter or you can set discrete
parameters.

.. literalinclude:: cookie_helper/003.php

.. php:function:: has_cookie(string $name[, ?string $value = null[, string $prefix = '']])

:param string $name: Cookie name
:param string|null $value: Cookie value
:param string $prefix: Cookie prefix
:rtype: bool

Checks if a cookie exists by name in the global response instance that
``Services::response()`` returns. This is an alias of
:php:meth:`CodeIgniter\\HTTP\\Response::hasCookie()`.