Настройка во время выполнения

Поведение функций зависит от установок в файле php.ini.

Опции настройки механизма сессий

Имя	По умолчанию	Место изменения	Список изменений
session.save_path	""	INI_ALL
session.name	"PHPSESSID"	INI_ALL
session.save_handler	"files"	INI_ALL
session.auto_start	"0"	INI_PERDIR
session.gc_probability	"1"	INI_ALL
session.gc_divisor	"100"	INI_ALL
session.gc_maxlifetime	"1440"	INI_ALL
session.serialize_handler	"php"	INI_ALL
session.cookie_lifetime	"0"	INI_ALL
session.cookie_path	"/"	INI_ALL
session.cookie_domain	""	INI_ALL
session.cookie_secure	"0"	INI_ALL	До PHP 7.2.0 значение по умолчанию было "".
session.cookie_httponly	"0"	INI_ALL	До PHP 7.2.0 значение по умолчанию было "".
session.cookie_samesite	""	INI_ALL	Директива доступна с PHP 7.3.0.
session.use_strict_mode	"0"	INI_ALL
session.use_cookies	"1"	INI_ALL
session.use_only_cookies	"1"	INI_ALL
session.referer_check	""	INI_ALL
session.cache_limiter	"nocache"	INI_ALL
session.cache_expire	"180"	INI_ALL
session.use_trans_sid	"0"	INI_ALL
session.trans_sid_tags	"a=href,area=href,frame=src,form="	INI_ALL	Директива доступна с PHP 7.1.0.
session.trans_sid_hosts	$_SERVER['HTTP_HOST']	INI_ALL	Директива доступна с PHP 7.1.0.
session.sid_length	"32"	INI_ALL	Директива была доступна с PHP 7.1.0 и устарела с PHP 8.4.0.
session.sid_bits_per_character	"4"	INI_ALL	Директива была доступна с PHP 7.1.0 и устарела с PHP 8.4.0.
session.upload_progress.enabled	"1"	INI_PERDIR
session.upload_progress.cleanup	"1"	INI_PERDIR
session.upload_progress.prefix	"upload_progress_"	INI_PERDIR
session.upload_progress.name	"PHP_SESSION_UPLOAD_PROGRESS"	INI_PERDIR
session.upload_progress.freq	"1%"	INI_PERDIR
session.upload_progress.min_freq	"1"	INI_PERDIR
session.lazy_write	"1"	INI_ALL
session.hash_function	"0"	INI_ALL	Удалена в PHP 7.1.0.
session.hash_bits_per_character	"4"	INI_ALL	Удалена в PHP 7.1.0.
session.entropy_file	""	INI_ALL	Удалена в PHP 7.1.0.
session.entropy_length	"0"	INI_ALL	Удалена в PHP 7.1.0.

Дополнительную информацию и определения режимов INI_* даёт раздел «Места установки параметров конфигурации».

Система управления сессиями поддерживает ряд опций, которые указываются в файле php.ini. Ниже приводится краткий обзор.

session.save_handler string

session.save_handler определяет имя обработчика, который сохраняет и извлекает данные сессии. По умолчанию значение директивы равно files. Обратите внимание, отдельные модули регистрируют свои обработчики (save_handler). Текущие зарегистрированные обработчики отображает функция phpinfo(). Смотрите также описание функции session_set_save_handler().

session.save_path string

session.save_path определяет аргумент, который передаётся в обработчик сохранения. Если выбран обработчик файлов по умолчанию, аргумент содержит путь, по которому будут создаваться файлы. Смотрите также описание функции session_save_path().

Для этой директивы можно задать необязательный аргумент N, который определяет глубину вложенных директорий, по которым будут распределены файлы сессий. Например, установка значения '5;/tmp' может расположить созданный файл сессии по такому пути: /tmp/4/b/1/e/3/sess_4b1e384ad74619bd212e236e52a5a174If. Чтобы использовать аргумент N, вначале необходимо создать все эти директории. Для этого в директории ext/session существует небольшой скрипт оболочки, который в Linux-системах называется mod_files.sh, а в системах Windows mod_files.bat. Заметьте также, что если значение аргумента N определили и оно больше 0, то сборщик мусора не будет автоматически собирать мусор, подробнее об этом сообщает файл php.ini. А также, если аргумент N задали, необходимо удостовериться, что значение директивы session.save_path указали в кавычках, поскольку разделитель (;) в файле php.ini также указывают для комментариев.

Модуль хранения файлов создаёт файлы с правами 600 по умолчанию. Значение по умолчанию можно изменить необязательным аргументом MODE: N;MODE;/path, где MODE — восьмеричное представление режима доступа к файлу. Установка аргумента MODE не влияет на обработку umask.

