silverstripe-framework/ORM/DB.php

601 lines
19 KiB
PHP
Raw Normal View History

<?php
namespace SilverStripe\ORM;
use SilverStripe\Core\Config\Config;
use SilverStripe\Core\Injector\Injector;
use SilverStripe\Control\Director;
use SilverStripe\Control\Cookie;
use SilverStripe\Dev\Deprecation;
2016-06-23 01:37:22 +02:00
use SilverStripe\ORM\Connect\DBConnector;
use SilverStripe\ORM\Connect\DBSchemaManager;
2016-09-09 08:43:05 +02:00
use SilverStripe\ORM\Connect\Query;
use SilverStripe\ORM\Queries\SQLExpression;
2016-09-09 08:43:05 +02:00
use SilverStripe\ORM\Connect\Database;
use InvalidArgumentException;
use LogicException;
/**
* Global database interface, complete with static methods.
* Use this class for interacting with the database.
*/
class DB {
/**
* This constant was added in SilverStripe 2.4 to indicate that SQL-queries
* should now use ANSI-compatible syntax. The most notable affect of this
* change is that table and field names should be escaped with double quotes
* and not backticks
*/
const USE_ANSI_SQL = true;
/**
* The global database connection.
2016-09-09 08:43:05 +02:00
* @var Database
*/
private static $connections = array();
/**
* The last SQL query run.
* @var string
*/
public static $lastQuery;
/**
* Internal flag to keep track of when db connection was attempted.
*/
private static $connection_attempted = false;
/**
* Set the global database connection.
* Pass an object that's a subclass of SS_Database. This object will be used when {@link DB::query()}
* is called.
*
2016-09-09 08:43:05 +02:00
* @param Database $connection The connecton object to set as the connection.
2016-06-23 01:37:22 +02:00
* @param string $name The name to give to this connection. If you omit this argument, the connection
* will be the default one used by the ORM. However, you can store other named connections to
* be accessed through DB::get_conn($name). This is useful when you have an application that
* needs to connect to more than one database.
*/
2016-09-09 08:43:05 +02:00
public static function set_conn(Database $connection, $name = 'default') {
self::$connections[$name] = $connection;
}
/**
* Get the global database connection.
*
* @param string $name An optional name given to a connection in the DB::setConn() call. If omitted,
* the default connection is returned.
2016-09-09 08:43:05 +02:00
* @return Database
*/
public static function get_conn($name = 'default') {
if(isset(self::$connections[$name])) {
return self::$connections[$name];
}
return null;
}
/**
* @deprecated since version 4.0 Use DB::get_conn instead
* @todo PSR-2 standardisation will probably un-deprecate this
*/
public static function getConn($name = 'default') {
Deprecation::notice('4.0', 'Use DB::get_conn instead');
return self::get_conn($name);
}
/**
* Retrieves the schema manager for the current database
*
* @param string $name An optional name given to a connection in the DB::setConn() call. If omitted,
* the default connection is returned.
* @return DBSchemaManager
*/
public static function get_schema($name = 'default') {
$connection = self::get_conn($name);
if($connection) {
return $connection->getSchemaManager();
}
return null;
}
/**
* Builds a sql query with the specified connection
*
* @param SQLExpression $expression The expression object to build from
* @param array $parameters Out parameter for the resulting query parameters
* @param string $name An optional name given to a connection in the DB::setConn() call. If omitted,
* the default connection is returned.
* @return string The resulting SQL as a string
*/
public static function build_sql(SQLExpression $expression, &$parameters, $name = 'default') {
$connection = self::get_conn($name);
if($connection) {
return $connection->getQueryBuilder()->buildSQL($expression, $parameters);
} else {
$parameters = array();
return null;
}
}
/**
* Retrieves the connector object for the current database
*
* @param string $name An optional name given to a connection in the DB::setConn() call. If omitted,
* the default connection is returned.
* @return DBConnector
*/
public static function get_connector($name = 'default') {
$connection = self::get_conn($name);
if($connection) {
return $connection->getConnector();
}
return null;
}
/**
* Set an alternative database in a browser cookie,
* with the cookie lifetime set to the browser session.
* This is useful for integration testing on temporary databases.
*
* There is a strict naming convention for temporary databases to avoid abuse:
* <prefix> (default: 'ss_') + tmpdb + <7 digits>
* As an additional security measure, temporary databases will
* be ignored in "live" mode.
*
* Note that the database will be set on the next request.
* Set it to null to revert to the main database.
2016-06-23 01:37:22 +02:00
* @param string $name
*/
public static function set_alternative_database_name($name = null) {
// Skip if CLI
if(Director::is_cli()) {
return;
}
if($name) {
if(!self::valid_alternative_database_name($name)) {
throw new InvalidArgumentException(sprintf(
'Invalid alternative database name: "%s"',
$name
));
}
2016-06-23 01:37:22 +02:00
$key = Config::inst()->get('SilverStripe\\Security\\Security', 'token');
if(!$key) {
throw new LogicException('"Security.token" not found, run "sake dev/generatesecuretoken"');
}
if(!function_exists('mcrypt_encrypt')) {
throw new LogicException('DB::set_alternative_database_name() requires the mcrypt PHP extension');
}
$key = md5($key); // Ensure key is correct length for chosen cypher
$ivSize = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_256, MCRYPT_MODE_CFB);
2013-01-24 07:56:02 +01:00
$iv = mcrypt_create_iv($ivSize);
$encrypted = mcrypt_encrypt(
MCRYPT_RIJNDAEL_256, $key, $name, MCRYPT_MODE_CFB, $iv
);
// Set to browser session lifetime, and restricted to HTTP access only
Cookie::set("alternativeDatabaseName", base64_encode($encrypted), 0, null, null, false, true);
Cookie::set("alternativeDatabaseNameIv", base64_encode($iv), 0, null, null, false, true);
} else {
NEW Cookie_Backend for managing cookie state I've decoupled `Cookie` from the actual act of setting and getting cookies. Currently there are a few limitations to how Cookie works that this change mitigates: 0. `Cookie` currently changes the super global `$_COOKIE` when setting to make the state of an application a bit more managable, but this is bad because we shouldn't be modifying super globals 0. One can't actually change the `$cookie_class` once the `Cookie::$inst` has been instantiated 0. One can't test cookies as there is no class that holds the state of the cookies (it's just held in the super global which is reset as part of `Director::test()` 0. One can't tell the origin of a cookie (eg: did the application set it and it needs to be sent, or did we receive it from the browser?) 0. `time()` was used, so testing was made difficult 0. There was no way to get all the cookies at once (without accessing the super global) Todos are on the phpdoc and I'd like to write some tests for the backend as well as update the docs (if there are any) around cookies. DOCS Adding `Cookie` docs Explains basic usage of `Cookie` as well as how the `Cookie_Backend` controls the setting and getting of cookies and manages state of sent vs received cookies Fixing `Cookie` usage `Cookie` is being used inconsistently with the API throughout framework. Either by not using `force_expiry` to expire cookies or setting them to null and then expiring them (which is redundant). NEW `Director::test()` takes `Cookie_Backend` rather than `array` for `$cookies` param
2014-05-04 15:34:58 +02:00
Cookie::force_expiry("alternativeDatabaseName", null, null, false, true);
Cookie::force_expiry("alternativeDatabaseNameIv", null, null, false, true);
}
}
/**
* Get the name of the database in use
*/
public static function get_alternative_database_name() {
$name = Cookie::get("alternativeDatabaseName");
$iv = Cookie::get("alternativeDatabaseNameIv");
if($name) {
2016-06-23 01:37:22 +02:00
$key = Config::inst()->get('SilverStripe\\Security\\Security', 'token');
if(!$key) {
throw new LogicException('"Security.token" not found, run "sake dev/generatesecuretoken"');
}
if(!function_exists('mcrypt_encrypt')) {
throw new LogicException('DB::set_alternative_database_name() requires the mcrypt PHP extension');
}
$key = md5($key); // Ensure key is correct length for chosen cypher
$decrypted = mcrypt_decrypt(
MCRYPT_RIJNDAEL_256, $key, base64_decode($name), MCRYPT_MODE_CFB, base64_decode($iv)
);
return (self::valid_alternative_database_name($decrypted)) ? $decrypted : false;
} else {
return false;
}
}
/**
* Determines if the name is valid, as a security
* measure against setting arbitrary databases.
*
* @param String $name
* @return Boolean
*/
public static function valid_alternative_database_name($name) {
if(Director::isLive()) return false;
$prefix = defined('SS_DATABASE_PREFIX') ? SS_DATABASE_PREFIX : 'ss_';
$pattern = strtolower(sprintf('/^%stmpdb\d{7}$/', $prefix));
return (bool)preg_match($pattern, $name);
}
/**
* Connect to a database.
*
* Given the database configuration, this method will create the correct
* subclass of {@link SS_Database}.
*
2016-06-23 01:37:22 +02:00
* @param array $databaseConfig A map of options. The 'type' is the name of the
* subclass of SS_Database to use. For the rest of the options, see the specific class.
* @param string $label identifier for the connection
2016-09-09 08:43:05 +02:00
* @return Database
*/
public static function connect($databaseConfig, $label = 'default') {
// This is used by the "testsession" module to test up a test session using an alternative name
if($name = self::get_alternative_database_name()) {
$databaseConfig['database'] = $name;
}
if(!isset($databaseConfig['type']) || empty($databaseConfig['type'])) {
user_error("DB::connect: Not passed a valid database config", E_USER_ERROR);
}
self::$connection_attempted = true;
$dbClass = $databaseConfig['type'];
// Using Injector->create allows us to use registered configurations
// which may or may not map to explicit objects
$conn = Injector::inst()->create($dbClass);
$conn->connect($databaseConfig);
self::set_conn($conn, $label);
return $conn;
}
/**
* Returns true if a database connection has been attempted.
* In particular, it lets the caller know if we're still so early in the execution pipeline that
* we haven't even tried to connect to the database yet.
*/
public static function connection_attempted() {
return self::$connection_attempted;
}
/**
* 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
2016-09-09 08:43:05 +02:00
* @return Query
*/
public static function query($sql, $errorLevel = E_USER_ERROR) {
self::$lastQuery = $sql;
return self::get_conn()->query($sql, $errorLevel);
}
/**
* Helper function for generating a list of parameter placeholders for the
* given argument(s)
*
* @param array|integer $input An array of items needing placeholders, or a
* number to specify the number of placeholders
2016-06-23 01:37:22 +02:00
* @param string $join The string to join each placeholder together with
* @return string|null Either a list of placeholders, or null
*/
public static function placeholders($input, $join = ', ') {
if(is_array($input)) {
$number = count($input);
} elseif(is_numeric($input)) {
$number = intval($input);
} else {
return null;
}
if($number === 0) return null;
return implode($join, array_fill(0, $number, '?'));
}
/**
* @param string $sql The parameterised query
* @param array $parameters The parameters to inject into the query
*
* @return string
*/
public static function inline_parameters($sql, $parameters) {
$segments = preg_split('/\?/', $sql);
$joined = '';
$inString = false;
$numSegments = count($segments);
for($i = 0; $i < $numSegments; $i++) {
$input = $segments[$i];
// Append next segment
$joined .= $segments[$i];
// Don't add placeholder after last segment
if($i === $numSegments - 1) {
break;
}
// check string escape on previous fragment
// Remove escaped backslashes, count them!
$input = preg_replace('/\\\\\\\\/', '', $input);
// Count quotes
$totalQuotes = substr_count($input, "'"); // Includes double quote escaped quotes
$escapedQuotes = substr_count($input, "\\'");
if((($totalQuotes - $escapedQuotes) % 2) !== 0) {
$inString = !$inString;
}
// Append placeholder replacement
if($inString) {
// Literal question mark
$joined .= '?';
continue;
}
// Encode and insert next parameter
$next = array_shift($parameters);
if(is_array($next) && isset($next['value'])) {
$next = $next['value'];
}
if (is_bool($next)) {
$value = $next ? '1' : '0';
}
elseif (is_int($next)) {
$value = $next;
}
else {
$value = DB::is_active() ? Convert::raw2sql($next, true) : $next;
}
$joined .= $value;
}
return $joined;
}
/**
* 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
2016-09-09 08:43:05 +02:00
* @return Query
*/
public static function prepared_query($sql, $parameters, $errorLevel = E_USER_ERROR) {
self::$lastQuery = $sql;
return self::get_conn()->preparedQuery($sql, $parameters, $errorLevel);
}
/**
* 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, including quotes. The field value can
* also be a SQL function or similar.
*
* Example:
* <code>
* array(
* // Command: insert
* "table name" => array(
* "command" => "insert",
* "fields" => array(
* "ClassName" => "'MyClass'", // if you're setting a literal, you need to escape and provide quotes
* "Created" => "now()", // alternatively, you can call DB functions
* "ID" => 234,
* ),
* "id" => 234 // an alternative to providing ID in the fields list
* ),
*
* // Command: update
* "other table" => array(
* "command" => "update",
* "fields" => array(
* "ClassName" => "'MyClass'",
* "LastEdited" => "now()",
* ),
* "where" => "ID = 234",
* "id" => 234 // an alternative to providing a where clause
* ),
* )
* </code>
*
* You'll note that only one command on a given table can be called.
* That's a limitation of the system that's due to it being written for {@link DataObject::write()},
* which needs to do a single write on a number of different tables.
*
* @todo Update this to support paramaterised queries
*
* @param array $manipulation
*/
public static function manipulate($manipulation) {
self::$lastQuery = $manipulation;
self::get_conn()->manipulate($manipulation);
}
/**
* Get the autogenerated ID from the previous INSERT query.
2016-06-23 01:37:22 +02:00
*
* @param string $table
* @return int
*/
public static function get_generated_id($table) {
return self::get_conn()->getGeneratedID($table);
}
/**
* Check if the connection to the database is active.
*
* @return boolean
*/
public static function is_active() {
return ($conn = self::get_conn()) && $conn->isActive();
}
/**
* Create the database and connect to it. This can be called if the
* initial database connection is not successful because the database
* does not exist.
*
* @param string $database Name of database to create
* @return boolean Returns true if successful
*/
public static function create_database($database) {
return self::get_conn()->selectDatabase($database, true);
}
/**
* Create a new table.
2016-06-23 01:37:22 +02:00
* @param string $table The name of the table
* @param array$fields A map of field names to field types
* @param array $indexes A map of indexes
* @param array $options An map of additional options. The available keys are as follows:
* - 'MSSQLDatabase'/'MySQLDatabase'/'PostgreSQLDatabase' - database-specific options such as "engine"
* for MySQL.
* - 'temporary' - If true, then a temporary table will be created
* @param array $advancedOptions Advanced creation options
* @return string The table name generated. This may be different from the table name, for example with
* temporary tables.
*/
public static function create_table($table, $fields = null, $indexes = null, $options = null,
$advancedOptions = null
) {
return self::get_schema()->createTable($table, $fields, $indexes, $options, $advancedOptions);
}
/**
* Create a new field on a table.
* @param string $table Name of the table.
* @param string $field Name of the field to add.
* @param string $spec The field specification, eg 'INTEGER NOT NULL'
*/
public static function create_field($table, $field, $spec) {
return self::get_schema()->createField($table, $field, $spec);
}
/**
* Generate the following table in the database, modifying whatever already exists
* as necessary.
*
* @param string $table The name of the table
* @param string $fieldSchema A list of the fields to create, in the same form as DataObject::$db
* @param string $indexSchema A list of indexes to create. The keys of the array are the names of the index.
* The values of the array can be one of:
* - true: Create a single column index on the field named the same as the index.
* - array('fields' => array('A','B','C'), 'type' => 'index/unique/fulltext'): This gives you full
* control over the index.
* @param boolean $hasAutoIncPK A flag indicating that the primary key on this table is an autoincrement type
* @param string $options SQL statement to append to the CREATE TABLE call.
* @param array $extensions List of extensions
*/
public static function require_table($table, $fieldSchema = null, $indexSchema = null, $hasAutoIncPK = true,
$options = null, $extensions = null
) {
self::get_schema()->requireTable($table, $fieldSchema, $indexSchema, $hasAutoIncPK, $options, $extensions);
}
/**
* Generate the given field on the table, modifying whatever already exists as necessary.
*
* @param string $table The table name.
* @param string $field The field name.
* @param string $spec The field specification.
*/
public static function require_field($table, $field, $spec) {
self::get_schema()->requireField($table, $field, $spec);
}
/**
* Generate the given index in the database, modifying whatever already exists as necessary.
*
* @param string $table The table name.
* @param string $index The index name.
* @param string|boolean $spec The specification of the index. See requireTable() for more information.
*/
public static function require_index($table, $index, $spec) {
self::get_schema()->requireIndex($table, $index, $spec);
}
/**
* If the given table exists, move it out of the way by renaming it to _obsolete_(tablename).
*
* @param string $table The table name.
*/
public static function dont_require_table($table) {
self::get_schema()->dontRequireTable($table);
}
/**
* See {@link SS_Database->dontRequireField()}.
*
* @param string $table The table name.
* @param string $fieldName The field name not to require
*/
public static function dont_require_field($table, $fieldName) {
self::get_schema()->dontRequireField($table, $fieldName);
}
/**
* Checks a table's integrity and repairs it if necessary.
*
2016-06-23 01:37:22 +02:00
* @param string $table The name of the table.
* @return boolean Return true if the table has integrity after the method is complete.
*/
public static function check_and_repair_table($table) {
return self::get_schema()->checkAndRepairTable($table);
}
/**
* Return the number of rows affected by the previous operation.
*
* @return integer The number of affected rows
*/
public static function affected_rows() {
return self::get_conn()->affectedRows();
}
/**
* Returns a list of all tables in the database.
* The table names will be in lower case.
*
* @return array The list of tables
*/
public static function table_list() {
return self::get_schema()->tableList();
}
/**
* Get a list of all the fields for the given table.
* Returns a map of field name => field spec.
*
* @param string $table The table name.
* @return array The list of fields
*/
public static function field_list($table) {
return self::get_schema()->fieldList($table);
}
/**
* Enable supression of database messages.
*/
public static function quiet() {
self::get_schema()->quiet();
}
/**
* Show a message about database alteration
*
* @param string $message to display
* @param string $type one of [created|changed|repaired|obsolete|deleted|error]
*/
public static function alteration_message($message, $type = "") {
self::get_schema()->alterationMessage($message, $type);
}
}