silverstripe-framework/ORM/Connect/Database.php

<?php

namespace SilverStripe\ORM\Connect;

use SilverStripe\Control\Director;
use SilverStripe\Core\Config\Config;
use SilverStripe\Dev\Debug;
use SilverStripe\ORM\PaginatedList;
use SilverStripe\ORM\Queries\SQLUpdate;
use SilverStripe\ORM\Queries\SQLInsert;
use BadMethodCallException;
use Exception;

/**
 * Abstract database connectivity class.
 * Sub-classes of this implement the actual database connection libraries
 */
abstract class Database {

	/**
	 * Database connector object
	 *
	 * @var DBConnector
	 */
	protected $connector = null;

	/**
	 * In cases where your environment does not have 'SHOW DATABASES' permission,
	 * you can set this to true. Then selectDatabase() will always connect without
	 * doing databaseExists() check.
	 *
	 * @var bool
	 */
	private static $optimistic_connect = false;

	/**
	 * Amount of queries executed, for debugging purposes.
	 *
	 * @var int
	 */
	protected $queryCount = 0;

	/**
	 * Get the current connector
	 *
	 * @return DBConnector
	 */
	public function getConnector() {
		return $this->connector;
	}

	/**
	 * Injector injection point for connector dependency
	 *
	 * @param DBConnector $connector
	 */
	public function setConnector(DBConnector $connector) {
		$this->connector = $connector;
	}

	/**
	 * Database schema manager object
	 *
	 * @var DBSchemaManager
	 */
	protected $schemaManager = null;

	/**
	 * Returns the current schema manager
	 *
	 * @return DBSchemaManager
	 */
	public function getSchemaManager() {
		return $this->schemaManager;
	}

	/**
	 * Injector injection point for schema manager
	 *
	 * @param DBSchemaManager $schemaManager
	 */
	public function setSchemaManager(DBSchemaManager $schemaManager) {
		$this->schemaManager = $schemaManager;

		if ($this->schemaManager) {
			$this->schemaManager->setDatabase($this);
		}
	}

	/**
	 * Query builder object
	 *
	 * @var DBQueryBuilder
	 */
	protected $queryBuilder = null;

	/**
	 * Returns the current query builder
	 *
	 * @return DBQueryBuilder
	 */
	public function getQueryBuilder() {
		return $this->queryBuilder;
	}

	/**
	 * Injector injection point for schema manager
	 *
	 * @param DBQueryBuilder $queryBuilder
	 */
	public function setQueryBuilder(DBQueryBuilder $queryBuilder) {
		$this->queryBuilder = $queryBuilder;
	}

	/**
	 * Execute the given SQL query.
	 *
	 * @param string $sql The SQL query to execute
	 * @param int $errorLevel The level of error reporting to enable for the query
	 * @return Query
	 */
	public function query($sql, $errorLevel = E_USER_ERROR) {
		// Check if we should only preview this query
		if ($this->previewWrite($sql)) {
			return null;
		}

		// Benchmark query
		$connector = $this->connector;
		return $this->benchmarkQuery(
			$sql,
			function($sql) use($connector, $errorLevel) {
				return $connector->query($sql, $errorLevel);
			}
		);
	}


	/**
	 * Execute the given SQL parameterised query with the specified arguments
	 *
	 * @param string $sql The SQL query to execute. The ? character will denote parameters.
	 * @param array $parameters An ordered list of arguments.
	 * @param int $errorLevel The level of error reporting to enable for the query
	 * @return Query
	 */
	public function preparedQuery($sql, $parameters, $errorLevel = E_USER_ERROR) {
		// Check if we should only preview this query
		if ($this->previewWrite($sql)) {
			return null;
		}

		// Benchmark query
		$connector = $this->connector;
		return $this->benchmarkQuery(
			$sql,
			function($sql) use($connector, $parameters, $errorLevel) {
				return $connector->preparedQuery($sql, $parameters, $errorLevel);
			},
			$parameters
		);
	}

