README

Sparrow是一个简单但强大的数据库工具包。Sparrow是一个流畅的SQL构建器，数据库抽象层，缓存管理器，查询统计生成器和微ORM，全部封装在一个类文件中。

构建SQL

// Include the library
include '/path/to/sparrow.php';

// Declare the class instance
$db = new Sparrow();

// Select a table
$db->from('user')

// Build a select query
$db->select();

// Display the SQL
echo $db->sql();

输出

SELECT * FROM user

方法链式调用

Sparrow允许您链式调用方法，因此您可以这样做

echo $db->from('user')->select()->sql();

WHERE条件

要向查询中添加WHERE条件，请使用where函数。

echo $db->from('user')
    ->where('id', 123)
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE id = 123

您可以多次调用where函数来添加多个条件。

echo $db->from('user')
    ->where('id', 123)
    ->where('name', 'bob')
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE id = 123 AND name = 'bob'

您还可以向where函数传递一个数组。以下会产生相同的输出。

$where = array('id' => 123, 'name' => 'bob');

echo $db->from('user')
    ->where($where)
    ->select()
    ->sql();

您甚至可以传递一个字符串字面量。

echo $db->from('user')
    ->where('id = 99')
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE id = 99

自定义运算符

WHERE查询的默认运算符是=。您可以通过在字段声明后放置它们来使用不同的运算符。

echo $db->from('user')
    ->where('id >', 123)
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE id > 123;

OR查询

默认情况下，WHERE条件通过AND关键字连接。要使用OR，只需在字段名前放置一个|分隔符。

echo $db->from('user')
    ->where('id <', 10)
    ->where('|id >', 20)
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE id < 10 OR id > 20

LIKE查询

要构建LIKE查询，可以使用特殊运算符%。

echo $db->from('user')
    ->where('name %', '%bob%')
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE name LIKE '%bob%'

要构建NOT LIKE查询，在%运算符前添加一个!。

echo $db->from('user')
    ->where('name !%', '%bob%')
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE name NOT LIKE '%bob%'

IN查询

要在WHERE条件中使用IN语句，请使用特殊运算符@并传递一个值数组。

echo $db->from('user')
    ->where('id @', array(10, 20, 30))
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE id IN (10, 20, 30)

要构建NOT IN查询，在@运算符前添加一个!。

echo $db->from('user')
    ->where('id !@', array(10, 20, 30))
    ->select()
    ->sql();

输出

SELECT * FROM user WHERE id NOT IN (10, 20, 30)

选择字段

要选择特定字段，请将数组传递给select函数。

echo $db->from('user')
    ->select(array('id','name'))
    ->sql();

输出

SELECT id, name FROM user

限制和偏移量

要在查询中添加限制或偏移量，可以使用limit和offset函数。

echo $db->from('user')
    ->limit(10)
    ->offset(20)
    ->select()
    ->sql();

输出

SELECT * FROM user LIMIT 10 OFFSET 20

您还可以向select函数传递其他参数。

echo $db->from('user')
    ->select('*', 50, 10)
    ->sql();

输出

SELECT * FROM user LIMIT 50 OFFSET 10

Distinct

要向查询中添加DISTINCT关键字，请调用distinct函数。

echo $db->from('user')
    ->distinct()
    ->select('name')
    ->sql();

输出

SELECT DISTINCT name FROM user

表连接

要添加表连接，请使用join函数并传递要连接的字段数组。

echo $db->from('user')
    ->join('role', array('role.id' => 'user.id'))
    ->select()
    ->sql();

输出

SELECT * FROM user INNER JOIN role ON role.id = user.id

默认连接类型是INNER连接。要构建其他类型的连接，可以使用其他连接函数leftJoin，rightJoin和fullJoin。

连接数组的工作方式与WHERE条件类似，因此您可以使用自定义运算符并添加多个条件。

echo $db->from('user')
    ->join('role', array('role.id' => 'user.id', 'role.id >' => 10))
    ->select()
    ->sql();

