CacheTool allows you to work with apc, opcache, and the file status cache through the cli. It will connect to a fastcgi server (like php-fpm) and operate it's cache.

Why is this useful?

Code Quality Rank: L5
Programming language: PHP
License: MIT License
Tags: Caching     Cache     Apc     Fastcgi     Opcode     Opcache     Fpm    
Latest version: v8.4.1

CacheTool alternatives and similar libraries

Based on the "Caching" category.
Alternatively, view CacheTool alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of CacheTool or a related project?

Add another 'Caching' Library


CacheTool - Manage cache in the CLI

Build Status Coverage Status

CacheTool allows you to work with APCu, OPcache, and the file status cache through the CLI. It will connect to a FastCGI server (like PHP-FPM) and operate on its cache.

Why is this useful?

  • Maybe you want to clear the bytecode cache without reloading php-fpm or using a web endpoint
  • Maybe you want to have a cron which deals with cache invalidation
  • Maybe you want to see some statistics right from the console
  • And many more...

Note that, unlike APCu and Opcache, the file status cache is per-process rather than stored in shared memory. This means that running stat:clear against PHP-FPM will only affect whichever FPM worker responds to the request, not the whole pool. Julien Pauli has written a post with more details on how the file status cache operates.


  • CacheTool 8.x works with PHP >=8.0
  • CacheTool 7.x works with PHP >=7.3
  • CacheTool 6.x works with PHP >=7.3
  • CacheTool 5.x works with PHP >=7.2
  • CacheTool 4.x works with PHP >=7.1
  • CacheTool 3.x works with PHP >=5.5.9
  • CacheTool 2.x works with PHP >=5.5.9
  • CacheTool 1.x works with PHP >=5.3.3

Installation - Latest version

curl -sLO https://github.com/gordalina/cachetool/releases/latest/download/cachetool.phar
chmod +x cachetool.phar

You can alternatively download a compressed phar by using the URLs below.

# if your php installation has the zlib extension enabled

# if your php installation has the bzip2 extension enabled

CacheTool is also packaged as a docker container available in docker hub and github container registries.

See below for docker usage instructions.

Installation - old versions

Use tag name in the binary file name. E.g to download cachetool 3.2.2 which is compatible with PHP >=5.5.9 use: cachetool-3.2.2.phar

curl -sO https://gordalina.github.io/cachetool/downloads/cachetool-3.2.2.phar
chmod +x cachetool-3.2.2.phar


CacheTool requires an adapter to connect to, it can be cli, fcgi, and web. The fcgi adapter is the most common, as it connects directly to php-fpm.

You can pass an IP address or a unix socket to the --fcgi adapter, or leave it blank and CacheTool will try to find the php-fpm socket for you. If it can't find it, it will default to

  • You can let CacheTool find the unix socket for you, or default to IP.
php cachetool.phar apcu:cache:info --fcgi
  • You can connect to a fastcgi server using an IP address
php cachetool.phar apcu:cache:info --fcgi=
  • You can connect to a fastcgi server using a unix socket
php cachetool.phar opcache:status --fcgi=/var/run/php5-fpm.sock
  • To connect to a chrooted fastcgi server you need to set --fcgi-chroot and --tmp-dir parameters
php cachetool.phar opcache:status --fcgi=/var/run/php5-fpm.sock --fcgi-chroot=/path/to/chroot --tmp-dir=/path/to/chroot/tmp
  • Using the CLI
php cachetool.phar opcache:status --cli
  • Using an HTTP interface
php cachetool.phar opcache:status --web --web-path=/path/to/your/document/root --web-url=http://url-to-your-document.root
  • Using SymfonyHttpClient
php cachetool.phar opcache:status --web=SymfonyHttpClient --web-path=/path/to/your/document/root --web-url=http://url-to-your-document.root

You have some useful commands that you can use

  apcu:cache:clear            Clears APCu cache
  apcu:cache:info             Shows APCu user & system cache information
  apcu:cache:info:keys        Shows APCu keys cache information
  apcu:key:delete             Deletes an APCu key
  apcu:key:exists             Checks if an APCu key exists
  apcu:key:fetch              Shows the content of an APCu key
  apcu:key:store              Store an APCu key with given value
  apcu:regexp:delete          Deletes all APCu key matching a regexp
  apcu:sma:info               Show APCu shared memory allocation information
  opcache:compile:script      Compile single script from path to the opcode cache
  opcache:compile:scripts     Compile scripts from path to the opcode cache
  opcache:configuration       Get configuration information about the cache
  opcache:invalidate:scripts  Remove scripts from the opcode cache
  opcache:reset               Resets the contents of the opcode cache
  opcache:reset:file-cache    Deletes all contents of the file cache directory
  opcache:status              Show summary information about the opcode cache
  opcache:status:scripts      Show scripts in the opcode cache
  stat:clear                  Clears the file status cache, including the realpath cache
  stat:realpath_get           Show summary information of realpath cache entries
  stat:realpath_size          Display size of realpath cache

