运行时配置

这些函数的行为受 php.ini 中的设置影响。

尽管默认的 APC 设定对于大多数安装已经没问题,但专业人员应考虑调整以下参数。

APC有两个主要的配置选项。第一,多少内存将被分配给APC;第二,每次请求APC是否检查文件修改。两个ini选项分别控制这些设置 apc.shm_sizeapc.stat.就这两项配置仔细阅读下面的章节。

一旦服务器运行起来了, apc.php 脚本可以拷贝到一个可以通过浏览器访问到的Web目录中,通过浏览器访问这个脚本会得到APC工作状态的详细分析,如果在PHP中启用了GD扩展,它甚至会显示一些有趣的图表。当然,首要的事情是要确保真的缓存了文件。 如果APC运行了, 缓存完全统计 数目 (在左上角)将显示缓存的命中率并且清除在最后 apc.ttl 秒内没有被访问的缓存。 这个数字使缓存的最小化的很好配置。如果缓存不断的被填充和清除,这将影响缓存的效果和脚本的性能。减少这个数字的最好方式就是给APC分配足够多的内存。除此之外, 可以通过 apc.filters 缓存更少的脚本。

APC配置选项
名字 默认 可修改范围 更新日志
apc.enabled "1" PHP_INI_SYSTEM PHP_INI_SYSTEM in APC 2. PHP_INI_ALL in APC <= 3.0.12.
apc.shm_segments "1" PHP_INI_SYSTEM  
apc.shm_size "30" PHP_INI_SYSTEM  
apc.optimization "0" PHP_INI_ALL PHP_INI_SYSTEM in APC 2. Removed in APC 3.0.13.
apc.num_files_hint "1000" PHP_INI_SYSTEM  
apc.user_entries_hint "4096" PHP_INI_SYSTEM Available since APC 3.0.0.
apc.ttl "0" PHP_INI_SYSTEM Available since APC 3.0.0.
apc.user_ttl "0" PHP_INI_SYSTEM Available since APC 3.0.0.
apc.gc_ttl "3600" PHP_INI_SYSTEM  
apc.cache_by_default "1" PHP_INI_ALL PHP_INI_SYSTEM in APC <= 3.0.12. Available since APC 3.0.0.
apc.filters NULL PHP_INI_SYSTEM  
apc.mmap_file_mask NULL PHP_INI_SYSTEM  
apc.slam_defense "0" PHP_INI_SYSTEM Available since APC 3.0.0.
apc.file_update_protection "2" PHP_INI_SYSTEM Available since APC 3.0.6.
apc.enable_cli "0" PHP_INI_SYSTEM Available since APC 3.0.7.
apc.max_file_size "1M" PHP_INI_SYSTEM Available since APC 3.0.7.
apc.use_request_time "1" PHP_INI_ALL Available since APC 3.1.3.
apc.stat "1" PHP_INI_SYSTEM Available since APC 3.0.10.
apc.write_lock "1" PHP_INI_SYSTEM Available since APC 3.0.11.
apc.report_autofilter "0" PHP_INI_SYSTEM Available since APC 3.0.11.
apc.include_once_override "0" PHP_INI_SYSTEM Available since APC 3.0.12.
apc.rfc1867 "0" PHP_INI_SYSTEM Available since APC 3.0.13.
apc.rfc1867_prefix "upload_" PHP_INI_SYSTEM  
apc.rfc1867_name "APC_UPLOAD_PROGRESS" PHP_INI_SYSTEM  
apc.rfc1867_freq "0" PHP_INI_SYSTEM  
apc.rfc1867_ttl "3600" PHP_INI_SYSTEM Available since APC 3.1.1.
apc.localcache "0" PHP_INI_SYSTEM Available since APC 3.0.14.
apc.localcache.size "512" PHP_INI_SYSTEM Available since APC 3.0.14.
apc.coredump_unmap "0" PHP_INI_SYSTEM Available since APC 3.0.16.
apc.stat_ctime "0" PHP_INI_SYSTEM Available since APC 3.0.13.
apc.preload_path NULL PHP_INI_SYSTEM Available since APC 3.1.1.
apc.file_md5 "0" PHP_INI_SYSTEM Available since APC 3.1.1.
apc.canonicalize "1" PHP_INI_SYSTEM Available since APC 3.1.1.
apc.lazy_functions 0 PHP_INI_SYSTEM Available since APC 3.1.3.
apc.lazy_classes 0 PHP_INI_SYSTEM Available since APC 3.1.3.
有关 PHP_INI_* 样式的更多详情与定义,见 配置可被设定范围

