Memcached Cache Adapter

This adapter stores the values in-memory using one (or more) Memcached server instances. Unlike the APCu adapter, and similarly to the Redis adapter, it is not limited to the current server's shared memory; you can store contents independent of your PHP environment. The ability to utilize a cluster of servers to provide redundancy and/or fail-over is also available.

このアダプターは、1 つ (または複数) の Memcached サーバーインスタンスを使用してメモリ内に値を格納します。 APCu アダプタとは異なり、Redis アダプタと同様に、現在のサーバーの共有メモリに限定されません。 PHP 環境から独立してコンテンツを保存できます。サーバーのクラスターを利用して、冗長性やフェイルオーバーを提供する機能も利用できます。

Caution

注意

Requirements: The Memcached PHP extension as well as a Memcached server must be installed, active, and running to use this adapter. Version 2.2 or greater of the Memcached PHP extension is required for this adapter.

要件: このアダプターを使用するには、Memcached PHP 拡張機能と Memcached サーバーがインストールされ、アクティブで、実行されている必要があります。このアダプターには、バージョン 2.2 以降の Memcached PHP 拡張機能が必要です。

This adapter expects a Memcached instance to be passed as the first parameter. A namespace and default cache lifetime can optionally be passed as the second and third parameters:

このアダプターは、Memcached インスタンスが最初のパラメーターとして渡されることを想定しています。名前空間とデフォルトのキャッシュの有効期間は、必要に応じて 2 番目と 3 番目のパラメーターとして渡すことができます。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
use Symfony\Component\Cache\Adapter\MemcachedAdapter;

$cache = new MemcachedAdapter(
    // the client object that sets options and adds the server instance(s)
    \Memcached $client,

    // a string prefixed to the keys of the items stored in this cache
    $namespace = '',

    // the default lifetime (in seconds) for cache items that do not define their
    // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
    // until MemcachedAdapter::clear() is invoked or the server(s) are restarted)
    $defaultLifetime = 0
);

Configure the Connection

The createConnection() helper method allows creating and configuring a Memcached class instance using a Data Source Name (DSN) or an array of DSNs:

createConnection() ヘルパー メソッドを使用すると、データ ソース名 (DSN) または DSN の配列を使用して Memcached クラス インスタンスを作成および構成できます。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
use Symfony\Component\Cache\Adapter\MemcachedAdapter;

// pass a single DSN string to register a single server with the client
$client = MemcachedAdapter::createConnection(
    'memcached://localhost'
    // the DSN can include config options (pass them as a query string):
    // 'memcached://localhost:11222?retry_timeout=10'
    // 'memcached://localhost:11222?socket_recv_size=1&socket_send_size=2'
);

// pass an array of DSN strings to register multiple servers with the client
$client = MemcachedAdapter::createConnection([
    'memcached://10.0.0.100',
    'memcached://10.0.0.101',
    'memcached://10.0.0.102',
    // etc...
]);

// a single DSN can define multiple servers using the following syntax:
// host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':'
$client = MemcachedAdapter::createConnection(
    'memcached:?host[localhost]&host[localhost:12345]&host[/some/memcached.sock:]=3'
);

The Data Source Name (DSN) for this adapter must use the following format:

このアダプターのデータ ソース名 (DSN) は、次の形式を使用する必要があります。
1
 
memcached://[user:pass@][ip|host|socket[:port]][?weight=int]

The DSN must include a IP/host (and an optional port) or a socket path, an optional username and password (for SASL authentication; it requires that the memcached extension was compiled with --enable-memcached-sasl) and an optional weight (for prioritizing servers in a cluster; its value is an integer between 0 and 100 which defaults to null; a higher value means more priority).

DSN には、IP/ホスト (およびオプションのポート) またはソケット パス、オプションのユーザー名とパスワード (SASL 認証用。thememcached 拡張機能が --enable-memcached-sasl でコンパイルされている必要があります)、およびオプションの重み (優先順位付け用) を含める必要があります。クラスタ内のサーバー。値は 0 ～ 100 の整数で、デフォルトは null です。値が大きいほど優先度が高くなります）。

