<?php
/**
* Part of the Joomla Framework Database Package
*
* @copyright Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE
*/
namespace Joomla\Database;
use Joomla\Database\Event\ConnectionEvent;
use Joomla\Database\Exception\ConnectionFailureException;
use Joomla\Database\Exception\ExecutionFailureException;
use Joomla\Database\Exception\PrepareStatementFailureException;
use Joomla\Event\DispatcherAwareInterface;
use Joomla\Event\DispatcherAwareTrait;
use Joomla\Event\EventInterface;
/**
* Joomla Framework Database Driver Class
*
* @since 1.0
*/
abstract class DatabaseDriver implements DatabaseInterface, DispatcherAwareInterface
{
use DispatcherAwareTrait;
/**
* The name of the database.
*
* @var string
* @since 1.0
*/
private $database;
/**
* The name of the database driver.
*
* @var string
* @since 1.0
*/
protected $name;
/**
* The type of the database server family supported by this driver.
*
* @var string
* @since 1.4.0
*/
public $serverType;
/**
* The database connection resource.
*
* @var resource
* @since 1.0
*/
protected $connection;
/**
* Holds the list of available db connectors.
*
* @var array
* @since 1.0
*/
protected static $connectors = [];
/**
* The number of SQL statements executed by the database driver.
*
* @var integer
* @since 1.0
*/
protected $count = 0;
/**
* The database connection cursor from the last query.
*
* @var resource
* @since 1.0
*/
protected $cursor;
/**
* Contains the current query execution status
*
* @var boolean
* @since 2.0.0
*/
protected $executed = false;
/**
* The affected row limit for the current SQL statement.
*
* @var integer
* @since 1.0
*/
protected $limit = 0;
/**
* The character(s) used to quote SQL statement names such as table names or field names, etc.
*
* If a single character string the same character is used for both sides of the quoted name, else the first character will be used for the
* opening quote and the second for the closing quote.
*
* @var string
* @since 1.0
*/
protected $nameQuote;
/**
* The null or zero representation of a timestamp for the database driver.
*
* @var string
* @since 1.0
*/
protected $nullDate;
/**
* The affected row offset to apply for the current SQL statement.
*
* @var integer
* @since 1.0
*/
protected $offset = 0;
/**
* Passed in upon instantiation and saved.
*
* @var array
* @since 1.0
*/
protected $options;
/**
* The current SQL statement to execute.
*
* @var mixed
* @since 1.0
*/
protected $sql;
/**
* The prepared statement.
*
* @var StatementInterface
* @since 2.0.0
*/
protected $statement;
/**
* The common database table prefix.
*
* @var string
* @since 1.0
*/
protected $tablePrefix;
/**
* True if the database engine supports UTF-8 character encoding.
*
* @var boolean
* @since 1.0
*/
protected $utf = true;
/**
* The database error number.
*
* @var integer
* @since 1.0
*/
protected $errorNum = 0;
/**
* The database error message.
*
* @var string
* @since 1.0
*/
protected $errorMsg;
/**
* DatabaseDriver instances container.
*
* @var DatabaseDriver[]
* @since 1.0
* @deprecated 3.0 Singleton storage will no longer be supported.
*/
protected static $instances = [];
/**
* The minimum supported database version.
*
* @var string
* @since 1.0
*/
protected static $dbMinimum;
/**
* The depth of the current transaction.
*
* @var integer
* @since 1.0
*/
protected $transactionDepth = 0;
/**
* DatabaseFactory object
*
* @var DatabaseFactory
* @since 2.0.0
*/
protected $factory;
/**
* Query monitor object
*
* @var QueryMonitorInterface
* @since 2.0.0
*/
protected $monitor;
/**
* Get a list of available database connectors.
*
* The list will only be populated with connectors that the class exists for and the environment supports its use.
* This gives us the ability to have a multitude of connector classes that are self-aware as to whether or not they
* are able to be used on a given system.
*
* @return array An array of available database connectors.
*
* @since 1.0
*/
public static function getConnectors()
{
if (empty(self::$connectors)) {
// Get an iterator and loop trough the driver classes.
$dir = __DIR__;
$iterator = new \DirectoryIterator($dir);
/** @var \DirectoryIterator $file */
foreach ($iterator as $file) {
// Only load for php files.
if (!$file->isDir()) {
continue;
}
$baseName = $file->getBasename();
// Derive the class name from the type.
/** @var DatabaseDriver $class */
$class = __NAMESPACE__ . '\\' . ucfirst(strtolower($baseName)) . '\\' . ucfirst(strtolower($baseName)) . 'Driver';
// If the class doesn't exist, or if it's not supported on this system, move on to the next type.
if (!class_exists($class) || !$class::isSupported()) {
continue;
}
// Everything looks good, add it to the list.
self::$connectors[] = $baseName;
}
}
return self::$connectors;
}
/**
* Method to return a DatabaseDriver instance based on the given options.
*
* There are three global options and then the rest are specific to the database driver.
*
* - The 'driver' option defines which DatabaseDriver class is used for the connection -- the default is 'mysqli'.
* - The 'database' option determines which database is to be used for the connection.
* - The 'select' option determines whether the connector should automatically select the chosen database.
*
* Instances are unique to the given options and new objects are only created when a unique options array is
* passed into the method. This ensures that we don't end up with unnecessary database connection resources.
*
* @param array $options Parameters to be passed to the database driver.
*
* @return DatabaseDriver
*
* @since 1.0
* @throws \RuntimeException
* @deprecated 3.0 Use DatabaseFactory::getDriver() instead
*/
public static function getInstance(array $options = [])
{
trigger_deprecation(
'joomla/database',
'2.0.0',
'%s() is deprecated and will be removed in 3.0, use %s::getDriver() instead.',
__METHOD__,
DatabaseFactory::class
);
// Sanitize the database connector options.
$options['driver'] = isset($options['driver']) ? preg_replace('/[^A-Z0-9_\.-]/i', '', $options['driver']) : 'mysqli';
$options['database'] = $options['database'] ?? null;
$options['select'] = $options['select'] ?? true;
$options['factory'] = $options['factory'] ?? new DatabaseFactory();
$options['monitor'] = $options['monitor'] ?? null;
// Get the options signature for the database connector.
$signature = md5(serialize($options));
// If we already have a database connector instance for these options then just use that.
if (empty(self::$instances[$signature])) {
// Set the new connector to the global instances based on signature.
self::$instances[$signature] = $options['factory']->getDriver($options['driver'], $options);
}
return self::$instances[$signature];
}
/**
* Splits a string of multiple queries into an array of individual queries.
*
* @param string $sql Input SQL string with which to split into individual queries.
*
* @return array
*
* @since 1.0
*/
public static function splitSql($sql)
{
$start = 0;
$open = false;
$comment = false;
$endString = '';
$end = \strlen($sql);
$queries = [];
$query = '';
for ($i = 0; $i < $end; $i++) {
$current = substr($sql, $i, 1);
$current2 = substr($sql, $i, 2);
$current3 = substr($sql, $i, 3);
$lenEndString = \strlen($endString);
$testEnd = substr($sql, $i, $lenEndString);
if (
$current === '"' || $current === "'" || $current2 === '--'
|| ($current2 === '/*' && $current3 !== '/*!' && $current3 !== '/*+')
|| ($current === '#' && $current3 !== '#__')
|| ($comment && $testEnd === $endString)
) {
// Check if quoted with previous backslash
$n = 2;
while (substr($sql, $i - $n + 1, 1) === '\\' && $n < $i) {
$n++;
}
// Not quoted
if ($n % 2 === 0) {
if ($open) {
if ($testEnd === $endString) {
if ($comment) {
$comment = false;
if ($lenEndString > 1) {
$i += ($lenEndString - 1);
$current = substr($sql, $i, 1);
}
$start = $i + 1;
}
$open = false;
$endString = '';
}
} else {
$open = true;
if ($current2 === '--') {
$endString = "\n";
$comment = true;
} elseif ($current2 === '/*') {
$endString = '*/';
$comment = true;
} elseif ($current === '#') {
$endString = "\n";
$comment = true;
} else {
$endString = $current;
}
if ($comment && $start < $i) {
$query .= substr($sql, $start, $i - $start);
}
}
}
}
if ($comment) {
$start = $i + 1;
}
if (($current === ';' && !$open) || $i === $end - 1) {
if ($start <= $i) {
$query .= substr($sql, $start, $i - $start + 1);
}
$query = trim($query);
if ($query) {
if (($i === $end - 1) && ($current !== ';')) {
$query .= ';';
}
$queries[] = $query;
}
$query = '';
$start = $i + 1;
}
$endComment = false;
}
return $queries;
}
/**
* Magic method to access properties of the database driver.
*
* @param string $name The name of the property.
*
* @return mixed A value if the property name is valid, null otherwise.
*
* @since 1.4.0
* @deprecated 3.0 This is a B/C proxy since $this->name was previously public
*/
public function __get($name)
{
switch ($name) {
case 'name':
trigger_deprecation(
'joomla/database',
'1.4.0',
'Accessing the name property of %s is deprecated, use the getName() method instead.',
self::class
);
return $this->getName();
default:
$trace = debug_backtrace();
trigger_error(
sprintf(
'Undefined property via __get(): %1$s in %2$s on line %3$s',
$name,
$trace[0]['file'],
$trace[0]['line']
),
\E_USER_NOTICE
);
}
}
/**
* Constructor.
*
* @param array $options List of options used to configure the connection
*
* @since 1.0
*/
public function __construct(array $options)
{
// Initialise object variables.
$this->database = $options['database'] ?? '';
$this->tablePrefix = $options['prefix'] ?? '';
$this->count = 0;
$this->errorNum = 0;
// Set class options.
$this->options = $options;
// Register the DatabaseFactory
$this->factory = $options['factory'] ?? new DatabaseFactory();
// Register the query monitor if available
$this->monitor = $options['monitor'] ?? null;
}
/**
* Destructor.
*
* @since 2.0.0
*/
public function __destruct()
{
$this->disconnect();
}
/**
* Alter database's character set.
*
* @param string $dbName The database name that will be altered
*
* @return boolean|resource
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function alterDbCharacterSet($dbName)
{
if ($dbName === null) {
throw new \RuntimeException('Database name must not be null.');
}
$this->setQuery($this->getAlterDbCharacterSet($dbName));
return $this->execute();
}
/**
* Create a new database using information from $options object.
*
* @param \stdClass $options Object used to pass user and database name to database driver. This object must have "db_name" and "db_user" set.
* @param boolean $utf True if the database supports the UTF-8 character set.
*
* @return boolean|resource
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function createDatabase($options, $utf = true)
{
if ($options === null) {
throw new \RuntimeException('$options object must not be null.');
}
if (empty($options->db_name)) {
throw new \RuntimeException('$options object must have db_name set.');
}
if (empty($options->db_user)) {
throw new \RuntimeException('$options object must have db_user set.');
}
$this->setQuery($this->getCreateDatabaseQuery($options, $utf));
return $this->execute();
}
/**
* Create a new DatabaseQuery object.
*
* @return QueryInterface
*
* @since 2.2
*/
public function createQuery(): QueryInterface
{
return $this->factory->getQuery($this->name, $this);
}
/**
* Disconnects the database.
*
* @return void
*
* @since 2.0.0
*/
public function disconnect()
{
$this->freeResult();
$this->connection = null;
$this->dispatchEvent(new ConnectionEvent(DatabaseEvents::POST_DISCONNECT, $this));
}
/**
* Dispatch an event.
*
* @param EventInterface $event The event to dispatch
*
* @return void
*
* @since 2.0.0
*/
protected function dispatchEvent(EventInterface $event)
{
try {
$this->getDispatcher()->dispatch($event->getName(), $event);
} catch (\UnexpectedValueException $exception) {
// Don't error if a dispatcher hasn't been set
}
}
/**
* Drops a table from the database.
*
* @param string $table The name of the database table to drop.
* @param boolean $ifExists Optionally specify that the table must exist before it is dropped.
*
* @return $this
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function dropTable($table, $ifExists = true)
{
$this->connect();
$this->setQuery('DROP TABLE ' . ($ifExists ? 'IF EXISTS ' : '') . $this->quoteName($table))
->execute();
return $this;
}
/**
* Execute the SQL statement.
*
* @return boolean
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function execute()
{
$this->connect();
// Increment the query counter.
$this->count++;
// Get list of bound parameters
$bounded =& $this->sql->getBounded();
// If there is a monitor registered, let it know we are starting this query
if ($this->monitor) {
// Take a local copy so that we don't modify the original query and cause issues later
$sql = $this->replacePrefix((string) $this->sql);
$this->monitor->startQuery($sql, $bounded);
}
// Execute the query.
$this->executed = false;
// Bind the variables
foreach ($bounded as $key => $obj) {
$this->statement->bindParam($key, $obj->value, $obj->dataType);
}
try {
$this->executed = $this->statement->execute();
// If there is a monitor registered, let it know we have finished this query
if ($this->monitor) {
$this->monitor->stopQuery();
}
return true;
} catch (ExecutionFailureException $exception) {
// If there is a monitor registered, let it know we have finished this query
if ($this->monitor) {
$this->monitor->stopQuery();
}
// Check if the server was disconnected.
if (!$this->connected()) {
try {
// Attempt to reconnect.
$this->connection = null;
$this->connect();
} catch (ConnectionFailureException $e) {
// If connect fails, ignore that exception and throw the normal exception.
throw $exception;
}
// Since we were able to reconnect, run the query again.
return $this->execute();
}
// Throw the normal query exception.
throw $exception;
}
}
/**
* Method to fetch a row from the result set cursor as an array.
*
* @return mixed Either the next row from the result set or false if there are no more rows.
*
* @since 1.0
*/
protected function fetchArray()
{
if ($this->statement) {
return $this->statement->fetch(FetchMode::NUMERIC);
}
}
/**
* Method to fetch a row from the result set cursor as an associative array.
*
* @return mixed Either the next row from the result set or false if there are no more rows.
*
* @since 1.0
*/
protected function fetchAssoc()
{
if ($this->statement) {
return $this->statement->fetch(FetchMode::ASSOCIATIVE);
}
}
/**
* Method to fetch a row from the result set cursor as an object.
*
* Note, the fetch mode should be configured before calling this method using `StatementInterface::setFetchMode()`.
*
* @return mixed Either the next row from the result set or false if there are no more rows.
*
* @since 1.0
*/
protected function fetchObject()
{
if ($this->statement) {
return $this->statement->fetch();
}
}
/**
* Method to free up the memory used for the result set.
*
* @return void
*
* @since 1.0
*/
protected function freeResult()
{
$this->executed = false;
if ($this->statement) {
$this->statement->closeCursor();
}
}
/**
* Get the number of affected rows for the previous executed SQL statement.
*
* @return integer The number of affected rows in the previous operation
*
* @since 2.0.0
*/
public function getAffectedRows()
{
$this->connect();
if ($this->statement) {
return $this->statement->rowCount();
}
return 0;
}
/**
* Method that provides access to the underlying database connection.
*
* @return resource The underlying database connection resource.
*
* @since 1.0
*/
public function getConnection()
{
return $this->connection;
}
/**
* Get the total number of SQL statements executed by the database driver.
*
* @return integer
*
* @since 1.0
*/
public function getCount()
{
return $this->count;
}
/**
* Return the query string to alter the database character set.
*
* @param string $dbName The database name
*
* @return string The query that alter the database query string
*
* @since 1.6.0
*/
protected function getAlterDbCharacterSet($dbName)
{
return 'ALTER DATABASE ' . $this->quoteName($dbName) . ' CHARACTER SET ' . $this->quote('UTF8');
}
/**
* Return the query string to create new Database.
*
* @param \stdClass $options Object used to pass user and database name to database driver. This object must have "db_name" and "db_user" set.
* @param boolean $utf True if the database supports the UTF-8 character set.
*
* @return string The query that creates database
*
* @since 2.0.0
*/
protected function getCreateDatabaseQuery($options, $utf)
{
return 'CREATE DATABASE ' . $this->quoteName($options->db_name);
}
/**
* Gets the name of the database used by this connection.
*
* @return string
*
* @since 1.0
*/
protected function getDatabase()
{
return $this->database;
}
/**
* Returns a PHP date() function compliant date format for the database driver.
*
* @return string
*
* @since 1.0
*/
public function getDateFormat()
{
return 'Y-m-d H:i:s';
}
/**
* Get the minimum supported database version.
*
* @return string
*
* @since 1.0
*/
public function getMinimum()
{
return static::$dbMinimum;
}
/**
* Get the name of the database driver.
*
* If $this->name is not set it will try guessing the driver name from the class name.
*
* @return string
*
* @since 1.4.0
*/
public function getName()
{
if (empty($this->name)) {
$reflect = new \ReflectionClass($this);
$this->name = strtolower(str_replace('Driver', '', $reflect->getShortName()));
}
return $this->name;
}
/**
* Get the number of returned rows for the previous executed SQL statement.
*
* @return integer The number of returned rows.
*
* @since 2.0.0
*/
public function getNumRows()
{
$this->connect();
if ($this->statement) {
return $this->statement->rowCount();
}
return 0;
}
/**
* Get the server family type.
*
* If $this->serverType is not set it will attempt guessing the server family type from the driver name. If this is not possible the driver
* name will be returned instead.
*
* @return string
*
* @since 1.4.0
*/
public function getServerType()
{
if (empty($this->serverType)) {
$name = $this->getName();
if (stristr($name, 'mysql') !== false) {
$this->serverType = 'mysql';
} elseif (stristr($name, 'postgre') !== false) {
$this->serverType = 'postgresql';
} elseif (stristr($name, 'pgsql') !== false) {
$this->serverType = 'postgresql';
} elseif (stristr($name, 'oracle') !== false) {
$this->serverType = 'oracle';
} elseif (stristr($name, 'sqlite') !== false) {
$this->serverType = 'sqlite';
} elseif (stristr($name, 'sqlsrv') !== false) {
$this->serverType = 'mssql';
} elseif (stristr($name, 'sqlazure') !== false) {
$this->serverType = 'mssql';
} elseif (stristr($name, 'mssql') !== false) {
$this->serverType = 'mssql';
} else {
$this->serverType = $name;
}
}
return $this->serverType;
}
/**
* Get the null or zero representation of a timestamp for the database driver.
*
* @return string
*
* @since 1.0
*/
public function getNullDate()
{
return $this->nullDate;
}
/**
* Get the common table prefix for the database driver.
*
* @return string The common database table prefix.
*
* @since 1.0
*/
public function getPrefix()
{
return $this->tablePrefix;
}
/**
* Gets an exporter class object.
*
* @return DatabaseExporter An exporter object.
*
* @since 1.0
* @throws \RuntimeException
*/
public function getExporter()
{
return $this->factory->getExporter($this->name, $this);
}
/**
* Gets an importer class object.
*
* @return DatabaseImporter
*
* @since 1.0
*/
public function getImporter()
{
return $this->factory->getImporter($this->name, $this);
}
/**
* Get the current query object or a new DatabaseQuery object.
*
* @param boolean $new False to return the current query object, True to return a new DatabaseQuery object.
* The $new parameter is deprecated in 2.2 and will be removed in 4.0, use createQuery() instead.
*
* @return DatabaseQuery
*
* @since 1.0
*/
public function getQuery($new = false)
{
if ($new) {
trigger_deprecation(
'joomla/database',
'2.2.0',
'The parameter $new is deprecated and will be removed in 4.0, use %s::createQuery() instead.',
self::class
);
return $this->createQuery();
}
return $this->sql;
}
/**
* Get a new iterator on the current query.
*
* @param string $column An option column to use as the iterator key.
* @param string $class The class of object that is returned.
*
* @return DatabaseIterator
*
* @since 1.0
*/
public function getIterator($column = null, $class = \stdClass::class)
{
if (!$this->executed) {
$this->execute();
}
/**
* Calling setQuery free's the statement from the iterator which will break the iterator.
* So we set statement to null so that freeResult on the statement here has no affect.
* If you unset the iterator object then that will close the cursor and free the result.
*/
$iterator = $this->factory->getIterator($this->name, $this->statement, $column, $class);
$this->statement = null;
return $iterator;
}
/**
* Shows the table CREATE statement that creates the given tables.
*
* @param mixed $tables A table name or a list of table names.
*
* @return array A list of the create SQL for the tables.
*
* @since 1.0
* @throws \RuntimeException
*/
abstract public function getTableCreate($tables);
/**
* Determine whether or not the database engine supports UTF-8 character encoding.
*
* @return boolean True if the database engine supports UTF-8 character encoding.
*
* @since 1.0
*/
public function hasUtfSupport()
{
return $this->utf;
}
/**
* Inserts a row into a table based on an object's properties.
*
* @param string $table The name of the database table to insert into.
* @param object $object A reference to an object whose public properties match the table fields.
* @param string $key The name of the primary key. If provided the object property is updated.
*
* @return boolean
*
* @since 1.0
* @throws \RuntimeException
*/
public function insertObject($table, &$object, $key = null)
{
$fields = [];
$values = [];
$tableColumns = $this->getTableColumns($table);
// Iterate over the object variables to build the query fields and values.
foreach (get_object_vars($object) as $k => $v) {
// Skip columns that don't exist in the table.
if (!\array_key_exists($k, $tableColumns)) {
continue;
}
// Only process non-null scalars.
if (\is_array($v) || \is_object($v) || $v === null) {
continue;
}
// Ignore any internal fields.
if ($k[0] === '_') {
continue;
}
// Prepare and sanitize the fields and values for the database query.
$fields[] = $this->quoteName($k);
$values[] = $this->quote($v);
}
// Create the base insert statement.
$query = $this->createQuery()
->insert($this->quoteName($table))
->columns($fields)
->values(implode(',', $values));
// Set the query and execute the insert.
$this->setQuery($query)->execute();
// Update the primary key if it exists.
$id = $this->insertid();
if ($key && $id && \is_string($key)) {
$object->$key = $id;
}
return true;
}
/**
* Method to check whether the installed database version is supported by the database driver
*
* @return boolean True if the database version is supported
*
* @since 1.0
*/
public function isMinimumVersion()
{
return version_compare($this->getVersion(), $this->getMinimum()) >= 0;
}
/**
* Method to get the first row of the result set from the database query as an associative array of ['field_name' => 'row_value'].
*
* @return mixed The return value or null if the query failed.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadAssoc()
{
$this->connect();
$ret = null;
// Execute the query and get the result set cursor.
$this->execute();
// Get the first row from the result set as an associative array.
$array = $this->fetchAssoc();
if ($array) {
$ret = $array;
}
// Free up system resources and return.
$this->freeResult();
return $ret;
}
/**
* Method to get an array of the result set rows from the database query where each row is an associative array
* of ['field_name' => 'row_value']. The array of rows can optionally be keyed by a field name, but defaults to
* a sequential numeric array.
*
* NOTE: Choosing to key the result array by a non-unique field name can result in unwanted
* behavior and should be avoided.
*
* @param string $key The name of a field on which to key the result array.
* @param string $column An optional column name. Instead of the whole row, only this column value will be in
* the result array.
*
* @return mixed The return value or null if the query failed.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadAssocList($key = null, $column = null)
{
$this->connect();
$array = [];
// Execute the query and get the result set cursor.
$this->execute();
// Get all of the rows from the result set.
while ($row = $this->fetchAssoc()) {
$value = $column ? ($row[$column] ?? $row) : $row;
if ($key) {
$array[$row[$key]] = $value;
} else {
$array[] = $value;
}
}
// Free up system resources and return.
$this->freeResult();
return $array;
}
/**
* Method to get an array of values from the <var>$offset</var> field in each row of the result set from the database query.
*
* @param integer $offset The row offset to use to build the result array.
*
* @return mixed The return value or null if the query failed.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadColumn($offset = 0)
{
$this->connect();
$array = [];
// Execute the query and get the result set cursor.
$this->execute();
// Get all of the rows from the result set as arrays.
while ($row = $this->fetchArray()) {
$array[] = $row[$offset];
}
// Free up system resources and return.
$this->freeResult();
return $array;
}
/**
* Method to get the first row of the result set from the database query as an object.
*
* @param string $class The class name to use for the returned row object.
*
* @return mixed The return value or null if the query failed.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadObject($class = \stdClass::class)
{
$this->connect();
$ret = null;
if ($this->statement) {
$fetchMode = $class === \stdClass::class ? FetchMode::STANDARD_OBJECT : FetchMode::CUSTOM_OBJECT;
// PDO doesn't allow extra arguments for \PDO::FETCH_CLASS, so only forward the class for the custom object mode
if ($fetchMode === FetchMode::STANDARD_OBJECT) {
$this->statement->setFetchMode($fetchMode);
} else {
$this->statement->setFetchMode($fetchMode, $class);
}
}
// Execute the query and get the result set cursor.
$this->execute();
// Get the first row from the result set as an object of type $class.
$object = $this->fetchObject();
if ($object) {
$ret = $object;
}
// Free up system resources and return.
$this->freeResult();
return $ret;
}
/**
* Method to get an array of the result set rows from the database query where each row is an object. The array
* of objects can optionally be keyed by a field name, but defaults to a sequential numeric array.
*
* NOTE: Choosing to key the result array by a non-unique field name can result in unwanted behavior and should be avoided.
*
* @param string $key The name of a field on which to key the result array.
* @param string $class The class name to use for the returned row objects.
*
* @return mixed The return value or null if the query failed.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadObjectList($key = '', $class = \stdClass::class)
{
$this->connect();
$array = [];
if ($this->statement) {
$fetchMode = $class === \stdClass::class ? FetchMode::STANDARD_OBJECT : FetchMode::CUSTOM_OBJECT;
// PDO doesn't allow extra arguments for \PDO::FETCH_CLASS, so only forward the class for the custom object mode
if ($fetchMode === FetchMode::STANDARD_OBJECT) {
$this->statement->setFetchMode($fetchMode);
} else {
$this->statement->setFetchMode($fetchMode, $class);
}
}
// Execute the query and get the result set cursor.
$this->execute();
// Get all of the rows from the result set as objects of type $class.
while ($row = $this->fetchObject()) {
if ($key) {
$array[$row->$key] = $row;
} else {
$array[] = $row;
}
}
// Free up system resources and return.
$this->freeResult();
return $array;
}
/**
* Method to get the first field of the first row of the result set from the database query.
*
* @return mixed The return value or null if the query failed.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadResult()
{
$this->connect();
$ret = null;
// Execute the query and get the result set cursor.
$this->execute();
// Get the first row from the result set as an array.
$row = $this->fetchArray();
if ($row) {
$ret = $row[0];
}
// Free up system resources and return.
$this->freeResult();
return $ret;
}
/**
* Method to get the first row of the result set from the database query as an array.
*
* Columns are indexed numerically so the first column in the result set would be accessible via <var>$row[0]</var>, etc.
*
* @return mixed The return value or null if the query failed.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadRow()
{
$this->connect();
$ret = null;
// Execute the query and get the result set cursor.
$this->execute();
// Get the first row from the result set as an array.
$row = $this->fetchArray();
if ($row) {
$ret = $row;
}
// Free up system resources and return.
$this->freeResult();
return $ret;
}
/**
* Method to get an array of the result set rows from the database query where each row is an array. The array
* of objects can optionally be keyed by a field offset, but defaults to a sequential numeric array.
*
* NOTE: Choosing to key the result array by a non-unique field can result in unwanted behavior and should be avoided.
*
* @param string $key The name of a field on which to key the result array.
*
* @return array An array of results.
*
* @since 1.0
* @throws \RuntimeException
*/
public function loadRowList($key = null)
{
$this->connect();
$array = [];
// Execute the query and get the result set cursor.
$this->execute();
// Get all of the rows from the result set as arrays.
while ($row = $this->fetchArray()) {
if ($key !== null) {
$array[$row[$key]] = $row;
} else {
$array[] = $row;
}
}
// Free up system resources and return.
$this->freeResult();
return $array;
}
/**
* Prepares a SQL statement for execution
*
* @param string $query The SQL query to be prepared.
*
* @return StatementInterface
*
* @since 2.0.0
* @throws PrepareStatementFailureException
*/
abstract protected function prepareStatement(string $query): StatementInterface;
/**
* Alias for quote method
*
* @param array|string $text A string or an array of strings to quote.
* @param boolean $escape True (default) to escape the string, false to leave it unchanged.
*
* @return string The quoted input string.
*
* @since 1.0
*/
public function q($text, $escape = true)
{
return $this->quote($text, $escape);
}
/**
* Quotes and optionally escapes a string to database requirements for use in database queries.
*
* @param array|string $text A string or an array of strings to quote.
* @param boolean $escape True (default) to escape the string, false to leave it unchanged.
*
* @return array|string The quoted input string.
*
* @since 1.0
*/
public function quote($text, $escape = true)
{
if (\is_array($text)) {
foreach ($text as $k => $v) {
$text[$k] = $this->quote($v, $escape);
}
return $text;
}
return '\'' . ($escape ? $this->escape($text) : $text) . '\'';
}
/**
* Quotes a binary string to database requirements for use in database queries.
*
* @param string $data A binary string to quote.
*
* @return string The binary quoted input string.
*
* @since 1.7.0
*/
public function quoteBinary($data)
{
// SQL standard syntax for hexadecimal literals
return "X'" . bin2hex($data) . "'";
}
/**
* Replace special placeholder representing binary field with the original string.
*
* @param string|resource $data Encoded string or resource.
*
* @return string The original string.
*
* @since 1.7.0
*/
public function decodeBinary($data)
{
return $data;
}
/**
* Alias for quoteName method
*
* @param array|string $name The identifier name to wrap in quotes, or an array of identifier names to wrap in quotes.
* Each type supports dot-notation name.
* @param array|string $as The AS query part associated to $name. It can be string or array, in latter case it has to be
* same length of $name; if is null there will not be any AS part for string or array element.
*
* @return array|string The quote wrapped name, same type of $name.
*
* @since 1.0
*/
public function qn($name, $as = null)
{
return $this->quoteName($name, $as);
}
/**
* Wrap an SQL statement identifier name such as column, table or database names in quotes to prevent injection
* risks and reserved word conflicts.
*
* @param array|string $name The identifier name to wrap in quotes, or an array of identifier names to wrap in quotes.
* Each type supports dot-notation name.
* @param array|string $as The AS query part associated to $name. It can be string or array, in latter case it has to be
* same length of $name; if is null there will not be any AS part for string or array element.
*
* @return array|string The quote wrapped name, same type of $name.
*
* @since 1.0
*/
public function quoteName($name, $as = null)
{
if (\is_string($name)) {
$name = $this->quoteNameString($name);
if ($as !== null) {
$name .= ' AS ' . $this->quoteNameString($as, true);
}
return $name;
}
$fin = [];
if ($as === null) {
foreach ($name as $str) {
$fin[] = $this->quoteName($str);
}
} elseif (\is_array($name) && (\count($name) === \count($as))) {
$count = \count($name);
for ($i = 0; $i < $count; $i++) {
$fin[] = $this->quoteName($name[$i], $as[$i]);
}
}
return $fin;
}
/**
* Quote string coming from quoteName call.
*
* @param string $name Identifier name to be quoted.
* @param boolean $asSinglePart Treat the name as a single part of the identifier.
*
* @return string Quoted identifier string.
*
* @since 1.7.0
*/
protected function quoteNameString($name, $asSinglePart = false)
{
$q = $this->nameQuote . $this->nameQuote;
// Double quote reserved keyword
$name = str_replace($q[1], $q[1] . $q[1], $name);
if ($asSinglePart) {
return $q[0] . $name . $q[1];
}
return $q[0] . str_replace('.', "$q[1].$q[0]", $name) . $q[1];
}
/**
* Quote strings coming from quoteName call.
*
* @param array $strArr Array of strings coming from quoteName dot-explosion.
*
* @return string Dot-imploded string of quoted parts.
*
* @since 1.0
* @deprecated 2.0 Use quoteNameString instead
*/
protected function quoteNameStr($strArr)
{
$parts = [];
foreach ($strArr as $part) {
if ($part === null) {
continue;
}
$parts[] = $this->quoteNameString($part, true);
}
return implode('.', $parts);
}
/**
* This function replaces a string identifier with the configured table prefix.
*
* @param string $sql The SQL statement to prepare.
* @param string $prefix The table prefix.
*
* @return string The processed SQL statement.
*
* @since 1.0
*/
public function replacePrefix($sql, $prefix = '#__')
{
$escaped = false;
$startPos = 0;
$quoteChar = '';
$literal = '';
$sql = trim($sql);
$n = \strlen($sql);
while ($startPos < $n) {
$ip = strpos($sql, $prefix, $startPos);
if ($ip === false) {
break;
}
$j = strpos($sql, "'", $startPos);
$k = strpos($sql, '"', $startPos);
if (($k !== false) && (($k < $j) || ($j === false))) {
$quoteChar = '"';
$j = $k;
} else {
$quoteChar = "'";
}
if ($j === false) {
$j = $n;
}
$literal .= str_replace($prefix, $this->tablePrefix, substr($sql, $startPos, $j - $startPos));
$startPos = $j;
$j = $startPos + 1;
if ($j >= $n) {
break;
}
// Quote comes first, find end of quote
while (true) {
$k = strpos($sql, $quoteChar, $j);
$escaped = false;
if ($k === false) {
break;
}
$l = $k - 1;
while ($l >= 0 && $sql[$l] === '\\') {
$l--;
$escaped = !$escaped;
}
if ($escaped) {
$j = $k + 1;
continue;
}
break;
}
if ($k === false) {
// Error in the query - no end quote; ignore it
break;
}
$literal .= substr($sql, $startPos, $k - $startPos + 1);
$startPos = $k + 1;
}
if ($startPos < $n) {
$literal .= substr($sql, $startPos, $n - $startPos);
}
return $literal;
}
/**
* Get the query monitor.
*
* @return QueryMonitorInterface|null The query monitor or null if not set.
*
* @since 2.0.0
*/
public function getMonitor()
{
return $this->monitor;
}
/**
* Set a query monitor.
*
* @param QueryMonitorInterface|null $monitor The query monitor.
*
* @return $this
*
* @since 2.0.0
*/
public function setMonitor(?QueryMonitorInterface $monitor = null)
{
$this->monitor = $monitor;
return $this;
}
/**
* Sets the SQL statement string for later execution.
*
* @param string|QueryInterface $query The SQL statement to set either as a Query object or a string.
* @param integer $offset The affected row offset to set. {@deprecated 3.0 Use LimitableInterface::setLimit() instead}
* @param integer $limit The maximum affected rows to set. {@deprecated 3.0 Use LimitableInterface::setLimit() instead}
*
* @return $this
*
* @since 1.0
* @throws \InvalidArgumentException
*/
public function setQuery($query, $offset = 0, $limit = 0)
{
$this->connect();
$this->freeResult();
if (\is_string($query)) {
// Allows taking advantage of bound variables in a direct query:
$query = $this->getQuery(true)->setQuery($query);
} elseif (!($query instanceof QueryInterface)) {
throw new \InvalidArgumentException(
sprintf(
'A query must be a string or a %s instance, a %s was given.',
QueryInterface::class,
\gettype($query) === 'object' ? (\get_class($query) . ' instance') : \gettype($query)
)
);
}
if ($offset > 0 || $limit > 0) {
trigger_deprecation(
'joomla/database',
'2.0.0',
'The "$offset" and "$limit" arguments of %s() are deprecated and will be removed in 3.0, use %s::setLimit() instead.',
__METHOD__,
QueryInterface::class
);
}
// Check for values set on the query object and use those if there is a zero value passed here
if ($limit === 0 && $query->limit > 0) {
$limit = $query->limit;
}
if ($offset === 0 && $query->offset > 0) {
$offset = $query->offset;
}
$query->setLimit($limit, $offset);
$sql = $this->replacePrefix((string) $query);
$this->statement = $this->prepareStatement($sql);
$this->sql = $query;
$this->limit = (int) max(0, $limit);
$this->offset = (int) max(0, $offset);
return $this;
}
/**
* Set the connection to use UTF-8 character encoding.
*
* @return boolean True on success.
*
* @since 1.0
*/
abstract public function setUtf();
/**
* Method to truncate a table.
*
* @param string $table The table to truncate
*
* @return void
*
* @since 1.0
* @throws \RuntimeException
*/
public function truncateTable($table)
{
$this->setQuery('TRUNCATE TABLE ' . $this->quoteName($table))
->execute();
}
/**
* Updates a row in a table based on an object's properties.
*
* @param string $table The name of the database table to update.
* @param object $object A reference to an object whose public properties match the table fields.
* @param array|string $key The name of the primary key.
* @param boolean $nulls True to update null fields or false to ignore them.
*
* @return boolean True on success.
*
* @since 1.0
* @throws \RuntimeException
*/
public function updateObject($table, &$object, $key, $nulls = false)
{
$fields = [];
$where = [];
$tableColumns = $this->getTableColumns($table);
if (\is_string($key)) {
$key = [$key];
}
if (\is_object($key)) {
$key = (array) $key;
}
// Create the base update statement.
$statement = 'UPDATE ' . $this->quoteName($table) . ' SET %s WHERE %s';
// Iterate over the object variables to build the query fields/value pairs.
foreach (get_object_vars($object) as $k => $v) {
// Skip columns that don't exist in the table.
if (!\array_key_exists($k, $tableColumns)) {
continue;
}
// Only process scalars that are not internal fields.
if (\is_array($v) || \is_object($v) || $k[0] === '_') {
continue;
}
// Set the primary key to the WHERE clause instead of a field to update.
if (\in_array($k, $key, true)) {
$where[] = $this->quoteName($k) . ($v === null ? ' IS NULL' : ' = ' . $this->quote($v));
continue;
}
// Prepare and sanitize the fields and values for the database query.
if ($v === null) {
// If the value is null and we want to update nulls then set it.
if ($nulls) {
$val = 'NULL';
} else {
// If the value is null and we do not want to update nulls then ignore this field.
continue;
}
} else {
// The field is not null so we prep it for update.
$val = $this->quote($v);
}
// Add the field to be updated.
$fields[] = $this->quoteName($k) . '=' . $val;
}
// We don't have any fields to update.
if (empty($fields)) {
return true;
}
// Set the query and execute the update.
$this->setQuery(sprintf($statement, implode(',', $fields), implode(' AND ', $where)))->execute();
return true;
}
/**
* Extract pure host name (or IP address) and port or socket from host name option.
*
* @param string $host Host given in options used to configure the connection.
* @param integer|null $port Port given in options used to configure the connection, null if none.
* @param string|null $socket Socket given in options used to configure the connection, null if none.
* @param integer $defaultPort The default port number to be used if no port is given.
* @param boolean $ipv6SquareBrackets True if database connector uses ipv6 address with square brackets, false if not.
*
* @return array Array with host, port and socket.
*
* @since 3.3.0
*/
protected function extractHostPortSocket(string $host, ?int $port, ?string $socket, int $defaultPort, bool $ipv6SquareBrackets = true): array
{
$portNew = $port ?? $defaultPort;
if (preg_match('/^unix:(?P<socket>[^:]+)$/', $host, $matches)) {
// UNIX socket URI, e.g. 'unix:/path/to/unix/socket.sock'
$host = null;
$socket = $matches['socket'];
$port = null;
} elseif (
preg_match(
'/^(?P<host>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))(:(?P<port>.+))?$/',
$host,
$matches
)
) {
// It's an IPv4 address with or without port
$host = $matches['host'];
if (!empty($matches['port'])) {
$portNew = $matches['port'];
}
} elseif (preg_match('/^(?P<host>\[.*\])(:(?P<port>.+))?$/', $host, $matches)) {
// We assume square-bracketed IPv6 address with or without port, e.g. [fe80:102::2%eth1]:3306
$host = $ipv6SquareBrackets ? $matches['host'] : rtrim(ltrim($matches['host'], '['), ']');
if (!empty($matches['port'])) {
$portNew = $matches['port'];
}
} elseif (preg_match('/^(?P<host>(\w+:\/{2,3})?[a-z0-9\.\-]+)(:(?P<port>[^:]+))?$/i', $host, $matches)) {
// Named host (e.g example.com or localhost) with or without port
$host = $matches['host'];
if (!empty($matches['port'])) {
$portNew = $matches['port'];
}
} elseif (preg_match('/^:(?P<port>[^:]+)$/', $host, $matches)) {
// Empty host, just port, e.g. ':3306'
$host = 'localhost';
$portNew = $matches['port'];
}
// ... else we assume normal (naked) IPv6 address, so host and port stay as they are or default
// Get the port number or socket name
if (is_numeric($portNew)) {
$port = (int) $portNew;
} else {
$socket = $portNew;
}
return [$host, $port, $socket];
}
}