这是配置指令的简短说明。

apc.enabled boolean

apc.enabled 可以设成 0 来禁用 APC.主要是用在当 APC 被静态编译入 PHP 时,因为没有其它方法来禁用了(编译为 DSO , 的时候,可以将php.ini中的extension 行注释掉)。

apc.shm_segments integer

编译器缓存要分配的共享内存块的数目。如果 APC 用光了共享内存但是已经将 apc.shm_size 设为了系统所能允许的最大值,可以尝试增大此值。

apc.shm_size integer

以 MB 为单位的每个共享内存块的大小。默认时,有些系统(包括大多数 BSD 变种)的共享内存块大小非常低。

apc.optimization integer

优化级别。设为 0 则禁用优化器,更高的值则使用更主动的优化。期望非常有限的速度提升。尚在试验中。

apc.num_files_hint integer

Web 服务器上的被包含或被请求的不同源文件的数目的大概估计。如果不确定则设为 0 或去掉此项;此设定主要用在有数千个源文件的站点。

apc.user_entries_hint integer

apc.num_files_hint类似, 根据唯一用户数来存储缓存变量。 如果不能确定则设置为0或或去掉此项。

apc.ttl integer

缓存条目在缓冲区中允许逗留的秒数。0 表示永不超时。建议值为7200~86400 设为 0 意味着缓冲区有可能被旧的缓存条目填满,从而导致无法缓存新条目。

apc.user_ttl integer

类似于apc.ttl,只是针对每个用户而言,建议值为7200~86400。 设为 0 意味着缓冲区有可能被旧的缓存条目填满,从而导致无法缓存新条目。 如果大于0,APC将尝试删除过期条目。

apc.gc_ttl integer

缓存条目在垃圾回收表中能够存在的秒数。此值提供了一个安全措施,即在服务器进程在执行缓存的源文件时,如果该文件被修改则旧版本将不会被回收,直到达到此 TTL 为止。设为零将禁用此特性。

apc.cache_by_default boolean

默认为 on,但可以设为 off 并和加号开头的 apc.filters 一起用,则文件仅在匹配过滤器时被缓存。

apc.filters string

一个以逗号分隔的 POSIX 扩展正则表达式的列表。如果任一个模式匹配源文件名,则该文件不被缓存。注意用来匹配的文件名是传递给 include/require 的文件名,而不是绝对路径。如果正则表达式的第一个字符是+ t则意味着任何匹配表达式的文件会被缓存,如果第一个字符是 - 则任何匹配项都不会被缓存。 -是默认值,可以省略掉。

apc.mmap_file_mask string

如果使用 --enable-mmap(默认启用)为APC编译了MMAP支持, 这里的值就是传递给mmap模块的mktemp风格的文件掩码(建议值为" /tmp/apc.XXXXXX")。 该掩码用于决定内存映射区域是否要被file-backed或者shared memory backed。 对于直接的file-backed内存映射,要设置成"/tmp/apc.XXXXXX"的样子(恰好6个X)。 要使用POSIX风格的shm_open/mmap就需要设置成"/apc.shm.XXXXXX"的样子。 你还可以设为"/dev/zero"来为匿名映射的内存使用内核的"/dev/zero"接口。 不定义此指令则表示强制使用匿名映射。

apc.slam_defense integer

在非常繁忙的服务器上,无论是启动服务还是修改文件, 都可能由于多个进程企图同时缓存一个文件而导致竞争条件。 这个选项用于设置进程在处理未被缓存的文件时跳过缓存步骤的百分率。 比如设为75表示在遇到未被缓存的文件时有75%的概率不进行缓存,从而减少碰撞几率。 反对使用该指令,鼓励设为 0来禁用这个特性。建议该用apc.write_lock指令。

