本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 PHP 的 Aurora DSQL 連接器 `PDO_PGSQL`
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql"></a>

[Aurora DSQL Connector for PHP](https://github.com/awslabs/aurora-dsql-connectors/tree/main/php/pdo_pgsql) 是建置在 上的 PHP 連接器[https://www.php.net/manual/en/ref.pdo-pgsql.php](https://www.php.net/manual/en/ref.pdo-pgsql.php)，整合 IAM 身分驗證，以將 PHP 應用程式連線至 Amazon Aurora DSQL 叢集。

連接器會處理字符產生、SSL 組態和連線管理，讓您可以專注於應用程式邏輯。

## 關於連接器
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-about"></a>

Aurora DSQL Connector for PHP 在 上新增了身分驗證層`PDO_PGSQL`，可處理產生 IAM 字符，讓您使用現有的 PDO 工作流程連線到 Aurora DSQL。Amazon Aurora DSQL 需要具有時間限制權杖的 IAM 身分驗證，連接器會自動為您管理權杖產生。

### 什麼是 Aurora DSQL 身分驗證？
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-authentication"></a>

在 Aurora DSQL 中，**身分驗證**涉及：
+ **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證
+ **權杖產生**：連接器使用 AWS 登入資料產生身分驗證權杖，這些權杖具有可設定的生命週期

Aurora DSQL Connector for PHP 了解這些要求，並在建立連線時自動產生 IAM 身分驗證字符。

### 功能
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-features"></a>
+ **自動 IAM 身分驗證** - 處理 Aurora DSQL 字符產生和重新整理
+ **建置於 `PDO_PGSQL`** - 包裝適用於 PHP 的標準 PostgreSQL 延伸模組
+ **無縫整合** - 適用於現有的 PDO 工作流程
+ **SSL 強制執行** - 一律使用 SSL 搭配 `verify-full` 模式和直接 TLS 交涉
+ **區域自動偵測** - 從 Aurora DSQL 叢集主機名稱擷取 AWS 區域
+ **AWS 憑證支援** - 支援 AWS 設定檔和自訂憑證提供者
+ **OCC 重試** - 選擇加入具有指數退避和抖動的樂觀並行控制重試
+ **PSR-3 記錄** - 重試診斷的相容記錄

## 範例應用程式
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-example-application"></a>

如需完整範例，請參閱 GitHub 上的[範例應用程式](https://github.com/awslabs/aurora-dsql-connectors/tree/main/php/pdo_pgsql/example)。

## 快速入門指南
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-quick-start"></a>

### 要求
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-requirements"></a>
+ PHP 8.2 或更新版本
+ `ext-pdo_pgsql` 延伸模組
+ [存取 Aurora DSQL 叢集](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS 設定的登入資料 （透過 AWS CLI、環境變數或 IAM 角色）

## 安裝
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-installation"></a>

將套件新增至您的專案：

```
composer require awslabs/aurora-dsql-pdo-pgsql
```

## Usage
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-usage"></a>

### 組態型連線
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-config-connection"></a>

```
<?php

require_once 'vendor/autoload.php';

use Aws\AuroraDsql\PdoPgsql\AuroraDsql;
use Aws\AuroraDsql\PdoPgsql\DsqlConfig;

$config = new DsqlConfig(
    host: 'your-cluster.dsql.us-east-1.on.aws',
    occMaxRetries: 3
);
$pdo = AuroraDsql::connect($config);

// Read
$stmt = $pdo->query('SELECT 1 AS result');
$row = $stmt->fetch(PDO::FETCH_ASSOC);
echo "Connected: {$row['result']}\n";

// Transactional write with automatic OCC retry
$id = $pdo->transaction(function (PDO $conn): string {
    $stmt = $conn->prepare('INSERT INTO users (name) VALUES (?) RETURNING id');
    $stmt->execute(['Alice']);
    return $stmt->fetchColumn();
});
```

### 連線字串格式
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-connection-string"></a>

對於簡單的指令碼或當您偏好連線字串語法時，連接器支援 `postgres://`和具有 Aurora DSQL 特定查詢參數的`postgresql://`連線字串：

```
$pdo = AuroraDsql::connectFromDsn(
    'postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres?region=us-east-1'
);
```

支援的查詢參數：`region`、`profile`、`tokenDurationSecs`、`ormPrefix`。

### OCC 重試
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-occ-retry"></a>

Aurora DSQL 使用樂觀並行控制 (OCC)。當兩個交易修改相同的資料時，第一個遞交獲勝，第二個收到 OCC 錯誤。

OCC 重試是選擇加入。在組態`occMaxRetries`中設定 ，以啟用具有指數退避和抖動的自動重試：

```
$config = new DsqlConfig(
    host: 'your-cluster.dsql.us-east-1.on.aws',
    occMaxRetries: 3
);
$pdo = AuroraDsql::connect($config);

// Single statements are automatically retried via exec()
$pdo->exec("CREATE INDEX ASYNC ON users (email)");

// Multi-statement transactions are retried via transaction()
$pdo->transaction(function (PDO $conn) {
    $conn->exec("UPDATE accounts SET balance = balance - 100 WHERE id = 1");
    $conn->exec("UPDATE accounts SET balance = balance + 100 WHERE id = 2");
});
```

**重要**  
`transaction()` 會在內部管理 `beginTransaction()`/`commit()`/`rollBack()`。您的回呼應僅包含資料庫操作，並且可以安全地重試。

## 組態選項
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-configuration"></a>

連接器也接受具有 組態查詢參數的 `postgres://`和 `postgresql://`連線字串。支援的查詢參數：`region`、`tokenDurationSecs`、 `profile`和 `ormPrefix`。


| 欄位 | Type | 預設 | Description | 
| --- | --- | --- | --- | 
| host | string | （必要） | 叢集端點或 26 個字元的叢集 ID | 
| region | ?string | null （自動偵測） | AWS region；如果 host 是叢集 ID，則為必要 | 
| user | string | "admin" | 資料庫使用者 | 
| database | string | "postgres" | 資料庫名稱 | 
| port | int | 5432 | Database port (資料庫連線埠) | 
| profile | ?string | null | AWS 登入資料的設定檔名稱 | 
| credentialsProvider | ?\$1Closure | null | 自訂 AWS 登入資料供應商 | 
| tokenDurationSecs | int | 900 (15 分鐘） | 字符有效性持續時間，以秒為單位 | 
| occMaxRetries | ?int | null （已停用） | exec() 和 的預設最大 OCC 重試次數 transaction() | 
| ormPrefix | ?string | null | 前綴為 的 ORM 字首 application\$1name | 
| logger | ?LoggerInterface | null | 用於重試警告和診斷的 PSR-3 記錄器 | 

## 身分驗證
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-auth"></a>

連接器會使用 AWS 登入資料產生字符，自動處理 Aurora DSQL 身分驗證。如果您未提供區域，連接器會從主機名稱剖析該 AWS 區域。

如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱[Aurora DSQL 的身分驗證和授權](authentication-authorization.md)。

### 管理員與一般使用者
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-admin-vs-regular"></a>
+ 名為「admin」的使用者會自動使用管理員身分驗證字符
+ 所有其他使用者都使用一般身分驗證字符
+ 連接器會為每個連線動態產生字符