Class \Scrivo\Cache\FileCache

Implementation of a file cache.

This is an implmentation of a file cache in PHP. It allows you to store serializable objects on disk. It was designed to be a fallback for the APC user cache, but nonetheless a very reasonable alternative.

Some configuration notes. If possible use a RAM disk, apart from the speed benefits it probably is also easier to limit the amount of space used by the cache when using a RAM disk, else you'll have to resort to disk quotas.

There is no software limit on the amount of data the cache uses. A garbage collector is run each FileCache::$gcInterval store requests. If data cannot be written the cache will acively purge data, keeping a certain percentage of the most frequently used entries in the cache.

Garbage collection only removes expired entries. When purging data another alogrithm is used: Data that was stored but never used will be deleted inmediately, the rest is sorted based on access time and then a given percentage (FileCache::$pctToKeepAfterPurge) of the last accessed files will be saved, the rest is removed.

Note: one of the former versions supported file locking with flock. But that does not work in a threaded web server and ISAPI. Since that is the common case nowadays file locking is dropped. Is it thread save? I believe so, but that is only because unserialize will return null when reading corrupted (not fully written) entries. Furthermore beacuse of PHP's problems with file locking cache slams are not allowed. So only the first thread is allowed to write a file, later threads are not.

Implements
Defined in: Cache/FileCache.php.

Constructor summary
Attr. Name / Description
public

FileCache($dir, $gcInterval, $pctToKeepAfterPurge)

Create a file cache.

Constant summary
Name Description
CACHE_SLAM Constant to indicate that a value was not stored in the cache because the entry was already taken.
DATA_STORED Constant to indicate that a value was succesfully stored in the cache.
NO_SPACE Constant to indicate that a value was not stored in the cache because there was not enough storage available.

Member summary
Attr. Type Name Description
private \..\String $dir The location of the cache directory.
private \..\String[] $escapedCharacters List of character sequences to escape troublesome characters in file names.
private int $gcInterval The gargbage collection interval.
private int $pctToKeepAfterPurge Percentage of most frequently accessed file that will be kept after the cache is purged when there's not enough space left.
private \..\String[] $reservedCharacters List of troublesome characters in file names.
private int $storeCount The counter for the number of store requests.

Method summary
Attr. Type Name / Description
public

delete($key)

Delete/remove a cache entry.
public object[]

entryList()

List all entries in the cache.
public mixed

fetch($key)

Retrieve a value from the cache.
private

fopen($file)

Just a wrapper for fopen that throws an exception instead of an error.
private

gc()

Run the garbage collector: delete all expired cache entries.
private

getFile($key)

Create a file name from a key, taking in account problematic characters for a file name.
public int

overwrite($key, $val, $ttl)

Store a variable in the cache, overwrite it if it already exists.
public

purge($percentageToKeep)

Clear the cache from its most irrelevant items.
public int

store($key, $val, $ttl)

Store a variable in the cache.
private

touch($file, $ttl)

Just a wrapper for touch that throws an exception instead of returning a status.
private

unlink($file)

Just a wrapper for unlink that throws an exception instead of returning a status.

 

Constructor

public FileCache(\Scrivo\String $dir=null, int $gcInterval=50, int $pctToKeepAfterPurge=50)

Create a file cache.

Parameters:
Type Name Def. Description
\Scrivo\String $dir null

The location where the cache schould store the files. The default is the 'ScrivoCache' folder in the system's temp directory.
int $gcInterval 50

The interval at which to run the garbage collector measured in store requests.
int $pctToKeepAfterPurge 50

Percentage of items that were accessed at least once that you want to keep after a cache purge due to storage shortage.

View source: Cache/FileCache.php line 127.

Constants

CACHE_SLAM

Constant to indicate that a value was not stored in the cache because the entry was already taken.

Inherited from \Scrivo\Cache

Value: 2

View source: Cache.php line 54.

DATA_STORED

Constant to indicate that a value was succesfully stored in the cache.

Inherited from \Scrivo\Cache

Value: 1

View source: Cache.php line 48.

NO_SPACE

Constant to indicate that a value was not stored in the cache because there was not enough storage available.

Inherited from \Scrivo\Cache

Value: 3

View source: Cache.php line 60.

Members


				

					
					
						private					
											\Scrivo\String
										
						$dir					
				

				

				
The location of the cache directory.
																		
View source:
		Cache/FileCache.php line 75.
		

				

					

				

					
					
						private					
											\Scrivo\String[]
										
						$escapedCharacters					
				

				

				
List of character sequences to escape troublesome characters in file
names.
																		
View source:
		Cache/FileCache.php line 113.
		

				

					

				

					
					
						private					
											int
										
						$gcInterval					
				

				

				
The gargbage collection interval.
				
This interval is measured in
number of store requests.
														
View source:
		Cache/FileCache.php line 83.
		

				

					

				

					
					
						private					
											int
										
						$pctToKeepAfterPurge					
				

				

				
Percentage of most frequently accessed file that will be kept after
the cache is purged when there's not enough space left.
																		
View source:
		Cache/FileCache.php line 98.
		

				

					

				

					
					
						private					
											\Scrivo\String[]
										
						$reservedCharacters					
				

				

				
List of troublesome characters in file names.
																		
