cuongcds · Trending

cuongcds/open-ses-php

Ví dụ gửi email qua AWS SES bằng AWS SDK for PHP.

View on GitHub Website / Demo Back to listing

0stars 0forks 1contributors PHP

README.md

# Open SES - PHP

Thư viện PHP (namespace `Open\Ses`) gửi email qua Open SES / AWS SES bằng AWS SDK for PHP, kèm các ví dụ trong [`examples/`](examples).

## Cài đặt qua Composer

Package có trên [Packagist](https://packagist.org/packages/cuongcds/open-ses-php):

```bash
composer require cuongcds/open-ses-php
```

Dùng trong code (autoload của Composer nạp `Open\Ses\*` và `aws/aws-sdk-php`):

```php
require __DIR__ . '/vendor/autoload.php';

use Open\Ses\SesMailer;

$mailer = new SesMailer(
    region: 'us-east-1',
    accessKeyId: '...',
    secretAccessKey: '...',
    senderEmail: 'no-reply@example.com',
    endpoint: 'https://open-ses.domain.com/ses',
);
$messageId = $mailer->send(['to@example.com'], 'Subject', '<p>Hello</p>', 'Hello');
```

## Chạy các ví dụ (khi clone repo)

```bash
composer install
cp .env.example .env
```

Điền các giá trị trong `.env`:

- `AWS_REGION`: region đã verify domain/email trên SES (ví dụ `ap-southeast-1`).
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`: IAM user/role có quyền `ses:SendEmail`, `ses:SendRawEmail`.
- `SES_SENDER_EMAIL`: địa chỉ đã verify trên SES (hoặc thuộc domain đã verify).
- `SES_CONFIGURATION_SET`: tên configuration set nếu cần theo dõi mở/click (không bắt buộc).
- `AWS_SES_ENDPOINT`: override host gọi API SES (không bắt buộc). Mặc định trong `.env.example` là endpoint chuẩn của AWS theo region (`https://email.ap-southeast-1.amazonaws.com`) — đổi region cho khớp `AWS_REGION`, hoặc thay bằng VPC endpoint/mock server riêng (ví dụ LocalStack: `https://localhost:4566`). Bỏ trống để SDK tự chọn endpoint theo `AWS_REGION`.

## Chạy ví dụ

Gửi email HTML/text đơn giản (SES `SendEmail`):

```bash
php examples/send-simple.php
```

Gửi email kèm file đính kèm (SES `SendRawEmail`, MIME thủ công):

```bash
php examples/send-with-attachment.php
```

## Tích hợp CodeIgniter 3.1.13

`examples/codeigniter/application/libraries/MY_Email.php` mở rộng `CI_Email` (theo cơ chế `MY_` prefix của CI3), nên code ứng dụng vẫn dùng `$this->load->library('email')` như bình thường. Transport được chọn bằng config `driver` trong `config/email.php`: `smtp` | `gmail` | `ses`. Cách dựng MIME, attachment, alt message, validate... vẫn do `CI_Email` xử lý; riêng `ses` thay phần gửi bằng `SesAdapter` (`SendRawEmail`).

1. Cài thư viện bằng `composer require cuongcds/open-ses-php` (xem "Cài đặt qua Composer"), rồi bật `$config['composer_autoload'] = TRUE;` trong `application/config/config.php` (chỉ cần cho driver `ses`).
2. Copy `application/libraries/MY_Email.php` và `application/config/email.php` vào project CI.
3. Đặt biến môi trường theo driver (hoặc sửa thẳng `config/email.php`):
   - `smtp`: `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_CRYPTO`.
   - `gmail`: `GMAIL_USER`, `GMAIL_APP_PASSWORD` (cần bật 2FA và tạo App Password; `From` phải là chính tài khoản hoặc alias đã verify).
   - `ses`: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SES_ENDPOINT` (Open SES), `SES_CONFIGURATION_SET`.
4. Chọn driver: đổi `MAIL_DRIVER` (hoặc `$config['driver']`), hoặc đổi lúc chạy bằng `$this->email->use_driver('ses')`.

```php
$this->load->library('email');
$this->email->from('sender@example.com', 'Sender')
    ->to('a@example.com')->subject('Hi')->message('<p>Hello</p>')->send();
```

Thêm dịch vụ SMTP khác: thêm 1 profile vào `$config['drivers']` với `protocol => 'smtp'` + các khoá `smtp_*`. Xem `application/controllers/Mail_demo.php`. Sau `send()` với driver `ses`, MessageId nằm ở `$this->email->message_id`.

## Cấu trúc

- `src/MailAdapterInterface.php`, `src/SesAdapter.php`: transport SES (`SendRawEmail`) dùng cho driver `ses` của `MY_Email`, tạo bằng `SesAdapter::fromConfig(...)` hoặc truyền sẵn `SesClient`.
- `src/SesMailer.php`: gửi email không kèm attachment qua API `SendEmail`.
- `src/SesRawMailer.php`: dựng MIME multipart thủ công để gửi kèm attachment qua API `SendRawEmail`.
- `examples/send-simple.php`, `examples/send-with-attachment.php`: script minh hoạ cách dùng.

## Lưu ý

- Nếu SES account đang ở **sandbox mode**, cả người gửi và người nhận đều phải được verify trước khi gửi được.
- Không commit file `.env` chứa credentials thật.

## Khác biệt so với AWS SES thật

Ví dụ này dùng nguyên AWS SDK for PHP (`aws/aws-sdk-php`) — code gọi API không đổi giữa AWS SES thật và Open SES, chỉ đổi cấu hình trong `.env`. Một số điểm khác cần lưu ý khi trỏ vào Open SES thay vì AWS:

| | AWS SES thật | Open SES |
|---|---|---|
| `AWS_SES_ENDPOINT` | Bỏ trống, hoặc endpoint AWS theo region (`email.<region>.amazonaws.com`) | Bắt buộc set, dạng `https://<domain>/ses` (ví dụ `https://open-ses.domain.com/ses` — thay `domain.com` bằng domain thật của Open SES) — route API nằm ở `/ses`, không phải `/`, do giới hạn kiến trúc của server nền |
| `AWS_REGION` | Phải khớp region đã verify identity trên AWS | Chuỗi tuỳ ý (ví dụ `us-east-1`) — chỉ dùng để tính chữ ký SigV4, server không kiểm tra region thật |
| API hỗ trợ | SES v1 (Query API) + SES v2 (JSON API) | Chỉ SES v1 Query API — 3 action `SendEmail`, `SendRawEmail`, `SendBulkTemplatedEmail` |
| Access Key / Secret Key | Cấp qua IAM | Cấp theo từng **App** trong Open SES console (mỗi App có Access Key/Secret Key + quota/rate-limit riêng) |
| Xác thực sender domain | Verify qua AWS Console (DNS TXT/CNAME) | Verify DKIM qua Open SES console (`App > Domains`) — có thể **tắt bắt buộc verify domain** cho từng App (chỉ nên dùng khi dev/test, không nên bật ở production) |
| TLS certificate | Chứng chỉ CA hợp lệ | `src/SesMailer.php`/`SesRawMailer.php` tự bỏ qua verify TLS khi có `endpoint` custom (dùng cho domain dev/nội bộ với cert self-signed) — khi không set `endpoint` (trỏ thẳng AWS thật), TLS verify vẫn bật bình thường |
| Sandbox mode | Có (giới hạn gửi tới địa chỉ chưa verify) | Không có khái niệm sandbox — chỉ giới hạn qua domain verification (nếu bật) và quota/rate-limit theo App |
| `ConfigurationSetName` (tracking mở/click) | Hỗ trợ | Chưa hỗ trợ ở phiên bản hiện tại — tham số bị bỏ qua nếu gửi |

Repository info

Default branch: master
Latest version: —
Created: 2026-09-21
Last activity: 2026-10-06
License: —
Open issues: 0
Watchers: 0

Topics

aws aws-ses codeigniter codeigniter3 mail mailer php php8 ses

Contributors

cuongcds

6 contributions