Deprecated by apc.write_lock.

apc.file_update_protection integer

当你在一个运行中的服务器上修改文件时,你应当执行原子操作。 也就是先写进一个临时文件,然后将该文件重命名(mv)到最终的名字。 文本编辑器以及 cp, tar 等程序却并不是这样操作的,从而导致有可能缓冲了残缺的文件。 默认值 2 表示在访问文件时如果发现修改时间距离访问时间小于 2 秒则不做缓冲。 那个不幸的访问者可能得到残缺的内容,但是这种坏影响却不会通过缓存扩大化。 如果你能确保所有的更新操作都是原子操作,那么可以用 0 关闭此特性。 如果你的系统由于大量的IO操作导致更新缓慢,你就需要增大此值。

apc.enable_cli integer

是否为CLI版本启用APC功能,仅用于测试和调试目的才打开此选项。 在正常情况下不是理想的创建、 填充和销毁 CLI 的每个请求上的 APC 缓存,但各种测试方案很有用,能够轻松地使 CLI 版本的 PHP APC

apc.max_file_size integer

Prevent files larger than this value from getting cached. Defaults to 1M.

apc.stat integer

是否启用脚本更新检查。 改变这个指令值要非常小心。 默认值 On 表示APC在每次请求脚本时都检查脚本是否被更新, 如果被更新则自动重新编译和缓存编译后的内容。但这样做对性能有不利影响。 如果设为 Off 则表示不进行检查,从而使性能得到大幅提高。 但是为了使更新的内容生效,你必须重启Web服务器(译者注:如果采用cgi/fcgi类似的,需重启cgi/fcgi进程)。 生产服务器上脚本文件很少更改, 可以通过禁用本选项获得显著的性能提升。

这个指令对于include/require的文件同样有效。但是需要注意的是, 如果你使用的是相对路径,APC就必须在每一次include/require时都进行检查以定位文件。 而使用绝对路径则可以跳过检查,所以鼓励你使用绝对路径进行include/require操作。

apc.write_lock boolean

在繁忙的服务器上,Web服务器第一次被启动,或者很多文件在同一时间被修改,APC可能会多次编译同一个文件,写锁保证只有一个进程将尝试编译并缓存未缓存的脚本。其他进程试图使用该脚本将不使用opcode缓存,而不是锁定和等待缓存生成。

apc.report_autofilter boolean

是否记录所有由于early/late binding原因而自动未被缓存的脚本。

apc.include_once_override boolean

优化include_oncerequire_once函数以避免执行额外的系统调用。

apc.rfc1867 boolean

RFC1867 File Upload Progress hook handler is only available if APC was compiled against PHP 5.2.0 or later. When enabled, any file uploads which includes a field called APC_UPLOAD_PROGRESS before the file field in an upload form will cause APC to automatically create an upload_key user cache entry where key is the value of the APC_UPLOAD_PROGRESS form entry.

Note that the hidden field specified by APC_UPLOAD_PROGRESS must come before the file field, otherwise the upload progress will not work correctly.

Note that the file upload tracking is not threadsafe at this point, so new uploads that happen while a previous one is still going will disable the tracking for the previous.

Example #1 An apc.rfc1867 example

<?php
print_r
(apc_fetch("upload_$_POST[APC_UPLOAD_PROGRESS]"));
?>

以上例程的输出类似于:

Array
(
    [total] => 1142543
    [current] => 1142543
    [rate] => 1828068.8
    [filename] => test
    [name] => file
    [temp_filename] => /tmp/php8F
    [cancel_upload] => 0
    [done] => 1
)

apc.rfc1867_prefix string

用于上传文件的缓冲项条目名称前缀

apc.rfc1867_name string

需要由APC处理的上传文件的隐藏表单项名称

apc.rfc1867_freq string

用户上传文件缓存项的更新频率。 取值可以是总文件大小的百分比,或者以 "k", "m", or "g" kilobytes, megabytes, or gigabytes 结尾的绝对尺寸 (大小写不敏感). 0 表示尽可能快的更新,不过这样可能会导致上传速度下降。

apc.rfc1867_ttl bool

TTL for rfc1867 entries.