Below are common examples of valid DSNs showing a combination of available values:

以下は、使用可能な値の組み合わせを示す有効な DSN の一般的な例です。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
use Symfony\Component\Cache\Adapter\MemcachedAdapter;

$client = MemcachedAdapter::createConnection([
    // hostname + port
    'memcached://my.server.com:11211'

    // hostname without port + SASL username and password
    'memcached://rmf:abcdef@localhost'

    // IP address instead of hostname + weight
    'memcached://127.0.0.1?weight=50'

    // socket instead of hostname/IP + SASL username and password
    'memcached://janesmith:mypassword@/var/run/memcached.sock'

    // socket instead of hostname/IP + weight
    'memcached:///var/run/memcached.sock?weight=20'
]);

Configure the Options

The createConnection() helper method also accepts an array of options as its second argument. The expected format is an associative array of key => value pairs representing option names and their respective values:

createConnection() ヘルパー メソッドは、2 番目の引数としてオプションの配列も受け入れます。期待される形式は、オプション名とそれぞれの値を表すキー => 値ペアの連想配列です。
1
2
3
4
5
6
7
8
9
10
11
12
 
use Symfony\Component\Cache\Adapter\MemcachedAdapter;

$client = MemcachedAdapter::createConnection(
    // a DSN string or an array of DSN strings
    [],

    // associative array of configuration options
    [
        'libketama_compatible' => true,
        'serializer' => 'igbinary',
    ]
);

Available Options

auto_eject_hosts (type: bool, default: false)
Enables or disables a constant, automatic, re-balancing of the cluster by auto-ejecting hosts that have exceeded the configured server_failure_limit.
構成された server_failure_limit を超えたホストを自動排出することにより、クラスターの一定の自動リバランスを有効または無効にします。
buffer_writes (type: bool, default: false)
Enables or disables buffered input/output operations, causing storage commands to buffer instead of being immediately sent to the remote server(s). Any action that retrieves data, quits the connection, or closes down the connection will cause the buffer to be committed.
バッファリングされた入力/出力操作を有効または無効にして、ストレージコマンドをリモートサーバーにすぐに送信する代わりにバッファリングさせます。データを取得する、接続を終了する、または接続を閉じるアクションによって、バッファーがコミットされます。
connect_timeout (type: int, default: 1000)

Specifies the timeout (in milliseconds) of socket connection operations when the no_block option is enabled.

no_block オプションが有効な場合のソケット接続操作のタイムアウト (ミリ秒単位) を指定します。

Valid option values include any positive integer.

有効なオプション値には、任意の正の整数が含まれます。
distribution (type: string, default: consistent)

Specifies the item key distribution method among the servers. Consistent hashing delivers better distribution and allows servers to be added to the cluster with minimal cache losses.

サーバー間でのアイテム キーの配布方法を指定します。 Consistenthashing により分散が向上し、キャッシュの損失を最小限に抑えてサーバーをクラスターに追加できます。

Valid option values include modula, consistent, and virtual_bucket.

有効なオプション値には、modula、consistent、および virtual_bucket が含まれます。
hash (type: string, default: md5)

Specifies the hashing algorithm used for item keys. Each hash algorithm has its advantages and its disadvantages. The default is suggested for compatibility with other clients.

項目キーに使用されるハッシュ アルゴリズムを指定します。各ハッシュ アルゴリズムには、長所と短所があります。デフォルトは、他のクライアントとの互換性のために提案されています。

Valid option values include default, md5, crc, fnv1_64, fnv1a_64, fnv1_32, fnv1a_32, hsieh, and murmur.

有効なオプション値には、default、md5、crc、fnv1_64、fnv1a_64、fnv1_32、fnv1a_32、hsieh、および murmur が含まれます。
libketama_compatible (type: bool, default: true)
Enables or disables "libketama" compatible behavior, enabling other libketama-based clients to access the keys stored by client instance transparently (like Python and Ruby). Enabling this option sets the hash option to md5 and the distribution option to consistent.
「libketama」互換の動作を有効または無効にして、他の libketama ベースのクライアントがクライアント インスタンスによって格納されたキーに透過的にアクセスできるようにします (Python や Ruby など)。このオプションを有効にすると、ハッシュ オプションが md5 に設定され、配布オプションが一貫性が保たれるように設定されます。
no_block (type: bool, default: true)
Enables or disables asynchronous input and output operations. This is the fastest transport option available for storage functions.
非同期の入出力操作を有効または無効にします。これは、ストレージ機能で使用できる最速のトランスポート オプションです。
number_of_replicas (type: int, default: 0)