Внимание

Если установить в качестве значения общедоступную для чтения директорию, например, /tmp (по умолчанию), остальные пользователи сервера смогут перехватить сессию пользователя, получив список файлов в этой директории.

Предостережение

При указании уже описанного необязательного аргумента уровня вложенности директорий N, учитывают, что значение выше чем 1 или 2 недопустимо для большей части сайтов из-за того, что нужно создать много директорий: например, значение 3 означает, что в файловой системе существует (2 ** session.sid_bits_per_character) ** 3 директорий, которые могут напрасно занимать много дискового пространства и индексных дескрипторов (inodes).

Значения больше 2 для аргумента N указывают, только если совершенно уверены, что размер сайта соответствует такому требованию.

session.name string

session.name определяет название сессии, которое будет использовано как название cookies. В директиве разрешено указывать только цифры и буквы. Значение по умолчанию — PHPSESSID. Смотрите также описание функции session_name().

session.auto_start bool

session.auto_start определяет, будет ли модуль сессии запускать сессию автоматически при старте. Значение по умолчанию 0 (отключено).

session.serialize_handler string

session.serialize_handler определяет имя обработчика, который будет использован для сериализации/десериализации данных. Поддерживаются формат сериализации PHP (наименование php_serialize), внутренний формат PHP (наименование php и php_binary) и WDDX (наименование wddx). WDDX доступен только в том случае, если PHP скомпилирован с поддержкой WDDX. php_serialize использует простую функцию сериализации/десериализации для внутренних нужд и не имеет тех ограничений, какие есть у php и php_binary. Старые обработчики сериализации не могут хранить ни числовые, ни строковые индексы, содержащие специальные символы (| и !) в $_SESSION. Используйте php_serialize, чтобы обойти ошибки числовых и строковых индексов при завершении скрипта. Значение по умолчанию php.

session.gc_probability int

Директива session.gc_probability в сочетании с директивой session.gc_divisor определяет вероятность запуска функции сборщика мусора (gc, garbage collection). Значение по умолчанию равно 1. Параметр принимает только значения, которые больше или равны 0. Описание директивы session.gc_divisor даёт дополнительную информацию.

session.gc_divisor int

Директива session.gc_divisor в сочетании с директивой session.gc_probability определяет вероятность запуска функции сборщика мусора (gc, garbage collection) при каждой инициализации сессии. Вероятность рассчитывается как gc_probability/gc_divisor, то есть 1/100 означает, что функция gc запускается в одном случае из ста, или 1% при каждом запросе. Значение директивы session.gc_divisor по умолчанию равно 100. Параметр принимает только значения больше 0.

session.gc_maxlifetime int

session.gc_maxlifetime задаёт отсрочку времени в секундах, после которой данные будут рассматриваться как "мусор" и потенциально будут удалены. Сбор мусора может произойти в течение старта сессии (в зависимости от значений session.gc_probability и session.gc_divisor). По умолчанию значение 1440 (24 минуты).

Замечание: Если разные скрипты имеют разные значения session.gc_maxlifetime, но при этом одни и те же места для хранения данных сессии, то скрипт с минимальным значением уничтожит все данные. В таком случае следует использовать эту директиву вместе с session.save_path.

session.referer_check string

session.referer_check содержит подстроку, которую можно использовать при проверке HTTP Referer. Если клиентом был послан referer и подстрока не была выявлена, то идентификатор сессии будет помечен как недействительный. По умолчанию используется пустая строка.

session.entropy_file string

session.entropy_file содержит путь к ресурсу (файлу), используемому как дополнительный источник энтропии в процессе создания идентификатора сессии. Например, /dev/random или /dev/urandom, которые доступны на многих Unix-системах. Эта возможность также поддерживается в Windows. Указание ненулевого значения в session.entropy_length предписывает PHP использовать в качестве источника энтропии Windows Random API.

Замечание: Удалено в PHP 7.1.0. session.entropy_file имеет значение по умолчанию равное /dev/urandom или /dev/arandom, если они доступны.

session.entropy_length int

session.entropy_length определяет количество байт, которые будут прочитаны из вышеуказанного файла. По умолчанию 32. Удалено в PHP 7.1.0.

session.use_strict_mode bool

session.use_strict_mode определяет будет ли модуль использовать режим строгого идентификатора (ID). Если от браузера получен неопределённый ID, то браузеру будет отправлен новый ID. Таким образом приложения защищаются от фиксации сессии с помощью строгого режима. По умолчанию 0 (отключено).

Замечание: Включение session.use_strict_mode является обязательным для общей безопасности сессии. Всем сайтам рекомендуется её включать. Смотрите примеры session_create_id().

