开始使用 - 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;