diff --git a/README.txt b/README.txt index 6705434..55a12b9 100644 --- a/README.txt +++ b/README.txt @@ -1,6 +1,6 @@ ## IMPORTANT NOTE ## -This file contains installation instructions for the 8.x-1.x version of the +This file contains installation instructions for the 8.x-2.x version of the Drupal Memcache module. Configuration differs between 8.x and 7.x versions of the module, so be sure to follow the 7.x instructions if you are configuring the 7.x-1.x version of this module! @@ -13,8 +13,8 @@ the 7.x-1.x version of this module! - http://pecl.php.net/package/memcache (recommended) - http://pecl.php.net/package/memcached -For more detailed instructions on installing a memcached daemon or either of the -memcache PECL extensions, please see the documentation online at +For more detailed instructions on installing a memcached daemon or either of +the memcache PECL extensions, please see the documentation online at https://www.drupal.org/node/1131458 which includes links to external walk-throughs for various operating systems. @@ -24,20 +24,25 @@ These are the steps you need to take in order to use this software. Order is important. 1. Make sure you have one of the PECL memcache packages installed. - 2. Enable the memcache module. - You need to enable the module in Drupal before you can configure it to run + 2. Enable the memcache module before you configure it to run as the default backend. This is so Drupal knows where to find everything. - 2. Edit settings.php to configure the servers, clusters and bins that memcache - is supposed to use. You do not need to set this if the only memcache backend - is localhost on port 11211. By default the main settings will be: + Note that enabling the module prior to configuring memcache as a backend + is not required if the configuration in this README's "Configuring + Memcache before Site or Module is Installed" section is being used. + 3. Edit settings.php to configure the servers, clusters and bins that memcache + is supposed to use. You do not need to set this if the only memcache + backend is localhost on port 11211. By default the main settings will be: $settings['memcache']['servers'] = ['127.0.0.1:11211' => 'default']; $settings['memcache']['bins'] = ['default' => 'default']; $settings['memcache']['key_prefix'] = ''; - 7. Edit settings.php to make memcache the default cache class, for example: - $settings['cache']['default'] = 'cache.backend.memcache'; - 8. If you wish to arbitrarily send cache bins to memcache, then you can do the - following. E.g. for the cache_render bin: + 4. If you wish to arbitrarily send cache bins to memcache such as cache_data + and cache_config, then you should include this before the default cache + bin is configured. + E.g. for the cache_render bin: $settings['cache']['bins']['render'] = 'cache.backend.memcache'; + 5. Edit settings.php to make memcache the default cache class, for example: + $settings['cache']['default'] = 'cache.backend.memcache'; + ## ADVANCED CONFIGURATION ## @@ -91,17 +96,17 @@ items. To enable stampede protection, add the following config in settings.php: $settings['memcache']['stampede_protection'] = TRUE; To avoid lock stampedes, it is important that you enable the memcache lock -implementation when enabling stampede protection -- enabling stampede protection -without enabling the Memcache lock implementation can cause worse performance. +implementation when enabling stampede protection, as failing to do so may +cause worse performance. Only change the following values if you're sure you know what you're doing, -which requires reading the memcachie.inc code. +which requires reading the MemcacheBackend.php code. -The value passed to Drupal\Core\Lock\LockBackendInterface::wait(), defaults to 5: +The value for Drupal\Core\Lock\LockBackendInterface::wait(), defaults to 5: $settings['memcache']['stampede_wait_time'] = 5; -The maximum number of calls to Drupal\Core\Lock\LockBackendInterface::wait() due -to stampede protection during a single request, defaults to 3: +The maximum number of calls to Drupal\Core\Lock\LockBackendInterface::wait() +due to stampede protection during a single request, defaults to 3: $settings['memcache']['stampede_wait_limit'] = 3; When adjusting these variables, be aware that: @@ -132,13 +137,13 @@ which hash algorithms are available. ### Memcache Distribution ### -To use this module with multiple memcached servers, it is important that you set -the hash strategy to consistent. This is controlled in the PHP extension, not the -Drupal module. +To use this module with multiple memcached servers, it is important that you +set the hash strategy to consistent. This is controlled in the PHP extension, +not the Drupal module. If using PECL memcache: -Edit /etc/php.d/memcache.ini (path may changed based on package/distribution) and -set the following: +Edit /etc/php.d/memcache.ini (path may changed based on package/distribution) +and set the following: memcache.hash_strategy=consistent You need to reload apache httpd after making that change. @@ -156,71 +161,209 @@ the default in this case but could be set using: Memcache locks can be enabled through the services.yml file. services: - # Replaces the default lock backend with a memcache implementation. + # Replaces the default lock backend with memcache. lock: class: Drupal\Core\Lock\LockBackendInterface factory: memcache.lock.factory:get - # Replaces the default persistent lock backend with a memcache implementation. + # Replaces the default persistent lock backend with memcache. lock.persistent: class: Drupal\Core\Lock\LockBackendInterface factory: memcache.lock.factory:getPersistent -## Cache Container on bootstrap ## -By default Drupal starts the cache_container on the database, in order to override that you can use the following code on your settings.php file. Make sure that the $class_load->addPsr4 is poiting to the right location of memcache (on this case modules/contrib/memcache/src) +## CACHE CONTAINER ON BOOTSTRAP ## +By default Drupal starts the cache_container on the database, in order to +override that and load the service container from memcache which is useful +when needing to refresh the service container during site installs or deploys, +you can use the following code in your settings.php file which overrides +core's streamlined bootstrap service container. Ensure that that the path in +$class_load->addPsr4 is poiting to the right location of memcache such as +modules/contrib/memcache/src so that the needed classes can be registered +without Drupal's autoloader being available. + +// Check for PHP Memcached libraries. $memcache_exists = class_exists('Memcache', FALSE); $memcached_exists = class_exists('Memcached', FALSE); -if ($memcache_exists || $memcached_exists) { - $class_loader->addPsr4('Drupal\\memcache\\', 'modules/contrib/memcache/src'); - - // Define custom bootstrap container definition to use Memcache for cache.container. - $settings['bootstrap_container_definition'] = [ - 'parameters' => [], - 'services' => [ - 'database' => [ - 'class' => 'Drupal\Core\Database\Connection', - 'factory' => 'Drupal\Core\Database\Database::getConnection', - 'arguments' => ['default'], - ], - 'settings' => [ - 'class' => 'Drupal\Core\Site\Settings', - 'factory' => 'Drupal\Core\Site\Settings::getInstance', - ], - 'memcache.config' => [ - 'class' => 'Drupal\memcache\DrupalMemcacheConfig', - 'arguments' => ['@settings'], - ], - 'memcache.backend.cache.factory' => [ - 'class' => 'Drupal\memcache\DrupalMemcacheFactory', - 'arguments' => ['@memcache.config'] - ], - 'memcache.backend.cache.container' => [ - 'class' => 'Drupal\memcache\DrupalMemcacheFactory', - 'factory' => ['@memcache.backend.cache.factory', 'get'], - 'arguments' => ['container'], - ], - 'lock.container' => [ - 'class' => 'Drupal\memcache\Lock\MemcacheLockBackend', - 'arguments' => ['container', '@memcache.backend.cache.container'], +$memcache_module_is_present = file_exists(DRUPAL_ROOT . '/modules/contrib/ +memcache/memcache.services.yml'); + +if ($memcache_module_is_present && ($memcache_exists || $memcached_exists)) { + // Use Memcached extension if available. + if ($memcached_exists) { + $settings['memcache']['extension'] = 'Memcached'; + } + // Register required class namespaces. + if (class_exists(\Composer\Autoload\ClassLoader::class)) { + $class_loader = new \Composer\Autoload\ClassLoader(); + $class_loader->addPsr4('Drupal\\memcache\\', 'modules/contrib/ + memcache/src'); + $class_loader->register(); + $settings['container_yamls'][] = DRUPAL_ROOT . '/modules/contrib/ + memcache/memcache.services.yml'; + // Bootstrap cache.container with memcache rather than database. + $settings['bootstrap_container_definition'] = [ + 'parameters' => [], + 'services' => [ + 'database' => [ + 'class' => 'Drupal\Core\Database\Connection', + 'factory' => 'Drupal\Core\Database\Database::getConnection', + 'arguments' => ['default'], + ], + 'settings' => [ + 'class' => 'Drupal\Core\Site\Settings', + 'factory' => 'Drupal\Core\Site\Settings::getInstance', + ], + 'memcache.config' => [ + 'class' => 'Drupal\memcache\DrupalMemcacheConfig', + 'arguments' => ['@settings'], + ], + 'memcache.backend.cache.factory' => [ + 'class' => 'Drupal\memcache\DrupalMemcacheFactory', + 'arguments' => ['@memcache.config'], + ], + 'memcache.backend.cache.container' => [ + 'class' => 'Drupal\memcache\DrupalMemcacheFactory', + 'factory' => ['@memcache.backend.cache.factory', 'get'], + 'arguments' => ['container'], + ], + 'lock.container' => [ + 'class' => 'Drupal\memcache\Lock\MemcacheLockBackend', + 'arguments' => ['container', '@memcache.backend.cache.container'], + ], + 'cache_tags_provider.container' => [ + 'class' => 'Drupal\Core\Cache\DatabaseCacheTagsChecksum', + 'arguments' => ['@database'], + ], + 'cache.container' => [ + 'class' => 'Drupal\memcache\MemcacheBackend', + 'arguments' => [ + 'container', + '@memcache.backend.cache.container', + '@lock.container', + '@memcache.config', + '@cache_tags_provider.container', + ], + ], ], - 'cache_tags_provider.container' => [ - 'class' => 'Drupal\Core\Cache\DatabaseCacheTagsChecksum', - 'arguments' => ['@database'], - ], - 'cache.container' => [ - 'class' => 'Drupal\memcache\MemcacheBackend', - 'arguments' => ['container', '@memcache.backend.cache.container', '@lock.container', '@memcache.config', '@cache_tags_provider.container'], + ]; + } +} + +### Per-Bin Overrides ### + +Since Drupal 8.2.x cache bins such as config, bootstrap, and discovery will +use the fast chained backend unless explicitly overridden prior to +setting an alternative default cache bin backend in settings.php: + + $settings['cache']['bins']['bootstrap'] = 'cache.backend.memcache'; + $settings['cache']['bins']['discovery'] = 'cache.backend.memcache'; + $settings['cache']['bins']['config'] = 'cache.backend.memcache'; + + // Use memcache as the default bin. + $settings['cache']['default'] = 'cache.backend.memcache'; + +### Configuring Memcache before Site or Module is Installed ### + +By autoloading the required classes and cache services as well as configuring +Drupal to bootstrap using memcache for cache.container, memcache bins can be +configured in settings.php before the module is enabled. This will prevent +errors such as "non-existent cache service" when the memcache backend is not +yet available but is configured in settings.php. This strategy also allows for +overriding core's streamlined service container definition when installing +Drupal which can be necessary when overriding default bin backends on site +install, overriding and updating default configuration, and refreshing the +service container during code deploys or before Drupal is fully bootstrapped. +This is a common requirement when using the Features module to update +configuration and when using modules such as content_translation which must +override default configuration at runtime. + +To leverage autoloading functionality and override, insert the following in +settings.php: + + + // Check for PHP Memcached libraries. +$memcache_exists = class_exists('Memcache', FALSE); +$memcached_exists = class_exists('Memcached', FALSE); +$memcache_module_is_present = file_exists(DRUPAL_ROOT . '/modules/contrib/ +memcache/memcache.services.yml'); + +if ($memcache_module_is_present && ($memcache_exists || $memcached_exists)) { + // Use Memcached extension if available. + if ($memcached_exists) { + $settings['memcache']['extension'] = 'Memcached'; + } + // Register required class namespaces. + if (class_exists(\Composer\Autoload\ClassLoader::class)) { + $class_loader = new \Composer\Autoload\ClassLoader(); + $class_loader->addPsr4('Drupal\\memcache\\', 'modules/contrib/ + memcache/src'); + $class_loader->register(); + $settings['container_yamls'][] = DRUPAL_ROOT . '/modules/contrib/memcache/ + memcache.services.yml'; + // Bootstrap cache.container with memcache rather than database. + $settings['bootstrap_container_definition'] = [ + 'parameters' => [], + 'services' => [ + 'database' => [ + 'class' => 'Drupal\Core\Database\Connection', + 'factory' => 'Drupal\Core\Database\Database::getConnection', + 'arguments' => ['default'], + ], + 'settings' => [ + 'class' => 'Drupal\Core\Site\Settings', + 'factory' => 'Drupal\Core\Site\Settings::getInstance', + ], + 'memcache.config' => [ + 'class' => 'Drupal\memcache\DrupalMemcacheConfig', + 'arguments' => ['@settings'], + ], + 'memcache.backend.cache.factory' => [ + 'class' => 'Drupal\memcache\DrupalMemcacheFactory', + 'arguments' => ['@memcache.config'], + ], + 'memcache.backend.cache.container' => [ + 'class' => 'Drupal\memcache\DrupalMemcacheFactory', + 'factory' => ['@memcache.backend.cache.factory', 'get'], + 'arguments' => ['container'], + ], + 'lock.container' => [ + 'class' => 'Drupal\memcache\Lock\MemcacheLockBackend', + 'arguments' => ['container', '@memcache.backend.cache.container'], + ], + 'cache_tags_provider.container' => [ + 'class' => 'Drupal\Core\Cache\DatabaseCacheTagsChecksum', + 'arguments' => ['@database'], + ], + 'cache.container' => [ + 'class' => 'Drupal\memcache\MemcacheBackend', + 'arguments' => [ + 'container', + '@memcache.backend.cache.container', + '@lock.container', + '@memcache.config', + '@cache_tags_provider.container', + ], + ], ], - ], - ]; + ]; + + // Override default fast chained backend for static bins. + // @see https://www.drupal.org/node/2754947 + $settings['cache']['bins']['bootstrap'] = 'cache.backend.memcache'; + $settings['cache']['bins']['discovery'] = 'cache.backend.memcache'; + $settings['cache']['bins']['config'] = 'cache.backend.memcache'; + + // Use memcache as the default bin. + $settings['cache']['default'] = 'cache.backend.memcache'; + + } } ## TROUBLESHOOTING ## PROBLEM: -Error: -Failed to set key: Failed to set key: cache_page-...... +Error messages such as "Failed to set key: cache_page-..." SOLUTION: Upgrade your PECL library to PECL package (2.2.1) (or higher). @@ -229,6 +372,29 @@ WARNING: Zlib compression at the php.ini level and Memcache conflict. See http://drupal.org/node/273824 +PROBLEM: +Data in cache_config and other bins is stale after code updates and +Drupal cache rebuilds which can result in errors due to new module +configuration appearing revert to old values, field definition not updating, +and views or other plugins missing configuration provided in config. + +SOLUTION: +Drupal core defaults sets static cache bins to use the fast chained backend +such as APCu if available, so objects in these bins (cache_config, +cache_discovery, cache_bootstrap) are permanently cached and rebuilding the +Drupal cache will not purge the objects since they are not yet set to expire. + +To override this behavior, edit settings.php to set memcache as the backend +for cache_config, cache_bootstrap, and cache_discovery bins prior to setting +memcache as the default backend: + + $settings['cache']['bins']['bootstrap'] = 'cache.backend.memcache'; + $settings['cache']['bins']['discovery'] = 'cache.backend.memcache'; + $settings['cache']['bins']['config'] = 'cache.backend.memcache'; + + // Use memcache as the default bin. + $settings['cache']['default'] = 'cache.backend.memcache'; + ## MEMCACHE ADMIN ## A module offering a UI for memcache is included. It provides aggregated and @@ -242,10 +408,10 @@ We also support the Memcached PECL extension. This extension backends to libmemcached and allows you to use some of the newer advanced features in memcached 1.4. -NOTE: It is important to realize that the memcache php.ini options do not impact -the memcached extension, this new extension doesn't read in options that way. -Instead, it takes options directly from Drupal. Because of this, you must -configure memcached in settings.php. Please look here for possible options: +NOTE: It is important to realize that the memcache php.ini options do not +impact the memcached extension, as this new extension doesn't read in options +that way. Instead, it takes options directly from Drupal and you must +configure memcached in settings.php. See here for possible options: https://secure.php.net/manual/en/memcached.constants.php @@ -272,7 +438,8 @@ Other options you could experiment with: with this feature enabled. It should only be enabled on extremely high traffic networks where memcache network traffic is a bottleneck. Additional reading about the binary protocol: - https://raw.githubusercontent.com/memcached/old-wiki/master/MemcacheBinaryProtocol.wiki + https://raw.githubusercontent.com/memcached/old-wiki/master/ + MemcacheBinaryProtocol.wiki Note: The information on the link above will eventually be ported to the new wiki under https://github.com/memcached/memcached/wiki. @@ -280,27 +447,27 @@ Other options you could experiment with: * This enables the no-delay feature for connecting sockets; it's been reported that this can speed up the Binary protocol (see above). This tells the TCP stack to send packets immediately and without waiting for - a full payload, reducing per-packet network latency (disabling "Nagling"). + a full payload, reducing "Nagling", or per-packet network latency It's possible to enable SASL authentication as documented here: http://php.net/manual/en/memcached.setsaslauthdata.php https://code.google.com/p/memcached/wiki/SASLHowto -SASL authentication requires a memcached server with SASL support (version 1.4.3 -or greater built with --enable-sasl and started with the -S flag) and the PECL -memcached client version 2.0.0 or greater also built with SASL support. Once -these requirements are satisfied you can then enable SASL support in the Drupal -memcache module by enabling the binary protocol and setting -memcache_sasl_username and memcache_sasl_password in settings.php. For example: +SASL authentication requires a memcached server with SASL support (version +1.4.3 or greater built with --enable-sasl and started with the -S flag) and the +PECL memcached client version 2.0.0 or greater also built with SASL support. +Once these requirements are satisfied you can then enable SASL support in the +Drupal memcache module by enabling the binary protocol and setting values for +memcache_sasl_username and memcache_sasl_password in settings.php: $settings['memcache']['sasl'] = [ 'username' => 'user', 'password' => 'password', ]; -// When using SASL, Memcached extension needs to be used -// because Memcache extension doesn't support it. -$settings['memcache']['extension'] = 'Memcached'; -$settings['memcache']['options'] = [ + // When using SASL, Memcached extension needs to be used + // because Memcache extension doesn't support it. + $settings['memcache']['extension'] = 'Memcached'; + $settings['memcache']['options'] = [ \Memcached::OPT_BINARY_PROTOCOL => TRUE, ];