System Configuration Reference¶
Basics¶
In the system configuration, the settings for the cookies can be set up.
Everything takes place in one single array. You can deploy your
configurations in typo3conf/AdditionalConfiguration.php
.
The whole configurtation consists of named arrays, that define the
concrete cookie settings for one single domain each. The default
settings are defined in the key of
\AawTeam\FeCookies\Configuration\Configuration::GLOBAL_KEY
(which is
the string _global_
).
Important
Use the constant
\AawTeam\FeCookies\Configuration\Configuration::GLOBAL_KEY
instead of _global_
, to have no problems in future versions.
The default configuration is:
use \AawTeam\FeCookies\Configuration\Configuration;
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['fe_cookies'] = [
Configuration::GLOBAL_KEY => [
Configuration::OPTION_NAME => Configuration::DEFAULT_COOKIE_NAME,
Configuration::OPTION_LIFETIME => null,
Configuration::OPTION_DOMAIN => null,
Configuration::OPTION_PATH => null,
Configuration::OPTION_SECURE => null,
Configuration::OPTION_HTTPONLY => null,
],
];
Behaviour¶
For the first time when the configuration is used, it looks, whether a configuration-set is defined for the currently requested domain. If yes, the set is merged with the default set, otherwise the default set is used. Like this it becomes possible, to just configure the relevant options.
Example:
use \AawTeam\FeCookies\Configuration\Configuration;
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['fe_cookies']['example.org'] = [
Configuration::OPTION_LIFETIME => 3600,
Configuration::OPTION_SECURE => true,
];
// Will become:
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['fe_cookies']['example.org'] = [
Configuration::OPTION_NAME => Configuration::DEFAULT_COOKIE_NAME,
Configuration::OPTION_LIFETIME => 3600,
Configuration::OPTION_DOMAIN => null,
Configuration::OPTION_PATH => null,
Configuration::OPTION_SECURE => true,
Configuration::OPTION_HTTPONLY => null,
];
Options¶
Every option in a configuration set is represented by a string. To make code easier to read and future-proof, you are encouraged to use the defined constants instead of the actual strings.
Tip
The options are designed to be used with the PHP function
setcookie()
, see
https://secure.php.net/manual/en/function.setcookie.php for
detailed information.
Option
Configuration::OPTION_NAME
Data type
string
Description
\AawTeam\FeCookies\Configuration\Configuration::OPTION_NAME = 'name';
The name of the cookie. This string must contain only
US-ASCII characters, except control characters (0-31;127),
space, tab or one of the following characters:
()<>@,;:"/[]?={}
.
For more information see section “2.2 Basic Rules” in RFC 2616 (https://www.ietf.org/rfc/rfc2616.txt).
Default value: Configuration::DEFAULT_COOKIE_NAME
("tx_fecookies"
)
Option
Configuration::OPTION_LIFETIME
Data type
int/null
Description
\AawTeam\FeCookies\Configuration\Configuration::OPTION_LIFETIME = 'lifetime';
Defines the lifetime of the cookie. The expiration datetime of
the cookie will be calculated by adding
Configuration::OPTION_LIFETIME
to
$GLOBALS['ACCESS_TIME']
.
If this value is null
, the cookie will expire, when the
browser session ends.
Default value: null
Option
Configuration::OPTION_DOMAIN
Data type
string/null
Description
\AawTeam\FeCookies\Configuration\Configuration::OPTION_DOMAIN = 'domain';
Defines the (sub)domain of the cookie.
If this value is null
, the cookie will be set for the
currently requested domain.
Default value: null
Option
Configuration::OPTION_PATH
Data type
string/null
Description
\AawTeam\FeCookies\Configuration\Configuration::OPTION_PATH = 'path';
Defines the path of the cookie.
If this value is null
, the cookie will be set to the
currently requested path
(GeneralUtility::getIndpEnv('TYPO3_SITE_PATH')
), or, when
Configuration::OPTION_DOMAIN
is set, to "/"
.
Default value: null
Option
Configuration::OPTION_SECURE
Data type
string/null
Description
\AawTeam\FeCookies\Configuration\Configuration::OPTION_SECURE = 'secure';
Defines the ‘secure’ option of the cookie. It will be transferred over secure (TLS/SSL) connection only.
If this value is null
, the cookie-secure option will be
set to true
, when the current request is made over a secure
connection
(GeneralUtility::getIndpEnv('TYPO3_SSL') == true
).
Otherwise it will become false
.
Important
Setting Configuration::OPTION_SECURE
to true
in a
non-TLS/SSL environment will throw an exception!
Default value: null
Option
Configuration::OPTION_HTTPONLY
Data type
string/null
Description
\AawTeam\FeCookies\Configuration\Configuration::OPTION_HTTPONLY = 'httpOnly';
Defines the ‘httpOnly’ option of the cookie. If set to
true
, the cookie will not be accessible for JavaScript in
the frontend.
If this value is null
, the ‘httpOnly’ option will be
ignored.
Important
Setting Configuration::OPTION_HTTPONLY
to true
will
make the cookie inaccessible to JavaScript in the frontend.
The JavaScript API won’t work in that case!
Only set if you know what you do.
Default value: null