[fix] Documents and tweaks m_action

bureau/class/m_action.php

@@ -1,4 +1,5 @@
 <?php
+
 /*
   LICENSE
 
@@ -18,6 +19,7 @@
   Purpose of file: Manage generic actions.
   ----------------------------------------------------------------------
  */
+
 /**
  * This class manage actions to be performed on the file system on behalf of alternc Classes
  * It primary use is to store the actions to be performed ( creating file or folder, deleting, setting permissions etc..) in the action sql table. 
@@ -30,70 +32,118 @@
  */
 class m_action {
     /* --------------------------------------------------------------------------- */
+
     /** Constructor
      */
     function m_action() {
+        
     }
 
-  /*
+    /**
-  * function to set the cration of a file 
+     * Plans the cration of a file 
+     * 
+     * @global type $err
+     * @global type $L_INOTIFY_DO_ACTION
+     * @return boolean
      */
     function do_action() {
         global $err, $L_INOTIFY_DO_ACTION;
         $err->log("action", "do_action");
-    touch($L_INOTIFY_DO_ACTION);
+        if( ! touch($L_INOTIFY_DO_ACTION) ){
+            return FALSE;
+        }
+        return TRUE;
     }
 
+    /**
+     * Plans a file creation
+     * 
+     * @param string $file
+     * @param string $content
+     * @param int $user
+     * @return boolean
+     */
     function create_file($file, $content = "", $user = "root") {
         return $this->set('create_file', $user, array('file' => $file, 'content' => $content));
     }
 
-  /*
+    /**
-  * function to set the cration of a file 
+     * Plans the cration of a dir 
+     * 
+     * @param string $dir
+     * @param int $user
+     * @return boolean
      */
     function create_dir($dir, $user = "root") {
         return $this->set('create_dir', $user, array('dir' => $dir));
     }
 
-  /*
+    /**
-  * function to set the perms upon user creation
+     * Plans a perms fix upon user creation 
+     * @param int $uid
+     * @param string $user
+     * @return boolean
      */
     function fix_user($uid, $user = "root") {
         return $this->set('fix_user', $user, array('uid' => $uid));
     }
-  /*
+
-  * function to set the cration of a file 
+    /**
+     * Plans a dir fix
+     * 
+     * @param type $dir
+     * @param type $user
+     * @return type
      */
     function fix_dir($dir, $user = "root") {
         return $this->set('fix_dir', $user, array('dir' => $dir));
     }
 
-  /*
+    /**
-  * function to set the cration of a file 
+     * Plans a file fix
+     * 
+     * @param type $file
+     * @param type $user
+     * @return type
      */
     function fix_file($file, $user = "root") {
         return $this->set('fix_file', $user, array('file' => $file));
     }
 
-  /*
+    /**
      * function to delete file / folder
+     * 
+     * @param type $dir
+     * @param type $user
+     * @return type
      */
     function del($dir, $user = "root") {
         return $this->set('delete', $user, array('dir' => $dir));
     }
 
-  /*
+    /**
      * function returning the first not locked line of the action table 
+     * 
+     * @param type $src
+     * @param type $dst
+     * @param type $user
+     * @return type
      */
     function move($src, $dst, $user = "root") {
         return $this->set('move', $user, array('src' => $src, 'dst' => $dst));
     }
 
-  /*
+    /**
+     * 
      * function archiving a directory ( upon account deletion )
-  * @param: $archive : directory to archive within the archive_del_data folder if set in variable sql table.
+     * 
-  * If archive_del_data is not set we delete the folder.
+     * @global type $cuid
-  * @param: $dir : sub_directory of the archive directory
+     * @global type $db
+     * @global type $err
+     * @param type $archive Directory to archive within the archive_del_data folder if set in variable sql table
+     *                      If archive_del_data is not set we delete the folder
+     * @param type $dir  sub_directory of the archive directory
+     * @return boolean
      */
     function archive($archive, $dir = "html") {
         global $cuid, $db, $err;
@@ -119,8 +169,15 @@ class m_action {
         return true;
     }
 
-  /*
+    /**
      * function inserting the action in the sql table
+     * 
+     * @global type $db
+     * @global type $err
+     * @param type $type
+     * @param type $user
+     * @param type $parameters
+     * @return boolean
      */
     function set($type, $user, $parameters) {
         global $db, $err;
@@ -160,16 +217,33 @@ class m_action {
         return true;
     }
 
+    /**
+     * This seems to be unused ?
+     * 
+     * @global type $err
+     * @global type $db
+     * @param type $all
+     * @return boolean
+     */
     function get_old($all = null) {
         global $err, $db;
 
         $purge = "select * from actions where TO_DAYS(curdate()) - TO_DAYS(creation) > 2;";
-		if(!$db->query($purge)){ 
+        $result = $db->query($purge);
+        if (! $result) {
             $err->raise("action", _("Error selecting  old actions"));
             return false;
         }
+        return $db->num_rows($result)   ;
     }
 
+    /**
+     * 
+     * @global type $err
+     * @global type $db
+     * @param type $all
+     * @return boolean
+     */
     function purge($all = null) {
         global $err, $db;
         if (is_null($all)) {
@@ -177,14 +251,21 @@ class m_action {
         } else {
             $purge = "delete from actions where TO_DAYS(curdate()) - TO_DAYS(creation) > 2;";
         }
-		if(!$db->query($purge)){ 
+        $result = $db->query($purge);
+        if (! $result) {
             $err->raise("action", _("Error purging old actions"));
             return false;
         }
+        return $db->num_rows($result)   ;
+        
     }
 
-  /*
+    /**
      *  function returning the first not locked line of the action table 
+     * 
+     * @global type $db
+     * @global type $err
+     * @return boolean or array
      */
     function get_action() {
         global $db, $err;
@@ -199,8 +280,13 @@ class m_action {
         }
     }
 
-  /*
+    /**
      * function locking an entry while it is being executed by the action script
+     * 
+     * @global type $db
+     * @global type $err
+     * @param type $id
+     * @return boolean
      */
     function begin($id) {
         global $db, $err;
@@ -211,8 +297,14 @@ class m_action {
         return true;
     }
 
-  /*
+    /**
      *  function locking an entry while it is being executed by the action script
+     * 
+     * @global type $db
+     * @global type $err
+     * @param type $id
+     * @param type $return
+     * @return boolean
      */
     function finish($id, $return = 0) {
         global $db, $err;
@@ -223,6 +315,13 @@ class m_action {
         return true;
     }
     
+    /**
+     * 
+     * @global type $db
+     * @global type $err
+     * @param type $id
+     * @return boolean
+     */
     function reset_job($id) {
         global $db, $err;
         if (!$db->query("update actions set end=0,begin=0,status='' where id=$id ;")) {
@@ -232,6 +331,13 @@ class m_action {
         return true;
     }
     
+    /**
+     * Returns a list of actions marked as executable and ready for execution
+     * 
+     * @global type $db
+     * @global type $err
+     * @return boolean 
+     */
     function get_job() {
         global $db, $err;
         $tab = array();
@@ -244,8 +350,12 @@ class m_action {
         }
     }
 
-  /*
+    /**
      *  function locking an entry while it is being executed by the action script
+     * 
+     * @global type $db
+     * @param type $id
+     * @return boolean
      */
     function cancel($id) {
         global $db;
@@ -253,6 +363,6 @@ class m_action {
         return true;
     }
 
-} /* Class action */
+}
 
-?>
+/* Class action */