viewgit/inc/functions.php:22 Function utf8_encode() is deprecated [8192]

Add some docs for VersionManager, tries to improve error checking in PdoManager to avoid crash, a=chris

Chris Pollett [2018-04-14 15:Apr:th]
Add some docs for VersionManager, tries to improve error checking in PdoManager to avoid crash, a=chris
Filename
src/library/UpgradeFunctions.php
src/library/VersionManager.php
src/models/datasources/PdoManager.php
tests/VersionManagerTest.php
diff --git a/src/library/UpgradeFunctions.php b/src/library/UpgradeFunctions.php
index 9cca66905..4c579024f 100644
--- a/src/library/UpgradeFunctions.php
+++ b/src/library/UpgradeFunctions.php
@@ -126,6 +126,7 @@ function upgradeDatabaseWorkDirectoryCheck()
 {
     $model = new M\Model();
     $sql = "SELECT ID FROM VERSION";
+    set_error_handler(null);
     for ($i = 0; $i < 3; $i++) {
         $result = @$model->db->execute($sql);
         if ($result !== false) {
@@ -139,7 +140,8 @@ function upgradeDatabaseWorkDirectoryCheck()
         }
         sleep(3);
     }
-    exit();
+    set_error_handler(C\NS_LIB . "yioop_error_handler");
+    webExit();
 }
 /**
  * If the database data of Yioop is older than the version of the
@@ -150,6 +152,7 @@ function upgradeDatabaseWorkDirectory()
 {
     $model = new M\Model();
     $sql = "SELECT ID FROM VERSION";
+    set_error_handler(null);
     $result = @$model->db->execute($sql);
     if ($result !== false) {
         $row = $model->db->fetchArray($result);
@@ -161,8 +164,9 @@ function upgradeDatabaseWorkDirectory()
             $current_version = 1;
         }
     } else {
-        exit(); // maybe someone else has locked DB, so bail
+        webExit(); // maybe someone else has locked DB, so bail
     }
+    set_error_handler(C\NS_LIB . "yioop_error_handler");
     $result = null; //don't lock db if sqlite
     $versions = range(1, C\YIOOP_VERSION);
     $key = array_search($current_version, $versions);
diff --git a/src/library/VersionManager.php b/src/library/VersionManager.php
index 536c55925..e4dbfbb80 100644
--- a/src/library/VersionManager.php
+++ b/src/library/VersionManager.php
@@ -31,14 +31,18 @@
 namespace seekquarry\yioop\library;

 /**
- *
+ * VersionManager can be used to create and manage versions of files in a folder
+ * so that a user can revert the files to any version desired back to the
+ * time the folder under manager was first managed. It is used by Yioop's
+ * Wiki system to handle versions of image and other media resources for a
+ * Wiki page.
  *
  * @author Chris Pollett
  */
 class VersionManager
 {
     /**
-     *
+     *  Return code constants for public VersionManager methods
      */
     const RENAME_FAILED = -12;
     const PUT_CONTENTS_FAILED = -11;
@@ -83,10 +87,16 @@ class VersionManager
     public $permissions;
     /**
      *
-     * @param string $managed_folder
-     * @param string $archive_name
-     * @param string $hash_algorithm
-     * @param int $permissions
+     * @param string $managed_folder what folder should be managed with
+     *      this versioning system
+     * @param string $archive_name file_name in the folder to use for the
+     *      subfolder containing the archived versions of files
+     * @param string $hash_algorithm what hash algorithm should be used to
+     *      generate archive filenames. Defaults to sha256
+     * @param int $permissions what to set the file permissions to for the
+     *      archive file. To keep things simple this defaults to world
+     *      read write. In practice you probably want to tailor this to
+     *      the situation for security
      */
     public function __construct($managed_folder = '.',
         $archive_name = '.archive', $hash_algorithm = 'sha256',
@@ -115,6 +125,13 @@ class VersionManager
      * be involved in new version. I.e.,  a single repository dir file for
      * folder will be made. If $file_changed is a nonexistent file in $folder
      * then the dir's in path to $file_changed will be updated.
+     *
+     * @param string $file_changed
+     * @param string $folder
+     * @param int $now
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
+     * @param array $force_update_list
      */
     public function createVersion($file_changed = "", $folder = "", $now = 0,
         $lock = true, $force_update_list = [])
@@ -205,7 +222,9 @@ class VersionManager
         return $hash_folder_name;
     }
     /**
-     *
+     * @param string $file name of file to get contents of
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function headGetContents($file, $lock = true)
     {
@@ -219,7 +238,9 @@ class VersionManager
         return file_get_contents($file);
     }
     /**
-     *
+     * @param string $file name of file to store data for
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function headPutContents($file, $data, $lock = true)
     {
@@ -247,7 +268,10 @@ class VersionManager
         return self::SUCCESS;
     }
     /**
-     *
+     * @param string $from_name name of file or dir to copy
+     * @param string $to_name name of file or dir to save copy to
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function headCopy($from_name, $to_name, $lock = true)
     {
@@ -274,7 +298,9 @@ class VersionManager
         return self::SUCCESS;
     }
     /**
-     *
+     * @param string $file name of file to delete
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function headDelete($file, $lock = true)
     {
@@ -304,7 +330,9 @@ class VersionManager
         return self::SUCCESS;
     }
     /**
-     *
+     * @param string $dir name of directory folder to make
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function headMakeDirectory($dir, $lock = true)
     {
@@ -326,7 +354,10 @@ class VersionManager
         return self::SUCCESS;
     }
     /**
-     *
+     * @param string $old_name original name of file
+     * @param string $new_name what to change it to
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function headRename($old_name, $new_name, $lock = true)
     {
@@ -355,7 +386,8 @@ class VersionManager
         return self::SUCCESS;
     }
     /**
-     *
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function headInfo($lock = true)
     {
@@ -367,7 +399,9 @@ class VersionManager
         return unserialize(file_get_contents("$version_path/HEAD"));
     }
     /**
-     *
+     * @param string $file name of file to get data about
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function versionGetContents($file, $timestamp,
         $get_nearest_version = false, $lock = true)
@@ -397,7 +431,11 @@ class VersionManager
         }
     }
     /**
-     *
+     * @param int $timestamp of version what to restore to
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
+     * @param bool $force_lock whether or not any existing lock should be
+     *      ignored
      */
     public function restoreVersion($timestamp, $lock = true,
         $force_lock = false)
@@ -437,7 +475,10 @@ class VersionManager
         return self::SUCCESS;
     }
     /**
-     *
+     * @param int $timestamp want to find the version in the repository
+     *      closest to, but not exceeding this value.
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function getActiveVersion($search_timestamp, $lock = true)
     {
@@ -524,7 +565,10 @@ class VersionManager
         return $max_timestamp;
     }
     /**
-     *
+     * @param int $start_time
+     * @param int $end_time
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     public function getVersionsInRange($start_time, $end_time, $lock = true)
     {
@@ -567,7 +611,7 @@ class VersionManager
         return $filtered_versions;
     }
     /**
-     *
+     * @param string $hash_name
      */
     protected function getArchivePathHashName($hash_name)
     {
@@ -577,9 +621,13 @@ class VersionManager
         return $archive_path;
     }
     /**
-     *
+     * @param string $file name of file want to get the archive name and
+     *      archive path for
+     * @param int $timestamp
+     * @param bool $make_path
      */
