PHPackages                             tqxxkj/simple-sql - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. tqxxkj/simple-sql

ActiveLibrary[Database & ORM](/categories/database)

tqxxkj/simple-sql
=================

简单的 SQL 查询工具

10PHP

Since Dec 7Pushed 4y ago1 watchersCompare

[ Source](https://github.com/JiangChunbo/simple-sql)[ Packagist](https://packagist.org/packages/tqxxkj/simple-sql)[ RSS](/packages/tqxxkj-simple-sql/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

SimpleSql
=========

[](#simplesql)

SimpleSql 是一个用 PHP 编写的，依赖 PDO 的简化数据库操作工具。

参考：Java JDBC 规范, MyBatis, MyBatis Plus

1. 入门
-----

[](#1-入门)

### 1.1. Connection 连接抽象

[](#11-connection-连接抽象)

#### 1.1.1. PDO

[](#111-pdo)

一个 PDO 对象本质上是一个数据库连接。在 SimpleSql 中。

> SimpleSql 提供了一个 `PdoBuilder` 构造器类用于简化构造 PDO 对象

#### 1.1.2. Connection

[](#112-connection)

尽管 PDO 代表着一个连接（Connection），但暴露的接口可能并不完善，所以另外提供了一个 Connection 接口，具有更多抽象功能。

> `PdoConnection` 是对 PDO 的包装 `MysqlConnection` 继承于 `PdoConnection`， 是对 MySQL 数据库连接的特定实现。

#### 1.1.3. DataSource

[](#113-datasource)

数据源，获取数据库连接的工厂。DataSource 是 SimpleSql 提供的接口，并提供了两个实现类：

- `UnpooledDataSource`，每次获取连接都会创建新的 PDO
- `PooledDataSource`，每次获取连接会从空闲的连接池中获取

> 注意，由于不涉及多线程共享数据库连接池，因此 `PooledDataSource` 的空闲连接理论上只有一个。

### 1.2. Statement 抽象

[](#12-statement-抽象)

#### 1.2.1. PDOStatement

[](#121-pdostatement)

`PDOStatement` 是 PDO 自带的 Statement 对象

#### 1.2.2. Statement

[](#122-statement)

`Statement` 是 SimpleSql 的接口，对 PDOStatement 的包装。

#### 1.2.3. PreparedStatement

[](#123-preparedstatement)

`PreparedStatement` 是一个预编译的 Statement

> SimpleSql 提供了 MySQL 的 `PreparedStatement` 的实现 —— `MysqlPreparedStatement`

### 1.3. 事务抽象

[](#13-事务抽象)

事务仅对于支持事务的数据库有效，否则并不生效。

#### 1.3.1. Transaction

[](#131-transaction)

`Tranasction` 是 SimpleSql 的事务抽象，同时提供了一个实现类 `PdoTransaction`。

因为每个事务依赖于一个数据库的连接，因此，`Transaction` 是对连接（PDO）的包装。

#### 1.3.2. TransactionFactory

[](#132-transactionfactory)

`TransactionFactory` 是 SimpleSql 提供的接口，是一个提供 `Transaction` 的工厂类。SimpleSql 也提供了一个基于 PDO 的实现类 `PdoTransactionFactory`。

### 1.4. 执行器抽象

[](#14-执行器抽象)

#### 1.4.1. Executor

[](#141-executor)

执行器是 SimpleSql 提供的执行 SQL 语句的抽象接口，是对事务接口的包装，也可以说是对数据库连接的包装。

#### 1.4.2. BaseExecutor

[](#142-baseexecutor)

`BaseExecutor` 是所有执行器的父类，应当实现所有通用接口，如事务的提交与回滚等。

#### 1.4.3. SimpleExecutor

[](#143-simpleexecutor)

`SimpleExecutor` 是一个简单的执行器实现。

### 1.5. SqlSession 抽象

[](#15-sqlsession-抽象)

#### 1.5.1. SqlSession

[](#151-sqlsession)

`SqlSession` 是数据库会话的抽象接口，也是对执行器的包装。

> SimpleSql 提供了一个默认的实现类 DefaultSqlSession

#### 1.5.2. SqlSessionFactory

[](#152-sqlsessionfactory)

获得 SqlSession 的工厂类

2. 使用方式
-------

[](#2-使用方式)

### 2.1. 获得一个会话

[](#21-获得一个会话)

```
use Tqxxkj\SimpleSql\Mapping\Environment;
use Tqxxkj\SimpleSql\Session\Defaults\DefaultSqlSessionFactory;

// 创建一个环境对象并设置属性
$environment = new Environment();
$environment->setProperties('localhost:test', 'mysql', 'localhost', '3306', 'root', 'JINGjiuBUchi', 'test');

// 将环境对象赋值给 sqlSessionFactory
$sqlSessionFactory = new DefaultSqlSessionFactory($environment);

// 获得一个会话对象
$session = $sqlSessionFactory->openSession();
```

无参 openSession() 默认具有以下行为：

- 使用默认的执行器
- 使用默认的事务隔离级别（对非自动提交有效）
- 自动提交

### 2.2. 查询数据

[](#22-查询数据)

```
$session = $sqlSessionFactory->openSession();
$list = $session->selectList("select * from `users`");
$user = $session->selectOne("select * from `users` where `id`=?", [
    1 => [1, PDO::PARAM_INT]
]);
$user = $session->selectOne("select * from `users` where `id`=:id", [
    ':id' => [1, PDO::PARAM_INT]
]);
```

一般有三种调用方式：

- 无参执行 SQL
- 有参执行 SQL，以 ? 为占位符，传入从 1 开始的索引数字
- 有参执行 SQL，以 :name 为占位符，传入对应的映射值

> 这种 session 调用方式是最原始的方式 需要指定参数类型，目前支持 PDO::PARAM\_INT 和 PDO::PARAM\_STR 两种

### 2.3. 添加数据

[](#23-添加数据)

```
$session = $sqlSessionFactory->openSession();
$list = $session->insert("insert into `users`(`username`) values(?)", [
    1 => ['hello', PDO::PARAM_STR]
]);
```

### 2.4. 删除数据或者修改数据

[](#24-删除数据或者修改数据)

```
$session = $sqlSessionFactory->openSession();
$affected_num = $session->update("delete from `users` where `id`=?", [
    1 => [1, PDO::PARAM_INT]
]);
$affected_num = $session->update("update `users` set `username`=? where `id`=?", [
    1 => ['hi', PDO::PARAM_STR],
    2 => [1, PDO::PARAM_INT]
]);
```

3. 进阶用法
-------

[](#3-进阶用法)

### 3.1. 使用 DAO 模型操作数据库

[](#31-使用-dao-模型操作数据库)

> 该项目约定数据库的设计中，主键不支持复合主键，且名称叫 id，类型为 int（硬编码）

#### 步骤一

[](#步骤一)

定义一个对应数据库表的 Service 对象，并继承 BaseService。

声明的自定义 Service 需要实现 tableName() 显式地表示表名称

```
class UserService extends BaseService
{
    protected function tableName(): string
    {
        return 'users';
    }
}
```

#### 步骤二

[](#步骤二)

传入 $session 给 Service 进行构造，使用 BaseService 暴露的方法进行操作

```
$session = $sqlSessionFactory->openSession(null, 0, true);
$usersService = new UserService($session);
$usersService->select();
```

### 3.2. save

[](#32-save)

调用 save 方法，传入一个关联数组，方法执行完毕之后，关联数组会得到一个以 'id' 为 key 的值，该值为实体的自增 id。

```
$user = [
    'username' => 'jcb',
    'password' => '123456',
    'password_salt' => '789456'
];
$usersService->save($user);
```

### 3.3. saveBatch

[](#33-savebatch)

保存多个实体，自增主键与 save 一样，传递给原数组

```
$entityList = [
    [
        'username' => 'jcb',
        'password' => '123456',
        'password_salt' => '789456',
    ],
    [
        'username' => 'zx',
        'password' => '999999',
        'password_salt' => '88888',
    ]
];
$userService->saveBatch($entityList);
```

### 3.4. getById

[](#34-getbyid)

通过 id 获得实体

```
$user = $userService->getById(1);
```

### 3.5. listByIds

[](#35-listbyids)

通过 id 数组获得实体

```
$users = $userService->listByIds([1, 2]);
```

### 3.6. getOne

[](#36-getone)

```
$qw = QueryWrapper::get()->eq('username', 'jcb');
$user = $userService->getOne($qw);
```

> - 查询数据通过 Wrapper 进行构造
> - 内部会在末尾添加 limit 1

### 3.7. list

[](#37-list)

根据查询条件获得所有数据

```
$qw = QueryWrapper::get();
$qw->select('count(*)', 'username');    // 支持聚合查询
$qw->groupBy('username');               // 分组
$qw->orderBy('count(*)', false);        // 聚合函数排序
$qw->having('count(*) > {0}', [5]);     // 分组筛选
$username_count = $userService->list($qw);
```

### 3.8. count

[](#38-count)

计数

```
$qw = QueryWrapper::get()->eq('username', 'jcb');
$count = $userService->count($qw);
```

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity28

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/77043106fb0a9bf06d09840f2e7750f342ddfb23f3db696716928dd091c4f1f9?d=identicon)[JiangChunbo](/maintainers/JiangChunbo)

---

Top Contributors

[![jiangchunbo](https://avatars.githubusercontent.com/u/50109770?v=4)](https://github.com/jiangchunbo "jiangchunbo (8 commits)")

### Embed Badge

![Health badge](/badges/tqxxkj-simple-sql/health.svg)

```
[![Health](https://phpackages.com/badges/tqxxkj-simple-sql/health.svg)](https://phpackages.com/packages/tqxxkj-simple-sql)
```

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90340.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)