Preface ¶

The Advanced PHP Cache is a PHP extension which primarily serves as an opcode cache for PHP. The basic idea is to save PHP from re-evaluating the PHP code to intermediate bytecode on each request. Installing and enabling APC already yields a significant performance benefit. However, APC is not a black box that will magically change all for the better. More over it is important to understand that APC needs memory to operate. > Note: By enabling APC you are trading memory for speed

In addition to the opcode cache, APC can also serve as a user cache for Yii via [CApcCache]. It should be noted that this will make APC's memory needs less predictable.

Installation ¶

APC is best installed by means of your distribution's packaging system. For RedHat based distros (RHEL, CentOS, Fedora, Mandriva), you'll need to install the php-pecl-apc package: ~~~ $ sudo yum install php-pecl-apc ~~~ For Debian based distributions, this will be the php-apc package: ~~~ $ sudo apt-get install php-apc ~~~ If you are running a self-compiled version of PHP, you can install APC via the PEAR/PECL command-line tool: ~~~ $ sudo pecl install APC ~~~ > Info: Be advised that this will compile the current version of APC on your system, so you'll need to have the GCC toolchain installed as well as the PHP headers along with the phpize helper.

You will almost certainly need to add APC to your PHP configuration. Otherwise, PHP won't load it. Simply drop a new file called apc.ini into /usr/local/etc/php.d (RedHat) or /usr/local/php.d/apache2/conf.d (Debian) with the following content: ~~~ extension=apc.so ~~~

Preparing Yii ¶

1. Preface
2. Installation
3. Configuration
4. Monitoring APC
5. Situation as of PHP v5.5

The Yii framework comes with a yiilite.php which can be used instead of yii.php. Despite its name, it includes the most used classes. The benefit to APC is that the opcode cache can be quickly filled via one single file instead of including several smaller files and dynamically loading several classes. This change must be done in the file index.php, in the webroot of your application.

If you wish to use APC as a user cache as well, you'll need to register the CApcCache as cache component in your config. Locate the components-stanza in your config and add the following lines:

'components'=>array(
  'cache'=>array(
    'class'=>'CApcCache',
  ),
  ...
),

Configuration ¶

Server Filesystem ¶

If you have several Yii-based applications running on one server, you might want to consider dropping one copy of the Yii framework (i.e. the content of the framework folder in the release tarball) into /usr/local/share/yii and let the include_path configuration setting point to that. APC will only have to pick up one copy of Yii then. In the process, you'll also conserve a bit of disk space.

APC Settings ¶

APC can be fine-tuned by a number of settings. Just toss them into your apc.ini, restart your webserver (or php-fpm process) and see the magic happening. The following options are the most important:

• apc.enabled Self explaining. This option enables or disables APC alltogether. Be advised that this is a system-wide setting, soyou cannot selectively switch APC on or off for e.g. certain directories via a .htaccess or .user.ini file.
  You'll want this to be set to on, which is the default value.
• apc.shm_size The size of the cache. Take note that is the size of the opcode and the user cache. Currently, APC does not allow you to specify seperate memory segments for these. As a general rule: Do not set this lower than 16MB and monitor APC's memory usage closely. If you set this too low, APC's memory might suffer heavy fragmentation, which will result in a high performance penalty or even constant segfaults.
  Monitor your APC activity (see the following section) and set a value where APC's memory isn't too fragmented (generally at least 32 MB).
• apc.stat Controls if APC should check for modified files on every request. This setting will bring you the greatest speed benefit. Set it to 0 on production servers but to 1 in development environments (otherwise PHP won't pick up changes you've applied to the code). If you're rolling out a new version of your software, simply restart your webserver or FastCGI process in order to clear the opcode cache.
• apc.shm_strings_buffer This setting got introduced in v3.1.14 of APC. It controls the internal strings buffer that is being shared between php-fpm worker instances, avoiding to store stings for each instance separately. The adequate size of this setting is extremely difficult to evaluate as no fill count is reported through APC's API. Try to set this as low as possible as the memory penalty for a value too high is quite hefty, increasing the memory need by several magnitudes in its extremes.

Other interesting parameters are:

• apc.cache_by_default Controls the default caching behaviour of APC. This can be used together with apc.filters for complex cache setups. But in most cases, you'll want this to be 1.
• apc.ttl Controls how long cached opcodes may be cached before being reloaded. Set this to 0 on your productions system so this will never happen. This is most useful together with apc.stat=0.
• apc.num_files_hint This is a hint for APC to reserve sufficient space for the opcode cache. It helps APC during the initial cache build. It isn't terribly important as it's really just a hint. But while you're at it: Set it to roughly the number of your project's PHP files.
• apc.user_entries_hint Same as apc.num_files_hint but for user cache entries, so it is only interesting if you're using APC as a user cache, too. A too high value might result in over-provisioning memory for the cache. This is highly individual, so you'll need to evaluate this yourself.
• apc.mmap_file_mask Filemask for the shared memory mechanism. There are three kinds of values this setting can take. Something like /tmp/apc.XXXXXX (place exactly 6 X's) will create an mmap'ed file in your /tmp directory. /dev/zero does the same but without creating a file. The best setting I could find has been /apc.shm.XXXXXX. For this to work properly, /dev/shm must be mounted on a tempfs. The benefit of using shared memory for APC lies in the lockless nature. The downside, however, is that this method for storing APC's content is everything but thread-safe. This is mostly important if you are running PHP in an Apache environment via mod_php with an MPM other than prefork, as you will experience constant segfaults.
• apc.lazy_classes and apc.lazy_functions These settings are marked as experimental. However, I've found no regressions after using these. If you're feeling lucky and you're using anonymous functions for evaluateExpression(), you may want to set these to 1.
• apc.include_once_override Setting this to on will speed up include* and require* calls. However, this setting will introduce changes in the behaviour of PHP. While Yii is content with this being switched on, other applications (such as phpMyAdmin) are not. So watch out for breaking applications.
• apc.serializer Starting with version 3.1.7, APC can facilitate a substitute for PHP's native serialize() function. This is most interesting in conjunction with the igbinary serializer, which aims to provide a more compact serialization. This might result into smaller cache sizes for you (among with a small speed benefit). But again: Your milage may vary, so evaluate carfully. It should be noted that the two serialization formats are incompatible. So when changing the serializer, clearing caches is advisable.
• apc.optimizer This setting receives mentioning every now and then. But truth be told: It doesn't do anything since APC v3.0.13. The APC optimizer got forked into a separate project which never really took off.

Monitoring APC ¶

Some of the aforementioned settings can be very specific to your setup and your application. So you need to take a look at what APC is doing. There are currently two ways of achieving this:

• APC itself comes with a bundled apc.php which will tell you a bit about memory consumption, fragmentation and cache content. You'll most likely find it in /usr/local/doc/apc. Copy it to a location where your webserver can reach it and take appropriate measures to protect it from unauthorized access (open the php file and set the password in its first lines).
• Available as an extension to your very own app comes the apcinfo extension which does roughly the same job as apc.php but integrates nicely into your app.

Situation as of PHP v5.5 ¶

The last officially released version of APC as of this writing is not compatible with PHP 5.5's ABI. A solution to this dilemma is fetching the tag 3.1.14 from git and building the APC extension from source. The alternative is to use the built-in opcache in conjunction with the APCu extension.