Docblock example on phunction::DB()

DB.php

<?php

/**
 * Database wrapper for MySQL, PostgreSQL, SQLite and Firebird.
 *
 * This method provides a simplified and secure way (using prepared statements and un-named variadic parameters)
 * to connect and query databases via PDO. The database connection is kept in an internal singleton registry.
 *
 * ----
 *
 * Connect:
 *
 * <code>
 * ph()->DB('mysql://host[:port]/database/', 'username', 'password'); // MySQL
 * </code>
 *
 * On MySQL, new connections define the charset/collation to UTF-8 and the timezone to date_default_timezone_get().
 * Connections to multiple databases is possible using the $ph argument in the ph() function:
 *
 * <code>
 * ph('sqlite_session_storage')->DB('sqlite://path/to/sqlite.db'); // SQLite
 * </code>
 *
 * Uppon connection (or when calling this function without arguments), the PDO object will be returned.
 * This is useful if/when you need to access specific PDO methods, for instance:
 *
 * <code>
 * ph()->DB()->quote(); // PDO::quote()
 * ph('sqlite_session_storage')->DB()->sqliteCreateFunction(); // PDO::sqliteCreateFunction()
 * </code>
 *
 * ----
 *
 * INSERTs and REPLACEs:
 *
 * On success, INSERT and REPLACE queries will return the last inserted/replaced ID (PK), returns false on error.
 *
 * <code>
 * $insert_id = ph()->DB('INSERT INTO `frameworks` (`name`) VALUES (?);', 'phunction');
 * </code>
 *
 * ----
 *
 * UPDATEs and DELETEs:
 *
 * On success, UPDATE and DELETE queries will return the number of rows that were affected, returns false on error.
 *
 * <code>
 * $affected_rows = ph()->DB('UPDATE `frameworks` SET `name` = ? WHERE `name` LIKE ? LIMIT 1;', 'ph', 'phunction');
 * </code>
 *
 * ----
 *
 * SELECTs, SHOWs, EXPLAINs, DESC[RIBE]s and PRAGMAs:
 *
 * On success, these queries will return a multi-dimensional associative array, returns false on error.
 *
 * <code>
 * $query_resultset = ph()->DB('SELECT * FROM `frameworks` WHERE `name` LIKE ?;', 'ph%');
 * </code>
 *
 * ----
 *
 * Other DDS queries are also supported and will return true on success, or false on error.
 *
 * <code>
 * $dds_query = ph()->DB('DROP TABLE `frameworks`;');
 * </code>
 *
 * ----
 *
 * @param string|null $query the DMS/DDS query or normalized PDO DSN, null returns the current PDO object
 * @param string ... un-named parameters to be escaped or auth credentials (on connect)
 * @return mixed false if the query fails to execute, on success see docblock
 */
public static function DB($query = null)
{
	static $db = array();
	static $result = array();

	if (isset($db[self::$id], $query) === true)
	{
		if (empty($result[self::$id][$hash = md5($query)]) === true)
		{
			$result[self::$id][$hash] = $db[self::$id]->prepare($query);
		}

		if (is_object($result[self::$id][$hash]) === true)
		{
			if ($result[self::$id][$hash]->execute(array_slice(func_get_args(), 1)) === true)
			{
				if (preg_match('~^(?:INSERT|REPLACE)\b~i', $query) > 0)
				{
					return $db[self::$id]->lastInsertId();
				}

				else if (preg_match('~^(?:UPDATE|DELETE)\b~i', $query) > 0)
				{
					return $result[self::$id][$hash]->rowCount();
				}

				else if (preg_match('~^(?:SELECT|SHOW|EXPLAIN|DESC(?:RIBE)?|PRAGMA)\b~i', $query) > 0)
				{
					return $result[self::$id][$hash]->fetchAll(PDO::FETCH_ASSOC);
				}

				return true;
			}
		}

		return false;
	}

	else if (preg_match('~^(?:mysql|pgsql):~i', $query) > 0)
	{
		try
		{
			$db[self::$id] = new PDO(preg_replace('~^([^:]+):/{0,2}([^:/]+)(?::(\d+))?/(\w+)/?$~', '$1:host=$2;port=$3;dbname=$4', $query), @func_get_arg(1), @func_get_arg(2));

			if (strcmp('mysql', $db[self::$id]->getAttribute(PDO::ATTR_DRIVER_NAME)) === 0)
			{
				self::DB('SET time_zone = ?;', date_default_timezone_get());
				self::DB('SET NAMES ? COLLATE ?;', 'utf8', 'utf8_unicode_ci');
			}
		}

		catch (PDOException $e)
		{
			return false;
		}
	}

	else if (preg_match('~^(?:sqlite|firebird):~', $query) > 0)
	{
		$db[self::$id] = new PDO(preg_replace('~^([^:]+):(?:/{2})?(.+)$~', '$1:$2', $query));
	}

	return (isset($db[self::$id]) === true) ? $db[self::$id] : false;
}

?>

Related to alixaxel/phunction#5.