Constants

The Memcached class defines numerous constants. These are passed to methods to configure behaviors, dictate fetching strategies, and evaluate the results of operations.

1. Result & Error Codes

Every operation updates the internal result code, which can be fetched via $m->getResultCode(). Checking these constants is the only bulletproof way to handle errors.

  • Memcached::RES_SUCCESS (0): The operation completed successfully.
  • Memcached::RES_NOTFOUND (16): The requested key was not found. This is a normal cache miss.
  • Memcached::RES_DATA_EXISTS (12): The key already exists. Triggered when using add() and a collision occurs.
  • Memcached::RES_NOTSTORED (14): The data was not stored. Common when a cas() operation fails because the token was invalidated.
  • Memcached::RES_E2BIG (37): The payload exceeds the Memcached server's item size limit (default 1MB).
  • Memcached::RES_BAD_KEY_PROVIDED (33): The key contains spaces, control characters, or exceeds 250 bytes.
  • Memcached::RES_PAYLOAD_FAILURE (-1001): PHP failed to serialize or compress the data before sending.

Network/Server Errors

  • Memcached::RES_FAILURE (1)
  • Memcached::RES_HOST_LOOKUP_FAILURE (2)
  • Memcached::RES_CONNECTION_FAILURE
  • Memcached::RES_WRITE_FAILURE
  • Memcached::RES_READ_FAILURE
  • Memcached::RES_TIMEOUT
  • Memcached::RES_SERVER_MARKED_DEAD

2. Behavior Options

Passed to $m->setOption(int $option, mixed $value) to alter the client's behavior.

Protocol & Network

  • Memcached::OPT_BINARY_PROTOCOL: (bool) Enables the binary protocol. Eliminates string parsing overhead on the server and is required for SASL.
  • Memcached::OPT_TCP_NODELAY: (bool) Disables Nagle's algorithm. Send requests immediately rather than waiting to buffer them into a larger packet.
  • Memcached::OPT_NO_BLOCK: (bool) Use asynchronous, non-blocking I/O.
  • Memcached::OPT_CONNECT_TIMEOUT: (int) Socket connection timeout in milliseconds.
  • Memcached::OPT_RETRY_TIMEOUT: (int) Time to wait before attempting to reconnect to a dead server.

Hashing & Distribution

  • Memcached::OPT_LIBKETAMA_COMPATIBLE: (bool) Enables standard Ketama consistent hashing. Highly recommended in all environments.
  • Memcached::OPT_DISTRIBUTION: (int) Dictates how keys are mapped to servers. Usually Memcached::DISTRIBUTION_CONSISTENT (Ketama) or Memcached::DISTRIBUTION_MODULA.
  • Memcached::OPT_HASH: (int) The hashing algorithm. E.g., Memcached::HASH_MURMUR or Memcached::HASH_MD5.

Custom PHP Behaviors

  • Memcached::OPT_PREFIX_KEY: (string) A namespace prefix transparently prepended to every key before hashing and sending to the server.
  • Memcached::OPT_SERIALIZER: (int) See Serializers below.
  • Memcached::OPT_COMPRESSION: (bool) Enable/disable transparent payload compression.
  • Memcached::OPT_COMPRESSION_TYPE: (int) See Compression Types below.

3. Serializers

Passed as the value to Memcached::OPT_SERIALIZER.

  • Memcached::SERIALIZER_PHP: The default, internal PHP serialize().
  • Memcached::SERIALIZER_IGBINARY: Highly compact, extremely fast binary serializer. Keeps PHP data structures intact.
  • Memcached::SERIALIZER_MSGPACK: Fast, cross-language binary serializer.
  • Memcached::SERIALIZER_JSON: Fast JSON serializer. Note: loses exact PHP types (e.g., objects without public properties).
  • Memcached::SERIALIZER_JSON_ARRAY: Like JSON, but forces decoding of all structures into associative arrays.

4. Compression Types

Passed as the value to Memcached::OPT_COMPRESSION_TYPE.

  • Memcached::COMPRESSION_FASTLZ: Bundled lightweight compressor. Low CPU overhead, moderate compression ratio.
  • Memcached::COMPRESSION_ZLIB: Standard Zlib. Slower CPU processing, excellent compression ratio.
  • Memcached::COMPRESSION_ZSTD: Modern standard. Blazing fast decompression, highly configurable ratio.

5. Fetch Flags

Passed as the final parameter to read methods like get() and getMulti().

  • Memcached::GET_PRESERVE_ORDER: (For getMulti). Forces the returned associative array to perfectly match the order of the array of keys requested. Keys that result in cache misses are injected as null.
  • Memcached::GET_EXTENDED: Changes the return format of get() and getMulti() from returning just the value, to returning an array structured as ['value' => mixed, 'cas' => float, 'flags' => int]. Required to perform CAS updates.