apc.localcache boolean

使用非锁定本地进程shadow-cache ,它可以减少了向缓冲区写入时锁之间的竞争。

apc.localcache.size integer

The size of the local process shadow-cache, should be set to a sufficiently large value, approximately half of apc.num_files_hint.

apc.coredump_unmap boolean

启用APC的信号句柄,例如SIGSEGV信号,当信号写入核心文件。当这些信号被接收,APC将试图取消映射的共享内存段,从核心文件中排除它。此设置可以提高系统的稳定性,当接受到致命的信号或者采用APC的大型共享内存段配置方式。

Warning

此功能是潜在的危险。如果发生致命错误取消映射一个共享内存段致命的信号句柄, 可能会导致不可预知的结果。

Note:

虽然有些内核可能会提供了便利,忽略各类共享内存时生成核心转储文件,这些实现可能也忽略了重要的共享内存段,比如 Apache scoreboard。

apc.stat_ctime integer

验证ctime(创建时间)可以避免SVN或者rsync带来的问题,确保自上次统计inode没有改变。APC通常只检查mtime(修改时间)。

apc.canonicalize bool

如果设置为on,则在no-state 模式(不检查文件更新)时会将相对路径改为绝对路径。

apc.preload_path string

apc.use_request_time bool

Use the SAPI request start time for TTL.

apc.file_md5 bool

记录文件的md5值

apc.lazy_functions integer

启用函数延迟加载

apc.lazy_classes integer

启用类延迟加载

User Contributed Notes

klaus at hax dot at 11-Jun-2013 01:02
Note: If you want to run a script on Windows with apc.enabled=1 as a scheduled task whilst another instance of php is running (like on a webserver) apparently you have to disable apc for this scheduled task, otherwise it will not run and you will have something in your error log like: PHP Fatal error: PHP Startup: apc_shm_create: shmget(0, 33554432, 658) failed: No such file or directory.

So simply execute your scheduled task with:

c:\php\php.exe -d apc.enabled=0 and all will be fine.
bas_vijfiwinkel 17-Aug-2012 05:36
I took some time to look at the preload_path option.

At the moment of writing the preload_path option is broken because of a bug in the APC source code
which will not allow you to properly preload the cache.

The way to fix it :
Inside 'main_apc.c' in the method called 'static int apc_load_data(const char *data_file TSRMLS_DC)', the length of the key of the value that needs to be stored is determined with the following line :
key_len = strlen(key);
If I am correct this is only the length of the string itself without the null-terminator
However, "_apc_store" seems to want the length of the key string including the terminator.
If I change the line above to :
key_len = strlen(key)+1;
then the preload function works as expected.
You can also notice that 1 character is missing when looking at the user cache entries apc.php. But if you try to use that as a key then APC will not return the contents so that didn't work as a workaround.

If one is able to compile the apc library from source, then one can of course easily fix this option by changing the source code.

Files in the specified path should have the extension '.data'.
The filename itself will become the key for the data that is in that specific file.
The data in the file is a serialized string representing what you want to assign to the specific key. For example s:2:"123" will generate the string "123".
One can only specify 1 value for each key and it should be null-terminated.

It is not possible to preload PHP scripts.
Only values that one retrieved with apc_fetch can be preloaded.
d_inkubus at yahoo dot com 20-Feb-2010 11:49
apc.include_once_override=1 can cause more problems than it solves.  If you're running into weird errors regarding relative paths, make sure this setting is off.  PHP 5.3 already implements most of the speed ups in these calls anyway.
amir w of colnect dot com TIPS 01-Feb-2010 05:30
apc.stat is an extremely important setting for a production server, especially if many files are accessed on every request, which is quite normal on complicated web applications.

Always aspire to use:
apc.stat="0"
so that APC does not try to check that each and every file exists on every request you make. It also means you can update files on your server without crashing incoming requests on that time fragment. Whenever you wish to force APC to re-read all the files, simply clear the cache or restart your server.
amir w of colnect dot com TIPS 01-Feb-2010 05:03
Want to avoid segmentation with apc.shm_segments?If your linux server limits the shared memory block size and you're forced to use apc.shm_segments instead, change the setting by using (here is 512M but change it as you like):
# sysctl -w kernel.shmmax=536870912

