Функция cot_setcookie в Cotonti

Обзор функции cot_setcookie в Cotonti
Функция cot_setcookie используется для установки cookies в веб-приложении на основе фреймворка Cotonti. Она позволяет задать все необходимые параметры для правильного и безопасного использования cookies, такие как имя, значение, время истечения срока действия, путь, домен, флаг безопасности (HTTPS), и флаг HttpOnly.

 

Код функции

/**
 * Set cookie with optional HttpOnly flag
 * @param string $name The name of the cookie
 * @param string $value The value of the cookie
 * @param int $expire The time the cookie expires in unixtime
 * @param string $path The path on the server in which the cookie will be available on.
 * @param string $domain The domain that the cookie is available.
 * @param bool $secure Indicates that the cookie should only be transmitted over a secure HTTPS connection.
 *     When set to TRUE, the cookie will only be set if a secure connection exists.
 * @param bool $httponly HttpOnly flag
 * @return bool
 */
function cot_setcookie($name, $value = '', $expire = '', $path = '', $domain = '', $secure = false, $httponly = true)
{
    if (mb_strpos($domain, '.') === false) {
        // Some browsers don't support cookies for local domains
        $domain = '';
    }

    $value = (string) $value;

    $domain = (empty($domain)) ? Cot::$cfg['cookiedomain'] : $domain;
    $path = (empty($path)) ? Cot::$cfg['cookiepath'] : $path;
    $expire = (empty($expire)) ? time() + Cot::$cfg['cookielifetime'] : $expire;

    if ($domain != '' && $domain != 'localhost') {
        // Make sure www. is stripped and leading dot is added for subdomain support on some browsers
        if (mb_strtolower(mb_substr($domain, 0, 4)) == 'www.') {
            $domain = mb_substr($domain, 4);
        }
        if ($domain[0] != '.') {
            $domain = '.' . $domain;
        }
    } else {
        $domain = false;
    }

    return setcookie($name, $value, $expire, $path, $domain, $secure, $httponly);
}

 

Теперь давайте разберем каждую часть этой функции детально.

Параметры функции

$name (string):

Это имя cookie.
 Оно должно быть строкой и используется для идентификации cookie на стороне клиента (в браузере).
 
Пример: 'user_session'.
$value (string):

Это значение, которое будет сохранено в cookie.

Пример: '1234567890'.
По умолчанию пустая строка ('').
$expire (int):

Время жизни cookie в формате Unix Timestamp (в секундах с 1 января 1970 года).
Если не указано, используется значение из конфигурации Cot::$cfg['cookielifetime'].

Пример: time() + 3600 (что означает, что cookie будет действовать 1 час).
$path (string):

Путь на сервере, для которого cookie будет доступно. Обычно указывается как '/', чтобы cookie была доступна для всего сайта.
Пример: '/user' или '/'.
$domain (string):

Домен, для которого cookie будет доступно. Например, .example.com для всех поддоменов.
Пример: '.example.com'.
Если не указано, будет использовано значение из конфигурации Cot::$cfg['cookiedomain'].
$secure (bool):

Если установлено в true, cookie будет передаваться только через HTTPS (защищенное соединение). В противном случае оно будет передаваться по любому соединению.
Пример: true, если требуется только HTTPS.
$httponly (bool):

Если установлено в true, то cookie будет доступно только через HTTP-запросы (не доступно через JavaScript, что помогает предотвратить XSS-атаки).

Пример: true (использовать флаг HttpOnly).

Пошаговое объяснение работы функции cot_setcookie().

Проверка домена:

if (mb_strpos($domain, '.') === false) {
    $domain = '';
}

 

Этот блок проверяет, является ли домен корректным (содержит ли хотя бы один символ точки). Если домен не имеет точки (например, это локальный домен или ошибка), то переменной $domain присваивается пустое значение, что делает cookie доступным только для текущего домена (например, для localhost).

Приведение значения $value к строке:

$value = (string) $value;

 

Это простое преобразование гарантирует, что значение cookie всегда будет строкой, даже если изначально оно было другим типом данных.

Установка значений по умолчанию:

$domain = (empty($domain)) ? Cot::$cfg['cookiedomain'] : $domain;
$path = (empty($path)) ? Cot::$cfg['cookiepath'] : $path;
$expire = (empty($expire)) ? time() + Cot::$cfg['cookielifetime'] : $expire;

 

Если параметры $domain, $path или $expire не были переданы, то используются значения по умолчанию из конфигурации Cotonti:

Cot::$cfg['cookiedomain'] — домен для cookie.
Cot::$cfg['cookiepath'] — путь, для которого cookie будет доступно.
Cot::$cfg['cookielifetime'] — время жизни cookie.

Обработка домена для поддоменов:

if ($domain != '' && $domain != 'localhost') {
    if (mb_strtolower(mb_substr($domain, 0, 4)) == 'www.') {
        $domain = mb_substr($domain, 4);
    }
    if ($domain[0] != '.') {
        $domain = '.' . $domain;
    }
} else {
    $domain = false;
}

 

В этой части функция обрабатывает домен для корректной работы с поддоменами:

Если домен начинается с www., то он удаляется.
Если домен не начинается с точки (.), то добавляется точка перед доменом (это нужно для того, чтобы cookie была доступна на всех поддоменах, например, для .example.com).
Если домен равен localhost или пуст, то устанавливается false, и cookie будет доступно только для текущего домена.

Установка cookie:

return setcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

 

Наконец, вызывается стандартная PHP-функция setcookie, которая устанавливает cookie в браузере с переданными параметрами:

Имя cookie ($name).
Значение cookie ($value).
Время истечения ($expire).
Путь ($path).
Домен ($domain).
Флаг безопасности ($secure).
Флаг HttpOnly ($httponly).

Эта функция возвращает true или false в зависимости от того, удалось ли установить cookie.

Пример использования функции

Пример установки cookie для хранения информации о сессии:

cot_setcookie('user_session', '1234567890', time() + 3600, '/', '.example.com', true, true);

Устанавливается cookie с именем user_session.
Значение cookie — '1234567890'.
Время жизни cookie — 1 час (3600 секунд).
Путь — для всего сайта ('/').
Домен — доступно для всех поддоменов .example.com.
Используется только HTTPS (secure = true).
Доступно только через HTTP-запросы (не через JavaScript) (httponly = true).

Заключение
Функция cot_setcookie является удобным инструментом для безопасной работы с cookies в фреймворке Cotonti.

Она позволяет:

Настроить все параметры cookie, включая безопасность (HTTPS и HttpOnly).
Обрабатывать домены и пути для правильной работы с cookies на разных поддоменах.
Учитывать параметры конфигурации, чтобы поддерживать совместимость с настройками сайта.
Это делает код безопасным и гибким для использования в различных сценариях.