README

QuEasy PHP框架 - 数据库

包 v-dem/queasy-db

QuEasy DB 是一组用于 CRUD 操作的数据库访问类。一些最常用的查询可以自动构建（如通过唯一字段值/值进行 SELECT、UPDATE、INSERT 和 DELETE）。更复杂的查询可以在数据库和/或表配置中定义。主要目标是使 SQL 查询与 PHP 代码分离，并提供 CRUD 操作的简单方式。

功能

• QuEasy DB 扩展了 PDO 类，因此任何使用 PDO 的项目都可以无缝迁移到使用 QuEasy DB。
• 只需一行 PHP 代码即可执行简单的 CRUD 数据库操作。
• 将 SQL 查询与 PHP 代码分离。

需求

• PHP 版本 5.3 或更高

安装

composer require v-dem/queasy-db

它还会安装 v-dem/queasy-helper。

用法

注意

• 您可以使用接受 Psr\Log\LoggerInterface 实现的 setLogger() 方法来记录所有查询，默认情况下使用 Psr\Log\NullLogger。
• 默认情况下，错误模式设置为 PDO::ERRMODE_EXCEPTION（与 PHP8 相同），如果未在 $options 中设置其他模式。

重要！

• 对于 MySQL 服务器，需要将选项 PDO::MYSQL_ATTR_INIT_COMMAND 设置为 SET GLOBAL SQL_MODE=ANSI_QUOTES 或在调用 DB 特定方法之前运行相同的查询。
• 对于 MSSQL 服务器，需要在调用 DB 特定方法之前运行 SET QUOTED_IDENTIFIER ON 或 SET ANSI_DEFAULTS ON 查询。

初始化

示例

$db = new queasy\db\Db(
    [
        'dsn' => 'pgsql:host=localhost;dbname=test',
        'user' => 'test_user',
        'password' => 'test_password',
        'options' => [
            ...options...
        ]
    ]
);

或

$db = new queasy\db\Db(
    [
        'connection' => [
            'dsn' => 'pgsql:host=localhost;dbname=test',
            'user' => 'test_user',
            'password' => 'test_password',
            'options' => [
                ...options...
            ]
        ]
    ]
);

或 PDO 方式

$db = new queasy\db\Db('pgsql:host=localhost;dbname=test', 'test_user', 'test_password', $options);

• 第四个参数 ($options) 是可选的，将传递给 PDO::prepare()

从 users 表中获取所有记录

$users = $db->users->all();

使用 foreach 遍历 users 表

foreach ($db->users as $user) {
    // Do something
}

通过 id 键从 users 表中获取单个记录

$user = $db->users->id[$userId];

可以使用 select() 方法传递 PDO 选项；select() 返回 PDOStatement 实例

$users = $db->users->id->select($userId, $options);

获取多条记录

$users = $db->users->id[[$userId1, $userId2]];

使用关联数组将记录插入 users 表

$db->users[] = [
    'email' => 'john.doe@example.com',
    'password_hash' => sha1('myverystrongpassword')
];

按照字段顺序将记录插入 users 表

$db->users[] = [
    'john.doe@example.com',
    sha1('myverystrongpassword')
];

使用关联数组将多条记录插入 users 表（它将生成单个 INSERT 语句）

$db->users[] = [
    [
        'email' => 'john.doe@example.com',
        'password_hash' => sha1('myverystrongpassword')
    ], [
        'email' => 'mary.joe@example.com',
        'password_hash' => sha1('herverystrongpassword')
    ]
];

按照顺序将多条记录插入 users 表

$db->users[] = [
    [
        'john.doe@example.com',
        sha1('myverystrongpassword')
    ], [
        'mary.joe@example.com',
        sha1('herverystrongpassword')
    ]
];

使用单独指定的字段名将多条记录插入 users 表

$db->users[] = [
    [
        'email',
        'password_hash'
    ], [
        [
            'john.doe@example.com',
            sha1('myverystrongpassword')
        ], [
            'mary.joe@example.com',
            sha1('herverystrongpassword')
        ]
    ]
];

还可以使用 insert() 方法（与上述方式相同）来传递 PDO 选项；对于单次插入返回最后插入的 ID，对于多次插入返回插入的行数

$userId = $db->users->insert([
    'email' => 'john.doe@example.com',
    'password_hash' => sha1('myverystrongpassword')
], $options);

$insertedRowsCount = $db->users->insert([
    [
        'email' => 'john.doe@example.com',
        'password_hash' => sha1('myverystrongpassword')
    ], [
        'email' => 'mary.joe@example.com',
        'password_hash' => sha1('herverystrongpassword')
    ]
], $options);

