ヘルパーと定数
クライアントのメソッド以外にパッケージが定義しているもの。
静的メソッド
| メソッド | 内容 |
|---|---|
| OpenEmail::init(), OpenEmail::getClient() | 共有クライアントを一度設定すれば、あとはどこからでも使えます。init が一度も実行されていない場合、getClient() は環境変数からクライアントを作ります。 |
| OpenEmail::resetClient() | 共有クライアントを破棄し、次の getClient() で新しいクライアントが作られるようにします。テストのケース間で必要になるのはこれです。 |
| new OpenEmail()、OpenEmail::createClient() | 独立したクライアント。どちらも、省略したものは環境変数から読み取ります。 |
| OpenEmail::createTempMail() | API キーを持たない使い捨て受信箱用のクライアント。 |
| OpenEmail::verifyWebhookSignature() | 配信の署名を定数時間で検証します。リプレイの許容期間は 5 分で、toleranceSeconds: で変更できます。デコードされたイベントを返し、失敗時には必ず WebhookSignatureException をスローします。 |
| OpenEmail::toBase64() | 添付ファイルのバイト列を、文字列、ストリームリソース、SplFileInfo、PSR-7 ストリームから Base64 にします。 |
| OpenEmail::isApiKey() | 値が oe_live_ または oe_test_ の形をしているかどうか。形式の検査であり、そのキーがまだ有効であることの証明ではありません。 |
| OpenEmail::isAccessToken() | 値が OAuth アクセストークンの形をしているかどうか。1〜512 文字で、oe_ で始まらないものです。 |
| OpenEmail::isSealed() | メッセージのボディが暗号文かどうか。2 つの署名形式では、ボディが平文で届いているため false です。 |
| OpenEmail::resolveLanguage()、OpenEmail::languageByCode()、OpenEmail::isRtlLanguage() | 言語ピッカーに必要な検索メソッドで、同梱の Languages::ALL テーブルを対象とします。 |
| $client->close() | クライアントの cURL ハンドルと、その背後の接続を解放します。参照されなくなったクライアントも、PHP が解放するときに同じことを行います。 |
定数
TypeScript SDK がエクスポートする値の集合は、どれも OpenEmail\Constants の final クラスで、メンバーごとに同じ名前の定数を 1 つ持ちます。そのため WebhookEvents::EMAIL_DELIVERED は email.delivered です。values() は集合全体を返し、外部から来た値を確認するのにも使えます。
use OpenEmail\Constants\ApiScopes;use OpenEmail\Constants\PageLimits;use OpenEmail\Constants\WebhookEvents; $events = WebhookEvents::values(); $scopes = [ApiScopes::EMAILS_SEND, ApiScopes::THREADS_READ]; $known = in_array('email.delivered', $events, true); echo count($events), ' ', implode(',', $scopes), ' ', PageLimits::MAX_LIMIT, ' ', $known ? 'known' : 'unknown', PHP_EOL;| 定数 | 内容 |
|---|---|
| OpenEmail::VERSION | パッケージのバージョン。 |
| ApiScopes | キー作成画面のためのスコープ語彙。 |
| WebhookEvents, WebhookSignatureHeaders | エンドポイントが購読できるイベントと、配信に付くヘッダーの名前。 |
| ErrorTypes | ApiException::$type が取るエラーの語彙。 |
| PageLimits | ほとんどのページ分割される一覧における limit: の最大値と既定値である MAX_LIMIT と DEFAULT_LIMIT で、それぞれ 100 と 25 です。それより多く受け付ける一覧もいくつかあり、各メソッドのリファレンスにそう書かれています。 |
| RuleFields, RuleOperators, RuleActions | ルールの条件とアクションを組み立てるための語彙。 |
| MessageEncryptionFormats | 受信処理が識別できる 5 つのエンベロープ。そのうち 3 つは封緘されています。 |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | me->get と me->ping が表す資格情報の種類、確認コードの確認方法、そして確認が失敗するときのコード。 |
| ThreadSorts、PeopleSorts、FileSorts とその他の *Sorts | 一覧を並べ替えられる順序。 |
| FormStatuses、BroadcastStatuses、SuppressionReasons とその他の集合 | リソースのフィールドが取り得る値。各集合は、保持するものにちなんで名付けられています。 |
| Languages::ALL | 翻訳付きの送信やプレビューが受け付けるすべての言語で、コード、名前、書字方向を持ちます。 |
オブジェクト
レスポンスは、デコードされた JSON を連想配列にしたものです。パッケージが独自のオブジェクトを作るのは答えの形を整える場合だけで、それぞれ OpenEmail\Result にあり、不変で、行に対する IteratorAggregate であり Countable でもあります。
| クラス | 持っているもの |
|---|---|
| Page | items、hasMore、nextCursor。ページ分割されるすべての list から返ります。 |
| PeoplePage | 同じものに seen を加えたもの。contacts->listPeople から返ります。 |
| TempMessagesPage | 同じものに expiresAt を加えたもの。tempMail->listMessages から返ります。 |
| AddressBookPage, AddressBook | unrestricted、addresses、domains。addresses->list（hasMore と nextCursor 付き）と addresses->listAll から返ります。 |
| BatchResult | items、sent、failed。emails->sendBatch から返ります。 |
| TemplateSends | items、total、page、pageSize。templates->listSends から返ります。 |
| OpenEmail\Http\HttpRequest, OpenEmail\Http\HttpResponse | httpClient: が受け取り、返すもの。var_dump()、print_r()、json_encode() ではリクエストの Authorization ヘッダーが [redacted] と表示されますが、var_export() と Symfony の dump() ではそのまま表示されます。 |
パッケージがスローするすべての例外は OpenEmail\Exception\OpenEmailException を実装しています。ApiException とそのサブクラス、NetworkException、WebhookSignatureException、そして InvalidArgumentException です。最後のものは、API が何かを返したからではなく、呼び出しそのものの誤りに対してスローされます。
まだラップされていないエンドポイント
パッケージのリリースが、すでに動作しているエンドポイントとの間に立ちはだかってはなりません。$client->raw->request() はパスと名前付き引数を受け取り、クライアントの資格情報、ベース URL、タイムアウト、リトライポリシーを適用したうえで、デコードされたボディを返します。
$result = $client->raw->request( '/labels', method: 'POST', query: ['dryRun' => true], body: ['name' => 'Invoices'], repeatable: true,); var_dump($result);GET は他の読み取りと同様にリトライされます。それ以外のメソッドは、2 回送信されてもよいという宣言である repeatable: true を渡さない限り 1 回だけ送信されます。query: は null や空の値を除外し、apiKey: は他のすべてのメソッドと同じように動作します。
あえて行わないこと
- リクエストボディの検証は行いません。ルールの唯一の写しはサーバーのスキーマであり、ここに 2 つ目の写しを置けば、いずれ 2 年前に誰かが固定したバージョンが、新しいサーバーなら受け入れるアドレスを拒否することになります。
- curl と json の拡張以外に実行時の依存関係はありません。PSR-18 クライアントは選択肢であって、必須ではありません。
- レスポンスの形を変えるのは 1 つの方法だけです：コレクションの
data配列をエンベロープから取り出し、上のオブジェクトのいずれかにします。それ以外のレスポンスはすべて、API が送ったとおりに、API の camelCase のキーのまま返ります。
パッケージのパリティチェックがこれを保証します。TypeScript のメソッドに対応する PHP のメソッドがない場合、異なる引数を受け取る場合、または異なるリクエストを送る場合に、ビルドを失敗させます。