Usage via Docker

Images are available in docker hub and github container registries:

  • gordalina/cachetool:latest
  • ghcr.io/gordalina/cachetool:latest

This is an example run with the web adapter:


docker run --rm -v $APPDIR:$APPDIR -w $DOCROOT gordalina/cachetool cachetool --web --web-url=$URL [options] [arguments]

If the website is behind a proxy and/or load balancer you may want to ask directly the webserver instead of the public facing ip. Additionally, the webserver may be listening in another port. This is an example for running cachetool from the webserver host in such a setup:


docker run --rm --add-host $DOMAIN: -v $APPDIR:$APPDIR -w $DOCROOT sbitio/cachetool --web --web-url=$URL [options] [arguments]

Thank you to @jonhattan and @NITEMAN for the work with docker.

Configuration File

You can have a configuration file with the adapter configuration, allowing you to call CacheTool without --fcgi, --cli, or --web option.

You can pass a --config <file> option to the application or it will choose to load a file automaically.

The file must be named .cachetool.yml or .cachetool.yaml. CacheTool will look for this file on the current directory and in any parent directory until it finds one. If the paths above fail it will try to load /etc/cachetool.yml or /etc/cachetool.yaml configuration file.

An example of what this file might look like is:

Will connect to fastcgi at

adapter: fastcgi

Will connect to cli (disregarding fastcgi configuration)

adapter: cli
fastcgi: /var/run/php5-fpm.sock

CacheTool writes files to the system temporary directory (given by sys_get_temp_dir()) but if you want to change this, for example, if your fastcgi service is run with PrivateTemp you can set it on the config file:

adapter: fastcgi
fastcgi: /var/run/php5-fpm.sock
temp_dir: /dev/shm/cachetool

Example for the web adapter:

adapter: web
webClient: SymfonyHttpClient # defaults to FileGetContents
webUrl: http://example.com
webPath: /var/www/example.com/current/web
webBasicAuth: user:password

You can define the supported extensions in the config file. By default, apcu, and opcache are enabled. To disable apcu, add this to your config file:

extensions: [opcache]

Usage (as a library)

Add it as a dependency

composer require gordalina/cachetool

If you want to use it in a Symfony 2.x project, require the 1.x version

composer require gordalina/cachetool:~1.0

Create instance

use CacheTool\Adapter\FastCGI;
use CacheTool\CacheTool;

$adapter = new FastCGI('');
$cache = CacheTool::factory($adapter, '/tmp);

You can use apcu and opcache functions



CacheTool depends on Proxies to provide functionality, by default when creating a CacheTool instance from the factory all proxies are enabled ApcuProxy, OpcacheProxy and PhpProxy, you can customize it or extend to your will like the example below:

use CacheTool\Adapter\FastCGI;
use CacheTool\CacheTool;
use CacheTool\Proxy;

$adapter = new FastCGI('/var/run/php5-fpm.sock');
$cache = new CacheTool();
$cache->addProxy(new Proxy\ApcuProxy());
$cache->addProxy(new Proxy\PhpProxy());

Updating CacheTool

Running php cachetool.phar self-update will update a phar install with the latest version.


After running composer install, run ./vendor/bin/phpunit


[RuntimeException] Error: Unable to open primary script: /dev/shm/cachetool-584743c678dbb.php (No such file or directory) Status: 404 Not Found Content-type: text/html; charset=UTF-8 No input file specified.

This means that cachetool could not write to /dev/shm provide a directory that cachetool can write to through php cachetool.phar --tmp-dir=/writable/dir or configuration. This directory should also be readable by the web user running php-fpm/apache.


To have cachetool working with SELinux read this comment by @driskell.


CacheTool is licensed under the MIT License - see the [LICENSE](LICENSE) for details

*Note that all licence references and agreements mentioned in the CacheTool README section above are relevant to that project's source code only.