Enabling the APC extension in PHP

June 14, 2012

UPDATE 2012-08-04: This article has been cleaned up by removing default options that were not necessary to define and by making the configuration more general in nature. You should now be able to use the configuration example as-is, with only minor modifications based on your site’s composition, traffic and usage.


Yes, I already have the other two documented and you’re probably running one of them already.

I know…

I just figured it wouldn’t be a complete set without the third (and consequently, the one I chose). Just in case anyone is wondering, the reasons I chose APC over the other two extensions are clear.

  1. Support - Nothing beats the integration of an extension the developers officially endorse. In fact, APC is already an integral part of PHP 6.

  2. Simplicity - APC only requires a few options to be modified and it’s ready to go. eAccelerator is very similar in this aspect, but there are still more changes that need to be made, and anyone who’s configured XCache knows it can be a process.

  3. Monitoring - APC’s monitoring page (apc.php) is by far the most visually appealing, simple page for all three. XCache receives an honorable mention here as their monitoring pages are also extremely detailed, only slightly less aesthetically pleasing and even offer some management options. Anyone who is familiar with eAccelerator’s page (eaccelerator.php) is probably not fond of it.

By reading the above, it becomes evident I have a clear second-place winner. That second-place winner would definitely be XCache. If it were not for the official PHP developer adoption of APC, and the other reasons listed above, XCache would still be running on this server.

So, without further adieu, here is how to get APC working properly with PHP.


First, you will need to download the sources for APC and build the extension. You can either download the source manually from pecl.php.net, or you can just install it using PECL like this:

pecl install apc

Should you choose to go the manual compilation route, it’s just like any other extension to build the sources:

./configure ; make ; make install


Now that the extension is built (and you’ve made sure no other opcode cachers are enabled), you can move on to configuration:

extension = apc.so
apc.enabled = 1
apc.enable_cli = 1
apc.shm_size = 64M
apc.num_files_hint = 1024
apc.ttl = 86400
apc.user_ttl = 86400
apc.gc_ttl = 3600
apc.filters = "-(.*)/apc\.php$"
apc.mmap_file_mask = /dev/zero
apc.max_file_size = 2M
;; Uncomment below ONLY when you're sure files are rarely
;; modified AND your site's traffic is relatively high. 
;; This will introduce a nice little performance boost.
;apc.stat = 0
apc.rfc1867 = 1
apc.rfc1867_prefix = "upload_"
apc.rfc1867_name = "APC_UPLOAD_PROGRESS"
apc.rfc1867_freq = 100k
apc.localcache = 1
apc.localcache.size = 512

As always, these options are strictly provided as a suggestion, and should be changed to suit your needs. Most people should be able to use them mostly as-is though, so don’t fret if you don’t understand what the options mean. Even though they are already explained in great detail here, I will still explain the relevant options from my example configuration above.

Of course, the first three lines enable the extension, but you knew that…

A brief note about the CLI option: It should typically be no issue to leave this enabled on most systems. This option facilitates testing via the command line by running your scripts directly. It will produce the same results as they would when run in a browser, as long as you run them as the same user the web server (or PHP processor) is configured to run as. Most people want to test scripts and get the same results locally as they would from the browser, plus some users simply write PHP scripts that are run via cron and this should increase performance of those scripts as well, so I vote for leaving this option enabled. You should test the option in production on your own system to make sure it has no negative effects, and if so, leave it enabled.

The next line defines the SHM size, which leads back to the brief SHM discussion from the eAccelerator article. Time for a quick rehash:

This particular setup limits caching to memory only, which should introduce great amounts of speed versus caching to disk. You can also enable disk caching, but expect a performance hit.

NOTE: The default maximum SHM size on most Linux distros is 32M. Do NOT increase this value without modifying the kernel sysctl (see below) unless you don’t like your webserver or PHP app to work right!

To raise the maximum SHM size on Linux, just run the following command (in bytes so assuming desired MB = M, do: M * 1024 * 1024):

sysctl -w kernel.shmmax=134217728

To calculate the amount of pages, divide your final number by 16 (16 MB per page) and enter that value into shmall:

sysctl -w kernel.shmall=8388608

This assumes you want to raise it to 128MB maximum SHM size. Now, to make that change permanent, just add the following lines to /etc/sysctl.conf:

Controls the maximum shared segment size, in bytes

kernel.shmmax = 134217728

Controls the maximum number of shared memory segments, in pages

kernel.shmall = 8388608

That takes care of SHM-specific options, so now let’s briefly discuss the rest of the ones that really matter:

apc.ttl - Lower traffic sites will typically leave this at 0 (default setting), as this prevents cache items from being removed after specific amounts of time. apc.user_ttl - See apc.ttl’s description. This is just the user cache entries’ TTL. apc.gc_ttl - Maximum number of seconds an entry remains on the garbage collection list (AKA - OpCode Cache Death Row). This is the default setting, but is left in there for quicker modification. apc.filters - This is to filter out files/folders that should not be cached. Leave the apc.php entry and add others to it as needed. apc.mmap_file_mask - Leave this set to /dev/zero if you intend to use SHM instead of file-based caching (recommended), otherwise set it to /tmp/apc.XXXXXX (exactly 6 Xs) for file-backed caching (not recommended). apc.file_update_protection - The number of seconds a file should exist without modification before caching. This prevents broken files from staying that way :) apc.max_file_size - The maximum file size that will be stored in the cache. apc.stat - This is a touchy subject. High traffic sites that rarely (or never) get modified should set it to 0 because if set to anything else, the file’s mtime (modification time) is checked every time it’s accessed, even if it’s already cached. Should there be changes made to scripts (not all that likely unless you’re doing active development), you will need to clear the cache or just restart your PHP interpreter (Apache if using mod_php, or Spawn-FCGI/PHP-FPM). While setting it to zero does mean manual cache clearing is necessary when changes are made to PHP scripts, it also means a nice little performance increase as there is no verification performed on modification times of files that have already been cached.

After you’ve installed and configured APC, you should restart your PHP interpreter and you’ll be ready to go.

Finally, go ahead and move apc.php to a location on your web server where only you can reach it (protect with HTTP authentication, if possible). You’ll be presented with lots of useful data and statistics. Plus, you’ll see a nice pie chart like the one below that I borrowed from Google:

Have a piece of pie?

comments powered by Disqus