View source:
		Cache/FileCache.php line 105.
		

				

					

				

					
					
						private					
											int
										
						$storeCount					
				

				

				
The counter for the number of store requests.
																	
Inital value:
						0
					

										
View source:
		Cache/FileCache.php line 90.
		

				

				

	


	

		
Methods

		

						

				
				
				public				
								delete(\Scrivo\String $key)
			

			

				
Delete/remove a cache entry.
														

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					\Scrivo\String
					$key
					
					
A cache unique name for the key.

				

							
		

														
View source:
		Cache/FileCache.php line 353.
		

			

						

				
				
				public				
									object[]
								entryList()
			

			

				
List all entries in the cache.
				
The cache list is an array in which the cache keys are the keys of
the array entries and the data of the entries are objects ot type
stdClass that contain at least contain the following properties:



    

  • accessed: the access time
    • 

  • expires: the expiration time
    • 

  • created: the creation time
    • 

  • size: the size of the entry
    • 

																	
Returns:

					

						object[]
						List all entries in the cache.					

														
View source:
		Cache/FileCache.php line 404.
		

			

						

				
				
				public				
									mixed
								fetch(\Scrivo\String $key)
			

			

				
Retrieve a value from the cache.
														

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					\Scrivo\String
					$key
					
					
The key for which to retrieve the value.

				

							
		

									
Returns:

					

						mixed
						Retrieve a value from the cache.					

														
View source:
		Cache/FileCache.php line 368.
		

			

						

				
				
				private				
								fopen(string $file)
			

			

				
Just a wrapper for fopen that throws an exception instead of an error.
														

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					string
					$file
					
					
				

							
		

														
View source:
		Cache/FileCache.php line 150.
		

			

						

				
				
				private				
								gc()
			

			

				
Run the garbage collector: delete all expired cache entries.
																										
View source:
		Cache/FileCache.php line 243.
		

			

						

				
				
				private				
								getFile(\Scrivo\String $key)
			

			

				
Create a file name from a key, taking in account problematic characters
for a file name.
														

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					\Scrivo\String
					$key
					
					
Key name to create a file name for.

				

							
		

														
View source:
		Cache/FileCache.php line 191.
		

			

						

				
				
				public				
									int
								overwrite(\Scrivo\String $key, mixed $val, int $ttl=3600)
			

			

				
Store a variable in the cache, overwrite it if it already exists.
				
Store any serializable variable in the cache. It is guaranteed that
the data will be written. But note that it is not guaranteed that the
next fetch will retrieve this value.
										

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					\Scrivo\String
					$key
					
					
A cache unique name for the key.

				

								

					mixed
					$val
					
					
The (serializable) variabele to strore.


				

								

					int
					$ttl
					3600
					
Time to live in seconds.

				

							
		

									
Returns:

					

						int
						Store a variable in the cache, overwrite it if it already exists.					

										

			
Throws:

			
				

					Exception Type
					Description
				

			
			
								

					\Scrivo\SystemException
					When trying to store a NULL value or
  when a file operation fails.
				

							
		

						
View source:
		Cache/FileCache.php line 339.
		

			

						

				
				
				public				
								purge(int $percentageToKeep=0)
			

			

				
Clear the cache from its most irrelevant items.
				
You can use this function to free up a certain amount of the file cache
First it deletes the items that were stored but never accessed. The
items that were accessed at least once are sorted on access time and
prec_to_keep of the most recently accessed files will be kept in the
cache. The others will be deleted.
										

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					int
					$percentageToKeep
					0
					
Percentage of items that were accessed
   at least once that you want to keep.

				

							
		

														
View source:
		Cache/FileCache.php line 208.
		

			

						

				
				
				public				
									int
								store(\Scrivo\String $key, mixed $val, int $ttl=3600)
			

			

				
Store a variable in the cache.
				
Store any serializable variable in the cache. Note that it is not
possible to overwrite an existing entry (cache slam). Such an event
will not raise an error but the function will report it.
										

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					\Scrivo\String
					$key
					
					
A cache unique name for the key.

				

								

					mixed
					$val
					
					
The (serializable) variabele to strore.


				

								

					int
					$ttl
					3600
					
Time to live in seconds.

				

							
		

									
Returns:

					

						int
						Store a variable in the cache.					

										

			
Throws:

			
				

					Exception Type
					Description
				

			
			
								

					\Scrivo\SystemException
					When trying to store a NULL value or
   when a file operation fails.
				

							
		

						
View source:
		Cache/FileCache.php line 279.
		

			

						

				
				
				private				
								touch(string $file, string $ttl)
			

			

				
Just a wrapper for touch that throws an exception instead of returning
a status.
														

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					string
					$file
					
					
				

								

					string
					$ttl
					
					
				

							
		

														
View source:
		Cache/FileCache.php line 165.
		

			

						

				
				
				private				
								unlink(string $file)
			

			

				
Just a wrapper for unlink that throws an exception instead of returning
a status.
														

			
Parameters:

			
				

					Type
					Name
					Def.
					Description
				

			
			
								

					string
					$file
					
					
				

							
		

														
View source:
		Cache/FileCache.php line 178.
		

			

					

	

	

						

						
Documentation generated by 
						phpDocumentor 2.0.0a12 
						and ScrivoDocumentor
						on August 29, 2013