單例模式確保類別在全域僅有一個實例,並提供全域存取點。PHP 中最經典應用是資料庫連線管理,避免重複建立連線耗盡資源。本文從經典實作進階至多資料庫連線池、依賴注入容器整合、執行緒安全考量,提供生產級代碼範本。
<?php
declare(strict_types=1);
namespace App\Core;
class Database {
/** @var self|null 唯一實例 */
private static ?self $instance = null;
/** @var \mysqli 資料庫連線物件 */
public readonly \mysqli $connection;
/**
* 私有建構子:防止外部 new Database()
* @param string $host
* @param string $username
* @param string $password
* @param string $database
* @param int $port
*/
private function __construct(
string $host = '127.0.0.1',
string $username = 'root',
string $password = '',
string $database = 'app',
int $port = 3306
) {
$this->connection = new \mysqli($host, $username, $password, $database, $port);
if ($this->connection->connect_errno) {
throw new \RuntimeException("MySQL 連線失敗: {$this->connection->connect_error}");
}
$this->connection->set_charset('utf8mb4');
}
/** 防止複製 */
private function __clone() {}
/** 防止反序列化建立新實例 */
public function __wakeup() {
throw new \Exception("Cannot unserialize singleton");
}
/**
* 統一存取點
* @return self
*/
public static function getInstance(): self {
if (self::$instance === null) {
self::$instance = new self(); // 使用預設配置
}
return self::$instance;
}
/** 便利查詢方法 */
public function query(string $sql): \mysqli_result|bool {
return $this->connection->query($sql);
}
/** 解構時關閉連線 (PHP 請求結束自動調用) */
public function __destruct() {
if ($this->connection instanceof \mysqli) {
$this->connection->close();
}
}
}
實際專案常需連接多個資料庫 (主庫、從庫、不同業務庫)。以「連線標識」為鍵管理多個單例:
<?php
declare(strict_types=1);
namespace App\Core;
class DatabasePool {
/** @var array 連線池 */
private static array $instances = [];
/** @var \mysqli */
public readonly \mysqli $connection;
private function __construct(
string $host,
string $username,
string $password,
string $database,
int $port = 3306
) {
$this->connection = new \mysqli($host, $username, $password, $database, $port);
if ($this->connection->connect_errno) {
throw new \RuntimeException("MySQL 連線失敗 [$host:$port]: {$this->connection->connect_error}");
}
$this->connection->set_charset('utf8mb4');
// 可選:啟用持久連線 (mysqli::real_connect with MYSQLI_CLIENT_PERSISTENT)
}
private function __clone() {}
public function __wakeup() { throw new \Exception("Cannot unserialize"); }
/**
* 獲取/建立指定配置的連線實例
* @param array $config ['host','username','password','database','port']
* @return self
*/
public static function getInstance(array $config): self {
$key = $config['host'] . ':' . ($config['port'] ?? 3306) . '#' . $config['database'];
if (!isset(self::$instances[$key]) || !self::$instances[$key] instanceof self) {
self::$instances[$key] = new self(
$config['host'],
$config['username'],
$config['password'],
$config['database'],
$config['port'] ?? 3306
);
}
return self::$instances[$key];
}
/** 移除指定連線 (如配置變更、重連) */
public static function removeInstance(array $config): void {
$key = $config['host'] . ':' . ($config['port'] ?? 3306) . '#' . $config['database'];
if (isset(self::$instances[$key])) {
self::$instances[$key]->__destruct();
unset(self::$instances[$key]);
}
}
/** 關閉所有連線 (測試/關機用) */
public static function closeAll(): void {
foreach (self::$instances as $instance) {
$instance->__destruct();
}
self::$instances = [];
}
public function query(string $sql): \mysqli_result|bool {
return $this->connection->query($sql);
}
// 可封裝 prepare/execute/transaction 等方法
}
<?php
// 配置通常從 .env / config.php 載入
$configs = [
'main' => ['host' => 'db-master', 'username' => 'app', 'password' => 'secret', 'database' => 'main_db'],
'replica' => ['host' => 'db-replica', 'username' => 'app', 'password' => 'secret', 'database' => 'main_db'],
'analytics' => ['host' => 'db-analytics', 'username' => 'analyst', 'password' => 'secret', 'database' => 'stats_db'],
];
// 寫入操作用主庫
$dbMain = DatabasePool::getInstance($configs['main']);
$dbMain->query("INSERT INTO logs (msg) VALUES ('test')");
// 讀取操作用從庫
$dbReplica = DatabasePool::getInstance($configs['replica']);
$result = $dbReplica->query("SELECT * FROM logs ORDER BY id DESC LIMIT 10");
// 不同業務庫
$analyticsDb = DatabasePool::getInstance($configs['analytics']);
單例模式雖簡單,但難以測試 (全域狀態)、隱藏依賴、違反單一職責。現代框架 (Laravel, Symfony, Slim) 均採用依賴注入容器管理服務生命週期:
<?php
// 服務提供者註冊 (以 Laravel 風格為例)
$container->singleton('db.main', function() {
return new DatabaseConnection(config('database.connections.main'));
});
$container->singleton('db.replica', function() {
return new DatabaseConnection(config('database.connections.replica'));
});
// 控制器/服務透過建構子注入
class UserService {
public function __construct(
private DatabaseConnection $mainDb,
private DatabaseConnection $replicaDb
) {}
public function getUser(int $id): ?User {
return $this->replicaDb->query("SELECT * FROM users WHERE id = ?", [$id])->fetchObject(User::class);
}
}
優勢:
| 場景 | 是否適用 | 替代方案 |
|---|---|---|
| 資料庫連線池、Redis 連線池 | ⚠️ 可用但建議用 DI 容器管理 | DI 容器 singleton scope |
| 配置管理、日誌記錄器 | ✅ 適合 | DI 容器 singleton |
| 快取管理器 | ✅ 適合 | DI 容器 singleton |
| 業務邏輯服務 (UserService, OrderService) | ❌ 反模式 | DI 容器 scoped/transient |
| 請求相關狀態 (Session, Request, Auth) | ❌ 嚴重錯誤 | DI 容器 request-scoped |