====== memcache Plugin ======

---- plugin ----
description: Abstraction wrapper to use persistent memory storage for caching data
author     : János Fekete
email      : jan@fjan.eu
type       : helper
lastupdate : 2015-07-20
compatible : Hrun
depends    : 
conflicts  : 
similar    : 
tags       : cache

downloadurl: https://github.com/fajan/memcache/archive/master.zip
bugtracker : https://github.com/fajan/memcache/issues
sourcerepo : https://github.com/fajan/memcache
donationurl: 

screenshot_img : 
----

===== Overview =====

This plugin is an abstraction layer to use a supported persistent memory storage as persistent data cache. The purpose is to supply a unified and portable way to allow plugin authors to use different persistent memory php extensions (e.g. APC / APCu or wincache).

If the environment does not have any supported persistent memory extension, it has a fallback engine that emulates persistent memory (but without the performance boost).

Plugin authors should check if there is real cache, and disable or lighten caching with the fallback cache.

===== Installation =====

It's recommended have one of the below engines installed and enabled on your system (check your [[http://php.net/manual/en/function.phpinfo.php|php configuration]]).

Supported persistent memory engines:
  * ''acp'' as [[http://php.net/manual/en/book.apc.php|APC]] or [[https://pecl.php.net/package/APCu|APCu]] 
  * ''wincache'' as [[http://php.net/manual/en/book.wincache.php|wincache]]

Fallback / emulation engine:
  * ''fake'', which uses the filesystem hence it is only for compatibility.

The plugins should be marked as dependency for plugins which use it to allow automatic installation.

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

Some engines may require [[#configuration]].

===== Usage =====

See tips and general info in [[#FAQ]].

==== Loading ====

To use the plugin simply load it, and after this you have multiple ways to use it.

<code php>
// load plugin:
   $plugin = plugin_load('helper', 'memcache');
   
// use plugin by instanced object:
   $used_driver = $plugin->driver();

// use plugin as static codes:
   $used_driver = memcache::driver();

// list of usable function:
   $function_list = $plugin->getMethods();
</code>

The methods available to utilize the persistent storage have the same name and arguments when used statically or by instanced class. 

The wrapper itself is singleton: so once its loaded, it remains available.

==== Methods ====

The following methods are available:

=== driver ===
<code php>
$loaded_plugin->driver();
memcache::driver();
</code>
Returns the backend driver as string (which is either ''wincache'' or ''apc'' currently or ''fake'' if neither is supported, and using the fallback instead).

=== emulated ===
<code php>
$loaded_plugin->emulated();
memcache::emulated();
</code>
Returns true if the cache is emulated (i.e. driver is ''fake'').

=== add ===
<code php>
$loaded_plugin->add(string $key, mixed $val [, int $ttl = 0]);
memcache::add(string $key, mixed $val [, int $ttl = 0]);
</code>
Add one arbitary value ''$val'' identified by ''$key'' to persistent storage, if it does not exists already.\\ Returns boolean success (false if key already exists or something went wrong).\\
If ''$ttl'' parameter is given and positive, it will set time-to-live (in seconds) after which the value/key is removed. If ''$ttl'' is 0 the data will remain in cache until it is deleted or ''$ttl'' overridden when later [[#set]] is used.

=== set ===
<code php>
$loaded_plugin->set(string $key, mixed $val [, int $ttl = 0]);
memcache::set(string $key, mixed $val [, int $ttl = 0]);
</code>
Set one arbitary value ''$val'' identified by ''$key'' to persistent storage: it's added if not exists or overwrite old value if already exists.\\ 
Returns boolean success (false if something went wrong).\\
If ''$ttl'' parameter is given and positive, it will set time-to-live (in seconds) after which the value/key is removed. If ''$ttl'' is 0 the data will remain in cache until it is deleted or ''$ttl'' overridden when later [[#set]] is used.

=== exists ===
<code php>
$loaded_plugin->exists(string $key);
memcache::exists(string $key);
</code>
Checks if a ''$key'' already exists. Returns boolean existence.

=== del ===
<code php>
$loaded_plugin->del(string $key);
memcache::del(string $key);
</code>
Deletes data identified by ''$key''.\\ 
Returns boolean success. (i.e. true if data is deleted, and false if data not exists or something went wrong.)

=== get ===
<code php>
$loaded_plugin->get(string $key [,bool &$success = false] );
memcache::get(string $key [,bool &$success = false]);
</code>
Retrieves a value identified by ''$key'', returns retrieved value or null.\\
The ''$success'' out-parameter can be checked to see success (you may have null as stored value: but ''$success'' will be true if that is the stored value).

=== clear ===
<code php>
$loaded_plugin->clear();
memcache::clear();
</code>
Empties the whole storage, removing every key-value pars regardless of TTL. This is server-wide, so data of every other scripts using the same storage will be purged as well.\\
Returns success (which is always true).


===== Configuration and Settings =====

Plugin configuration options:
  * ''debug_check_keys'' : Both apc and wincache supports arrays for many functions, this class DOES NOT. The variables are not checked for better performance, but checking can be enabled for debugging in which case non-string keys trigger error.

Later versions or added engines may add some.

=== Change Log ===

  * **2015-06-22**
    * Initial release

=== Known Bugs and Issues ===

None yet...

=== ToDo/Wish List ===

Requests for additional engine support or new features.

===== FAQ =====

TODO

===== Discussion =====