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，您需要使用以下连接字符串

协议://主机名:端口

要使用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 代表表中的自增ID字段。此属性是保存和删除记录所必需的。
• 属性 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 许可证下发布。