silverstripe-framework/src/ORM/DB.php

<?php

namespace SilverStripe\ORM;

use BadMethodCallException;
use InvalidArgumentException;
use SilverStripe\Control\Director;
use SilverStripe\Control\HTTPRequest;
use SilverStripe\Core\Config\Config;
use SilverStripe\Core\Convert;
use SilverStripe\Core\Environment;
use SilverStripe\Core\Injector\Injector;
use SilverStripe\Dev\Deprecation;
use SilverStripe\ORM\Connect\Database;
use SilverStripe\ORM\Connect\DBConnector;
use SilverStripe\ORM\Connect\DBSchemaManager;
use SilverStripe\ORM\Connect\Query;
use SilverStripe\ORM\Queries\SQLExpression;

/**
 * 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;

    /**
     * Session key for alternative database name
     */
    const ALT_DB_KEY = 'alternativeDatabaseName';

    /**
     * Allow alternative DB to be disabled.
     * Necessary for DB backed session store to work.
     *
     * @config
     * @var bool
     */
    private static $alternative_database_enabled = true;

    /**
     * The global database connection.
     *
     * @var Database
     */
    protected static $connections = [];

    /**
     * List of configurations for each connection
     *
     * @var array List of configs each in the $databaseConfig format
     */
    protected static $configs = [];



    /**
     * 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.
     *
     * @param Database $connection The connection object to set as the connection.
     * @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.
     */
    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.
     * @return Database
     */
    public static function get_conn($name = 'default')
    {
        if (isset(self::$connections[$name])) {
            return self::$connections[$name];
        }

        // lazy connect
        $config = static::getConfig($name);
        if ($config) {
            return static::connect($config, $name);
        }

        return null;
    }

    /**
     * @deprecated 4.0.1 Use DB::get_conn() instead
     * @todo PSR-2 standardisation will probably un-deprecate this
     */
    public static function getConn($name = 'default')
    {
        Deprecation::notice('4.0.1', '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 = [];
            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.
     *
     * @param string $name
     */
    public static function set_alternative_database_name($name = null)
    {
        // Ignore if disabled
        if (!Config::inst()->get(static::class, 'alternative_database_enabled')) {
            return;
        }
        // Skip if CLI
        if (Director::is_cli()) {
            return;
        }
        // Validate name
        if ($name && !self::valid_alternative_database_name($name)) {
            throw new InvalidArgumentException(sprintf(
                'Invalid alternative database name: "%s"',
                $name
            ));
        }

        // Set against session
        if (!Injector::inst()->has(HTTPRequest::class)) {
            return;
        }
        /** @var HTTPRequest $request */
        $request = Injector::inst()->get(HTTPRequest::class);
        if ($name) {
            $request->getSession()->set(self::ALT_DB_KEY, $name);
        } else {
            $request->getSession()->clear(self::ALT_DB_KEY);
        }
    }

    /**
     * Get the name of the database in use
     *
     * @return string|false Name of temp database, or false if not set
     */
    public static function get_alternative_database_name()
    {
        // Ignore if disabled
        if (!Config::inst()->get(static::class, 'alternative_database_enabled')) {
            return false;
        }
        // Skip if CLI
        if (Director::is_cli()) {
            return false;
        }
        // Skip if there's no request object yet
        if (!Injector::inst()->has(HTTPRequest::class)) {
            return null;
        }
        /** @var HTTPRequest $request */
        $request = Injector::inst()->get(HTTPRequest::class);
        // Skip if the session hasn't been started
        if (!$request->getSession()->isStarted()) {
            return null;
        }

        $name = $request->getSession()->get(self::ALT_DB_KEY);
        if (self::valid_alternative_database_name($name)) {
            return $name;
        }

        return false;
    }

    /**
     * Determines if the name is valid, as a security
     * measure against setting arbitrary databases.
     *
     * @param string $name
     * @return bool
     */
    public static function valid_alternative_database_name($name)
    {
        if (Director::isLive() || empty($name)) {
            return false;
        }

        $prefix = Environment::getEnv('SS_DATABASE_PREFIX') ?: 'ss_';
        $pattern = strtolower(sprintf('/^%stmpdb\d{7}$/', $prefix));
        return (bool)preg_match($pattern ?? '', $name ?? '');
    }

    /**
     * Specify connection to a database
     *
     * Given the database configuration, this method will create the correct
     * subclass of {@link SS_Database}.
     *
     * @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
     * @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'])) {
            throw new InvalidArgumentException("DB::connect: Not passed a valid database config");
        }

        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);
        self::set_conn($conn, $label);
        $conn->connect($databaseConfig);

        return $conn;
    }

    /**
     * Set config for a lazy-connected database
     *
     * @param array $databaseConfig
     * @param string $name
     */
    public static function setConfig($databaseConfig, $name = 'default')
    {
        static::$configs[$name] = $databaseConfig;
    }

    /**
     * Get the named connection config
     *
     * @param string $name
     * @return mixed
     */
    public static function getConfig($name = 'default')
    {
        if (isset(static::$configs[$name])) {
            return static::$configs[$name];
        }
    }

    /**
     * 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
     * @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
     * @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 ?? 0, '?'));
    }

    /**
     * @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::get_conn() !== null) ? 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
     * @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.
     *
     * @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.
     * @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.
     *
     * @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 suppression of database messages.
     *
     * @param bool $quiet
     */
    public static function quiet($quiet = true)
    {
        self::get_schema()->quiet($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);
    }
}