	/**
	 * Determines if the query should be previewed, and thus interrupted silently.
	 * If so, this function also displays the query via the debuging system.
	 * Subclasess should respect the results of this call for each query, and not
	 * execute any queries that generate a true response.
	 *
	 * @param string $sql The query to be executed
	 * @return boolean Flag indicating that the query was previewed
	 */
	protected function previewWrite($sql) {
		// Only preview if previewWrite is set, we are in dev mode, and
		// the query is mutable
		if (isset($_REQUEST['previewwrite'])
			&& Director::isDev()
			&& $this->connector->isQueryMutable($sql)
		) {
			// output preview message
			Debug::message("Will execute: $sql");
			return true;
		} else {
			return false;
		}
	}

	/**
	 * Allows the display and benchmarking of queries as they are being run
	 *
	 * @param string $sql Query to run, and single parameter to callback
	 * @param callable $callback Callback to execute code
	 * @param array $parameters Parameters for any parameterised query
	 * @return mixed Result of query
	 */
	protected function benchmarkQuery($sql, $callback, $parameters = array()) {
		if (isset($_REQUEST['showqueries']) && Director::isDev()) {
			$this->queryCount++;
			$starttime = microtime(true);
			$result = $callback($sql);
			$endtime = round(microtime(true) - $starttime, 4);
			// replace parameters as closely as possible to what we'd expect the DB to put in
			if (strtolower($_REQUEST['showqueries']) == 'inline') {
				$sql = DB::inline_parameters($sql, $parameters);
			}
			Debug::message("\n$sql\n{$endtime}s\n", false);
			return $result;
		} else {
			return $callback($sql);
		}
	}

	/**
	 * Get the autogenerated ID from the previous INSERT query.
	 *
	 * @param string $table The name of the table to get the generated ID for
	 * @return integer the most recently generated ID for the specified table
	 */
	public function getGeneratedID($table) {
		return $this->connector->getGeneratedID($table);
	}

	/**
	 * Determines if we are connected to a server AND have a valid database
	 * selected.
	 *
	 * @return boolean Flag indicating that a valid database is connected
	 */
	public function isActive() {
		return $this->connector->isActive();
	}

	/**
	 * Returns an escaped string. This string won't be quoted, so would be suitable
	 * for appending to other quoted strings.
	 *
	 * @param mixed $value Value to be prepared for database query
	 * @return string Prepared string
	 */
	public function escapeString($value) {
		return $this->connector->escapeString($value);
	}

	/**
	 * Wrap a string into DB-specific quotes.
	 *
	 * @param mixed $value Value to be prepared for database query
	 * @return string Prepared string
	 */
	public function quoteString($value) {
		return $this->connector->quoteString($value);
	}

	/**
	 * Escapes an identifier (table / database name). Typically the value
	 * is simply double quoted. Don't pass in already escaped identifiers in,
	 * as this will double escape the value!
	 *
	 * @param string|array $value The identifier to escape or list of split components
	 * @param string $separator Splitter for each component
	 * @return string
	 */
	public function escapeIdentifier($value, $separator = '.') {
		// Split string into components
		if(!is_array($value)) {
			$value = explode($separator, $value);
		}

		// Implode quoted column
		return '"' . implode('"'.$separator.'"', $value) . '"';
	}

	/**
	 * Escapes unquoted columns keys in an associative array
	 *
	 * @param array $fieldValues
	 * @return array List of field values with the keys as escaped column names
	 */
	protected function escapeColumnKeys($fieldValues) {
		$out = array();
		foreach($fieldValues as $field => $value) {
			$out[$this->escapeIdentifier($field)] = $value;
		}
		return $out;
	}

