{"record":{"id":"89fd93fde5e85b53","repo":"yiisoft/yii2","slug":"memcache-requires-php-extension-extension-to-be-l","errorCode":null,"errorMessage":"MemCache requires PHP $extension extension to be loaded.","messagePattern":"MemCache requires PHP \\$extension extension to be loaded\\.","errorType":"exception","errorClass":"InvalidConfigException","httpStatus":null,"severity":"error","filePath":"framework/caching/MemCache.php","lineNumber":222,"sourceCode":"                    $server->retryInterval,\n                    $server->status,\n                    $server->failureCallback\n                );\n            }\n        }\n    }\n\n    /**\n     * Returns the underlying memcache (or memcached) object.\n     * @return \\Memcache|\\Memcached the memcache (or memcached) object used by this cache component.\n     * @throws InvalidConfigException if memcache or memcached extension is not loaded\n     */\n    public function getMemcache()\n    {\n        if ($this->_cache === null) {\n            $extension = $this->useMemcached ? 'memcached' : 'memcache';\n            if (!extension_loaded($extension)) {\n                throw new InvalidConfigException(\"MemCache requires PHP $extension extension to be loaded.\");\n            }\n\n            if ($this->useMemcached) {\n                $this->_cache = $this->persistentId !== null ? new \\Memcached($this->persistentId) : new \\Memcached();\n                if ($this->username !== null || $this->password !== null) {\n                    $this->_cache->setOption(\\Memcached::OPT_BINARY_PROTOCOL, true);\n                    $this->_cache->setSaslAuthData($this->username, $this->password);\n                }\n                if (!empty($this->options)) {\n                    $this->_cache->setOptions($this->options);\n                }\n            } else {\n                $this->_cache = new \\Memcache();\n            }\n        }\n\n        return $this->_cache;\n    }","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/caching/MemCache.php#L204-L240","documentation":"Thrown by yii\\caching\\MemCache::getMemcache() when the PHP extension backing the component is not loaded in the current process: it checks extension_loaded() for 'memcached' or 'memcache' depending on the useMemcached flag. The component deliberately fails at first use rather than silently caching nowhere. The two extensions are distinct PECL packages with different APIs, so the flag must match the extension that is actually installed.","triggerScenarios":"Configuring the cache component as MemCache on a host without ext-memcache; setting useMemcached = true while only the old memcache extension (or neither) is installed; deploying to a container/Docker image built without the extension; extension present but not enabled for the SAPI in use (php-fpm vs CLI differ — migrations/console commands fail while web works); opcode/JIT or phpbrew environments missing the .so load.","commonSituations":"Works on the dev machine, fails in CI or production because the Docker image lacks php-memcached; php-fpm has the extension but CLI (used by yii migrate) does not; switching a project from memcache to memcached without updating installs; Alpine/special PHP builds where the package was never added.","solutions":["Install and enable the matching extension: apt-get install php-memcached (or pecl install memcached / pecl install memcache), then restart php-fpm and verify with php -m | grep memcache.","Make useMemcached match what is installed: true requires ext-memcached, false requires ext-memcache.","If you cannot install extensions, switch the cache component to one without extension needs (FileCache, DbCache) or Redis with predis.","In Docker/CI images, add the extension in the build (docker-php-ext-install / install-php-extensions) and confirm for both web and CLI SAPIs."],"exampleFix":"// before\n// host has neither ext-memcache nor ext-memcached\n'cache' => ['class' => \\yii\\caching\\MemCache::class], // throws on first cache use\n\n// after (option 1: install the extension)\n// $ apt-get install -y php-memcached && systemctl restart php8.2-fpm\n// $ php -m | grep memcached\n'cache' => ['class' => \\yii\\caching\\MemCache::class, 'useMemcached' => true],\n\n// after (option 2: no extension possible)\n'cache' => ['class' => \\yii\\caching\\FileCache::class],","handlingStrategy":"validation","validationCode":"// At boot, before the cache component is first used\n$extension = $useMemcached ? 'memcached' : 'memcache';\nif (!extension_loaded($extension)) {\n    throw new \\RuntimeException(\"PHP extension '{$extension}' is required by the MemCache component.\");\n    // or degrade: use \\yii\\caching\\FileCache as a temporary cache backend\n}","typeGuard":null,"tryCatchPattern":"try {\n    Yii::$app->cache->get('warmup');\n} catch (\\yii\\base\\InvalidConfigException $e) {\n    // memcache(d) missing in this SAPI: fail the deploy check loudly\n    throw new \\RuntimeException('Cache backend unavailable: ' . $e->getMessage(), 0, $e);\n}","preventionTips":["Verify php -m and php-fpm -m both list the required extension in every environment (web and CLI differ)","Bake the extension into Docker/CI images instead of relying on the host","Match useMemcached to the installed extension; memcached and memcache are different PECL packages","Add a deploy-time cache smoke test so a missing extension fails the pipeline, not production traffic"],"tags":["php","yii2","cache","memcache","php-extension","environment","deployment"],"backgroundTag":"missing-php-extension","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}