Merge branch 'main' into issue-3911issue-3911

1 files changed, 250 insertions, 0 deletions

diff --git a/lib/classes/DBManager.php b/lib/classes/DBManager.php
new file mode 100644
index 0000000..7854cff
--- /dev/null
+++ b/lib/classes/DBManager.php
@@ -0,0 +1,250 @@
+<?php
+# Lifter010: TODO
+
+/*
+ * Copyright (C) 2007 - Marcus Lunzenauer <mlunzena@uos.de>
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ */
+
+/**
+ * This class provides a singleton instance that is used to manage PDO database
+ * connections.
+ *
+ * Example of use:
+ * @code
+ *   # get hold of the DBManager's singleton
+ *   $manager = DBManager::getInstance();
+ *
+ *   # set PDO connections using a DSN
+ *   $manager->setConnection('example',
+ *                           'mysql:host=localhost;dbname=example',
+ *                           'root', '');
+ *   # or an existing instance of PDO
+ *   $manager->setConnection('example2', $existingPdo);
+ *
+ *   # retrieve a PDO connection later in your code
+ *   $db = $manager->getConnection("studip");
+ *
+ *   # or as a shortcut
+ *   $db = DBManager::get("studip");
+ *
+ *   # or even shorter ("studip" is the default key)
+ *   $db = DBManager::get();
+ *
+ *   # and use the connection
+ *   $db->query('SELECT * FROM user_info');
+ *
+ *   # you may even alias connections
+ *   $manager->aliasConnection("studip", "studip-slave");
+ *
+ *   # but this is just sugar for
+ *   $studip = $manager->getConnection("studip");
+ *   $manager->setConnection("studip-slave", $studip);
+ *
+ * @endcode
+ */
+class DBManager
+{
+
+
+    /**
+     * the singleton instance
+     *
+     * @access  private
+     * @var     DBManager
+     */
+    static private $instance;
+
+
+    /**
+     * an array of connections of the singleton instance
+     *
+     * @access  private
+     * @var     array
+     */
+    private $connections;
+
+
+    /**
+     * @access private
+     *
+     * @return void
+     */
+    private function __construct()
+    {
+        $this->connections = [];
+    }
+
+
+    /**
+     * This method returns the singleton instance of this class.
+     *
+     * @return DBManager  the singleton instance
+     */
+    static public function getInstance()
+    {
+        if (is_null(DBManager::$instance)) {
+            DBManager::$instance = new DBManager();
+        }
+        return DBManager::$instance;
+    }
+
+
+    /**
+     * This method returns the database connection to the given key. Throws a
+     * DBManagerException if there is no such connection.
+     *
+     * Example usage:
+     * @code
+     * try {
+     *     $db = DBManager::getInstance()->getConnection("foo");
+     *     $db->exec($sql);
+     * } catch (DBManagerException $e) {
+     *     echo "oops";
+     * }
+     * @endcode
+     *
+     * @param  string  the key
+     *
+     * @throw DBManagerException
+     *
+     * @return PDO     the database connection
+     */
+    public function getConnection($database)
+    {
+
+        if (!isset($this->connections[$database])) {
+            throw new DBManagerException('Database connection: "'.$database.
+                                         '" does not exist.');
+        }
+
+        return $this->connections[$database];
+    }
+
+
+    /**
+     * This method maps the specified key to the specified database connection.
+     *
+     * You can either use an instance of class PDO or specify a DSN (optionally
+     * with username/password).
+     *
+     * The (possibly newly created) connection is configured to throw exceptions
+     * and to buffer queries if it is a MySQL connection.
+     *
+     * Examples:
+     * @code
+     *    $dbManager = DBManager::getInstance();
+     *
+     *    // using an existing PDO connection
+     *    $existingPdo = new LoggingPDO($dsn);
+     *    $dbManager->setConnection('studip', $pdo);
+     *
+     *    // using a DSN with username and password
+     *    $dbManager->setConnection('studip', $dsn , $username, $password);
+     * @endcode
+     *
+     * @param  string      the key
+     * @param  string|PDO  either a DSN or an existing PDO connection
+     * @param  string      (optional) the connection's username
+     * @param  array       (optional) the connection's password
+     *
+     * @return DBManager this instance, useful for cascading method calls
+     */
+    public function setConnection($database, $dsnOrConnection, $user = NULL,
+                                  $pass = NULL)
+    {
+        $connection = $dsnOrConnection instanceof PDO
+            ? $dsnOrConnection
+            : new StudipPDO($dsnOrConnection, $user, $pass);
+
+        $this->configureConnection($connection);
+        $this->connections[$database] = $connection;
+
+        return $this;
+    }
+
+
+    // PDO connection should throw exceptions and use buffered queries
+    private function configureConnection($connection)
+    {
+
+        $connection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
+        if ($connection->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
+            $connection->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, true);
+            // $connection->exec('SET CHARACTER SET latin1');
+        }
+    }
+
+    /**
+     * This method creates an alias for a database connection.
+     *
+     * This is useful if you want to use different keys but access the same
+     * database, e.g. if you want to use master-slave replication in the future
+     *
+     * @param  string    the old key of the database connection
+     * @param  string    the new key of the database connection
+     *
+     * @return DBManager this instance, useful for cascading method calls
+     */
+    public function aliasConnection($old, $new)
+    {
+
+        if (!isset($this->connections[$old])) {
+            throw new DBManagerException('No database found using key: ' . $old);
+        }
+
+        $this->connections[$new] = $this->connections[$old];
+
+        return $this;
+    }
+
+
+    /**
+     * Shortcut static method to retrieve the database connection for a given
+     * key.
+     *
+     * Example usage:
+     * @code
+     * // instead of
+     * $db = DBManager::getInstance()->getConnection("studip");
+     *
+     * // this can be shortened to
+     * $db = DBManager::get("studip");
+     *
+     * // or in this case (as "studip" is the default key)
+     * $db = DBManager::get();
+     * @endcode
+     *
+     * @param  string  the key
+     *
+     * @return StudipPDO     the database connection
+     */
+    static public function get($database = 'studip')
+    {
+        $manager = DBManager::getInstance();
+        return $manager->getConnection($database);
+    }
+}
+
+
+/**
+ * The DBManager throws this exception if it cannot find a connection using
+ * a non existant key.
+ */
+class DBManagerException extends Exception
+{
+
+    /**
+     * @param  string   the message of this exception
+     *
+     * @return void
+     */
+    public function __construct($message)
+    {
+        parent::__construct($message);
+    }
+}