输出

SELECT * FROM user INNER JOIN role ON role.id = user.id AND role.id > 10

排序

要向查询中添加排序，请使用sortAsc和sortDesc函数。

echo $db->from('user')
    ->sortDesc('id')
    ->select()
    ->sql();

输出

SELECT * FROM user ORDER BY id DESC

您还可以向排序函数传递一个数组。

echo $db->from('user')
    ->sortAsc(array('rank','name'))
    ->select()
    ->sql();

输出

SELECT * FROM user ORDER BY rank ASC, name ASC

分组

要按字段分组，请使用groupBy函数。

echo $db->from('user')
    ->groupBy('points')
    ->select(array('id','count(*)'))
    ->sql();

输出

SELECT id, count(*) FROM user GROUP BY points;

插入查询

要构建插入查询，请将数据数组传递给insert函数。

$data = array('id' => 123, 'name' => 'bob');

echo $db->from('user')
    ->insert($data)
    ->sql();

输出

INSERT INTO user (id, name) VALUES (123, 'bob')

更新查询

要构建更新查询，请将数据数组传递给update函数。

$data = array('name' => 'bob', 'email' => 'bob@aol.com');
$where = array('id' => 123);

echo $db->from('user')
    ->where($where)
    ->update($data)
    ->sql();

输出

UPDATE user SET name = 'bob', email = 'bob@aol.com' WHERE id = 123

删除查询

要构建删除查询，请使用delete函数。

echo $db->from('user')
    ->where('id', 123)
    ->delete()
    ->sql();

输出

DELETE FROM user WHERE id = 123

执行查询

Sparrow还可以执行它构建的查询。您需要调用setDb()方法，传递连接字符串、连接信息数组或连接对象。

支持的数据库类型是mysql、mysqli、pgsql、sqlite和sqlite3。

使用连接字符串

$db->setDb('mysql://admin:hunter2@localhost/mydb');

连接字符串使用以下格式

type://username:password@hostname[:port]/database

对于sqlite，您需要使用

type://database

使用连接数组

$db->setDb(array(
    'type' => 'mysql',
    'hostname' => 'localhost',
    'database' => 'mydb',
    'username' => 'admin',
    'password' => 'hunter2'
));

可能的数组选项是type、hostname、database、username、password和port。

使用连接对象

$mysql = mysql_connect('localhost', 'admin', 'hunter2');

mysql_select_db('mydb');

$db->setDb($mysql);

您还可以使用PDO进行数据库连接。要使用连接字符串或数组方法，请在数据库类型前加上pdo

$db->setDb('pdomysql://admin:hunter2@localhost/mydb');

可能的PDO类型有pdomysql、pdopgsql和pdosqlite。

您还可以直接传入任何PDO对象。

$pdo = new PDO('mysql:host=localhost;dbname=mydb', 'admin', 'hunter2');

$db->setDb($pdo);

获取记录

要获取多条记录，使用many函数。

$rows = $db->from('user')
    ->where('id >', 100)
    ->many();

返回的结果是关联数组的数组。

array(
    array('id' => 101, 'name' => 'joe'),
    array('id' => 102, 'name' => 'ted');
)

要获取单条记录，使用one函数。

$row = $db->from('user')
    ->where('id', 123)
    ->one();

返回的结果是单个关联数组。

array('id' => 123, 'name' => 'bob')

要获取列的值，使用value函数并传入列名。

$username = $db->from('user')
    ->where('id', 123)
    ->value('username');

所有获取函数都会自动执行选择，除非您想指定返回的字段，否则不需要包含select函数。

$row = $db->from('user')
    ->where('id', 123)
    ->select(array('id', 'name'))
    ->one();

非查询

对于更新、插入和删除等非查询，在构建查询后使用execute函数。

$db->from('user')
    ->where('id', 123)
    ->delete()
    ->execute();

执行

