This is the INSTALL file for apc php cache.

For a deeper explanation of the components involved, please visit 
http://apc.communityconnect.com/.

#################################################################
# URGENT: To users with APC version prior to version 1.0.10
#################################################################
You will have to make a new php.ini entry in you file for
apc.mode - See "Runtime configuration"

#################################################################
# Compiling and installing as a Zend extension (post-PHP install)
#################################################################

1) Run phpize (this shouldn't be necessary after 1.0.10)
2) Run ./configure --enable-apc --with-php-config=<path to php-config>
3) Run make
4) copy modules/php_apc.so to /path/to/where/you/keep/extensions/
5) in your php.ini file add the line
	zend_extension="/path/to/where/you/keep/extensions/php_apc.so"
6) in your php.ini file add the line
	# for switching off the APC
	apc.mode = off 
  # for using SHM support
  apc.mode = shm
  # for using MMAP support 
  apc.mode = mmap

   don't forget that you can't put comments on the same line as your ini options
   See FAQ for pros and contras of SHM / MMAP support
7) You're all set!

#################################################################
# Compiling and installing as php built-in (during php compile)
#################################################################

0) Untar these sources into PHP_SRC_DIR/ext/apc/
1) In the top-level directory of the php source tree, run autoconf
2) Run ./configure --enable-apc <whatever other compile flags you want>
3) make;  make install
4) in your php.ini file add the line
        apc.mode = off # for switching off the APC
        apc.mode = shm # for using SHM support
        apc.mode = mmap # for using MMAP support
   See FAQ for pros and contras of SHM / MMAP support
5) You're all set!


#################################################################
# Runtime configuration
#################################################################

The following php.ini runtime settings are supported.  (M) means the command
is supported in the mmap implemntation, (S) for sysv shared memory 
implementation.

apc.mode
	supported: (M/S)
	default: off
	Sets the operating mode of the APC cache.
	Valid values are: off, shm or mmap
	If set to shm, then apc is operating in shared memory mode
	if set to mmap, then apc is operating in memory mapped files mode
	Please see FAQ for pro and contra of those modes

apc.cache_rt
	supported: (SHM)
  default: safe
	cache_rt defines the cache retrieval policy.  safe is the default
	behaviour - global locks are taken around all cache retrievals.
	fast uses an optimistic cache address cacheing to avoid global
	locks for faster object retrieval.  A timestamped magic value at the 
	end of all objects tries to ensure that no corruption can occur.
  This is an experimental feature.

apc.cachedir
	supported: (M)
	default: NULL
	cachedir sets the top-level dir under which to write compiled php
	files.  If this is not set, cache files will be created along side 
	their corresponding php files, with the same name and a _apc 
	extension.  The webserver user must have permision to create files
	in this directory.

apc.hash_buckets 
	supported: (S)
	default: 1024
	hash_buckets sets the number of hash_buckets in the master index.  
	Since for technical reasons, the master index is statically allocated,
	it is important that this number be larger than the number of php 
	files to be cached (don't forget includes!)  Each bucket takes 264 
	bytes of memory, so setting this to a large (but reasonable) value
	does no harm. As a rule of thumb, the number of buckets should be
	at least one third greater than the total number of files you are
	going to cache.

apc.regex 
	supported: (M,S)
	default: NULL
	example: apc.regex="no_cache.inc:bad_file.inc"
	regex is a colon delimited list of POSIX extended regex of files 
	NOT to cache.

apc.shm_segments 
	supported: (S)
	default: 10
	shm_segements sets the maximum number of sysv shared memory segments 
	to be used.

apc.shm_segment_size 
	supported: (S)
	default: 33554431
	shm_segment_size sets the size of sysv shared memory segments to use,
	in bytes.

apc.ttl 
	supported: (M,S)
	default: 0
	values: {0,1}
	ttl sets a global ttl on all cache objects.  Objects not updated in
	ttl seconds will be expired and delted.

apc.check_mtime
	supported: (S)
	default: 0
	values: {0,1}
	specifies whether a source file should be re-compiled if it has been
	modified since it was last compiled. This may result in a slight loss
	of efficiency.

apc.relative_includes
	supported: (M,S)
	default: 1
	values: {0,1}
	specifies whether a relative paths may be passed to the PHP file
	inclusion functions (include(), require(), include_once(), etc.).
	This may result in a slight loss of efficiency. Note: this option
	must be enabled for the PHP include path to function correctly!

apc.check_compiled_source
	supported: (M,S)
	default: 0
	values: {0,1}
	specifies whether or not to check to see if the php source file you
	are reading is actually a compiled file.  This is the so-called
	encoder functionality.  As there does not exist a standalone compiler,
	current version mmap files should be used.

#################################################################
# Exported functions
#################################################################

The following new php functions are exported.  As above (M) indicates
functions that exist under the mmap implementation, (S) for sysv 
shared memory implementation.

void apcinfo([string /path/to/apcinfo/page])	
	supported: (M,S)
	Outputs detailed information regarding the configuration and content
	of the cache.  The sysv implementation displays global cache 
	information, the mmap implementation displays only cache statistics
	for the particular child being queried.  If a uri is to apcinfo()
  the genrated page will have links to apc_rm and apc_dump_cache_object()
	see extras/apcinfo.php for an example implementation.

int apc_dump_cache_object(string /path/to/apcinfo/page)
	supported: (M,S)
	Dumps extremely detailed information about the specified cache object
	as html.  Information dumped includes the complete op-tree for the 
	page and all the functions and classes serialized from the page.

int apc_rm(string pathname)  
	supported: (M,S)
	Takes the full path of a php file (NOT cache file), and expires that 
	item's associated cache object. Returns 1 on success, 0 on failure
	(failure usually indicates the object was not present in the cache.)

int apc_reset_cache()
	supported: (S)
	Clears all entries from the cache.  Returns 1 on success.

int apc_set_my_ttl(int seconds)
	supported: (S)
	Sets the ttl of the calling file to ttl seconds.

int apc_cache_index(array &output)
	supported: (S,M)
	Fetches an associative array keyed with cache object names and
	with data bucket an array consisting of:
	SHM:
		element0 -> cache offset
		element1 -> object length
		element2 -> last access time
		element3 -> hit counter
		element4 -> ttl 
		element5 -> last modification time
	MMAP:
		element0 -> object length
		element2 -> creation time
		element3 -> hit counter
		element4 -> inode
	As with all other functions, the shm return global cache information
	the mmap version returns that particular child's view of the cache.

int apc_cache_info(array &output)
        supported: (S,M)
        Fetches an associative array keyed with cache header names and values
        SHM:
                "total buckets"
                "maximum shared memory segments"
                "shared memory segment size"
                "time-to-live"
                "hits"
                "misses"
                "hit rate"
                "cache filter"
                "shared memory ID"
                "local shared memory address"
                "creation pathname"
        SHM Info:
                "Total Size"
                "Total Available"
		SHM Toggles:
				"check file modification times"
				"support relative includes"
				"check for compiled source"
		MMAP:
				"time-to-live"
				"cache directory"
				"cache filter"
		MMAP Toggles:
				"check file modification times"
				"support relative includes"
				"check for compiled source"


#####################################################################
# Add ons
#####################################################################

Mike Bretz and his team have developed a beauty of a web interface for
managing and analyzing your APC installs.  A (very possibly out of date
when you read this) is in the extras dir, and the latest version is
available off http://apc.neuropeans.com/.  
