最後更新:2026-10-25
返回 README
- PHP 8.0 以上
- PHP
pdo_mysql擴充 - Composer
- MySQL 5.7 以上;使用
total()需 MySQL 8.0 以上(視窗函式)
composer require pardnchiu/mysql-cligit clone https://github.com/pardnio/php-mysql-cli.git
cd php-mysql-cli
composer install套件以 PSR-4 將 pardnchiu\ 對應至 src/。
<TARGET> 為 READ 或 WRITE,使用到的目標需設定完整六個變數;原始碼中的預設值因型別轉換優先序不會生效。
| 變數 | 必填 | 說明 |
|---|---|---|
DB_<TARGET>_HOST |
是 | 主機 |
DB_<TARGET>_PORT |
是 | 埠號 |
DB_<TARGET>_USER |
是 | 帳號 |
DB_<TARGET>_PASSWORD |
是 | 密碼 |
DB_<TARGET>_DATABASE |
是 | 資料庫名稱 |
DB_<TARGET>_CHARSET |
是 | 編碼,建議 utf8mb4 |
DB_READ_HOST=127.0.0.1
DB_READ_PORT=3306
DB_READ_USER=read_user
DB_READ_PASSWORD=read_password
DB_READ_DATABASE=app
DB_READ_CHARSET=utf8mb4
DB_WRITE_HOST=127.0.0.1
DB_WRITE_PORT=3306
DB_WRITE_USER=write_user
DB_WRITE_PASSWORD=write_password
DB_WRITE_DATABASE=app
DB_WRITE_CHARSET=utf8mb4| 項目 | 值 |
|---|---|
| 重試 | 最多 3 次,間隔 100ms、200ms,最後一次失敗拋出原例外 |
| Session 逾時 | wait_timeout、interactive_timeout 設為 600 秒 |
| PDO 選項 | ERRMODE_EXCEPTION、FETCH_ASSOC |
| 慢查詢 | 執行超過 20ms 寫入 [Info] PD\SQL: [Slow Query: <ms>ms] [<sql>] |
| 連線共用 | 連線為靜態屬性,第一次呼叫時依目標建立並在整個請求中共用;要改用另一個目標需先 SQL::close() |
<?php
require __DIR__ . '/vendor/autoload.php';
use pardnchiu\SQL;
$users = SQL::table("users")
->where("status", "active")
->where("age", ">", 18)
->orderBy("created_at", "DESC")
->limit(20)
->get();<?php
require __DIR__ . '/vendor/autoload.php';
use pardnchiu\SQL;
$page = 2;
$rows = SQL::table("orders")
->total()
->leftJoin("users", "orders.user_id", "users.id")
->select("orders.user_id", "COUNT(orders.id) AS order_count", "SUM(orders.amount) AS amount")
->where("orders.created_at", ">=", "2026-01-01")
->groupBy("orders.user_id")
->orderBy("amount", "DESC")
->limit(10)
->offset(($page - 1) * 10)
->get();
$total = $rows[0]["total"] ?? 0;<?php
require __DIR__ . '/vendor/autoload.php';
use pardnchiu\SQL;
$id = SQL::table("users", "WRITE")->insertGetId([
"name" => "Pardn",
"email" => "dev@example.com",
"created_at" => "2026-10-25 12:00:00",
]);
$result = SQL::table("users", "WRITE")
->where("id", $id)
->update([
"last_login" => "NOW()",
"status" => "active",
]);
echo $result["affected_rows"];<?php
require __DIR__ . '/vendor/autoload.php';
use pardnchiu\SQL;
try {
$rows = SQL::read(
"SELECT u.id, COUNT(o.id) AS orders FROM users u LEFT JOIN orders o ON u.id = o.user_id WHERE u.created_at > ? GROUP BY u.id",
["2026-01-01"]
);
SQL::close();
SQL::write("UPDATE users SET status = ? WHERE id = ?", ["inactive", 42]);
} catch (\InvalidArgumentException $e) {
error_log("[Invalid] sql: " . $e->getMessage());
} catch (\Throwable $e) {
error_log("[Upstream] sql: " . $e->getMessage());
}| 方法 | 簽章 | 說明 |
|---|---|---|
table |
table(string $table, string $target = "READ"): static |
建立連線(若尚未建立)並重設建構器狀態 |
read |
read(string $query, array $params = []): array |
以 READ 目標執行原生 SQL |
write |
write(string $query, array $params = []): array |
以 WRITE 目標執行原生 SQL |
query |
query(string $query, array $params = []): array |
直接在現有連線執行;未連線拋出 \Exception |
close |
close(): void |
釋放連線並清空狀態 |
| 方法 | 簽章 | 說明 |
|---|---|---|
select |
select(string ...$fields) 或 select(array $fields) |
預設 *;不含 . 的欄位整段加反引號,函式運算式需含 .(如 COUNT(orders.id))才不會被包住 |
total |
total(): static |
外包 SELECT COUNT(*) OVER() AS total, data.* |
join/innerJoin |
join($table, $first, $operator, $second = null) |
INNER JOIN;省略 $second 時運算子為 = |
leftJoin |
同上 | LEFT JOIN |
rightJoin |
同上 | RIGHT JOIN |
where |
where($column, $operator, $value = null) |
省略 $value 時為 =;LIKE 自動包成 %value%;多個條件以 AND 串接 |
orderBy/order |
orderBy($column, $direction = "DESC") |
僅接受 ASC/DESC,否則拋出 \InvalidArgumentException |
groupBy |
groupBy(string ...$columns) 或 groupBy(array $columns) |
GROUP BY |
limit |
limit(int $limit) |
LIMIT |
offset |
offset(int $offset) |
OFFSET |
| 方法 | 回傳 | 說明 |
|---|---|---|
get() |
array |
查詢結果列(關聯陣列) |
insert(array $data)/insertGetId(array $data) |
string|null |
新增一列並回傳 lastInsertId |
update(array $data) |
array |
["info" => string, "insert_id" => string, "affected_rows" => int];未呼叫 where() 時會更新整張表 |
update() 中值為下列函式名稱(不分大小寫)時以原文寫入而非綁定:NOW()、CURRENT_TIMESTAMP、UUID()、RAND()、CURDATE()、CURTIME()、UNIX_TIMESTAMP()、UTC_TIMESTAMP()、SYSDATE()、LOCALTIME()、LOCALTIMESTAMP()、PI()、DATABASE()、USER()、VERSION()。
| 情境 | 例外 |
|---|---|
未呼叫 table() 就執行 |
\Exception("Invalid: Table (null).") |
read()/write() 傳入空查詢 |
\InvalidArgumentException("Invalid: Query (empty).") |
read()/write() 參數非陣列 |
\InvalidArgumentException("Invalid: Params (not an array).") |
| 排序方向不合法 | \InvalidArgumentException("Invalid: Direction (<dir>).") |
| 連線重試耗盡 | 原始 \PDOException |
©️ 2024 邱敬幃 Pardn Chiu