Reworked the whole thing so that it uses the factory pattern.

Author: boenrobot

extrasetup.php

@@ -19,10 +19,10 @@
         }
 
         if (0 === strpos($filename, 'php/')) {
-//            $newFileName = 'src/' . substr($filename, strlen('php/'));
-//            $info['name'] = $newFileName;
-//            $pkg->files[$newFileName] = $info;
-//            unset($pkg->files[$filename]);
+            //$newFileName = 'src/' . substr($filename, strlen('php/'));
+            //$info['name'] = $newFileName;
+            //$pkg->files[$newFileName] = $info;
+            //unset($pkg->files[$filename]);
         }
     }
     $extrafiles[] = $pkg;

package.xml

@@ -112,6 +112,21 @@
     <min>1.4.0</min>
    </pearinstaller>
   </required>
+  <optional>
+   <package>
+    <name>PEAR2_Autoload</name>
+    <channel>pear2.php.net</channel>
+    <min>0.2.4</min>
+   </package>
+   <extension>
+    <name>apc</name>
+    <min>3.0.13</min>
+   </extension>
+   <extension>
+    <name>wincache</name>
+    <min>1.1.0</min>
+   </extension>
+  </optional>
  </dependencies>
  <phprelease>
   <filelist>

src/PEAR2/Cache/SHM.php

@@ -36,71 +36,34 @@
  * @license  http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
  * @link     http://pear2.php.net/PEAR2_Cache_SHM
  */
