Documentation

Cookie
in package

SMF

Uses BackwardCompatibility

Represents a cookie.

Properties

$custom_data : mixed
$default_domain : string
$default_path : string
$domain : string
$expires : int
$hash : string
$httponly : bool
$member : int
$name : string
$path : string
$samesite : string
$secure : bool
$backcompat : array<string|int, mixed>

Methods

__construct() : mixed: Constructor.
encrypt() : string: Hashes password with salt and authentication secret.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
getCookie() : object|null: Constructs an instance of this class for a cookie that was sent to the server by the client.
set() : mixed: A wrapper for setcookie that gives integration hooks access to it.
setcookie() : void: Backward compatibility wrapper for the set() method.
setDefaults() : void: Sets the values of self::$default_domain and self::$default_path.
setLoginCookie() : mixed: Sets the SMF-style login cookie and session based on the id_member and password passed.
setTFACookie() : mixed: Sets the Two Factor Authentication cookie.
urlParts() : array<string|int, mixed>: Get the domain and path for the cookie.

$custom_data


    public
        mixed
    $custom_data

Arbitrary data to include in the cookie.

MOD AUTHORS: if you want to add data to the cookie, this is the place.

$default_domain


    public
    static    string
    $default_domain

The domain of the site where the cookie is used. This is normally the domain name of the forum's site.

$default_path


    public
    static    string
    $default_path

The path to the part of the site where the cookie is used. This is normally the URL path to the forum.

$domain


    public
        string
    $domain

The domain of the site where the cookie is used. This is normally the domain name of the forum's site.

$expires


    public
        int
    $expires

UNIX timestamp of the expiry date of the cookie.

$hash


    public
        string
    $hash

Hashed password or TFA secret, or '' when forcing a logout.

Only normally used for login and TFA cookies. This is an HMAC hash of an already hashed value.

$httponly


    public
        bool
    $httponly

Whether the cookie can only be used for HTTP requests.

$member


    public
        int
    $member

The member this cookie is for.

Only normally used for login and TFA cookies. Either User::$me->id, or 0 when forcing a logout.

$name


    public
        string
    $name

The name of the cookie.

$path


    public
        string
    $path

The path to the part of the site where the cookie is used. This is normally the URL path to the forum.

$samesite


    public
        string
    $samesite

Value for the cookie's 'SameSite' attribute.

$secure


    public
        bool
    $secure

Whether the cookie must be secure.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['setLoginCookie' => 'setLoginCookie', 'setTFACookie' => 'setTFACookie', 'urlParts' => 'url_parts', 'encrypt' => 'hash_salt', 'setcookie' => 'smf_setcookie']]

BackwardCompatibility settings for this class.

__construct()

Constructor.


    public
                    __construct([string $name = null ][, mixed $custom_data = null ][, int $expires = null ][, string $domain = null ][, string $path = null ][, bool $secure = null ][, bool $httponly = null ][, string $samesite = null ]) : mixed

Parameters

$name : string = null: Name of the cookie.
$custom_data : mixed = null: Data to include in the cookie.
$expires : int = null: When the cookie expires. If not set, determined automatically.
$domain : string = null: The domain of the site where the cookie is used. If not set, determined automatically.
$path : string = null: The part of the site where the cookie is used. If not set, determined automatically.
$secure : bool = null: Whether cookie must be secure. If not set, determined by Config::$modSettings['secureCookies'].
$httponly : bool = null: Whether cookie can only be used for HTTP requests. If not set, determined by Config::$modSettings['httponlyCookies'].
$samesite : string = null: Value for the cookie's 'SameSite' attribute. If not set, determined by Config::$modSettings['samesiteCookies'].

encrypt()

Hashes password with salt and authentication secret.


    public
            static        encrypt(string $password, string $salt) : string

This is solely used for cookies.

Parameters

$password : string: The password.
$salt : string: The salt.

Return values

string —

The hashed password.

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

getCookie()

Constructs an instance of this class for a cookie that was sent to the server by the client.


    public
            static        getCookie(string $name) : object|null

Parameters

$name : string: The name of the cookie.

Return values

object|null —

An instance of this class for the cookie, or null if no cookie with that name was sent by the client.

set()

A wrapper for setcookie that gives integration hooks access to it.


    public
                    set() : mixed

setcookie()

Backward compatibility wrapper for the set() method.


    public
            static        setcookie(string $name[, string $value = '' ][, int $expires = 0 ][, string $path = '' ][, string $domain = '' ][, bool|null $secure = null ][, bool $httponly = true ][, string|null $samesite = null ]) : void

Parameters

$name : string
$value : string = ''
$expires : int = 0
$path : string = ''
$domain : string = ''
$secure : bool|null = null
$httponly : bool = true
$samesite : string|null = null

setDefaults()

Sets the values of self::$default_domain and self::$default_path.


    public
            static        setDefaults() : void

setLoginCookie()

Sets the SMF-style login cookie and session based on the id_member and password passed.


    public
            static        setLoginCookie(int $cookie_length, int $id[, string $password = '' ]) : mixed

password should be already encrypted with the cookie salt.
logs the user out if id_member is zero.
sets the cookie and session to last the number of seconds specified by cookie_length, or ends them if cookie_length is less than 0.
when logging out, if the globalCookies setting is enabled, attempts to clear the subdomain's cookie too.

Parameters

$cookie_length : int: How many seconds the cookie should last. If negative, forces logout.
$id : int: The ID of the member to set the cookie for
$password : string = '': The hashed password

setTFACookie()

Sets the Two Factor Authentication cookie.


    public
            static        setTFACookie(int $cookie_length, int $id, string $secret) : mixed

Parameters

$cookie_length : int: How long the cookie should last, in seconds.
$id : int: The ID of the member.
$secret : string: Should be a salted secret using self::encrypt().

urlParts()

Get the domain and path for the cookie.


    public
            static        urlParts(bool $local, bool $global) : array<string|int, mixed>

Normally, local and global should be the localCookies and globalCookies settings, respectively.

Uses $boardurl to determine these two things.

Parameters

$local : bool: Whether we want local cookies.
$global : bool: Whether we want global cookies.

Return values

array<string|int, mixed> —

The domain and path for the cookie, in that order.

Cookie in package SMF Uses BackwardCompatibility

Table of Contents

Properties

Methods

Properties

$custom_data

$default_domain

$default_path

$domain

$expires

$hash

$httponly

$member

$name

$path

$samesite

$secure

$backcompat

Methods

__construct()

Parameters

encrypt()

Parameters

Return values

exportStatic()

getCookie()

Parameters

Return values

set()

setcookie()

Parameters

setDefaults()

setLoginCookie()

Parameters

setTFACookie()

Parameters

urlParts()

Parameters

Return values

Cookie
in package

SMF

Uses BackwardCompatibility