diff --git a/README.txt b/README.txt index 6705434..c93e9e2 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! @@ -24,20 +24,23 @@ 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 - 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 + 2. Enable the memcache module before you configure memcache to run + as the default backend. This is so Drupal knows where to find everything. + Enabling the module prior to configuring memcache backends is not required + if the configuration "Autoloading Memcache Classes / Services" 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_config and cache_data, + 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 ## @@ -166,55 +169,133 @@ Memcache locks can be enabled through the services.yml file. class: Drupal\Core\Lock\LockBackendInterface factory: memcache.lock.factory:getPersistent -## Cache Container on bootstrap ## +## 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) $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'], + $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'], + ], + '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'], + ], ], - 'memcache.backend.cache.factory' => [ - 'class' => 'Drupal\memcache\DrupalMemcacheFactory', - 'arguments' => ['@memcache.config'] + ]; + } + +### 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'; + +### Autoloading Memcache Classes / Services ### + +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 the default backend +when installing Drupal which can be necessary when using modules such as +content_translation that override default configuration at runtime. Insert the following +to settings.php: + + + $memcache_exists = class_exists('Memcache', FALSE); + $memcached_exists = class_exists('Memcached', FALSE); + if ($memcache_exists || $memcached_exists) { + + if (class_exists(ClassLoader::class)) { + $class_loader = new 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'], + ], ], - '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'], - ], - ], - ]; -} + ]; + } ## TROUBLESHOOTING ## @@ -229,6 +310,27 @@ WARNING: Zlib compression at the php.ini level and Memcache conflict. See http://drupal.org/node/273824 +PROBLEM: +Error: +Data in cache_config and other bins is stale after code updates and +Drupal cache rebuilds. + +SOLUTION: +Drupal core sets static cache bins to use the fast chained backend +so objects in static 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, set cache_config and other static caches +to use memcache as the backend prior 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 @@ -298,9 +400,9 @@ $settings['memcache']['sasl'] = [ '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, ];