	/**
	 * Execute a complex manipulation on the database.
	 * A manipulation is an array of insert / or update sequences.  The keys of the array are table names,
	 * and the values are map containing 'command' and 'fields'.  Command should be 'insert' or 'update',
	 * and fields should be a map of field names to field values, NOT including quotes.
	 *
	 * The field values could also be in paramaterised format, such as
	 * array('MAX(?,?)' => array(42, 69)), allowing the use of raw SQL values such as
	 * array('NOW()' => array()).
	 *
	 * @see SQLWriteExpression::addAssignments for syntax examples
	 *
	 * @param array $manipulation
	 */
	public function manipulate($manipulation) {
		if (empty($manipulation)) return;

		foreach ($manipulation as $table => $writeInfo) {
			if(empty($writeInfo['fields'])) continue;
			// Note: keys of $fieldValues are not escaped
			$fieldValues = $writeInfo['fields'];

			// Switch command type
			switch ($writeInfo['command']) {
				case "update":

					// Build update
					$query = new SQLUpdate("\"$table\"", $this->escapeColumnKeys($fieldValues));

					// Set best condition to use
					if(!empty($writeInfo['where'])) {
						$query->addWhere($writeInfo['where']);
					} elseif(!empty($writeInfo['id'])) {
						$query->addWhere(array('"ID"' => $writeInfo['id']));
					}

					// Test to see if this update query shouldn't, in fact, be an insert
					if($query->toSelect()->count()) {
						$query->execute();
						break;
					}
					// ...if not, we'll skip on to the insert code

				case "insert":
					// Ensure that the ID clause is given if possible
					if (!isset($fieldValues['ID']) && isset($writeInfo['id'])) {
						$fieldValues['ID'] = $writeInfo['id'];
					}

					// Build insert
					$query = new SQLInsert("\"$table\"", $this->escapeColumnKeys($fieldValues));

					$query->execute();
					break;

				default:
					user_error("SS_Database::manipulate() Can't recognise command '{$writeInfo['command']}'",
								E_USER_ERROR);
			}
		}
	}

	/**
	 * Enable supression of database messages.
	 */
	public function quiet() {
		$this->schemaManager->quiet();
	}

	/**
	 * Clear all data out of the database
	 */
	public function clearAllData() {
		$tables = $this->getSchemaManager()->tableList();
		foreach ($tables as $table) {
			$this->clearTable($table);
		}
	}

	/**
	 * Clear all data in a given table
	 *
	 * @param string $table Name of table
	 */
	public function clearTable($table) {
		$this->query("TRUNCATE \"$table\"");
	}

	/**
	 * Generates a WHERE clause for null comparison check
	 *
	 * @param string $field Quoted field name
	 * @param bool $isNull Whether to check for NULL or NOT NULL
	 * @return string Non-parameterised null comparison clause
	 */
	public function nullCheckClause($field, $isNull) {
		$clause = $isNull
			? "%s IS NULL"
			: "%s IS NOT NULL";
		return sprintf($clause, $field);
	}

	/**
	 * Generate a WHERE clause for text matching.
	 *
	 * @param String $field Quoted field name
	 * @param String $value Escaped search. Can include percentage wildcards.
	 * Ignored if $parameterised is true.
	 * @param boolean $exact Exact matches or wildcard support.
	 * @param boolean $negate Negate the clause.
	 * @param boolean $caseSensitive Enforce case sensitivity if TRUE or FALSE.
	 * Fallback to default collation if set to NULL.
	 * @param boolean $parameterised Insert the ? placeholder rather than the
	 * given value. If this is true then $value is ignored.
	 * @return String SQL
	 */
	abstract public function comparisonClause($field, $value, $exact = false, $negate = false, $caseSensitive = null,
											$parameterised = false);