• 第二个参数 ($options) 是可选的，将传递给 PDO::prepare()

获取最后插入的 ID（lastInsertId() 方法的别名）

$newUserId = $db->id();

通过 id 键更新 users 表中的记录

$db->users->id[$userId] = [
    'password_hash' => sha1('mynewverystrongpassword')
]

$updatedRowsCount = $db->users->id->update($userId, [
    'password_hash' => sha1('mynewverystrongpassword')
], $options);

• 第三个参数 ($options) 是可选的，将传递给 PDO::prepare()

更新多条记录

$db->users->id[[$userId1, $userId2]] = [
    'is_blocked' => true
]

通过 id 键删除 users 表中的记录

unset($db->users->id[$userId]);

删除多条记录

unset($db->users->id[[$userId1, $userId2]]);

$deletedRowsCount = $db->users->id->delete([[$userId1, $userId2]], $options);

• 第二个参数 ($options) 是可选的，将传递给 PDO::prepare()

获取 users 表中所有记录的计数

$usersCount = count($db->users);

使用事务

$db->trans(function() use($db) {
    // Run queries inside a transaction, for example:
    $db->users[] = [
        'john.doe@example.com',
        sha1('myverystrongpassword')
    ];
});

• 在异常发生时，事务将回滚，并将异常重新抛出到外部代码。

运行自定义查询（返回 PDOStatement）

$users = $db->run('
    SELECT  *
    FROM    "users"
    WHERE   "name" LIKE concat(\'%\', :searchName, \'%\')',
    [
        ':searchName' => 'John'
    ],
    $options
)->fetchAll();

• 第三个参数 ($options) 是可选的，将传递给 PDO::prepare()

运行配置中预定义的查询

此功能可以帮助保持代码整洁，并将 SQL 代码放置在 PHP 之外，例如在配置文件中。

$db = new queasy\db\Db(
    [
        'connection' => [
            'dsn' => 'pgsql:host=localhost;dbname=test',
            'user' => 'test_user',
            'password' => 'test_password'
        ],
        'queries' => [
            'searchUsersByName' => [
                'sql' => '
                    SELECT  *
                    FROM    "users"
                    WHERE   "name" LIKE concat(\'%\', :searchName, \'%\')',
                'returns' => Db::RETURN_ALL
            ]
        ]
    ]
);

$users = $db->searchUsersByName([
    'searchName' => 'John'
]);

• returns 选项的可能值有：Db::RETURN_STATEMENT（默认，返回 PDOStatement 实例）、Db::RETURN_ONE、Db::RETURN_ALL、Db::RETURN_VALUE

还可以按表对预定义查询进行分组

$db = new queasy\db\Db(
    [
        'connection' => [
            'dsn' => 'pgsql:host=localhost;dbname=test',
            'user' => 'test_user',
            'password' => 'test_password'
        ],
        'tables' => [
            'users' => [
                'searchByName' => [
                    'sql' => '
                        SELECT  *
                        FROM    "user_roles"
                        WHERE   "name" LIKE concat(\'%\', :searchName, \'%\')',
                    'returns' => Db::RETURN_ALL
                ]
            ]
        ]
    ]
);

$users = $db->users->searchByName([
    'searchName' => 'John'
]);

结合使用 v-dem/queasy-db、v-dem/queasy-config 和 v-dem/queasy-log

config.php

return [
    'db' => [
        'connection' => [
            'dsn' => 'pgsql:host=localhost;dbname=test',
            'user' => 'test_user',
            'password' => 'test_password'
        ],
        'tables' => [
            'users' => [
                'searchByName' => [
                    'sql' => '
                        SELECT  *
                        FROM    "users"
                        WHERE   "name" LIKE concat(\'%\', :searchName, \'%\')',
                    'returns' => Db::RETURN_ALL
                ]
            ]
        ]
    ],

    'logger' => [
        [
            'class' => queasy\log\ConsoleLogger::class,
            'minLevel' => Psr\Log\LogLevel::DEBUG
        ]
    ]
];

初始化

$config = new queasy\config\Config('config.php'); // Can be also INI, JSON or XML

$logger = new queasy\log\Logger($config->logger);

$db = new queasy\db\Db($config->db);
$db->setLogger($logger);

$users = $db->users->searchByName([
    'searchName' => 'John'
]);

• 所有查询都将使用 Psr\Log\LogLevel::DEBUG 级别进行记录。此外，还可以使用任何与 PSR-3 兼容的其他日志记录类。