開始使用 - Medoo

版本: v2.3.0

快速開始

Medoo 的入門非常簡單。

環境需求

PHP 7.3+，安裝了 PDO 擴充。
SQL 資料庫，例如 MySQL、MSSQL、SQLite 或其他支援的引擎。
確保已安裝並啟用對應的 PDO 驅動程式。
基本 SQL 知識。

PHP PDO 擴充列表

下表列出了根據資料庫類型與平台需要安裝的 PDO 擴充功能。

名稱	驅動程式
MySQL、MariaDB	php_pdo_mysql
MSSQL	php_pdo_sqlsrv / php_pdo_dblib
Oracle	php_pdo_oci
SQLite	php_pdo_sqlite
PostgreSQL	php_pdo_pgsql
Sybase	php_pdo_dblib

安裝 PHP PDO 驅動

Medoo 需要 PHP 和 PDO 支援。如果尚未安裝 PDO，請依照下列步驟操作。

// 編輯 php.ini，並移除你要啟用之資料庫擴充前面的分號。

// Windows 使用 .dll，Linux/UNIX 使用 .so。

// 修改前
;extension=php_pdo_mysql.dll
;extension=php_pdo_mysql.so

// 修改後
extension=php_pdo_mysql.dll
extension=php_pdo_mysql.so

// 儲存檔案，然後重新啟動 PHP 或 Apache/Nginx。

// 如果 PDO 安裝正確，它會顯示在 phpinfo() 中。

也可以直接在終端安裝，PDO 擴充功能會自動啟用並完成設定。


$ sudo apt-get install php7.4-mysql

使用 Composer 安裝

如果你使用 Composer，請透過以下命令安裝 Medoo。


$ composer require catfan/medoo

Composer 會自動安裝相依套件。只有在需要手動更新相依套件時，才需要執行 composer update。


$ composer update

手動安裝

你也可以直接下載 medoo.php，將其放入專案中，再透過 require 引入。

require 'Medoo.php';

連線設定

傳入設定陣列即可初始化 Medoo 並建立資料庫連線。

// 載入 Composer 的自動載入器。
require 'vendor/autoload.php';

// 匯入 Medoo 命名空間。
use Medoo\Medoo;

$database = new Medoo([
	// 必填。
	'type' => 'mysql',
	'host' => 'localhost',
	'database' => 'name',
	'username' => 'your_username',
	'password' => 'your_password',

	// 可選。
	'charset' => 'utf8mb4',
	'collation' => 'utf8mb4_general_ci',
	'port' => 3306,

	// 可選：資料表前綴。所有資料表名稱都會變成 PREFIX_table。
	'prefix' => 'PREFIX_',

	// 可選：啟用查詢記錄。預設關閉，以獲得更好的效能。
	'logging' => true,

	// 可選。
	// 錯誤模式。
	// 定義 PDO 如何回報錯誤。
	// PDO::ERRMODE_SILENT（預設） | PDO::ERRMODE_WARNING | PDO::ERRMODE_EXCEPTION
	// 參考：https://www.php.net/manual/en/pdo.error-handling.php.
	'error' => PDO::ERRMODE_SILENT,

	// 可選。
	// PDO 連線選項。
	// 參考：https://www.php.net/manual/en/pdo.setattribute.php.
	'option' => [
		PDO::ATTR_CASE => PDO::CASE_NATURAL
	],

	// 可選：資料庫連線建立後要執行的命令。
	'command' => [
		'SET SQL_MODE=ANSI_QUOTES'
	]
]);

自訂 DSN 連線

你也可以提供自訂 DSN，用來連線至 Medoo 預設未直接支援的資料庫，或補充額外的 DSN 參數。

DSN 連線字串格式


{驅動程式}:{鍵}={值};{鍵}={值}

$database = new Medoo([
	'dsn' => [
		// DSN 中使用的 PDO 驅動程式名稱。
		'driver' => 'mydb',
		// 以鍵值對形式提供的 DSN 參數。
		'server' => '12.23.34.45',
		'port' => '8886'
	],
	// 可選：指定 Medoo 應採用的資料庫方言行為。
	'type' => 'mysql',

	'username' => 'your_username',
	'password' => 'your_password'
]);

// 最終產生的 DSN 字串：
mydb:server=12.23.34.45;port=8886

透過 PDO 物件初始化