(but if you want the change to be permanent after a restart you would have to add the following line in /etc/sysctl.conf

kernel.shmmax=536870912)

and updating apc.ini

apc.shm_segments="1"
apc.shm_size="512"


apc.stat is an extremely important setting for a production server, especially if many files are accessed on every request, which is quite normal on complicated web applications.

Always aspire to use:
apc.stat="0"
so that APC does not try to check that each and every file exists on every request you make. It also means you can update files on your server without crashing incoming requests on that time fragment. Whenever you wish to force APC to re-read all the files, simply clear the cache or restart your server.
fusionstream [a](t) gmail.com 14-Jan-2010 02:25
If you are getting 0kb out of 0kb for your upload progress with large files, make sure that upload_max_filesize and post_max_size are larger than the file you are uploading. As far as I can tell, apc.max_file_size does not affect it.
Will 10-Nov-2009 04:27
For anyone wondering why shm_segments is being ignored on their setup, it could be because of the following:

If you've configured APC to use memory mapped files (with the --enable-mmap option), the shm_segments setting is ignored unless you specify a file mask via the mmap_file_mask setting.

This is because APC won't attempt to create multiple anonymous files to map into memory without a mask (since it has no way of naming them sensibly). To set up multiple segments you have to give a file mask so they can be named separately.

apc.mmap_file_mask=/tmp/apc.XXXXXX

Make sure to use exactly 6 "X"s (this is the part that is changed by APC). You can place these files anywhere, they don't have to go in /tmp.

With that said, I'm not sure what the performance impact of having multiple MMAP segments would be. I'm guessing it would probably be negative so you probably don't want to do this.
neorush at gmail dot com 26-Aug-2009 03:16
apc_fetch always returned false.  Turns out that "apc.rfc1867" was set to "0".  I added this line to my php.ini:
apc.rfc1867 = 1
but it could have certainly been changed with ini_set().  That took me way to long to figure out.
bishop 26-Feb-2009 07:22
The apc.rfc1867 example code above is a little fast and loose for those running in environments where APC RFC1867 may or may not be available.  This is a little more expressive:

<?php

// if we have PHP and APC
$havePHP = (1 === version_compare(PHP_VERSION, '5.2.0') ? true : false);
$haveAPC = (extension_loaded('apc') && 1 === version_compare(phpversion('apc'), '3.0.13') ? true : false);
if (
$havePHP && $haveAPC) {
   
// if APC and upload tracking is enabled
   
if (ini_get('apc.enabled') && ini_get('apc.rfc1867')) {
       
// get the stats
       
$key = ini_get('apc.rfc1867_prefix') . $_REQUEST['apcid'];
       
$stats = apc_fetch($key);
    }
}

?>
lamperz at gmail dot com 30-Oct-2008 09:52
I'm trying to get upload progress with apc_fetch.
I founded apc_fetch always return false till the upload completed.After fews hours debug, I finally notice that my APC_UPLOAD_PROGRESS was set after the file form.

SO, You should write your form like this
<input type="hidden" id="file_id" name="APC_UPLOAD_PROGRESS" value="blablabla"/>
<input type="file" id="select_file" name="file" value="upload" onchange="parent.test();"/>

the hidden field with name="APC_UPLOAD_PROGRESS" SHOULD be ALWAYS BEFORE input type="file"
danbettles at yahoo dot co dot uk 11-Oct-2008 04:26
To automatically cache only PHP class files named "<class name>.class.php", add the following lines to php.ini.

apc.cache_by_default = "Off"
apc.filters = "+\.class\.php$"

Notes:
- The regexp is case /sensitive/, so if, say, your project contains filenames with mixed case, you'll need something like "+\.(class|CLASS)\.(php|PHP)$".  I've tried delimiting patterns and using the "i" modifier, but that doesn't seem to work.
- Setting cache_by_default to "On" and applying the positive filter will /not/ work.

If you have more complicated requirements and, like me, you're not familiar with POSIX Extended Regular Expressions (ERE) inparticular, you may find the following link useful.  http://www.regular-expressions.info/refflavors.html