Configuration Directives

The php-memcached extension exposes several php.ini directives. These directives configure global defaults for standard Memcached instances, as well as strictly define the behavior of the built-in Session Handler.

These values can be set in your php.ini or dynamically using ini_set(), though modifying session directives at runtime must occur before session_start() is called.

Global Client Options

These options dictate the default behaviors of freshly instantiated Memcached objects. They can often be overridden on a per-instance basis via $m->setOption().

Directive	Default	Description & Best Practice
memcached.serializer	"igbinary"*	Sets the default serializer. Valid values: php, igbinary, json, json_array, msgpack. (Note: Defaults to igbinary if installed, else msgpack, else php). Best Practice: Always use igbinary in production.
memcached.compression_type	"fastlz"	Sets the default compression algorithm. Valid values: "fastlz", "zlib", "zstd". fastlz prioritizes CPU speed, zlib prioritizes size, zstd is highly optimized for both.
memcached.compression_threshold	2000	The minimum payload size (in bytes) before compression is attempted. Small payloads don't benefit from compression and waste CPU.
memcached.compression_factor	"1.3"	Minimum required space saving to keep the compressed data. 1.3 means it must save at least 23% space, otherwise the uncompressed plain text is stored.
memcached.compression_level	3	The compression intensity level (Used by Zlib and Zstd). Higher numbers = smaller cache footprint but higher CPU usage.
memcached.store_retry_count	0	Number of retries for failed store commands. Allows transparent fail-over to secondary servers if a node briefly drops.
memcached.item_size_limit	0	Client-side enforcement of maximum payload size in bytes. 0 means no limit (though the Memcached server will still reject >1MB payloads by default with RES_E2BIG).
memcached.default_consistent_hash	Off	Best Practice: Set to On. Enables Ketama consistent hashing globally, ensuring adding/removing servers doesn't invalidate your entire cache.
memcached.default_binary_protocol	Off	If On, defaults all new instances to the Binary protocol. Required for SASL authentication.
memcached.default_connect_timeout	0	Default connection timeout in milliseconds.

Session Handler Options

These directives only apply when session.save_handler = memcached is configured in php.ini.

Locking Directives

Session locking is critical to prevent concurrent AJAX requests or overlapping page loads from overwriting session data.

Directive	Default	Description
memcached.sess_locking	On	Enables or disables session locking. Turn this off only if your app handles state purely asynchronously and you understand the risks of race conditions.
memcached.sess_lock_wait_min	150	Minimum time (in milliseconds) to sleep before checking if a locked session is available.
memcached.sess_lock_wait_max	150	Maximum sleep time (in milliseconds) between retries. The wait time doubles on each retry until it hits this ceiling.
memcached.sess_lock_retries	5	Maximum number of attempts to acquire the lock before throwing a PHP Warning (Unable to clear session lock record).
memcached.sess_lock_expire	0	Maximum time (in seconds) the lock lives in memcached before being force-cleared. 0 falls back to PHP's max_execution_time.

Persistence and Routing

Directive	Default	Description
memcached.sess_persistent	Off	If On, keeps the Memcached connection alive between PHP requests. Best Practice: Turn On in high-traffic environments to save TCP handshake overhead.
memcached.sess_prefix	"memc.sess.key."	Prefix added to the session ID to create the Memcached key.
memcached.sess_consistent_hash	On	Ensures consistent hashing is used for session data across server pools.
memcached.sess_consistent_hash_type	"ketama"	Consistent hash algorithm. Options: ketama, ketama_weighted.
memcached.sess_binary_protocol	On	Forces the Binary protocol. Required for replicas, SASL, and generally higher performance.
memcached.sess_connect_timeout	1000	Socket connection timeout in milliseconds.

Replication (High Availability)

Directive	Default	Description
memcached.sess_number_of_replicas	0	Number of secondary servers to write session data to simultaneously. Provides redundancy.
memcached.sess_randomize_replica_read	Off	If On, reads session data from a random replica rather than always prioritizing the primary node. Balances read load.
memcached.sess_remove_failed_servers	Off	If On, auto-removes unresponsive servers from the session pool.
memcached.sess_server_failure_limit	0	Number of continuous connection failures required before a server is removed.

Authentication

Directive	Default	Description
memcached.sess_sasl_username	NULL	Username for SASL authentication.
memcached.sess_sasl_password	NULL	Password for SASL authentication.