	/**
	 * function to return an SQL datetime expression that can be used with the adapter in use
	 * used for querying a datetime in a certain format
	 *
	 * @param string $date to be formated, can be either 'now', literal datetime like '1973-10-14 10:30:00' or
	 *                     field name, e.g. '"SiteTree"."Created"'
	 * @param string $format to be used, supported specifiers:
	 * %Y = Year (four digits)
	 * %m = Month (01..12)
	 * %d = Day (01..31)
	 * %H = Hour (00..23)
	 * %i = Minutes (00..59)
	 * %s = Seconds (00..59)
	 * %U = unix timestamp, can only be used on it's own
	 * @return string SQL datetime expression to query for a formatted datetime
	 */
	abstract public function formattedDatetimeClause($date, $format);

	/**
	 * function to return an SQL datetime expression that can be used with the adapter in use
	 * used for querying a datetime addition
	 *
	 * @param string $date, can be either 'now', literal datetime like '1973-10-14 10:30:00' or field name,
	 *                      e.g. '"SiteTree"."Created"'
	 * @param string $interval to be added, use the format [sign][integer] [qualifier], e.g. -1 Day, +15 minutes,
	 *                         +1 YEAR
	 * supported qualifiers:
	 * - years
	 * - months
	 * - days
	 * - hours
	 * - minutes
	 * - seconds
	 * This includes the singular forms as well
	 * @return string SQL datetime expression to query for a datetime (YYYY-MM-DD hh:mm:ss) which is the result of
	 *                the addition
	 */
	abstract public function datetimeIntervalClause($date, $interval);

	/**
	 * function to return an SQL datetime expression that can be used with the adapter in use
	 * used for querying a datetime substraction
	 *
	 * @param string $date1, can be either 'now', literal datetime like '1973-10-14 10:30:00' or field name
	 *                       e.g. '"SiteTree"."Created"'
	 * @param string $date2 to be substracted of $date1, can be either 'now', literal datetime
	 *                      like '1973-10-14 10:30:00' or field name, e.g. '"SiteTree"."Created"'
	 * @return string SQL datetime expression to query for the interval between $date1 and $date2 in seconds which
	 *                is the result of the substraction
	 */
	abstract public function datetimeDifferenceClause($date1, $date2);

	/**
	 * Returns true if this database supports collations
	 *
	 * @return boolean
	 */
	abstract public function supportsCollations();

	/**
	 * Can the database override timezone as a connection setting,
	 * or does it use the system timezone exclusively?
	 *
	 * @return Boolean
	 */
	abstract public function supportsTimezoneOverride();

	/**
	 * Query for the version of the currently connected database
	 * @return string Version of this database
	 */
	public function getVersion() {
		return $this->connector->getVersion();
	}

	/**
	 * Get the database server type (e.g. mysql, postgresql).
	 * This value is passed to the connector as the 'driver' argument when
	 * initiating a database connection
	 *
	 * @return string
	 */
	abstract public function getDatabaseServer();

	/**
	 * Return the number of rows affected by the previous operation.
	 * @return int
	 */
	public function affectedRows() {
		return $this->connector->affectedRows();
	}

	/**
	 * The core search engine, used by this class and its subclasses to do fun stuff.
	 * Searches both SiteTree and File.
	 *
	 * @param array $classesToSearch List of classes to search
	 * @param string $keywords Keywords as a string.
	 * @param integer $start Item to start returning results from
	 * @param integer $pageLength Number of items per page
	 * @param string $sortBy Sort order expression
	 * @param string $extraFilter Additional filter
	 * @param boolean $booleanSearch Flag for boolean search mode
	 * @param string $alternativeFileFilter
	 * @param boolean $invertedMatch
	 * @return PaginatedList Search results
	 */
	abstract public function searchEngine($classesToSearch, $keywords, $start, $pageLength, $sortBy = "Relevance DESC",
		$extraFilter = "", $booleanSearch = false, $alternativeFileFilter = "", $invertedMatch = false);

	/**
	 * Determines if this database supports transactions
	 *
	 * @return boolean Flag indicating support for transactions
	 */
	abstract public function supportsTransactions();