-class SHM implements \IteratorAggregate
+abstract class SHM implements \IteratorAggregate
 {
-    /**
-     * @var Adapter The adapter of this instance. 
-     */
-    protected $adapter;
 
     /**
      * Creates a new shared memory storage.
      * 
-     * Estabilishes a separate persistent storage.
+     * Estabilishes a separate persistent storage. Adapter is automatically
+     * chosen based on the available extensions.
+     * 
+     * @param string $persistentId The ID for the storage.
      * 
-     * @param string|Adapter $persistentId The ID for the storage or an
-     * already instanciated storage adapter. If an ID is specified, an adapter
-     * will automatically be chosen based on the available extensions.
+     * @return self|SHM A new instance of an SHM adapter (child of this class).
      */
-    public function __construct($persistentId)
+    public static function factory($persistentId)
     {
-        if ($persistentId instanceof Adapter) {
-            $this->adapter = $persistentId;
+        if ('cli' === PHP_SAPI) {
+            return new Adapter\Placebo($persistentId);
+        } elseif (version_compare(phpversion('wincache'), '1.1.0', '>=')) {
+            return new Adapter\Wincache($persistentId);
+        } elseif (version_compare(phpversion('apc'), '3.0.13', '>=')) {
+            return new Adapter\APC($persistentId);
         } else {
-            if ('cli' === PHP_SAPI) {
-                $this->adapter = new Adapter\Placebo($persistentId);
-            } elseif (version_compare(phpversion('wincache'), '1.1.0', '>=')) {
-                $this->adapter = new Adapter\Wincache($persistentId);
-            } elseif (version_compare(phpversion('apc'), '3.0.13', '>=')) {
-                $this->adapter = new Adapter\APC($persistentId);
-            } else {
-                throw new SHM\InvalidArgumentException(
-                    'No appropriate adapter available', 1
-                );
-            }
+            throw new SHM\InvalidArgumentException(
+                'No appropriate adapter available', 1
+            );
         }
     }
 
-    /**
-     * Get the currently set SHM adapter.
-     * 
-     * @return Adapter The currently set adapter 
-     */
-    public function getAdapter()
-    {
-        return $this->adapter;
-    }
-    
-    /**
-     * Calls a method from the adapter.
-     * 
-     * This is a magic method, thanks to which any method you call will be
-     * redirected to the adapter. Every adapter implements at minimum the
-     * {@link Adapter} interface, so check it out for what you can expect as
-     * common functionality.
-     * 
-     * @param string $method The adapter method to call.
-     * @param array  $args   The arguments to the method.
-     * 
-     * @return mixed Whatever the adapter method returns.
-     */
-    public function __call($method, $args)
-    {
-        return call_user_func_array(
-            array($this->adapter, $method), $args
-        );
-    }
-    
     /**
      * Gets a value from the shared memory storage.
      * 
@@ -114,7 +77,7 @@ public function __call($method, $args)
      */
     public function __get($key)
     {
-        return $this->adapter->get($key);
+        return $this->get($key);
     }
 
     /**
@@ -131,7 +94,7 @@ public function __get($key)
      */
     public function __set($key, $value)
     {
-        return $this->adapter->set($key, $value);
+        return $this->set($key, $value);
     }
 
     /**
@@ -147,7 +110,7 @@ public function __set($key, $value)
      */
     public function __isset($key)
     {
-        return $this->adapter->exists($key);
+        return $this->exists($key);
     }
 
     /**
@@ -163,25 +126,150 @@ public function __isset($key)
      */
     public function __unset($key)
     {
-        return $this->adapter->delete($key);
+        return $this->delete($key);
     }
 
     /**
-     * Retrieve an external iterator
+     * Creates a new shared memory storage.
+     * 
+     * Estabilishes a separate persistent storage.
+     * 
+     * @param string $persistentId The ID for the storage. The storage will be
+     * reused if it exists, or created if it doesn't exist. Data and locks are
+     * namespaced by this ID.
+     */
+    abstract public function __construct($persistentId);
+    
+    /**
+     * Obtains a named lock.
      * 
-     * Returns an external iterator.
+     * @param string $key     Name of the key to obtain. Note that $key may
+     * repeat for each distinct $persistentId.
+     * @param double $timeout If the lock can't be immediatly obtained, the
+     * script will block for at most the specified amount of seconds. Setting
+     * this to 0 makes lock obtaining non blocking, and setting it to NULL makes
+     * it block without a time limit.
      * 
-     * @param string $filter   A PCRE regular expression. Only matching keys
-     * will be iterated over. Setting this to NULL matches all keys of this
-     * instance.
-     * @param bool   $keysOnly Whether to return only the keys, or return both
-     * the keys and values.
+     * @return bool TRUE on success, FALSE on failure.
+     */
+    abstract public function lock($key, $timeout = null);
+    
+    /**
+     * Releases a named lock.
      * 
-     * @return An array or instance of an object implementing {@link \Iterator}
-     * or {@link \Traversable}.
+     * @param string $key Name of the key to release. Note that $key may
+     * repeat for each distinct $persistentId.
+     * 
+     * @return bool TRUE on success, FALSE on failure.
      */
-    public function getIterator($filter = null, $keysOnly = false)
-    {
-        return $this->adapter->getIterator($filter, $keysOnly);
-    }
+    abstract public function unlock($key);
+    
+    /**
+     * Checks if a specified key is in the storage.
+     * 
+     * @param string $key Name of key to check.
+     * 
+     * @return bool TRUE if the key is in the storage, FALSE otherwise. 
+     */
+    abstract public function exists($key);
+    
+    /**
+     * Adds a value to the shared memory storage.
+     * 
+     * Adds a value to the storage if it doesn't exist, or fails if it does.
+     * 
+     * @param string $key   Name of key to associate the value with.
+     * @param mixed  $value Value for the specified key.
+     * @param int    $ttl   Seconds to store the value. If set to 0 indicates no
+     * time limit.
+     * 
+     * @return bool TRUE on success, FALSE on failure.
+     */
+    abstract public function add($key, $value, $ttl = 0);
+    
+    /**
+     * Sets a value in the shared memory storage.
+     * 
+     * Adds a value to the storage if it doesn't exist, overwrites it otherwise.
+     * 
+     * @param string $key   Name of key to associate the value with.
+     * @param mixed  $value Value for the specified key.
+     * @param int    $ttl   Seconds to store the value. If set to 0 indicates no
+     * time limit.
+     * 
+     * @return bool TRUE on success, FALSE on failure.
+     */
+    abstract public function set($key, $value, $ttl = 0);
+    
+    /**
+     * Gets a value from the shared memory storage.
+     * 
+     * Gets the current value, or throws an exception if it's not stored.
+     * 
+     * @param string $key Name of key to get the value of.
+     * 
+     * @return mixed The current value of the specified key.
+     */
+    abstract public function get($key);
+    
+    /**
+     * Deletes a value from the shared memory storage.
+     * 
+     * @param string $key Name of key to delete.
+     * 
+     * @return bool TRUE on success, FALSE on failure.
+     */
+    abstract public function delete($key);
+    
+    /**
+     * Increases a value from the shared memory storage.
+     * 
+     * Increases a value from the shared memory storage. Unlike a plain
+     * set($key, get($key)+$step) combination, this function also implicitly
+     * performs locking.
+     * 
+     * @param string $key  Name of key to increase.
+     * @param int    $step Value to increase the key by.
+     * 
+     * @return int The new value.
+     */
+    abstract public function inc($key, $step = 1);
+    
+    /**
+     * Decreases a value from the shared memory storage.
+     * 
+     * Decreases a value from the shared memory storage. Unlike a plain
+     * set($key, get($key)-$step) combination, this function also implicitly
+     * performs locking.
+     * 
+     * @param string $key  Name of key to decrease.
+     * @param int    $step Value to decrease the key by.
+     * 
+     * @return int The new value.
+     */
+    abstract public function dec($key, $step = 1);
+
+    /**
+     * Sets a new value if a key has a certain value.
+     * 
+     * Sets a new value if a key has a certain value. This function only works
+     * when $old and $new are longs.
+     * 
+     * @param string $key Key of the value to compare and set.
+     * @param int    $old The value to compare the key against.
+     * @param int    $new The value to set the key to.
+     * 
+     * @return bool TRUE on success, FALSE on failure. 
+     */
+    abstract public function cas($key, $old, $new);
+    
+    /**
+     * Clears the persistent storage.
+     * 
+     * Clears the persistent storage, i.e. removes all keys. Locks are left
+     * intact.
+     * 
+     * @return void
+     */
+    abstract public function clear();
 }