1 Installation Instructions for APC
2 ---------------------------------
4 This version of APC should work on PHP 4.3.0 - 4.4.x and
5 5.1.0 - 5.2.x. Yes, that means PHP 5.0.x is no longer
6 supported. Upgrade to PHP 5.1.x or 5.2.x and you will
7 notice all sorts of performance increases.
11 Building from CVS can be done like this:
13 cvs -d :pserver:cvsread@cvs.php.net:/repository login
15 cvs -d :pserver:cvsread@cvs.php.net:/repository co pecl/apc
18 ./configure --enable-apc-mmap --with-apxs --with-php-config=/usr/local/php/bin/php-config
22 Suggested Configuration (in your php.ini file)
23 ----------------------------------------------
30 apc.num_files_hint=1024
31 apc.mmap_file_mask=/tmp/apc.XXXXXX
34 These are fully described at the bottom of this file.
38 If you are trying to get every little bit of speed out of PHP4+APC, you need
39 to tell APC where to find your httpd.h file and also add -DAPC_PHP4_STAT to
40 your CPPFLAGS. (if you don't have httpd.h, install the apache_dev package
42 export CPPFLAGS="-I/usr/include/apache-1.3 -DAPC_PHP4_STAT" (for bash on Debian)
43 setenv CPPFLAGS "-I/usr/include/apache-1.3 -DAPC_PHP4_STAT" (for tsch on Debian)
44 and then re-run your configure script.
46 This optimization saves a stat syscall on the main script file. In PHP5 this
47 optimization is automatic and doesn't need any special build flags.
49 The second thing you are going to want to do to save another syscall is to
50 compile using the --with-apxs configure switch. This should work for both
51 Apache1 and Apache2. Point it directly at your apxs2 script for Apache2.
52 eg. --with-apxs=/usr/local/bin/apxs2
54 +---------------------+
55 | QUICK INSTALL (DSO) |
56 +---------------------+
58 These instructions assume your PHP installation is located in /usr/local/php and you
59 want Apache optimizations (--with-apxs).
61 $ gunzip -c apc_x.y.tar.gz | tar xf -
63 $ /usr/local/php/bin/phpize
64 $ ./configure --enable-apc --enable-apc-mmap --with-apxs --with-php-config=/usr/local/php/bin/php-config
68 You will probably need to run the final command (make install) as root.
70 The above sequence of commands will install a .so file in your PHP
71 installation extension directory. The output of make install should display
72 that path to the screen.
74 Next you must edit your php.ini file, which is normally located in
75 /usr/local/php/lib/php.ini, and add the following line:
79 Replace "/path/to/php/extensions" with whatever path was displayed when you
80 ran make install above.
82 Then restart your web server and consult the output of phpinfo(). If there is
83 an informational section for APC, the installation was successful.
85 +------------------------+
86 | QUICK INSTALL (Static) |
87 +------------------------+
89 APC will not successfully compile on all systems as a DSO. If you run into
90 problems using the DSO quick install, you can try to compile it statically
91 into PHP. (The DSO install is recommended, though.)
93 These instructions assume the current directory is the root of the PHP source
94 tree, and that you have already configured PHP by running its bundled
98 $ gunzip -c apc_x.y.tar.gz | tar xf -
105 Once this is complete, simply restart your web server. You do not need to
106 modify your php.ini file to enable APC.
112 These instructions assume your PHP installation is located in /usr/local/php.
114 1. Unpack your distribution file.
116 You will have downloaded a file named something like apc_x.y.tar.gz.
117 Unzip this file with a command like
119 gunzip apc_x.y.tar.gz
121 Next you have to untar it with
125 This will create an apc_x.y directory. cd into this new directory:
131 phpize is a script that should have been installed with PHP, and is
132 normally located in /usr/local/php/bin assuming you installed PHP in
133 /usr/local/php. (If you do not have the phpize script, you must reinstall
134 PHP and be sure not to disable PEAR.)
136 Run the phpize command:
138 /usr/local/php/bin/phpize
140 Its output should resemble this:
142 autoheader: `config.h.in' is created
143 You should update your `aclocal.m4' by running aclocal.
145 PHP Api Version: 20020918
146 Zend Module Api No: 20020429
147 Zend Extension Api No: 20021010
149 phpize should create a configure script in the current directory. If you
150 get errors instead, you might be missing some required development tools,
151 such as autoconf or libtool. You can try downloading the latest versions
152 of those tools and running phpize again.
154 3. Run the configure script.
156 phpize creates a configure script. The only option you need to specify is
157 the location of your php-config script:
159 ./configure --enable-apc
161 php-config should be located in the same directory as phpize.
163 If you prefer to use mmap instead of the default IPC shared memory support,
164 add --enable-apc-mmap to your configure line.
166 If you prefer to use sysv IPC semaphores over the safer fcntl() locks, add
167 --enable-sem to your configure line. If you don't have a problem
168 with your server segaulting, or any other unnatural accumulation of
169 semaphores on your system, the semaphore based locking is slightly faster.
171 4. Compile and install the files. Simply type: make install
173 (You may need to be root in order to install)
175 If you encounter errors from libtool or gcc during this step, please
176 contact the project maintainer (dcowgill@php.net).
180 make install should have printed a line resembling the following:
182 Installing shared extensions: /path/to/extension/
184 Copy the path /path/to/extension/ and add the following line to your
185 php.ini file (normally located in /usr/local/php/lib/php.ini):
189 If you don't have a php.ini file in that location, you can create it now.
191 6. Restart the web server and test the installation.
193 Restart your web server now (for apache, it's apachectl restart) and
194 create a small test PHP file in your document root. The file should
195 contain just the following line:
199 Request that file in a web browser. If there is an entry for APC in the
200 list of installed modules, the installation was successful.
202 If APC is not listed, consult your web server error log. If it contains an
203 error message saying that it can't load the APC extension, your system
204 might not be able to load shared libraries created with PHP's build
205 system. One alternative would be to compile APC statically into PHP. See
206 the Quick Install (Static) instructions above.
208 You should consult your error log anyway to see if APC generated any
209 errors. On BSD-based platforms, it is typical for APC to be unable to
210 allocate the default-sized shared memory segment. See below for hints on
211 raising your system's shared memory limitations.
217 Although the default APC settings are fine for many installations, serious
218 users should consider tuning the following parameters:
221 ------------------ --------------------------------------------------
222 apc.enabled This can be set to 0 to disable APC. This is
223 primarily useful when APC is statically compiled
224 into PHP, since there is no other way to disable
225 it (when compiled as a DSO, the zend_extension
226 line can just be commented-out).
229 apc.shm_segments The number of shared memory segments to allocate
230 for the compiler cache. If APC is running out of
231 shared memory but you have already set
232 apc.shm_size as high as your system allows, you
233 can try raising this value. Setting this to a
234 value other than 1 has no effect in mmap mode
235 since mmap'ed shm segments don't have size limits.
238 apc.shm_size The size of each shared memory segment in MB.
239 By default, some systems (including most BSD
240 variants) have very low limits on the size of a
241 shared memory segment.
244 apc.optimization This option has been deprecated.
247 apc.num_files_hint A "hint" about the number of distinct source files
248 that will be included or requested on your web
249 server. Set to zero or omit if you're not sure;
250 this setting is mainly useful for sites that have
251 many thousands of source files.
254 apc.user_entries_hint Just like num_files_hint, a "hint" about the number
255 of distinct user cache variables to store.
256 Set to zero or omit if you're not sure;
259 apc.ttl The number of seconds a cache entry is allowed to
260 idle in a slot in case this cache entry slot is
261 needed by another entry. Leaving this at zero
262 means that your cache could potentially fill up
263 with stale entries while newer entries won't be
267 apc.user_ttl The number of seconds a user cache entry is allowed
268 to idle in a slot in case this cache entry slot is
269 needed by another entry. Leaving this at zero
270 means that your cache could potentially fill up
271 with stale entries while newer entries won't be
276 apc.gc_ttl The number of seconds that a cache entry may
277 remain on the garbage-collection list. This value
278 provides a failsafe in the event that a server
279 process dies while executing a cached source file;
280 if that source file is modified, the memory
281 allocated for the old version will not be
282 reclaimed until this TTL reached. Set to zero to
283 disable this feature.
286 apc.cache_by_default On by default, but can be set to off and used in
287 conjunction with positive apc.filters so that files
288 are only cached if matched by a positive filter.
291 apc.filters A comma-separated list of POSIX extended regular
292 expressions. If any pattern matches the source
293 filename, the file will not be cached. Note that
294 the filename used for matching is the one passed
295 to include/require, not the absolute path. If the
296 first character of the expression is a + then the
297 expression will be additive in the sense that any
298 files matched by the expression will be cached, and
299 if the first character is a - then anything matched
300 will not be cached. The - case is the default, so
304 apc.mmap_file_mask If compiled with MMAP support by using --enable-mmap
305 this is the mktemp-style file_mask to pass to the
306 mmap module for determing whether your mmap'ed memory
307 region is going to be file-backed or shared memory
308 backed. For straight file-backed mmap, set it to
309 something like /tmp/apc.XXXXXX (exactly 6 X's).
310 To use POSIX-style shm_open/mmap put a ".shm"
311 somewhere in your mask. eg. "/apc.shm.XXXXXX"
312 You can also set it to "/dev/zero" to use your
313 kernel's /dev/zero interface to anonymous mmap'ed
314 memory. Leaving it undefined will force an
318 apc.slam_defense ** DEPRECATED - Use apc.write_lock instead **
319 On very busy servers whenever you start the server or
320 modify files you can create a race of many processes
321 all trying to cache the same file at the same time.
322 This option sets the percentage of processes that will
323 skip trying to cache an uncached file. Or think of it
324 as the probability of a single process to skip caching.
325 For example, setting this to 75 would mean that there is
326 a 75% chance that the process will not cache an uncached
327 file. So the higher the setting the greater the defense
328 against cache slams. Setting this to 0 disables this
332 apc.file_update_protection
333 When you modify a file on a live web server you really
334 should do so in an atomic manner. That is, write to a
335 temporary file and rename (mv) the file into its permanent
336 position when it is ready. Many text editors, cp, tar and
337 other such programs don't do this. This means that there
338 is a chance that a file is accessed (and cached) while it
339 is still being written to. This file_update_protection
340 setting puts a delay on caching brand new files. The
341 default is 2 seconds which means that if the modification
342 timestamp (mtime) on a file shows that it is less than 2
343 seconds old when it is accessed, it will not be cached.
344 The unfortunate person who accessed this half-written file
345 will still see weirdness, but at least it won't persist.
346 If you are certain you always atomically update your files
347 by using something like rsync which does this correctly, you
348 can turn this protection off by setting it to 0. If you
349 have a system that is flooded with io causing some update
350 procedure to take longer than 2 seconds, you may want to
354 apc.enable_cli Mostly for testing and debugging. Setting this enables APC
355 for the CLI version of PHP. Normally you wouldn't want to
356 create, populate and tear down the APC cache on every CLI
357 request, but for various test scenarios it is handy to be
358 able to enable APC for the CLI version of APC easily.
361 apc.max_file_size Prevents large files from being cached.
364 apc.stat Whether to stat the main script file and the fullpath
365 includes. If you turn this off you will need to restart
366 your server in order to update scripts.
369 apc.write_lock On busy servers when you first start up the server, or when
370 many files are modified, you can end up with all your processes
371 trying to compile and cache the same files. With write_lock
372 enabled, only one process at a time will try to compile an
373 uncached script while the other processes will run uncached
374 instead of sitting around waiting on a lock.
377 apc.report_autofilter Logs any scripts that were automatically excluded from being
378 cached due to early/late binding issues.
381 apc.rfc1867 RFC1867 File Upload Progress hook handler is only available
382 if you compiled APC against PHP 5.2.0 or later. When enabled
383 any file uploads which includes a field called
384 APC_UPLOAD_PROGRESS before the file field in an upload form
385 will cause APC to automatically create an upload_<key>
386 user cache entry where <key> is the value of the
387 APC_UPLOAD_PROGRESS form entry.
389 Note that the file upload tracking is not threadsafe at this
390 point, so new uploads that happen while a previous one is
391 still going will disable the tracking for the previous.
394 apc.rfc1867_prefix Key prefix to use for the user cache entry generated by
395 rfc1867 upload progress functionality.
398 apc.rfc1867_name Specify the hidden form entry name that activates APC upload
399 progress and specifies the user cache key suffix.
400 (Default: "APC_UPLOAD_PROGRESS")
402 apc.rfc1867_freq The frequency that updates should be made to the user cache
403 entry for upload progress. This can take the form of a
404 percentage of the total file size or a size in bytes
405 optionally suffixed with 'k', 'm', or 'g' for kilobytes,
406 megabytes, or gigabytes respectively (case insensitive).
407 A setting of 0 updates as often as possible, which may cause
411 apc.localcache ** REMOVED
412 apc.localcache.size ** REMOVED
414 apc.include_once_override
415 Optimize include_once and require_once calls and avoid the
416 expensive system calls used.