你也可以根據現有且已初始化的 PDO 物件建立 Medoo 實例。

$pdo = new PDO('mysql:dbname=test;host=127.0.0.1', 'user', 'password');

$database = new Medoo([
	// 重用已初始化並完成連線的 PDO 實例。
	'pdo' => $pdo,

	// 可選：指定 Medoo 應採用的資料庫方言行為。
	'type' => 'mysql'
]);

MySQL

此選項僅適用於 MySQL。

$database = new Medoo([
	// 可選：MySQL socket（不要與 server 和 port 同時使用）。
	'socket' => '/tmp/mysql.sock',
]);

MariaDB

MariaDB 的處理方式與 MySQL 相同。資料庫類型會自動對應到 mysql。

$database = new Medoo([
	'type' => 'mariadb',
	'host' => 'localhost',
	'database' => 'name',
	'username' => 'your_username',
	'password' => 'your_password',
]);

MSSQL

現代 MSSQL 連線通常會在 Windows 和 Linux/UNIX 上透過 pdo_sqlsrv 擴充建立。Medoo 預設使用 pdo_sqlsrv 驅動程式。對於仍需 pdo_dblib 的舊環境，請在初始化時明確指定驅動程式。詳細資訊請參閱 https://github.com/Microsoft/msphpsql。

$database = new Medoo([
	'type' => 'mssql',
	'host' => 'localhost',
	'database' => 'name',
	'username' => 'your_username',
	'password' => 'your_password',

	// 可選：應用程式名稱。
	'appname' => 'test',

	// 可選。
	// 強制 Medoo 為 MSSQL 使用 dblib 驅動程式。
	// 預設值：sqlsrv。
	'driver' => 'dblib'
]);

使用 sqlsrv 驅動程式時，Medoo 也支援 MSSQL 的連線選項。詳細資訊請參閱 https://docs.microsoft.com/en-us/sql/connect/php/connection-options?view=sql-server-2017。

$database = new Medoo([
	'type' => 'mssql',
	'host' => 'localhost',
	'database' => 'name',
	'username' => 'your_username',
	'password' => 'your_password',

	// 可選：MSSQL 連線選項。
	'application_intent' => 'ReadOnly',
	'attach_db_file_name' => './database.sql',
	'authentication' => 'SqlPassword',
	'column_encryption' => 'Enabled',
	'connection_pooling' => 1,
	'encrypt' => 1,
	'failover_partner' => 'MultiSubnetFailover',
	'key_store_authentication' => 'KeyVaultPassword',
	'key_store_principal_id' => 'AzureName',
	'key_store_secret' => 'AzurePass',
	'login_timeout' => '20',
	'multiple_active_result_sets' => 1,
	'multi_subnet_failover' => 'Yes',
	'scrollable' => 'buffered',
	'trace_file' => './path',
	'trace_on' => 1,
	'transaction_isolation' => PDO::SQLSRV_TXN_SNAPSHOT,
	'transparent_network_ip_resolution' => 'Enabled',
	'trust_server_certificate' => 1,
	'wsid' => 'Computer1'
]);

SQLite

檔案型資料庫

$database = new Medoo([
	'type' => 'sqlite',
	'database' => 'my/database/path/database.db'
]);

記憶體資料庫

$database = new Medoo([
	'type' => 'sqlite',
	'database' => ':memory:'
]);

臨時資料庫

連線關閉時臨時資料庫將被刪除。

$database = new Medoo([
	'type' => 'sqlite',
	'database' => ''
]);

// 或者完全省略 database 選項。
$database = new Medoo([
	'type' => 'sqlite'
]);

檢查 DSN 字串

你可以透過呼叫 info() 來查看最終產生的 DSN 字串。

$database = new Medoo([
	'type' => 'mysql',
	'host' => '127.0.0.1',
	'database' => 'test',
	'username' => 'your_username',
	'password' => 'your_password',
]);

echo $database->info()['dsn'];

// mysql:dbname=test;host=127.0.0.1

測試模式

此模式非常適合測試。你可以在不同資料庫類型之間，透過 $database->queryString 驗證產生的 SQL；查詢會被產生，但不會執行。

$database = new Medoo([
	'testMode' => true
]);

// 設定資料庫類型。
$database->type = 'mysql';

$database->select("account", ["user_name"], ["user_id[>]" => 10]);

echo $database->queryString;