Utilitaires et constantes
Ce que le package définit d'autre en plus des méthodes du client.
Méthodes statiques
| Méthode | Ce que c'est |
|---|---|
| OpenEmail::init(), OpenEmail::getClient() | Configurez le client partagé une fois, puis accédez-y de n'importe où. getClient() en construit un à partir de l'environnement si init n'a jamais été appelé. |
| OpenEmail::resetClient() | Abandonne le client partagé, pour que le prochain getClient() en construise un neuf, ce qu'un test veut entre deux cas. |
| new OpenEmail(), OpenEmail::createClient() | Un client distinct. Les deux lisent l'environnement pour tout ce que vous omettez. |
| OpenEmail::createTempMail() | Un client de boîte jetable qui ne porte aucune clé API. |
| OpenEmail::verifyWebhookSignature() | Vérifie la signature d'une livraison en temps constant, avec une fenêtre de rejeu de cinq minutes que modifie toleranceSeconds:. Renvoie l'événement décodé, et lève WebhookSignatureException en cas d'échec. |
| OpenEmail::toBase64() | Le Base64 des octets d'une pièce jointe, à partir d'une chaîne, d'une ressource de flux, d'un SplFileInfo ou d'un flux PSR-7. |
| OpenEmail::isApiKey() | Indique si une valeur a la forme oe_live_ ou oe_test_. Une vérification de forme, pas une preuve que la clé fonctionne encore. |
| OpenEmail::isAccessToken() | Indique si une valeur a la forme d'un jeton d'accès OAuth : de 1 à 512 caractères, sans commencer par oe_. |
| OpenEmail::isSealed() | Indique si le corps d'un message est du chiffré. Vaut false pour les deux formats signés, dont les corps sont arrivés en clair. |
| OpenEmail::resolveLanguage(), OpenEmail::languageByCode(), OpenEmail::isRtlLanguage() | Les fonctions de recherche dont un sélecteur de langue a besoin, sur la table Languages::ALL intégrée. |
| $client->close() | Libère le handle cURL du client et la connexion qui se trouve derrière. Un client qui n'est plus référencé fait de même quand PHP le libère. |
Constantes
Chaque ensemble de valeurs qu'exporte le SDK TypeScript est une classe finale dans OpenEmail\Constants, avec une constante par membre sous les mêmes noms : WebhookEvents::EMAIL_DELIVERED vaut donc email.delivered. values() renvoie l'ensemble complet, et c'est aussi ainsi qu'on vérifie une valeur venue de l'extérieur.
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;| Constante | Ce qu'il contient |
|---|---|
| OpenEmail::VERSION | La version du paquet. |
| ApiScopes | Le vocabulaire des portées, pour un écran de création de clé. |
| WebhookEvents, WebhookSignatureHeaders | Les événements auxquels un endpoint peut s'abonner, et les noms des en-têtes que porte une livraison. |
| ErrorTypes | Le vocabulaire d'erreurs que prend ApiException::$type. |
| PageLimits | Le limit: maximal et par défaut de la plupart des listes paginées, MAX_LIMIT et DEFAULT_LIMIT : 100 et 25. Quelques listes acceptent davantage, et la référence de chaque méthode l'indique. |
| RuleFields, RuleOperators, RuleActions | Le vocabulaire à partir duquel se construisent les conditions et les actions d'une règle. |
| MessageEncryptionFormats | Les cinq enveloppes que l'ingestion peut nommer. Trois d'entre elles sont scellées. |
| CredentialKinds, StepUpMethods, StepUpErrorCodes | Quel identifiant décrivent me->get et me->ping, comment un code de vérification est contrôlé, et les codes avec lesquels une vérification peut échouer. |
| ThreadSorts, PeopleSorts, FileSorts et les autres *Sorts | Les ordres dans lesquels une liste peut être triée. |
| FormStatuses, BroadcastStatuses, SuppressionReasons et les autres ensembles | Les valeurs que peut prendre un champ d'une ressource. Chaque ensemble est nommé d'après ce qu'il contient. |
| Languages::ALL | Chaque langue qu'accepte un envoi traduit ou un aperçu, avec son code, ses noms et son sens d'écriture. |
Objets
Une réponse est le JSON décodé, sous forme de tableau associatif. Le package ne construit son propre objet que là où il façonne la réponse, et chacun se trouve dans OpenEmail\Result, est immuable, et est IteratorAggregate et Countable sur ses lignes.
| Classe | Ce qu'il contient |
|---|---|
| Page | items, hasMore et nextCursor, renvoyés par chaque list paginé. |
| PeoplePage | Les mêmes, plus seen, renvoyés par contacts->listPeople. |
| TempMessagesPage | Les mêmes, plus expiresAt, renvoyés par tempMail->listMessages. |
| AddressBookPage, AddressBook | unrestricted, addresses et domains, renvoyés par addresses->list (avec hasMore et nextCursor) et addresses->listAll. |
| BatchResult | items, sent et failed, renvoyés par emails->sendBatch. |
| TemplateSends | items, total, page et pageSize, renvoyés par templates->listSends. |
| OpenEmail\Http\HttpRequest, OpenEmail\Http\HttpResponse | Ce qu'un httpClient: reçoit et renvoie. var_dump(), print_r() et json_encode() affichent l'en-tête Authorization d'une requête sous la forme [redacted], tandis que var_export() et le dump() de Symfony l'affichent tel quel. |
Chaque exception que lève le package implémente OpenEmail\Exception\OpenEmailException : ApiException et ses sous-classes, NetworkException, WebhookSignatureException et InvalidArgumentException, levée pour une erreur dans l'appel lui-même plutôt que pour quelque chose que l'API a répondu.
Un endpoint que ceci n'encapsule pas encore
Une version du package ne devrait jamais s'interposer entre vous et un endpoint qui fonctionne déjà. $client->raw->request() prend un chemin et des arguments nommés, et renvoie le corps décodé, en appliquant l'identifiant, l'URL de base, le délai d'expiration et la politique de réessai du client.
$result = $client->raw->request( '/labels', method: 'POST', query: ['dryRun' => true], body: ['name' => 'Invoices'], repeatable: true,); var_dump($result);Un GET est réessayé comme n'importe quelle lecture. Toute autre méthode n'est envoyée qu'une fois, sauf si vous passez repeatable: true, qui est votre affirmation qu'elle peut être envoyée deux fois. query: ignore les valeurs null ou vides, et apiKey: fonctionne comme sur toutes les autres méthodes.
Ce qu'il ne fait délibérément pas
- Elle ne valide aucun corps de requête. Le schéma du serveur est l'unique copie des règles, et une seconde copie ici finirait par refuser une adresse qu'un serveur plus récent accepte, dans une version que quelqu'un a épinglée deux ans plus tôt.
- Elle n'a aucune dépendance d'exécution en dehors des extensions curl et json. Un client PSR-18 est une option, jamais une obligation.
- Elle ne remanie une réponse que d'une seule façon : le tableau
datad'une collection est sorti de son enveloppe et placé dans l'un des objets ci-dessus. Toute autre réponse revient telle que l'API l'a envoyée, avec les clés camelCase de l'API.
Le contrôle de parité du package garantit tout cela. Il fait échouer le build quand une méthode TypeScript n'a pas de jumelle PHP, prend des arguments différents ou envoie une requête différente.