Внимание

Если пользовательский обработчик сессии, зарегистрированный с помощью session_set_save_handler(), не реализует SessionUpdateTimestampHandlerInterface::validateId() и не предоставляет callback-функцию validate_sid, соответственно, режим строгого идентификатора сессии будет отключён, независимо от значения этой директивы. Особо обратите внимание, что SessionHandler не реализует SessionHandler::validateId().

session.use_cookies bool

session.use_cookies определяет, будет ли модуль использовать cookies для хранения идентификатора сессии на стороне клиента. По умолчанию 1 (включено).

session.use_only_cookies bool

session.use_only_cookies определяет, будет ли модуль использовать только cookies для хранения идентификатора сессии на стороне клиента. Включение этого параметра предотвращает атаки с передачей идентификаторов сессии в URL-адресах. Значение по умолчанию 1 (включено).

session.cookie_lifetime int

session.cookie_lifetime указывает время жизни cookies, отправляемого в браузер клиента, в секундах. Значение 0 означает, что cookies будут валидны до закрытия браузера. По умолчанию равно 0. Смотрите также session_get_cookie_params() и session_set_cookie_params().

Замечание: Отметка окончания времени устанавливается по отношению к серверному времени, которое не обязательно совпадает с временем в браузере клиента.

session.cookie_path string

session.cookie_path определяет устанавливаемый путь в сессионной cookie. По умолчанию /. Смотрите также session_get_cookie_params() и session_set_cookie_params().

session.cookie_domain string

session.cookie_domain определяет устанавливаемый домен в сессионной cookie. В соответствии со спецификацией нет смысла дополнительно указывать имя хоста, который сгенерировал cookies. Смотрите также session_get_cookie_params() и session_set_cookie_params().

session.cookie_secure bool

session.cookie_secure указывает, должны ли cookies передаваться только через защищённое соединение. Когда для этой настройки установлено значение on, сессии работают только с HTTPS-соединениями. Если значение off, то сессии работают и с HTTP-, и с HTTPS-соединениями. Значение по умолчанию off. Смотрите также описание функций session_get_cookie_params() и session_set_cookie_params().

session.cookie_httponly bool

Отметка, согласно которой доступ к cookie с идентификатором сессии может быть получен только через HTTP-протокол. Это означает, что cookie не будет доступна через скриптовые языки, такие как JavaScript. Данная настройка позволяет эффективно защитить от XSS-атак (к сожалению, эта функция поддерживается не всеми браузерами).

session.cookie_samesite string

Позволяет серверам утверждать, что cookie не должен отправляться вместе с межсайтовыми запросами. Это утверждение позволяет браузерам пользователей снизить риск утечки информации из разных источников и обеспечивает определённую защиту от подделки кросс-доменных запросов. Обратите внимание, что это поддерживают не все браузеры. Пустое значение означает, что атрибут cookie сайта не будет установлен. Lax и Strict означают, что cookie не будет отправлен для кросс-доменных POST-запросов; Lax отправит cookie для междоменных GET-запросов, а Strict не будет этого делать.

session.cache_limiter string

session.cache_limiter определяет режим кеширования, используемого для страниц сессий. Может принимать одно из следующих значений: nocache, private, private_no_expire или public. По умолчанию nocache. Подробнее о данных значениях смотрите в session_cache_limiter().

session.cache_expire int

session.cache_expire указывает время жизни кешированных страниц сессий в минутах, это никак не влияет на ограничитель nocache. По умолчанию 180. Смотрите также session_cache_expire().

session.use_trans_sid bool

session.use_trans_sid указывает, используется ли прозрачная поддержка sid или нет. По умолчанию 0 (отключено).

Замечание: Управление сессией на основе URL имеет дополнительные риски безопасности по сравнению с управлением на основе cookies. В качестве примера можно упомянуть такие ситуации, когда пользователи могут отправить URL, содержащий идентификатор активной сессии, своим друзьям по электронной почте или сохранить ссылку с идентификатором в закладках и все время посещать сайт с одним и тем же идентификатором. Начиная с PHP 7.1.0, полный путь URL, то есть https://php.net/, обрабатывается "trans sid". Раньше PHP обрабатывал только относительный URL-адреса. Перезапись целевого хоста задаётся session.trans_sid_hosts.

session.trans_sid_tags string

session.trans_sid_tags задаёт перезаписываемые теги HTML для включения идентификатора сессии когда включена поддержка прозрачных "sid". По умолчанию a=href,area=href,frame=src,input=src,form= form — специальных тег. <input hidden="session_id" name="session_name"> добавляется в форму.

