Helfer und Konstanten
Was das Paket neben den Methoden des Clients noch definiert.
Statische Methoden
| Methode | Was es ist |
|---|---|
| OpenEmail::init(), OpenEmail::getClient() | Konfigurieren Sie den gemeinsamen Client einmal und erreichen Sie ihn dann von überall. getClient() baut einen aus der Umgebung, wenn init nie gelaufen ist. |
| OpenEmail::resetClient() | Verwirft den gemeinsamen Client, sodass das nächste getClient() einen neuen erzeugt, genau das braucht ein Test zwischen zwei Fällen. |
| new OpenEmail(), OpenEmail::createClient() | Ein separater Client. Beide lesen alles, was Sie weglassen, aus der Umgebung. |
| OpenEmail::createTempMail() | Ein Client für Wegwerf-Postfächer, der keinen API-Schlüssel trägt. |
| OpenEmail::verifyWebhookSignature() | Prüft die Signatur einer Zustellung in konstanter Zeit, mit einem Replay-Fenster von fünf Minuten, das toleranceSeconds: ändert. Gibt das decodierte Event zurück und wirft bei jedem Fehlschlag WebhookSignatureException. |
| OpenEmail::toBase64() | Base64 für die Bytes von Anhängen, aus einem String, einer Stream-Ressource, einer SplFileInfo oder einem PSR-7-Stream. |
| OpenEmail::isApiKey() | Ob ein Wert die Form oe_live_ oder oe_test_ hat. Eine Prüfung der Form, kein Beweis, dass der Schlüssel noch funktioniert. |
| OpenEmail::isAccessToken() | Ob ein Wert die Form eines OAuth-Zugriffstokens hat: 1 bis 512 Zeichen, nicht mit oe_ beginnend. |
| OpenEmail::isSealed() | Ob der Body einer Nachricht Ciphertext ist. false bei den beiden signierten Formaten, deren Bodys im Klartext eingegangen sind. |
| OpenEmail::resolveLanguage(), OpenEmail::languageByCode(), OpenEmail::isRtlLanguage() | Die Abfragen, die ein Sprachauswahlfeld braucht, über die mitgelieferte Tabelle Languages::ALL. |
| $client->close() | Gibt das cURL-Handle des Clients und die Verbindung dahinter frei. Ein Client, auf den nichts mehr verweist, tut dasselbe, wenn PHP ihn freigibt. |
Konstanten
Jede Wertemenge, die das TypeScript-SDK exportiert, ist eine finale Klasse in OpenEmail\Constants, mit einer Konstante pro Element unter denselben Namen, WebhookEvents::EMAIL_DELIVERED ist also email.delivered. values() gibt die ganze Menge zurück, und so prüfen Sie auch einen Wert, der von außen kam.
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;| Konstante | Was sie enthält |
|---|---|
| OpenEmail::VERSION | Die Version des Pakets. |
| ApiScopes | Das Scope-Vokabular, für einen Bildschirm zum Anlegen von Keys. |
| WebhookEvents, WebhookSignatureHeaders | Die Events, die ein Endpunkt abonnieren kann, und die Namen der Header, die eine Zustellung mitführt. |
| ErrorTypes | Das Fehlervokabular, das ApiException::$type annimmt. |
| PageLimits | Das größte und das standardmäßige limit: bei den meisten Listen mit Seiten, MAX_LIMIT und DEFAULT_LIMIT: 100 und 25. Einige Listen nehmen mehr, und die Referenz jeder Methode sagt das. |
| RuleFields, RuleOperators, RuleActions | Das Vokabular, aus dem die Bedingungen und Aktionen einer Regel aufgebaut werden. |
| MessageEncryptionFormats | Die fünf Umschläge, die die Eingangsverarbeitung benennen kann. Drei davon sind versiegelt. |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | Welchen Zugang me->get und me->ping beschreiben, wie ein Bestätigungscode geprüft wird und die Codes, mit denen eine Bestätigung scheitern kann. |
| ThreadSorts, PeopleSorts, FileSorts und die anderen *Sorts | Die Reihenfolgen, nach denen eine Liste sortiert werden kann. |
| FormStatuses, BroadcastStatuses, SuppressionReasons und die anderen Mengen | Die Werte, die ein Feld einer Ressource annehmen kann. Jede Menge ist nach dem benannt, was sie enthält. |
| Languages::ALL | Jede Sprache, die ein übersetzter Versand oder eine Vorschau akzeptiert, mit ihrem Code, ihren Namen und ihrer Schreibrichtung. |
Objekte
Eine Antwort ist das decodierte JSON als assoziatives Array. Das Paket baut nur dort ein eigenes Objekt, wo es die Antwort formt, und jedes liegt in OpenEmail\Result, ist unveränderlich und ist IteratorAggregate und Countable über seine Zeilen.
| Klasse | Was es trägt |
|---|---|
| Page | items, hasMore und nextCursor, aus jedem list mit Seiten. |
| PeoplePage | Dasselbe plus seen, aus contacts->listPeople. |
| TempMessagesPage | Dasselbe plus expiresAt, aus tempMail->listMessages. |
| AddressBookPage, AddressBook | unrestricted, addresses und domains, aus addresses->list (mit hasMore und nextCursor) und addresses->listAll. |
| BatchResult | items, sent und failed, aus emails->sendBatch. |
| TemplateSends | items, total, page und pageSize, aus templates->listSends. |
| OpenEmail\Http\HttpRequest, OpenEmail\Http\HttpResponse | Was ein httpClient: empfängt und zurückgibt. var_dump(), print_r() und json_encode() zeigen den Authorization-Header einer Anfrage als [redacted], var_export() und Symfonys dump() dagegen unverändert. |
Jede Exception, die das Paket wirft, implementiert OpenEmail\Exception\OpenEmailException: ApiException und ihre Unterklassen, NetworkException, WebhookSignatureException und InvalidArgumentException, die bei einem Fehler im Aufruf selbst geworfen wird und nicht bei etwas, das die API gesagt hat.
Ein Endpunkt, den dies noch nicht kapselt
Ein Release des Pakets sollte nie das sein, was zwischen Ihnen und einem Endpunkt steht, der bereits funktioniert. $client->raw->request() nimmt einen Pfad und benannte Argumente und gibt den decodierten Body zurück, mit den Zugangsdaten, der Basis-URL, dem Timeout und den Wiederholungsregeln des Clients.
$result = $client->raw->request( '/labels', method: 'POST', query: ['dryRun' => true], body: ['name' => 'Invoices'], repeatable: true,); var_dump($result);Ein GET wird wie jeder andere Lesevorgang wiederholt. Jede andere Methode wird einmal gesendet, sofern Sie nicht repeatable: true übergeben, womit Sie zusichern, dass sie zweimal gesendet werden darf. query: überspringt Werte, die null oder leer sind, und apiKey: funktioniert wie bei jeder anderen Methode.
Was es bewusst nicht tut
- Es validiert keinen Request-Body. Das Schema des Servers ist die einzige Kopie der Regeln, und eine zweite Kopie hier würde irgendwann eine Adresse ablehnen, die ein neuerer Server akzeptiert, in einer Version, die jemand vor zwei Jahren festgeschrieben hat.
- Es hat keine Laufzeitabhängigkeiten außer den Erweiterungen curl und json. Ein PSR-18-Client ist eine Option, nie eine Voraussetzung.
- Es formt eine Antwort nur auf eine Weise um: Das
data-Array einer Sammlung wird aus seinem Umschlag in eines der Objekte oben herausgelöst. Jede andere Antwort kommt so zurück, wie die API sie gesendet hat, mit den camelCase-Schlüsseln der API.
Die Paritätsprüfung des Pakets sorgt dafür, dass das stimmt. Sie lässt den Build fehlschlagen, wenn eine TypeScript-Methode kein PHP-Gegenstück hat, andere Argumente nimmt oder eine andere Anfrage sendet.