-    protected function getArchiveFileAndPath($file, $timestamp, $make_path = false)
+    protected function getArchiveFileAndPath($file, $timestamp,
+        $make_path = false)
     {
         $hash_name = hash($this->hash_algorithm, $file . $timestamp);
         $first_prefix = substr($hash_name, 0, 2);
@@ -595,7 +643,8 @@ class VersionManager
         return [$hash_name, $archive_path];
     }
     /**
-     *
+     * @param int $timestamp
+     * @param bool $make_path
      */
     protected function getVersionPath($timestamp, $make_path = false)
     {
@@ -612,7 +661,11 @@ class VersionManager
         return $version_path;
     }
     /**
-     *
+     * @param string $file name of file
+     * @param int $timestamp
+     * @param bool $get_nearest_version
+     * @param string $path_so_far
+     * @param string $hash_path_so_far
      */
     protected function getHashNamePath($file, $timestamp,
         $get_nearest_version = false, $path_so_far = "", $hash_path_so_far = "")
@@ -668,8 +721,8 @@ class VersionManager
     /**
      *
      *
-     * @param string $dir directory name
-     * @return int
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     protected function unlinkHead($lock = true)
     {
@@ -687,7 +740,12 @@ class VersionManager
         return self::SUCCESS;
     }
     /**
-     *
+     * @param string $file
+     * @param string $target
+     * @param int $timestamp
+     * @param string $hash_name_type
+     * @param bool $lock whether or not a lock should be obtained before
+     *      carrying out the operation
      */
     protected function copyFromVersionOrHashName($file, $target, $timestamp,
         $hash_name_type = "", $lock = true)
