cachefile : update presentation and getter/setter

git-svn-id: https://svn.fournier38.fr/svn/ProgSVN/trunk@5806 bf3deb0d-5f1a-0410-827f-c0cc1f45334c

cachefile.php

@@ -1,26 +1,49 @@
 <?php
 /** DomFramework
-    @package domframework
+  * @package domframework
-    @author Dominique Fournier <dominique@fournier38.fr> */
+  * @author Dominique Fournier <dominique@fournier38.fr>
+  */
 
-/** A cache manager in file */
+/** A cache manager in file
+  */
 class cachefile
 {
-  /** Where to store the cached information */
+  /** Where to store the cached information
+    */
   public $directory = "./cache";
-  /** If TRUE : no information is cached */
+
+  /** If TRUE : no information is cached
+    */
   public $nocache = false;
 
-  /** Check if there is some garbage to clean */
+  /** Getter/setter for $directory cache
+    * @param string|null $val The directory to use
+    * @return $this or $this->directory value
+    */
+  public function directory ($val = null)
+  // {{{
+  {
+    if ($val === null)
+      return $this->directory;
+    if (! is_string ($val) || trim ($val) === "")
+      throw new \Exception ("CacheFile directory not a string or empty", 500);
+    $this->directory = $val;
+    return $this; 
+  }
+  // }}}
+  
+  /** Check if there is some garbage to clean
+    */
   public function garbage ()
+  // {{{
   {
     try
     {
       $this->cachedir ();
     }
-    catch (Exception $e)
+    catch (\Exception $e)
     {
-      throw new Exception ($e->getMessage(), $e->getCode());
+      throw new \Exception ($e->getMessage(), $e->getCode());
     }
 
     $fileCache = $this->directory."/".sha1 ("Garbage-Lock");
@@ -67,63 +90,73 @@ class cachefile
       }
     }
   }
+  // }}}
 
   /** This function check if the cachedir exists and create it if it is not the
-      case.
+    * case.
-      Check if the cache dir is writable and readable */
+    * Check if the cache dir is writable and readable
+    * @return true if OK
+    * @throw Exception if an error occured
+    */
   public function cachedir ()
+  // {{{
   {
     if (! isset ($this->directory) || $this->directory === "")
-      throw new Exception (dgettext ("domframework",
+      throw new \Exception (dgettext ("domframework",
                            "No cache directory defined"), 500);
     if (! file_exists ($this->directory))
     {
       // Need to create the cache dir
       $parent = realpath (dirname ($this->directory));
       if (! is_writeable (dirname ($this->directory)))
-        throw new Exception (sprintf (dgettext ("domframework",
+        throw new \Exception (sprintf (dgettext ("domframework",
                "Directory %s is not writable : can not create cache directory"),
                 $parent), 500);
       if (!mkdir ($this->directory))
-        throw new Exception (sprintf (dgettext ("domframework",
+        throw new \Exception (sprintf (dgettext ("domframework",
                            "Can not create cache directory %s"),
                              $this->directory), 500);
       chmod ($this->directory, 0777);
     }
     if (! is_writable ($this->directory))
-      throw new Exception (sprintf (dgettext ("domframework",
+      throw new \Exception (sprintf (dgettext ("domframework",
                            "Cache directory %s is not writable"),
                                     $this->directory), 500);
     if (! is_readable ($this->directory))
-      throw new Exception (sprintf (dgettext ("domframework",
+      throw new \Exception (sprintf (dgettext ("domframework",
                            "Cache directory %s is not readable"),
                                     $this->directory), 500);
     if (!file_exists ($this->directory."/.htaccess"))
       file_put_contents ($this->directory."/.htaccess", "deny from all\n");
     return true;
   }
+  // }}}
 
   /** This function write data in cache
-      The cache system can not save FALSE value
+    * @param string $id Cache identifier (add the authentication, the METHOD...)
-      @param string $id Cache identifier (add the authentication, the METHOD...)
+    * @param mixed $data The data to save
-      @param string $data The data to save
+    * @param integer|null $ttl The cache Time to Leave in seconds (3600s by
-      @param integer|null $ttl The cache Time to Leave in seconds (3600s by
+    * default)
-                               default)*/
+    * @return true
+    * @throw if an error occured
+    */
   public function write ($id, $data, $ttl = 3600)
+  // {{{
   {
     if ($this->nocache !== false)
       return false;
-    if ($data === false)
-      throw new Exception (dgettext ("domframework",
-                           "Can not store FALSE in cache"), 500);
     try
     {
       $this->cachedir ();
     }
-    catch (Exception $e)
+    catch (\Exception $e)
     {
-      throw new Exception ($e->getMessage(), $e->getCode());
+      throw new \Exception ($e->getMessage(), $e->getCode());
     }
+    if (! is_integer ($ttl) || $ttl <= 0)
+      throw new \Exception ("CacheFile TTL invalid : not integer or negative".
+      " : '$ttl'",
+      500);
 
     $this->garbage ();
     $fileCache = $this->directory."/".sha1 ($id);
@@ -136,11 +169,16 @@ class cachefile
     chmod ($fileCache, 0666);
     return true;
   }
+  // }}}
 
   /** This function read data from cache. Return FALSE in case of empty or too
-      older cache
+    * older cache
-      @param string $id Cache identifier (add the authentication, the METHOD) */
+    * @param string $id Cache identifier (add the authentication, the METHOD)
+    * @return false if the cache is empty or too old
+    * @return mixed The data stored in cache
+    */
   public function read ($id)
+  // {{{
   {
     if ($this->nocache !== false)
       return false;
@@ -148,9 +186,9 @@ class cachefile
     {
       $this->cachedir ();
     }
-    catch (Exception $e)
+    catch (\Exception $e)
     {
-      throw new Exception ($e->getMessage(), $e->getCode());
+      throw new \Exception ($e->getMessage(), $e->getCode());
     }
 
     $this->garbage ();
@@ -158,11 +196,11 @@ class cachefile
     if (!file_exists ($fileCache))
       return false;
     if (!is_readable ($fileCache))
-      throw new Exception (sprintf (dgettext ("domframework",
+      throw new \Exception (sprintf (dgettext ("domframework",
                                     "File cache %s is not readable"),
                                     $fileCache), 500);
     if (!is_writable ($fileCache))
-      throw new Exception (sprintf (dgettext ("domframework",
+      throw new \Exception (sprintf (dgettext ("domframework",
                                     "File cache %s is not writable"),
                                     $fileCache), 500);
     // Lock : waiting the reconstruction of the cache by another process
@@ -202,11 +240,14 @@ class cachefile
 
     return false;
   }
+  // }}}
 
   /** This function delete an id in cache
-      @param string $id Cache identifier (add the authentication, the METHOD...)
+    * @param string $id Cache identifier (add the authentication, the METHOD...)
+    * @return boolean The cache is well deleted
     */
   public function delete ($id)
+  // {{{
   {
     $fileCache = $this->directory."/".sha1 ($id);
     if (!file_exists ($fileCache))
@@ -214,4 +255,5 @@ class cachefile
     unlink ($fileCache);
     return true;
   }
+  // }}}
 }