Installation
Session support is enabled in PHP by default. If you would
not like to build your PHP with session support, you should
specify the --disable-session option to configure. To use
shared memory allocation (mm) for session storage configure
PHP --with-mm[=DIR] .
The windows version of PHP has built in support for this
extension. You do not need to load any additional extension
in order to use these functions.
Note: By default, all data related to a particular session
will be stored in a file in the directory specified by the
session.save_path INI option. A file for each session (regardless
of if any data is associated with that session) will be
created. This is due to the fact that a session is opened
(a file is created) but no data is even written to that
file. Note that this behavior is a side-effect of the limitations
of working with the file system and it is possible that
a custom session handler (such as one which uses a database)
does not keep track of sessions which store no data.
Runtime Configuration
The behaviour of these functions is affected by settings
in php.ini.
Table 1. Session configuration options
Name Default Changeable
session.save_path "/tmp" PHP_INI_ALL
session.name "PHPSESSID" PHP_INI_ALL
session.save_handler "files" PHP_INI_ALL
session.auto_start "0" PHP_INI_ALL
session.gc_probability "1" PHP_INI_ALL
session.gc_divisor "100" PHP_INI_ALL
session.gc_maxlifetime "1440" PHP_INI_ALL
session.serialize_handler "php" PHP_INI_ALL
session.cookie_lifetime "0" PHP_INI_ALL
session.cookie_path "/" PHP_INI_ALL
session.cookie_domain "" PHP_INI_ALL
session.cookie_secure "" PHP_INI_ALL
session.use_cookies "1" PHP_INI_ALL
session.use_only_cookies "0" PHP_INI_ALL
session.referer_check "" PHP_INI_ALL
session.entropy_file "" PHP_INI_ALL
session.entropy_length "0" PHP_INI_ALL
session.cache_limiter "nocache" PHP_INI_ALL
session.cache_expire "180" PHP_INI_ALL
session.use_trans_sid "0" PHP_INI_SYSTEM | PHP_INI_PERDIR
session.bug_compat_42 "1" PHP_INI_ALL
session.bug_compat_warn "1" PHP_INI_ALL
session.hash_function "0" PHP_INI_ALL
session.hash_bits_per_character "4" PHP_INI_ALL
url_rewriter.tags "a=href,area=href,frame=src,input=src,form=fakeentry"
PHP_INI_ALL
For further details and definition of the PHP_INI_* constants
see ini_set().
The session management system supports a number of configuration
options which you can place in your php.ini file. We will
give a short overview.
session.save_handler string
session.save_handler defines the name of the handler which
is used for storing and retrieving data associated with
a session. Defaults to files. See also session_set_save_handler().
session.save_path string
session.save_path defines the argument which is passed to
the save handler. If you choose the default files handler,
this is the path where the files are created. Defaults to
/tmp. See also session_save_path().
There is an optional N argument to this directive that
determines the number of directory levels your session files
will be spread around in. For example, setting to '5;/tmp'
may end up creating a session file and location like /tmp/4/b/1/e/3/sess_4b1e384ad74619bd212e236e52a5a174If
. In order to use N you must create all of these directories
before use. A small shell script exists in ext/session to
do this, it's called mod_files.sh. Also note that if N is
used and greater than 0 then automatic garbage collection
will not be performed, see a copy of php.ini for further
information. Also, if you use N, be sure to surround session.save_path
in "quotes" because the separator (;) is also
used for comments in php.ini.
Warning
If you leave this set to a world-readable directory, such
as /tmp (the default), other users on the server may be
able to hijack sessions by getting the list of files in
that directory.
Note: Windows users have to change this variable in order
to use PHP's session functions. Make sure to specify a valid
path, e.g.: c:/temp.
session.name string
session.name specifies the name of the session which is
used as cookie name. It should only contain alphanumeric
characters. Defaults to PHPSESSID. See also session_name().
session.auto_start boolean
session.auto_start specifies whether the session module
starts a session automatically on request startup. Defaults
to 0 (disabled).
session.serialize_handler string
session.serialize_handler defines the name of the handler
which is used to serialize/deserialize data. Currently,
a PHP internal format (name php) and WDDX is supported (name
wddx). WDDX is only available, if PHP is compiled with WDDX
support. Defaults to php.
session.gc_probability integer
session.gc_probability in conjunction with session.gc_divisor
is used to manage probability that the gc (garbage collection)
routine is started. Defaults to 1. See session.gc_divisor
for details.
session.gc_divisor integer
session.gc_divisor coupled with session.gc_probability defines
the probability that the gc (garbage collection) process
is started on every session initialization. The probability
is calculated by using gc_probability/gc_divisor, e.g. 1/100
means there is a 1% chance that the GC process starts on
each request. session.gc_divisor defaults to 100.
session.gc_maxlifetime integer
session.gc_maxlifetime specifies the number of seconds after
which data will be seen as 'garbage' and cleaned up.
Note: If you are using the default file-based session handler,
your filesystem must keep track of access times (atime).
Windows FAT does not so you will have to come up with another
way to handle garbage collecting your session if you are
stuck with a FAT filesystem or any other fs where atime
tracking is not available. Since PHP 4.2.3 it has used mtime
(modified date) instead of atime. So, you won't have problems
with filesystems where atime tracking is not available.
session.referer_check string
session.referer_check contains the substring you want to
check each HTTP Referer for. If the Referer was sent by
the client and the substring was not found, the embedded
session id will be marked as invalid. Defaults to the empty
string.
session.entropy_file string
session.entropy_file gives a path to an external resource
(file) which will be used as an additional entropy source
in the session id creation process. Examples are /dev/random
or /dev/urandom which are available on many Unix systems.
session.entropy_length integer
session.entropy_length specifies the number of bytes which
will be read from the file specified above. Defaults to
0 (disabled).
session.use_cookies boolean
session.use_cookies specifies whether the module will use
cookies to store the session id on the client side. Defaults
to 1 (enabled).
session.use_only_cookies boolean
session.use_only_cookies specifies whether the module will
only use cookies to store the session id on the client side.
Defaults to 0 (disabled, for backward compatibility). Enabling
this setting prevents attacks involved passing session ids
in URLs. This setting was added in PHP 4.3.0.
session.cookie_lifetime integer
session.cookie_lifetime specifies the lifetime of the cookie
in seconds which is sent to the browser. The value 0 means
"until the browser is closed." Defaults to 0.See
also session_get_cookie_params() and session_set_cookie_params().
session.cookie_path string
session.cookie_path specifies path to set in session_cookie.
Defaults to /.See also session_get_cookie_params() and session_set_cookie_params().
session.cookie_domain string
session.cookie_domain specifies the domain to set in session_cookie.
Default is none at all. See also session_get_cookie_params()
and session_set_cookie_params().
session.cookie_secure boolean
session.cookie_secure specifies whether cookies should only
be sent over secure connections. Defaults to off. This setting
was added in PHP 4.0.4. See also session_get_cookie_params()
and session_set_cookie_params().
session.cache_limiter string
session.cache_limiter specifies cache control method to
use for session pages (none/nocache/private/private_no_expire/public).
Defaults to nocache. See also session_cache_limiter().
session.cache_expire integer
session.cache_expire specifies time-to-live for cached session
pages in minutes, this has no effect for nocache limiter.
Defaults to 180. See also session_cache_expire().
session.use_trans_sid boolean
session.use_trans_sid whether transparent sid support is
enabled or not. Defaults to 0 (disabled).
Note: For PHP 4.1.2 or less, it is enabled by compiling
with --enable-trans-sid. From PHP 4.2.0, trans-sid feature
is always compiled.
URL based session management has additional security risks
compared to cookie based session management. Users may send
a URL that contains an active session ID to their friends
by email or users may save a URL that contains a session
ID to their bookmarks and access your site with the same
session ID always, for example.
session.bug_compat_42 boolean
PHP versions 4.2.0 and lower have an undocumented feature/bug
that allows you to to initialize a session variable in the
global scope, albeit register_globals is disabled. PHP 4.3.0
and later will warn you, if this feature is used, and if
session.bug_compat_warn is also enabled.
session.bug_compat_warn boolean
PHP versions 4.2.0 and lower have an undocumented feature/bug
that allows you to to initialize a session variable in the
global scope, albeit register_globals is disabled. PHP 4.3.0
and later will warn you, if this feature is used by enabling
both session.bug_compat_42 and session.bug_compat_warn.
session.hash_function integer
session.hash_function allows you to specify the hash algorithm
used to generate the session IDs. '0' means MD5 (128 bits)
and '1' means SHA-1 (160 bits).
Note: This was introduced in PHP 5.
session.hash_bits_per_character integer
session.hash_bits_per_character allows you to define how
many bits are stored in each character when converting the
binary hash data to something readable. The possible values
are '4' (0-9, a-f), '5' (0-9, a-v), and '6' (0-9, a-z, A-Z,
"-", ",").
Note: This was introduced in PHP 5.
url_rewriter.tags string
url_rewriter.tags specifies which HTML tags are rewritten
to include session id if transparent sid support is enabled.
Defaults to a=href,area=href,frame=src,input=src,form=fakeentry,fieldset=
Note: If you want XHTML conformity, remove the form entry
and use the <fieldset> tags around your form fields.
The track_vars and register_globals configuration settings
influence how the session variables get stored and restored.
Note: As of PHP 4.0.3, track_vars is always turned on.