DELETE FROM user WHERE id = 123

自定义查询

您还可以通过传递给sql函数来运行原始SQL。

$posts = $db->sql('SELECT * FROM posts')->many();

$user = $db->sql('SELECT * FROM user WHERE id = 123')->one();

$db->sql('UPDATE user SET name = 'bob' WHERE id = 1')->execute();

转义值

Sparrow的SQL构建函数会自动引用和转义值以防止SQL注入。在编写自己的查询时，您可以手动引用和转义值，可以使用quote函数。

$name = "O'Dell";

printf("SELECT * FROM user WHERE name = %s", $db->quote($name));

输出

SELECT * FROM user WHERE name = 'O\'Dell'

查询属性

执行查询后，将填充几个属性值，您可以直接访问它们。

// Last query executed
$db->last_query;

// Number of rows returned
$db->num_rows;

// Last insert id
$db->insert_id;

// Number of affected rows
$db->affected_rows;

每次执行新查询时，这些值都会重置。

辅助方法

获取表中行的数量。

$count = $db->from('user')->count();

从表中获取最小值。

$min = $db->from('employee')->min('salary');

从表中获取最大值。

$max = $db->from('employee')->max('salary');

从表中获取平均值。

$avg = $db->from('employee')->avg('salary');

从表中获取总和。

$avg = $db->from('employee')->sum('salary');

直接访问

您还可以通过使用getDb函数直接访问数据库对象。

$mysql = $db->getDb();

mysql_info($mysql);

缓存

要启用缓存，您需要使用带有连接字符串或连接对象的setCache方法。

使用连接字符串

$db->setCache('memcache://:11211');

使用缓存对象

$cache = new Memcache();
$cache->addServer('localhost', 11211);

$db->setCache($cache);

然后，您可以将缓存键传递给查询函数，Sparrow将在执行查询之前尝试从缓存中获取。如果发生缓存未命中，Sparrow将执行查询并使用指定的缓存键存储结果。

$key = 'all_users';

$users = $db->from('user')->many($key);

缓存类型

支持的缓存有memcache、memcached、apc、xcache、file和memory。

要使用memcache或memcached，您需要使用以下连接字符串

protocol://hostname:port

要使用apc或xcache，只需传递缓存名称

$db->setCache('apc');

要将文件系统用作缓存，请传入目录路径

$db->setCache('/usr/local/cache');

$db->setCache('./cache');

请注意，本地目录必须以./开头。

默认缓存是memory，并且仅存在于脚本期间。

缓存过期

要仅在设置的时间段内缓存数据，您可以传递一个额外的参数，该参数表示以秒为单位的过期时间。

$key = 'top_users';
$expire = 600;

$users = $db->from('user')
    ->sortDesc('score')
    ->limit(100)
    ->many($key, $expire);

在上面的示例中，我们正在获取最高得分的前100名用户列表，并将其缓存600秒（10分钟）。您可以将过期参数传递给任何接受缓存键参数的查询方法。

直接访问

您可以通过使用getCache函数直接访问缓存对象。

$memcache = $db->getCache();

echo $memcache->getVersion();

您还可以直接操作缓存数据。要缓存值，请使用store函数。

$db->store('id', 123);

要检索缓存值，请使用fetch函数。

$id = $db->fetch('id');

要删除缓存值，请使用clear函数。

$db->clear('id');

要完全清空缓存，请使用flush函数。

$db->flush();

使用对象

Sparrow还提供了一些用于处理对象的功能。只需定义一个具有公共属性以表示数据库字段和静态变量以描述数据库关系的类即可。

class User {
    // Class properties
    public $id;
    public $name;
    public $email;

    // Class configuration
    static $table = 'user';
    static $id_field = 'id';
    static $name_field = 'name';
}

类配置

• 属性 table 代表数据库表。此属性为必需。
• 属性 id_field 代表表中的自增标识字段。此属性为保存和删除记录所必需。
• 属性 name_field 用于通过名称查找记录。此属性为可选。

