+++ /dev/null
-Installation Instructions for APC
----------------------------------
-
-This version of APC should work on PHP 4.3.0 - 4.4.x and
-5.1.0 - 5.2.x. Yes, that means PHP 5.0.x is no longer
-supported. Upgrade to PHP 5.1.x or 5.2.x and you will
-notice all sorts of performance increases.
-
-CVS Instructions
-----------------
-Building from CVS can be done like this:
-
- cvs -d :pserver:cvsread@cvs.php.net:/repository login
- Password: phpfi
- cvs -d :pserver:cvsread@cvs.php.net:/repository co pecl/apc
- cd pecl/apc
- phpize
- ./configure --enable-apc-mmap --with-apxs --with-php-config=/usr/local/php/bin/php-config
- make
- make install
-
-Suggested Configuration (in your php.ini file)
-----------------------------------------------
- extension=apc.so
- apc.enabled=1
- apc.shm_segments=1
- apc.shm_size=128
- apc.ttl=7200
- apc.user_ttl=7200
- apc.num_files_hint=1024
- apc.mmap_file_mask=/tmp/apc.XXXXXX
- apc.enable_cli=1
-
-These are fully described at the bottom of this file.
-
-PHP 4 Optimization
-------------------
-If you are trying to get every little bit of speed out of PHP4+APC, you need
-to tell APC where to find your httpd.h file and also add -DAPC_PHP4_STAT to
-your CPPFLAGS. (if you don't have httpd.h, install the apache_dev package
-for your OS) and do:
- export CPPFLAGS="-I/usr/include/apache-1.3 -DAPC_PHP4_STAT" (for bash on Debian)
- setenv CPPFLAGS "-I/usr/include/apache-1.3 -DAPC_PHP4_STAT" (for tsch on Debian)
-and then re-run your configure script.
-
-This optimization saves a stat syscall on the main script file. In PHP5 this
-optimization is automatic and doesn't need any special build flags.
-
-The second thing you are going to want to do to save another syscall is to
-compile using the --with-apxs configure switch. This should work for both
-Apache1 and Apache2. Point it directly at your apxs2 script for Apache2.
-eg. --with-apxs=/usr/local/bin/apxs2
-
-+---------------------+
-| QUICK INSTALL (DSO) |
-+---------------------+
-
-These instructions assume your PHP installation is located in /usr/local/php and you
-want Apache optimizations (--with-apxs).
-
-$ gunzip -c apc_x.y.tar.gz | tar xf -
-$ cd apc_x.y
-$ /usr/local/php/bin/phpize
-$ ./configure --enable-apc --enable-apc-mmap --with-apxs --with-php-config=/usr/local/php/bin/php-config
-$ make
-$ make install
-
-You will probably need to run the final command (make install) as root.
-
-The above sequence of commands will install a .so file in your PHP
-installation extension directory. The output of make install should display
-that path to the screen.
-
-Next you must edit your php.ini file, which is normally located in
-/usr/local/php/lib/php.ini, and add the following line:
-
- extension="apc.so"
-
-Replace "/path/to/php/extensions" with whatever path was displayed when you
-ran make install above.
-
-Then restart your web server and consult the output of phpinfo(). If there is
-an informational section for APC, the installation was successful.
-
-+------------------------+
-| QUICK INSTALL (Static) |
-+------------------------+
-
-APC will not successfully compile on all systems as a DSO. If you run into
-problems using the DSO quick install, you can try to compile it statically
-into PHP. (The DSO install is recommended, though.)
-
-These instructions assume the current directory is the root of the PHP source
-tree, and that you have already configured PHP by running its bundled
-configure script.
-
-$ cd ext
-$ gunzip -c apc_x.y.tar.gz | tar xf -
-$ cd ..
-$ ./buildconf
-$ ./config.nice
-$ make
-$ make install
-
-Once this is complete, simply restart your web server. You do not need to
-modify your php.ini file to enable APC.
-
-+-----------------+
-| VERBOSE INSTALL |
-+-----------------+
-
-These instructions assume your PHP installation is located in /usr/local/php.
-
-1. Unpack your distribution file.
-
- You will have downloaded a file named something like apc_x.y.tar.gz.
- Unzip this file with a command like
-
- gunzip apc_x.y.tar.gz
-
- Next you have to untar it with
-
- tar xvf apc_x.y.tar
-
- This will create an apc_x.y directory. cd into this new directory:
-
- cd apc_x.y
-
-2. Run phpize.
-
- phpize is a script that should have been installed with PHP, and is
- normally located in /usr/local/php/bin assuming you installed PHP in
- /usr/local/php. (If you do not have the phpize script, you must reinstall
- PHP and be sure not to disable PEAR.)
-
- Run the phpize command:
-
- /usr/local/php/bin/phpize
-
- Its output should resemble this:
-
- autoheader: `config.h.in' is created
- You should update your `aclocal.m4' by running aclocal.
- Configuring for:
- PHP Api Version: 20020918
- Zend Module Api No: 20020429
- Zend Extension Api No: 20021010
-
- phpize should create a configure script in the current directory. If you
- get errors instead, you might be missing some required development tools,
- such as autoconf or libtool. You can try downloading the latest versions
- of those tools and running phpize again.
-
-3. Run the configure script.
-
- phpize creates a configure script. The only option you need to specify is
- the location of your php-config script:
-
- ./configure --enable-apc
-
- php-config should be located in the same directory as phpize.
-
- If you prefer to use mmap instead of the default IPC shared memory support,
- add --enable-apc-mmap to your configure line.
-
- If you prefer to use sysv IPC semaphores over the safer fcntl() locks, add
- --enable-sem to your configure line. If you don't have a problem
- with your server segaulting, or any other unnatural accumulation of
- semaphores on your system, the semaphore based locking is slightly faster.
-
-4. Compile and install the files. Simply type: make install
-
- (You may need to be root in order to install)
-
- If you encounter errors from libtool or gcc during this step, please
- contact the project maintainer (dcowgill@php.net).
-
-5. Edit your php.ini
-
- make install should have printed a line resembling the following:
-
- Installing shared extensions: /path/to/extension/
-
- Copy the path /path/to/extension/ and add the following line to your
- php.ini file (normally located in /usr/local/php/lib/php.ini):
-
- extension="apc.so"
-
- If you don't have a php.ini file in that location, you can create it now.
-
-6. Restart the web server and test the installation.
-
- Restart your web server now (for apache, it's apachectl restart) and
- create a small test PHP file in your document root. The file should
- contain just the following line:
-
- <?php phpinfo() ?>
-
- Request that file in a web browser. If there is an entry for APC in the
- list of installed modules, the installation was successful.
-
- If APC is not listed, consult your web server error log. If it contains an
- error message saying that it can't load the APC extension, your system
- might not be able to load shared libraries created with PHP's build
- system. One alternative would be to compile APC statically into PHP. See
- the Quick Install (Static) instructions above.
-
- You should consult your error log anyway to see if APC generated any
- errors. On BSD-based platforms, it is typical for APC to be unable to
- allocate the default-sized shared memory segment. See below for hints on
- raising your system's shared memory limitations.
-
-+-----------------+
-| CONFIGURING APC |
-+-----------------+
-
-Although the default APC settings are fine for many installations, serious
-users should consider tuning the following parameters:
-
- OPTION DESCRIPTION
- ------------------ --------------------------------------------------
- apc.enabled This can be set to 0 to disable APC. This is
- primarily useful when APC is statically compiled
- into PHP, since there is no other way to disable
- it (when compiled as a DSO, the zend_extension
- line can just be commented-out).
- (Default: 1)
-
- apc.shm_segments The number of shared memory segments to allocate
- for the compiler cache. If APC is running out of
- shared memory but you have already set
- apc.shm_size as high as your system allows, you
- can try raising this value. Setting this to a
- value other than 1 has no effect in mmap mode
- since mmap'ed shm segments don't have size limits.
- (Default: 1)
-
- apc.shm_size The size of each shared memory segment in MB.
- By default, some systems (including most BSD
- variants) have very low limits on the size of a
- shared memory segment.
- (Default: 30)
-
- apc.optimization This option has been deprecated.
- (Default: 0)
-
- apc.num_files_hint A "hint" about the number of distinct source files
- that will be included or requested on your web
- server. Set to zero or omit if you're not sure;
- this setting is mainly useful for sites that have
- many thousands of source files.
- (Default: 1000)
-
- apc.user_entries_hint Just like num_files_hint, a "hint" about the number
- of distinct user cache variables to store.
- Set to zero or omit if you're not sure;
- (Default: 4096)
-
- apc.ttl The number of seconds a cache entry is allowed to
- idle in a slot in case this cache entry slot is
- needed by another entry. Leaving this at zero
- means that your cache could potentially fill up
- with stale entries while newer entries won't be
- cached.
- (Default: 0)
-
- apc.user_ttl The number of seconds a user cache entry is allowed
- to idle in a slot in case this cache entry slot is
- needed by another entry. Leaving this at zero
- means that your cache could potentially fill up
- with stale entries while newer entries won't be
- cached.
- (Default: 0)
-
-
- apc.gc_ttl The number of seconds that a cache entry may
- remain on the garbage-collection list. This value
- provides a failsafe in the event that a server
- process dies while executing a cached source file;
- if that source file is modified, the memory
- allocated for the old version will not be
- reclaimed until this TTL reached. Set to zero to
- disable this feature.
- (Default: 3600)
-
- apc.cache_by_default On by default, but can be set to off and used in
- conjunction with positive apc.filters so that files
- are only cached if matched by a positive filter.
- (Default: On)
-
- apc.filters A comma-separated list of POSIX extended regular
- expressions. If any pattern matches the source
- filename, the file will not be cached. Note that
- the filename used for matching is the one passed
- to include/require, not the absolute path. If the
- first character of the expression is a + then the
- expression will be additive in the sense that any
- files matched by the expression will be cached, and
- if the first character is a - then anything matched
- will not be cached. The - case is the default, so
- it can be left off.
- (Default: "")
-
- apc.mmap_file_mask If compiled with MMAP support by using --enable-mmap
- this is the mktemp-style file_mask to pass to the
- mmap module for determing whether your mmap'ed memory
- region is going to be file-backed or shared memory
- backed. For straight file-backed mmap, set it to
- something like /tmp/apc.XXXXXX (exactly 6 X's).
- To use POSIX-style shm_open/mmap put a ".shm"
- somewhere in your mask. eg. "/apc.shm.XXXXXX"
- You can also set it to "/dev/zero" to use your
- kernel's /dev/zero interface to anonymous mmap'ed
- memory. Leaving it undefined will force an
- anonymous mmap.
- (Default: "")
-
- apc.slam_defense ** DEPRECATED - Use apc.write_lock instead **
- On very busy servers whenever you start the server or
- modify files you can create a race of many processes
- all trying to cache the same file at the same time.
- This option sets the percentage of processes that will
- skip trying to cache an uncached file. Or think of it
- as the probability of a single process to skip caching.
- For example, setting this to 75 would mean that there is
- a 75% chance that the process will not cache an uncached
- file. So the higher the setting the greater the defense
- against cache slams. Setting this to 0 disables this
- feature.
- (Default: 0)
-
- apc.file_update_protection
- When you modify a file on a live web server you really
- should do so in an atomic manner. That is, write to a
- temporary file and rename (mv) the file into its permanent
- position when it is ready. Many text editors, cp, tar and
- other such programs don't do this. This means that there
- is a chance that a file is accessed (and cached) while it
- is still being written to. This file_update_protection
- setting puts a delay on caching brand new files. The
- default is 2 seconds which means that if the modification
- timestamp (mtime) on a file shows that it is less than 2
- seconds old when it is accessed, it will not be cached.
- The unfortunate person who accessed this half-written file
- will still see weirdness, but at least it won't persist.
- If you are certain you always atomically update your files
- by using something like rsync which does this correctly, you
- can turn this protection off by setting it to 0. If you
- have a system that is flooded with io causing some update
- procedure to take longer than 2 seconds, you may want to
- increase this a bit.
- (Default: 2)
-
- apc.enable_cli Mostly for testing and debugging. Setting this enables APC
- for the CLI version of PHP. Normally you wouldn't want to
- create, populate and tear down the APC cache on every CLI
- request, but for various test scenarios it is handy to be
- able to enable APC for the CLI version of APC easily.
- (Default: 0)
-
- apc.max_file_size Prevents large files from being cached.
- (Default: 1M)
-
- apc.stat Whether to stat the main script file and the fullpath
- includes. If you turn this off you will need to restart
- your server in order to update scripts.
- (Default: 1)
-
- apc.write_lock On busy servers when you first start up the server, or when
- many files are modified, you can end up with all your processes
- trying to compile and cache the same files. With write_lock
- enabled, only one process at a time will try to compile an
- uncached script while the other processes will run uncached
- instead of sitting around waiting on a lock.
- (Default: 1)
-
- apc.report_autofilter Logs any scripts that were automatically excluded from being
- cached due to early/late binding issues.
- (Default: 0)
-
- apc.rfc1867 RFC1867 File Upload Progress hook handler is only available
- if you compiled APC 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 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.
- (Default: 0)
-
- apc.rfc1867_prefix Key prefix to use for the user cache entry generated by
- rfc1867 upload progress functionality.
- (Default: "upload_")
-
- apc.rfc1867_name Specify the hidden form entry name that activates APC upload
- progress and specifies the user cache key suffix.
- (Default: "APC_UPLOAD_PROGRESS")
-
- apc.rfc1867_freq The frequency that updates should be made to the user cache
- entry for upload progress. This can take the form of a
- percentage of the total file size or a size in bytes
- optionally suffixed with 'k', 'm', or 'g' for kilobytes,
- megabytes, or gigabytes respectively (case insensitive).
- A setting of 0 updates as often as possible, which may cause
- slower uploads.
- (Default: 0)
-
- apc.localcache ** REMOVED
- apc.localcache.size ** REMOVED
-
- apc.include_once_override
- Optimize include_once and require_once calls and avoid the
- expensive system calls used.
- (Default: 0)