Замечание: До PHP 7.1.0 для этого использовался url_rewriter.tags. С PHP 7.1.0, fieldset больше не считается за специальный тег.

session.trans_sid_hosts string

session.trans_sid_hosts задаёт, какие хосты будут перезаписаны для включения идентификатора сессии, когда включена поддержка прозрачных "sid". По умолчанию $_SERVER['HTTP_HOST']. Несколько хостов можно указать через запятую. Не допускается вставлять пробелы между хостами. Так правильно: php.net,wiki.php.net,bugs.php.net.

session.sid_length int

session.sid_length позволяет указать длину идентификатора сессии. Это значение должно быть в диапазоне 22-256. По умолчанию 32. Если вам нужна совместимость, указывайте 32, 40 и т. д. Более длинные идентификаторы сложнее подобрать. Рекомендуется использовать длину не менее 32.

Подсказка

Заметки по совместимости: Используйте 32 для session.hash_function=0 (MD5) и session.hash_bits_per_character=4, session.hash_function=1 (SHA1) и session.hash_bits_per_character=6. 26 для session.hash_function=0 (MD5) и session.hash_bits_per_character=5. 22 для session.hash_function=0 (MD5) и session.hash_bits_per_character=6. Вы должны сконфигурировать INI-настройки таким образом, чтобы идентификатор сессии состоял как минимум из 128 бит. Не забудьте задать соответствующие значения для session.sid_bits_per_character, иначе ваши идентификаторы будут слабыми.

Замечание: Эта настройка появилась в PHP 7.1.0.

session.sid_bits_per_character int

session.sid_bits_per_character позволяет задать количество бит в одном символе идентификатора сессии. Доступные значения '4' (0-9, a-f), '5' (0-9, a-v), и '6' (0-9, a-z, A-Z, "-", ","). По умолчанию 4. Чем больше бит, тем сильнее идентификатор сессии. В большинстве окружений рекомендуется 5.

Замечание: Эта настройка появилась в PHP 7.1.0.

session.hash_function mixed

session.hash_function позволяет указать алгоритм хеширования, используемый для генерации идентификатора сессии. '0' означает MD5 (128 bits), а '1' означает SHA-1 (160 bits).

Возможно указать любой из алгоритмов, предусмотренных модулем hash (если он доступен), например, sha512 или whirlpool. Полный список алгоритмов может быть получен с помощью функции hash_algos().

Замечание: Удалена в PHP 7.1.0.

session.hash_bits_per_character int

session.hash_bits_per_character позволяет указать сколько бит хранится в каждом символе при преобразовании бинарного представления во что-либо более удобочитаемое. Возможные значения: '4' (0-9, a-f), '5' (0-9, a-v) и '6' (0-9, a-z, A-Z, "-", ",").

Замечание: Удалена в PHP 7.1.0.

session.upload_progress.enabled bool

Включает отслеживание прогресса загрузки файлов и заполнение соответствующей переменной в массиве $_SESSION. По умолчанию 1, включено.

session.upload_progress.cleanup bool

Чистка информации о прогрессе загрузки файлов по завершении обработки POST-данных (то есть когда загрузка завершена). По умолчанию 1, включено.

Замечание: Строго рекомендуется не отключать эту опцию.

session.upload_progress.prefix string

Префикс, используемый для ключа прогресса загрузки в массиве $_SESSION. Для обеспечения уникальности данный ключ будет присоединён к значению $_POST[ini_get("session.upload_progress.name")]. По умолчанию равен "upload_progress_".

session.upload_progress.name string

Имя ключа, используемого в массиве $_SESSION, для хранения информации о прогрессе. Смотрите также директиву session.upload_progress.prefix. Если элемент $_POST[ini_get("session.upload_progress.name")] не передан, прогресс загрузки данного файла не будет отслеживаться. По умолчанию "PHP_SESSION_UPLOAD_PROGRESS".

session.upload_progress.freq mixed

Определяет частоту обновления информации о прогрессе загрузки. Можно указать значение в байтах (то есть "обновлять информацию о прогрессе каждые 100 байт") или в процентах (то есть "обновлять информацию о прогрессе после получения 1% данных от размера файла"). По умолчанию "1%".

session.upload_progress.min_freq int

Минимальная задержка между обновлениями, в секундах. По умолчанию "1" (одна секунда).

session.lazy_write bool

Если session.lazy_write установлен в 1, то данные сессии будут перезаписываться только при их изменении. По умолчанию 1, включено.

Прогресс загрузки файлов не будет обрабатываться, если не включена опция session.upload_progress.enabled и не установлена переменная $_POST[ini_get("session.upload_progress.name")]. Подробнее об этом смотрите в главе "Отслеживание прогресса загрузки файлов с помощью сессий".