Specifies the number of replicas that should be stored for each item (on different servers). This does not dedicate certain memcached servers to store the replicas in, but instead stores the replicas together with all of the other objects (on the "n" next servers registered).

各アイテム (異なるサーバー上) に保存するレプリカの数を指定します。これは、特定の memcached サーバーをレプリカの保存専用にするのではなく、レプリカを他のすべてのオブジェクトと一緒に ("n" 個の次の登録済みサーバー上に) 保存します。

Valid option values include any positive integer.

有効なオプション値には、任意の正の整数が含まれます。
prefix_key (type: string, default: an empty string)

Specifies a "domain" (or "namespace") prepended to your keys. It cannot be longer than 128 characters and reduces the maximum key size.

キーの先頭に追加する「ドメイン」(または「名前空間」) を指定します。 128 文字を超えることはできず、最大キー サイズが減少します。

Valid option values include any alphanumeric string.

有効なオプション値には、任意の英数字文字列が含まれます。
poll_timeout (type: int, default: 1000)

Specifies the amount of time (in seconds) before timing out during a socket polling operation.

socketpolling 操作中にタイムアウトになるまでの時間 (秒単位) を指定します。

Valid option values include any positive integer.

有効なオプション値には、任意の正の整数が含まれます。
randomize_replica_read (type: bool, type: false)
Enables or disables randomization of the replica reads starting point. Normally the read is done from primary server and in case of a miss the read is done from "primary+1", then "primary+2", all the way to "n" replicas. This option sets the replica reads as randomized between all available servers; it allows distributing read load to multiple servers with the expense of more write traffic.
レプリカ読み取りの開始点のランダム化を有効または無効にします。通常、読み取りはプライマリ サーバーから行われ、ミスの場合は「プライマリ + 1」から「プライマリ + 2」、「n」レプリカまで読み取りが行われます。 .このオプションは、使用可能なすべてのサーバー間でランダム化されたレプリカの読み取りを設定します。より多くの書き込みトラフィックを犠牲にして、複数のサーバーに読み取り負荷を分散できます。
recv_timeout (type: int, default: 0)

Specifies the amount of time (in microseconds) before timing out during an outgoing socket (read) operation. When the no_block option isn't enabled, this will allow you to still have timeouts on the reading of data.

発信ソケット (読み取り) 操作中にタイムアウトになるまでの時間 (マイクロ秒単位) を指定します。

Valid option values include 0 or any positive integer.

有効なオプション値には、0 または任意の正の整数が含まれます。
retry_timeout (type: int, default: 0)

Specifies the amount of time (in seconds) before timing out and retrying a connection attempt.

タイムアウトして接続試行を再試行するまでの時間 (秒単位) を指定します。

Valid option values include any positive integer.

有効なオプション値には、任意の正の整数が含まれます。
send_timeout (type: int, default: 0)

Specifies the amount of time (in microseconds) before timing out during an incoming socket (send) operation. When the no_block option isn't enabled, this will allow you to still have timeouts on the sending of data.

着信ソケット (送信) 操作中にタイムアウトになるまでの時間 (マイクロ秒単位) を指定します。 no_block オプションが有効になっていない場合でも、データの送信にタイムアウトを設定できます。

Valid option values include 0 or any positive integer.

有効なオプション値には、0 または任意の正の整数が含まれます。
serializer (type: string, default: php)

Specifies the serializer to use for serializing non-scalar values. The igbinary options requires the igbinary PHP extension to be enabled, as well as the memcached extension to have been compiled with support for it.

非スカラー値のシリアル化に使用するシリアライザーを指定します。 igbinary オプションでは、igbinary PHP 拡張機能を有効にする必要があります。また、memcached 拡張機能をコンパイルしてサポートする必要があります。