	/**
	 * Invoke $callback within a transaction
	 *
	 * @param callable $callback Callback to run
	 * @param callable $errorCallback Optional callback to run after rolling back transaction.
	 * @param bool|string $transactionMode Optional transaction mode to use
	 * @param bool $errorIfTransactionsUnsupported If true, this method will fail if transactions are unsupported.
	 * Otherwise, the $callback will potentially be invoked outside of a transaction.
	 * @throws Exception
	 */
	public function withTransaction(
		$callback, $errorCallback = null, $transactionMode = false, $errorIfTransactionsUnsupported = false
	) {
		$supported = $this->supportsTransactions();
		if(!$supported && $errorIfTransactionsUnsupported) {
			throw new BadMethodCallException("Transactions not supported by this database.");
		}
		if($supported) {
			$this->transactionStart($transactionMode);
		}
		try {
			call_user_func($callback);
		} catch (Exception $ex) {
			if($supported) {
				$this->transactionRollback();
			}
			if($errorCallback) {
				call_user_func($errorCallback);
			}
			throw $ex;
		}
		if($supported) {
			$this->transactionEnd();
		}
	}

	/*
	 * Determines if the current database connection supports a given list of extensions
	 *
	 * @param array $extensions List of extensions to check for support of. The key of this array
	 * will be an extension name, and the value the configuration for that extension. This
	 * could be one of partitions, tablespaces, or clustering
	 * @return boolean Flag indicating support for all of the above
	 * @todo Write test cases
	 */
	public function supportsExtensions($extensions) {
		return false;
	}

	/**
	 * Start a prepared transaction
	 * See http://developer.postgresql.org/pgdocs/postgres/sql-set-transaction.html for details on
	 * transaction isolation options
	 *
	 * @param string|boolean $transactionMode Transaction mode, or false to ignore
	 * @param string|boolean $sessionCharacteristics Session characteristics, or false to ignore
	 */
	abstract public function transactionStart($transactionMode = false, $sessionCharacteristics = false);

	/**
	 * Create a savepoint that you can jump back to if you encounter problems
	 *
	 * @param string $savepoint Name of savepoint
	 */
	abstract public function transactionSavepoint($savepoint);

	/**
	 * Rollback or revert to a savepoint if your queries encounter problems
	 * If you encounter a problem at any point during a transaction, you may
	 * need to rollback that particular query, or return to a savepoint
	 *
	 * @param string|boolean $savepoint Name of savepoint, or leave empty to rollback
	 * to last savepoint
	 */
	abstract public function transactionRollback($savepoint = false);

	/**
	 * Commit everything inside this transaction so far
	 *
	 * @param boolean $chain
	 */
	abstract public function transactionEnd($chain = false);

	/**
	 * Determines if the used database supports application-level locks,
	 * which is different from table- or row-level locking.
	 * See {@link getLock()} for details.
	 *
	 * @return boolean Flag indicating that locking is available
	 */
	public function supportsLocks() {
		return false;
	}

	/**
	 * Returns if the lock is available.
	 * See {@link supportsLocks()} to check if locking is generally supported.
	 *
	 * @param string $name Name of the lock
	 * @return boolean
	 */
	public function canLock($name) {
		return false;
	}

	/**
	 * Sets an application-level lock so that no two processes can run at the same time,
	 * also called a "cooperative advisory lock".
	 *
	 * Return FALSE if acquiring the lock fails; otherwise return TRUE, if lock was acquired successfully.
	 * Lock is automatically released if connection to the database is broken (either normally or abnormally),
	 * making it less prone to deadlocks than session- or file-based locks.
	 * Should be accompanied by a {@link releaseLock()} call after the logic requiring the lock has completed.
	 * Can be called multiple times, in which case locks "stack" (PostgreSQL, SQL Server),
	 * or auto-releases the previous lock (MySQL).
	 *
	 * Note that this might trigger the database to wait for the lock to be released, delaying further execution.
	 *
	 * @param string $name Name of lock
	 * @param integer $timeout Timeout in seconds
	 * @return boolean
	 */
	public function getLock($name, $timeout = 5) {
		return false;
	}

