README

简单的PDO包装器

为了充分利用这个库，数据库中的每个表都应该有一个名为id的主键。

入门指南

使用composer

composer require llwebsol/easy-db

1. 创建配置

$config = new EasyDb\Core\Config([
    'db_type' => 'mysql',
    'host' => 'localhost',
    'db_name' => 'my_test_db',
    'user' => 'root',
    'password' => ''
]);

接受的db_type选项

• mysql
• pgsql
• sqlite*
• sqlsrv*

*目前未测试

完整选项列表

db_type
host
db_name
port
user
password

// mysql specific:
unix_socket
charset

// sqlsrv specific:
app
connection_pooling
encrypt
failover_partner
login_timeout
multiple_active_result_sets
quoted_id
server
trace_file
trace_on
transaction_isolation
trust_server_certificate
wsid

// sqlite specific:
path

2. 获取DB实例

使用连接池获取给定配置的数据库实例。

$db = ConnectionPool::getDbInstance($config);

3. 查询数据库

一旦你有DB类的实例，你可以使用几个辅助方法

- 查询

接受任何所需的数据库查询，可选的绑定参数数组

返回一个用于遍历结果集的生成器

$query = 'SELECT * FROM users WHERE name = :user_name';
$params = [':user_name' => 'Ted'];

$users = $db->query($query,$params);

- QueryOne

从数据库获取单个记录的辅助方法

将记录作为数组返回，(不包装在生成器中)

$query = 'SELECT * FROM users WHERE id = :user_id';
$params = [':user_id' => 7]

$user = $db->queryOne($query,$params);

- 插入

将记录插入给定的表，返回最后一个插入的id

$data = [
    'name' => 'Chris',
    'email' => 'chris@landlordwebsolutions.com'
];

$inserted_id = $db->insert('users', $data);

- 更新

更新给定表中的记录，返回受影响的行数

$data = [
    'email' => 'new.email@email.com'
];

$rows_affected = $db->update('users', 76, $data);

- 保存

这只是一个别名，如果$data有'id'字段，则更新，否则插入

- 删除

从给定表删除记录，返回受影响的行数或false如果无效

// Delete the record with id=76 from 'users'
$rows_deleted = $db->delete('users', 76);

- 删除Where

删除符合where子句条件的给定表中的记录，返回删除的行数

// Delete all clients from Toronto or New York with a name starting with 'T'

$where = 'name LIKE :name_compare AND city_id IN (:toronto_id,:new_york_id)';
$params = [
    ':name_compare' =>  't%',
    ':toronto_id' => 5142,
    ':new_york_id' => 1432
];

$records_deleted = $db->deleteWhere('clients', $where, $params);

- 更新Where

更新符合where子句条件的给定表中的记录，返回更新的行数

Set Status to 'disabled' for all users with hotmail accounts

$update = [ 'status' => 'disabled' ];
$where  = 'email LIKE :email_compare';
$params = [ ':email_compare' => '%@hotmail.com' ]

$rows_updated = $db->updateWhere('users', $update, $where, $params);

- Find In

返回一个生成器，包含表中所有满足$column_name IN ( $in_array )的记录

$records = $db->findIn('clients', 'city_id', [5142,1432,76,222]);

SQL等效

SELECT *
FROM clients
WHERE city_id IN (5142,1432,76,222);

4. 事件

你可以为数据库交互的任何阶段添加事件监听器

支持的事件

• ON_ERROR
• BEFORE_QUERY
• AFTER_QUERY
• BEFORE_UPDATE
• AFTER_UPDATE
• BEFORE_INSERT
• AFTER_INSERT
• BEFORE_DELETE
• AFTER_DELETE

辅助方法

• BEFORE_SAVE (BEFORE_INSERT和BEFORE_UPDATE)
• AFTER_SAVE (AFTER_INSERT和AFTER_UPDATE)

示例

回显执行的每个查询的SQL

use EasyDb\Events\Listener;

class QueryListener implements Listener
{
    /**
     * @param EventData $data
     * @param array     &$ref_parameters [optional]
     */
    public static function handleEvent(EventData $data, array &$ref_parameters = []){
        echo $data->getSql();
    }
}

// Register the listener
Listeners::register(Event::BEFORE_QUERY, QueryListener::class);

将用户id添加到所有插入的记录中

*假设所有表都有一个created_user列

use EasyDb\Events\Listener;

class InsertListener implements Listener
{
    /**
     * @param EventData $data
     * @param array     &$ref_parameters [optional]
     */
    public static function handleEvent(EventData $data, array &$ref_parameters = []){
        $ref_parameters['created_user'] = $_SESSION['user'];
    }
}

// Register the listener
Listeners::register(Event::BEFORE_QUERY, InsertListener::class);

*仅对BEFORE_INSERT和BEFORE_UPDATE事件可用

5. 事务

你可以使用以下3个方法执行单个事务的多个操作

• beginTransaction
• commitTransaction
• rollbackTransaction

示例

/**
* @param array $save_records
* @param DB    $db
*
* @return int $records_saved
*/
function save_a_bunch_of_records(array $save_records, DB $db){
    $db->beginTransaction();

    $records_saved = 0;
    foreach($save_records as $table_name => $record){
        try{
            $records_saved += $db->save($table_name, $record);
        }
        catch(QueryException $ex){

            // All or nothing. Undo all previous saves
            $db->rollbackTransaction();

            return false;
        }
    }

    $db->commitTransaction();
    return $records_saved;
}