Valid option values include php and igbinary.

有効なオプション値には、php と igbinary が含まれます。
server_failure_limit (type: int, default: 0)

Specifies the failure limit for server connection attempts before marking the server as "dead". The server will remain in the server pool unless auto_eject_hosts is enabled.

サーバーを「停止」とマークするまでのサーバー接続試行の失敗制限を指定します。 auto_eject_hosts が有効になっていない限り、サーバーはサーバー プールに残ります。

Valid option values include any positive integer.

有効なオプション値には、任意の正の整数が含まれます。
socket_recv_size (type: int)

Specified the maximum buffer size (in bytes) in the context of incoming (receive) socket connection data.

着信 (受信) ソケット接続データのコンテキストで最大バッファー サイズ (バイト単位) を指定します。

Valid option values include any positive integer, with a default value that varies by platform and kernel configuration.

有効なオプション値には任意の正の整数が含まれ、デフォルト値はプラットフォームおよびカーネル構成によって異なります。
socket_send_size (type: int)

Specified the maximum buffer size (in bytes) in the context of outgoing (send) socket connection data.

発信 (送信) ソケット接続データのコンテキストで指定された最大バッファー サイズ (バイト単位)。

Valid option values include any positive integer, with a default value that varies by platform and kernel configuration.

有効なオプション値には任意の正の整数が含まれ、デフォルト値はプラットフォームおよびカーネル構成によって異なります。
tcp_keepalive (type: bool, default: false)
Enables or disables the "`keep-alive`_" Transmission Control Protocol (TCP) feature, which is a feature that helps to determine whether the other end has stopped responding by sending probes to the network peer after an idle period and closing or persisting the socket based on the response (or lack thereof).
「`keep-alive`_」伝送制御プロトコル (TCP) 機能を有効または無効にします。これは、アイドル期間の後にネットワーク ピアにプローブを送信し、ソケットを閉じるか永続化することによって、相手側が応答を停止したかどうかを判断するのに役立つ機能です。応答 (またはその欠如) に基づいています。
tcp_nodelay (type: bool, default: false)
Enables or disables the "`no-delay`_" (Nagle's algorithm) Transmission Control Protocol (TCP) algorithm, which is a mechanism intended to improve the efficiency of networks by reducing the overhead of TCP headers by combining a number of small outgoing messages and sending them all at once.
"`no-delay`_" (Nagle のアルゴリズム) Transmission Control Protocol (TCP) アルゴリズムを有効または無効にします。これは、多数の小さな発信メッセージを組み合わせて送信することにより、TCP ヘッダーのオーバーヘッドを削減することで、ネットワークの効率を向上させることを目的としたメカニズムです。それらすべてを一度に。
use_udp (type: bool, default: false)

Enables or disables the use of User Datagram Protocol (UDP) mode (instead of Transmission Control Protocol (TCP) mode), where all operations are executed in a "fire-and-forget" manner; no attempt to ensure the operation has been received or acted on will be made once the client has executed it.

ユーザー データグラム プロトコル (UDP) モード (Transmission Control Protocol (TCP) モードの代わりに) の使用を有効または無効にします。このモードでは、すべての操作が「ファイア アンド フォーゲット」方式で実行されます。クライアントが操作を実行した後は、操作が受信されたか実行されたかを確認する試みは行われません。

Caution

注意

Not all library operations are tested in this mode. Mixed TCP and UDP servers are not allowed.

このモードでは、すべてのライブラリ操作がテストされるわけではありません。 TCP サーバーと UDP サーバーを混在させることはできません。
verify_key (type: bool, default: false)
Enables or disables testing and verifying of all keys used to ensure they are valid and fit within the design of the protocol being used.
使用されているすべてのキーのテストと検証を有効または無効にして、それらが有効であり、使用されているプロトコルの設計に適合していることを確認します。

Tip

ヒント

Reference the Memcached extension's predefined constants documentation for additional information about the available options.

使用可能なオプションの詳細については、Memcached 拡張機能の定義済み定数のドキュメントを参照してください。