README

简介

该 数据库 包旨在通过使用通用数据库引擎来管理数据操作。

// Example for initialising a database driver in a custom application class.

use Joomla\Application\AbstractApplication;
use Joomla\Database;

class MyApplication extends AbstractApplication
{
	/**
	 * Database driver.
	 *
	 * @var    Database\DatabaseDriver
	 * @since  1.0
	 */
	protected $db;

	protected function doExecute()
	{
		// Do stuff
	}

	protected function initialise()
	{
		// Make the database driver.
		$dbFactory = new Database\DatabaseFactory;

		$this->db = $dbFactory->getDriver(
			$this->get('database.driver'),
			array(
				'host' => $this->get('database.host'),
				'user' => $this->get('database.user'),
				'password' => $this->get('database.password'),
				'port' => $this->get('database.port'),
				'socket' => $this->get('database.socket'),
				'database' => $this->get('database.name'),
			)
		);
	}
}

转义字符串和输入

在使用查询之前必须转义字符串（永远不要信任任何变量输入，即使它来自您的数据源的先前数据库查询）。这可以通过使用 escape 和 quote 方法完成。

escape 方法通常转义不安全的字符（通常转义引号字符，但这取决于数据库引擎）。它还允许可选地转义其他字符（例如，在结合 LIKE 子句使用时使用下划线或百分号）。

quote 方法将转义字符串并将其用引号括起来，但是，在某些情况下可以关闭转义。quote 方法还可以接受字符串数组并返回一个转义和引号（除非关闭）的字符串数组。

function search($title)
{
	// Get the database driver from the factory, or by some other suitable means.
	$db = DatabaseDriver::getInstance($options);

	// Search for an exact match of the title, correctly sanitising the untrusted input.
	$sql1 = 'SELECT * FROM #__content WHERE title = ' . $db->quote($title);

	// Special treatment for a LIKE clause.
	$search = $db->quote($db->escape($title, true) . '%', false);
	$sql2 = 'SELECT * FROM #__content WHERE title LIKE ' . $search;

	if (is_array($title))
	{
		$sql3 = 'SELECT * FROM #__content WHERE title IN ('
			. implode(',', $db->quote($title)) . ')';
	}

	// Do the database calls.
}

在第一种情况下，标题变量只是转义和引号。标题字符串中的任何引号字符都将前置反斜杠，整个字符串将用引号括起来。

在第二种情况下，示例显示了如何处理将用于 LIKE 子句的搜索字符串。在这种情况下，标题变量使用带有第二个参数 true 的 escape 手动转义。这将强制其他特殊字符也进行转义（否则，如果用户包括过多的通配符，可能会遇到严重的性能问题）。然后，结果传递给 quote 方法，但关闭了转义（因为已经手动完成）。

在第三种情况下，标题变量是一个数组，因此可以将整个数组传递给 quote 方法（这节省了使用闭包和括号）。

这些方法有简写版本可用

• q 可以代替 quote
• qn 可以代替 quoteName
• e 可以代替 escape

当使用 Database\DatabaseQuery 类时，这些简写版本也可用。

遍历结果

Database\DatabaseIterator 类允许遍历数据库结果

$db = DatabaseDriver::getInstance($options);
$iterator = $db->setQuery(
	$db->getQuery(true)->select('*')->from('#__content')
)->getIterator();

foreach ($iterator as $row)
{
    // Deal with $row
}

它还可以计数结果。

$count = count($iterator);

日志记录

Database\DatabaseDriver 实现了 Psr\Log\LoggerAwareInterface，因此可以集成支持该标准的外部日志记录包。

驱动程序使用 LogLevel::ERROR 日志级别记录所有错误。

如果启用了调试（使用 setDebug(true)），则所有查询都将使用 LogLevel::DEBUG 日志级别进行记录。日志的上下文包括

• sql : 执行的查询。
• category : 使用 "databasequery" 值。

使用 Monolog 记录错误的示例

将此添加到 composer.json

{
	"require" : {
		"monolog/monolog" : "1.*"
	}
}

然后我们将 Monolog 推送到 Database 实例。

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Processor\PsrLogMessageProcessor;

// Create logger object
$logger = new Logger('sql');

// Push logger handler, use DEBUG level that we can log all information
$logger->pushHandler(new StreamHandler('path/to/log/sql.log', Logger::DEBUG));

// Use PSR-3 logger processor that we can replace {sql} with context like array('sql' => 'XXX')
$logger->pushProcessor(new PsrLogMessageProcessor);

// Push into DB
$db->setLogger($logger);
$db->setDebug(true);

// Do something
$db->setQuery('A WRONG QUERY')->execute();

这是日志文件

[2014-07-29 07:25:22] sql.DEBUG: A WRONG QUERY {"sql":"A WRONG QUERY","category":"databasequery","trace":[...]} []
[2014-07-29 07:36:01] sql.ERROR: Database query failed (error #42000): SQL: 42000, 1064, You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'A WRONG QUERY' at line 1 {"code":42000,"message":"SQL: 42000, 1064, You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'A WRONG QUERY' at line 1"} []

通过 Composer 安装

将 "joomla/database": "~3.0" 添加到您的 composer.json 中的 require 块，然后运行 composer install。

{
	"require": {
		"joomla/database": "~3.0"
	}
}

或者，您可以直接在命令行中运行以下命令

composer require joomla/database "~3.0"

如果您想包含测试源，请使用

composer require --prefer-source joomla/database "~3.0"