	/**
	 * Remove an application-level lock file to allow another process to run
	 * (if the execution aborts (e.g. due to an error) all locks are automatically released).
	 *
	 * @param string $name Name of the lock
	 * @return boolean Flag indicating whether the lock was successfully released
	 */
	public function releaseLock($name) {
		return false;
	}

	/**
	 * Instruct the database to generate a live connection
	 *
	 * @param array $parameters An map of parameters, which should include:
	 *  - server: The server, eg, localhost
	 *  - username: The username to log on with
	 *  - password: The password to log on with
	 *  - database: The database to connect to
	 *  - charset: The character set to use. Defaults to utf8
	 *  - timezone: (optional) The timezone offset. For example: +12:00, "Pacific/Auckland", or "SYSTEM"
	 *  - driver: (optional) Driver name
	 */
	public function connect($parameters) {
		// Ensure that driver is available (required by PDO)
		if(empty($parameters['driver'])) {
			$parameters['driver'] = $this->getDatabaseServer();
		}

		// Notify connector of parameters
		$this->connector->connect($parameters);

		// SS_Database subclass maintains responsibility for selecting database
		// once connected in order to correctly handle schema queries about
		// existence of database, error handling at the correct level, etc
		if (!empty($parameters['database'])) {
			$this->selectDatabase($parameters['database'], false, false);
		}
	}

	/**
	 * Determine if the database with the specified name exists
	 *
	 * @param string $name Name of the database to check for
	 * @return boolean Flag indicating whether this database exists
	 */
	public function databaseExists($name) {
		return $this->schemaManager->databaseExists($name);
	}

	/**
	 * Retrieves the list of all databases the user has access to
	 *
	 * @return array List of database names
	 */
	public function databaseList() {
		return $this->schemaManager->databaseList();
	}

	/**
	 * Change the connection to the specified database, optionally creating the
	 * database if it doesn't exist in the current schema.
	 *
	 * @param string $name Name of the database
	 * @param boolean $create Flag indicating whether the database should be created
	 * if it doesn't exist. If $create is false and the database doesn't exist
	 * then an error will be raised
	 * @param int|boolean $errorLevel The level of error reporting to enable for the query, or false if no error
	 * should be raised
	 * @return boolean Flag indicating success
	 */
	public function selectDatabase($name, $create = false, $errorLevel = E_USER_ERROR) {
		// In case our live environment is locked down, we can bypass a SHOW DATABASE check
		$canConnect = Config::inst()->get(get_class($this), 'optimistic_connect')
			|| $this->schemaManager->databaseExists($name);
		if($canConnect) {
			return $this->connector->selectDatabase($name);
		}

		// Check DB creation permisson
		if (!$create) {
			if ($errorLevel !== false) {
				user_error("Attempted to connect to non-existing database \"$name\"", $errorLevel);
			}
			// Unselect database
			$this->connector->unloadDatabase();
			return false;
		}
		$this->schemaManager->createDatabase($name);
		return $this->connector->selectDatabase($name);
	}

	/**
	 * Drop the database that this object is currently connected to.
	 * Use with caution.
	 */
	public function dropSelectedDatabase() {
		$databaseName = $this->connector->getSelectedDatabase();
		if ($databaseName) {
			$this->connector->unloadDatabase();
			$this->schemaManager->dropDatabase($databaseName);
		}
	}

	/**
	 * Returns the name of the currently selected database
	 *
	 * @return string|null Name of the selected database, or null if none selected
	 */
	public function getSelectedDatabase() {
		return $this->connector->getSelectedDatabase();
	}

	/**
	 * Return SQL expression used to represent the current date/time
	 *
	 * @return string Expression for the current date/time
	 */
	abstract public function now();

	/**
	 * Returns the database-specific version of the random() function
	 *
	 * @return string Expression for a random value
	 */
	abstract public function random();
}