initial work on memcached adapter docs

Author: robfrawley

components/cache/cache_pools.rst

@@ -110,6 +110,102 @@ helper allows creating a connection to a Redis server using a DSN configuration:
 
 See the method's docblock for more options.
 
+Memcached Cache Adapter
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.3
+    The Memcached adapter was introduced in Symfony 3.3.
+
+This adapter stores the contents in the memory of a Memcached server. Unlike the
+APCu adapter, and similarly to the Redis adapter, it's not limited to the shared
+memory of the current server, so you can store contents independent of your PHP
+environment, including the ability to utilize a cluster of servers if needed.
+
+.. tip::
+
+    **Requirements:**
+
+    The Memcached PHP extension as well as the Memcached server daemon must be
+    installed and active to use this adapter.
+
+This adapter expects a ``\Memcached`` class instance passed as the first parameter
+during construction::
+
+    use Symfony\Component\Cache\Adapter\MemcachedAdapter;
+
+    $cache = new MemcachedAdapter(
+        // the object that stores a valid connection to your Memcached system
+        \Memcached $memcachedConnection,
+        // the string prefixed to the keys of the items stored in this cache
+        $namespace = '',
+        // in seconds; applied to cache items that don't define their own lifetime
+        // 0 means to store the cache items indefinitely (i.e. until the Memcached memory
+        // contents are flushed or the daemon(s) restarted)
+        $defaultLifetime = 0
+    );
+
+The :method:`Symfony\\Component\\Cache\\Adapter\\MemcachedAdapter::createConnection`
+helper method allows creating and configuring a ``\Memcached`` instance using a DSN
+or array of DSNs::
+
+    $memcachedConnection = MemcachedAdapter::createConnection('memcached://localhost');
+
+    $memcachedConnection = MemcachedAdapter::createConnection(array(
+        'memcached://localhost:11211?weight=25',
+        'memcached://localhost:11212?weight=25',
+        'memcached://localhost:11213?weight=50',
+    ));
+
+Passing ``weight`` is option, even when multiple servers are being registered. When no
+``weight`` is passed, all servers are utilized equally. When passing the ``weight`` DSN
+option, servers with a higher value will be utilized more than those with lesser values.
+
+.. note::
+
+    **DSN Examples:**
+
+    A Memcached DSN can specify either a host (with an optional port) or socket path,
+    as well as a ``weight`` and a ``persistent_id`` query value, using the following
+    syntax:
+
+    .. code-block:: text
+
+        memcached://[ip|host|socket[:port]]?[weight=int]&[persistent_id=string]
+
+    For example, the below list provides examples of valid DSNs using different
+    combinations of values:
+
+    .. code-block:: text
+
+        memcached://my.server.com:11211
+        memcached://127.0.0.1?weight=50&persistent_id=my_persistent_id
+        memcached:///var/run/memcached.sock
+        memcached:///var/run/memcached.sock?weight=20
+
+The :method:`Symfony\\Component\\Cache\\Adapter\\MemcachedAdapter::createConnection`
+helper method also accepts an array of options as its second argument::
+
+    $memcachedConnection = MemcachedAdapter::createConnection(array(
+        // dsns...
+        'memcached://localhost:11211',
+        'memcached://localhost:11212',
+    ), array(
+        // options...
+        'compression' => true,
+        'hash' => 'md5',
+        'serializer' => 'igbinary',
+    ));
+
+Common options include:
+
+* **compression**: bool
+* @todo: add options
+
+
+
+See the :method:`Symfony\\Component\\Cache\\Adapter\\MemcachedAdapter::createConnection`
+method's docblock for more information about valid DSNs and options.
+
 PDO & Doctrine DBAL Cache Adapter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~