@@ -826,6 +884,7 @@ class VersionManager
      * directory
      *
      * @param string $file_or_dir the filename or directory name to be deleted
+     * @param int $timestamp
      */
     protected function deleteVersionFileOrFolder($file_or_dir, $timestamp = 0)
     {
diff --git a/src/models/datasources/PdoManager.php b/src/models/datasources/PdoManager.php
index 978b02e51..3f680bb3d 100644
--- a/src/models/datasources/PdoManager.php
+++ b/src/models/datasources/PdoManager.php
@@ -78,7 +78,8 @@ class PdoManager extends DatasourceManager
     {
         try {
             $db_host = $db_host;
-            $this->pdo = new \PDO($db_host, $db_user, $db_password);
+            $this->pdo = new \PDO($db_host, $db_user, $db_password,
+                [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
         } catch (\PDOException $e) {
             $this->pdo = false;
             L\crawlLog('Connection failed: ' . $e->getMessage());
diff --git a/tests/VersionManagerTest.php b/tests/VersionManagerTest.php
index 7ec26e659..67b4f0790 100644
--- a/tests/VersionManagerTest.php
+++ b/tests/VersionManagerTest.php
@@ -35,13 +35,14 @@ use seekquarry\yioop\library\VersionManager;
 use seekquarry\yioop\library\UnitTest;

 /**
- * UnitTest for the VersionManager class.
+ * UnitTests for the VersionManager class.
  *
  * @author Chris Pollett
  */
 class VersionManagerTest extends UnitTest
 {
-    /** our dbms manager handle so we can call unlinkRecursive
+    /**
+     * our dbms manager handle so we can call unlinkRecursive
      * @var object
      */
     public $db;
@@ -52,7 +53,7 @@ class VersionManagerTest extends UnitTest
         "/test_files/version_manager_test";
     /**
      * Sets up a miminal DBMS manager class so that we will be able to use
-     * unlinkRecursive to tear down own WebQueueBundle
+     * unlinkRecursive to tear down the files created bby our tests
      */
     public function __construct()
     {
@@ -63,22 +64,21 @@ class VersionManagerTest extends UnitTest
         }
     }
     /**
-     * Set up a web queue bundle that can store 1000 urls in ram, has bloom
-     * filter space for 1000 urls and which uses a maximum value returning
-     * priority queue.
+     * Does nothing
      */
     public function setUp()
     {
     }
     /**
-     * Delete the directory and files associated with the WebQueueBundle
+     * Delete the files created associated with the VersionManager tests
      */
     public function tearDown()
     {
         $this->db->unlinkRecursive($this->version_test_folder, false);
     }
     /**
-     *
+     * Test the ability to create a new version of a folder within the
+     * VervionManager archive.
      */
     public function createVersionFolderTestCase()
     {
@@ -97,7 +97,8 @@ class VersionManagerTest extends UnitTest
             "First test file is in stored in HEAD info");
     }
     /**
-     *
+     * Tests that we can put and get files from the head version of
+     * the managed folder's version archive.
      */
     public function getPutContentsTestCase()
     {
@@ -193,7 +194,8 @@ class VersionManagerTest extends UnitTest
             "Test sub folder file correctly deleted on version restore");
     }
     /**
-     *
+     * Tests restoring a folder to a given timestamp, making sure the
+     * correct files are present after the restore.
      */
     public function restoreVersionTestCase()
     {
@@ -231,7 +233,8 @@ class VersionManagerTest extends UnitTest
             "After Restore symlink restored");
     }
     /**
-     *
+     * Tests getting the active version of the repository at a given
+     * timestamp and between a range of timestamps
      */
     public function versionGettersTestCase()
     {
ViewGit