Skip to content
This repository was archived by the owner on Oct 25, 2026. It is now read-only.

Latest commit

 

History

History
215 lines (159 loc) · 6.36 KB

doc.zh.md

File metadata and controls

215 lines (159 loc) · 6.36 KB

php-mysql-cli - 技術文件

最後更新:2026-10-25

返回 README

前置需求

  • PHP 8.0 以上
  • PHP pdo_mysql 擴充
  • Composer
  • MySQL 5.7 以上;使用 total() 需 MySQL 8.0 以上(視窗函式)

安裝

使用 Composer

composer require pardnchiu/mysql-cli

從原始碼

git 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();

JOIN、聚合與分頁總數

<?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"];

進階:原生 SQL 與錯誤處理

<?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());
}

API 參考

起點與連線

方法 簽章 說明
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