加载对象

要定义对象，请使用 using 函数并传入类名。

$db->using('User');

设置对象后，您可以使用 find 方法来填充对象。如果您传入一个整数，Sparrow 将使用 id 字段进行搜索。

$user = $db->find(123);

这将执行

SELECT * FROM user WHERE id = 123

如果您传入一个字符串，Sparrow 将使用名称字段进行搜索。

$user = $db->find('Bob');

这将执行

SELECT * FROM user WHERE name = 'Bob';

如果您传入一个数组，Sparrow 将使用数组中指定的字段。

$user = $db->find(
    array('email' => 'bob@aol.com')
);

这将执行

SELECT * FROM user WHERE email = 'bob@aol.com'

如果 find 方法检索多个记录，它将返回对象数组而不是单个对象。

保存对象

要保存对象，只需填充对象属性并使用 save 函数。

$user = new User();
$user->name = 'Bob';
$user->email = 'bob@aol.com';

$db->save($user);

这将执行

INSERT INTO user (name, email) VALUES ('Bob', 'bob@aol.com')

要更新对象，请使用包含 id_field 属性的 save 函数。

$user = new User();
$user->id = 123;
$user->name = 'Bob';
$user->email = 'bob@aol.com';

$db->save($user);

这将执行

UPDATE user SET name = 'Bob', email = 'bob@aol.com' WHERE id = 123

要更新现有记录，只需从数据库中获取一个对象，更新其属性，然后保存。

// Fetch an object from the database
$user = $db->find(123);

// Update the object
$user->name = 'Fred';

// Update the database
$db->save($user);

默认情况下，对象的所有属性都将包含在更新中。要指定特定字段，请将额外的字段数组传递给 save 函数。

$db->save($user, array('email'));

这将执行

UPDATE user SET email = 'bob@aol.com' WHERE id = 123

删除对象

要删除对象，请使用 remove 函数。

$user = $db->find(123);

$db->remove($user);

高级查找

您可以使用 SQL 构建函数进一步定义加载对象的准则。

$db->using('User')
    ->where('id >', 10)
    ->sortAsc('name')
    ->find();

这将执行

SELECT * FROM user WHERE id > 10 ORDER BY name ASC

您还可以传入原始 SQL 来加载您的对象。

$db->using('User')
    ->sql('SELECT * FROM user WHERE id > 10')
    ->find();

统计信息

Sparrow 内置查询统计跟踪。要启用它，只需设置 stats_enabled 属性。

$db->stats_enabled = true;

运行您的查询后，获取统计数组

$stats = $db->getStats();

统计数组包含所有查询的总时间和所有执行查询的数组及其单独的查询时间。

array(6) {
  ["queries"]=>
  array(2) {
    [0]=>
    array(4) {
      ["query"]=>
          string(38) "SELECT * FROM user WHERE uid=1"
      ["time"]=>
          float(0.00016617774963379)
      ["rows"]=>
          int(1)
      ["changes"]=>
          int(0)
    }
    [1]=>
    array(4) {
      ["query"]=>
          string(39) "SELECT * FROM user WHERE uid=10"
      ["time"]=>
          float(0.00026392936706543)
      ["rows"]=>
          int(0)
      ["changes"]=>
          int(0)
    }
  }
  ["total_time"]=>
      float(0.00043010711669922)
  ["num_queries"]=>
      int(2)
  ["num_rows"]=>
      int(2)
  ["num_changes"]=>
      int(0)
  ["avg_query_time"]=>
      float(0.00021505355834961)
}

调试

当 Sparrow 在执行查询时遇到错误，它将抛出一个带有数据库错误消息的异常。如果您想显示生成的 SQL 以及错误消息，请设置 show_sql 属性。

$db->show_sql = true;

要求

Sparrow 需要 PHP 5.1 或更高版本。

许可协议

Sparrow 在 MIT 许可协议下发布。